跳转至

00 · 扩写写作规范(所有扩写子代理必读)

本文档是「12-智能体开发」模块从面试速查扩写为「小白也能入门的极致详细教程」的统一写作规范。 任何子代理动手扩写章节前,必须先完整阅读本文,再阅读自己要扩写的章节原文。


1. 扩写目标与定位

  • 读者:编程基础薄弱、从未接触过 Agent 概念的小白(哪怕不懂 Transformer),同时兼顾秋招面试复习。
  • 定位:本模块 = 小白入门教程(主体)+ 面试速查(每章末尾「面试考点」保留)。
  • 篇幅:每章 md 扩写后 不少于 1200 行(不含行号),鼓励到 1500 行左右。ipynb 与扩写后的 md 内容一致。
  • 风格:口语化、循序渐进、类比丰富、不跳步。任何术语第一次出现时给「中文名(英文名)+一句大白话解释+一个生活类比」。

2. 每章固定结构(扩写后必须包含,顺序如下)

  1. # 章节标题(与文件名一致)
  2. 开头的引用块故事(保留/顺延原「阿零」故事开场)
  3. ## 本节要解决的问题(保留原表格,可扩充每行的「小白版一句话」列)
  4. ## 故事引入(保留原文并适当扩写)
  5. ## 本章路线图(新增:mermaid 流程图展示本章 5-6 个知识点怎么串起来 + 一段文字说明:前置知识、学完能获得什么、与前后章的衔接)
  6. ## 核心概念(每个概念小节 ### (x) 标题 内部统一采用「四段式」):
  7. 一句话直觉(> 💡 引用块,用生活类比讲清它是什么)
  8. 大白话详解(逐句展开,避免术语堆叠;术语首次出现加粗并给解释)
  9. 形象类比 / 举例(至少 1 个生活场景类比或具体数字例子)
  10. mermaid 图(照应原文既有图;可新增 1-2 张,如「对比图」「流程图」)
  11. ## 深入原理(保留原有表格并扩充:
  12. 每张表格加「白话理解」列或对重点行做「> 💡 解读」;
  13. 至少新增 1 张「常见误区对照表」(错误理解 vs 正确理解 vs 类比))
  14. ## 代码实战(逐行拆解):
  15. 先有「代码要做什么(大白话版)」段落;
  16. Python 代码块保持可运行(mock、不联网、固定种子);
  17. 代码块之后逐块/逐段讲解代码(**第 1 段:xxx** 这种子标题,解释每一行在干什么、参数为什么这么设、去掉会怎样);
  18. 输出示意保留,并在其后「读输出」段落逐行解释输出含义;
  19. 末尾「动手改一改」:给出 2-3 个小的改动练习(如改参数看输出变化、加一个新工具),附预期结果说明。
  20. ## 常见误区(新增章节):用表格或列表汇总 5-8 个新手高频误区(每个:误区描述 → 为什么错 → 正确理解)。
  21. ## 动手练习(新增章节):3-5 道由易到难的练习题(问答题 + 小代码任务),附「提示」不附完整答案(答案留给读者),但对每道题给出「考察点」说明。
  22. ## 面试考点(保留全部原有 Q&A,可再补充 1-3 个新问答)
  23. ## 小结与下一章预告(保留/顺延,预告内容与下一章主题一致;第 10 章为「小结与全书总结」)

3. 写作语言规范

  • 用词:多用「其实」「相当于」「你可以把它想象成」;避免「显然」「易知」「众所周知」。
  • 类比库(可复用):上下文窗口=工作台桌面;KV Cache=草稿纸不重抄;记忆=档案柜+图书馆;工具=手脚;MCP=USB-C 统一接口;Skill=菜谱;pass@k=抓娃娃多买几次;GRPO=小组内部比排名;多 Agent=开公司/团队协作。可自行增加更好的类比,但不要替换阿零的故事设定。
  • 数字:所有数值(token 数、概率、公式结果)必须可手算/与源 md 一致,严禁编造。代码输出示意必须与实际代码逻辑一致(可参照前文手算复核过的数值,如 pass@k 0.7183、KV 压缩 320→121、GRPO adv=[1.18,-0.17,0.51,-1.52])。
  • 引用:论文/产品引用沿用「年份+一句话定位」风格(ReAct 2022、Toolformer 2023、MemGPT 2023、SWE-bench 2024、MCP Anthropic 2024、GAIA 2023、OSWorld 2024、HumanEval 2021、GraphRAG 2024、RRF Cormack 2009、GRPO DeepSeekMath 2024、Shumailov 模型坍塌 2023 等),不编造论文标题与年份。
  • 链接:章节间互链用相对文件名(含 .md),仓库 notebook 用 ../04-LLM大模型/教学/19-KV缓存.ipynb 形式;新增行文如需链接必须验证目标存在(可用 glob 检查)。

4. mermaid 图规范

  • 每章 mermaid 图总数 ≥ 4(含新增的「本章路线图」「对比图」等)。
  • 语法保持 GitHub 可渲染(flowchart/sequenceDiagram/graph 关键字、节点 ["..."]、边 --> 等),禁止语法错误。
  • 节点文字用中文,长文字用 <br/> 换行。

5. 表格规范

  • 章节「本节要解决的问题」表格保留并可加列;
  • 「深入原理」至少 2 张表并给解读;
  • 「常见误区」用表格或列表;
  • 所有表格对齐、分隔行正确(| --- |)。

6. 代码规范

  • 必须可运行:Python 3、仅标准库(或 numpy)+ mock,不联网,random.seed 固定;
  • if __name__ == "__main__": 保护块:md 中保留(单文件脚本语境),ipynb 中改写为顶层直接调用;
  • 中文字符串、emoji、注释全部保留;
  • 每个代码块前有「代码要做什么」,后有待办拆解讲解与输出解读。

7. 字数与质量自查清单(写完逐条核对)

  • [ ] 行数 ≥ 1200(可参考源文件行数估算新增量)
  • [ ] 八个必要小节齐全(问题/故事/路线图/核心概念/深入原理/代码实战/面试考点/小结)
  • [ ] 新增「常见误区」「动手练习」「本章路线图」三小节
  • [ ] mermaid ≥ 4 且语法无误;表格 ≥ 3
  • [ ] 术语首次出现均有白话解释+类比
  • [ ] 代码逐行拆解+输出解读+动手改一改
  • [ ] 全部数值与源 md 一致、可手算复核
  • [ ] 链接有效、故事线(阿零)贯穿、预告指向下一章

8. 防上下文耗尽(重要!)

扩写一章约 1200-1500 行,单次 write 输出会撑爆上下文(已有代理因此失败)。必须:

  1. 先读 规范文件 + 章节原文;
  2. 把扩写后内容拆成 2-3 段:第一段 write 覆盖写入前 60% 内容(# 标题 → 代码实战之前,含「本章路线图」「核心概念」「深入原理」),结尾留一个自然断点;
  3. 第二段用 read 读回已写部分末尾(确认断点),再用 edit(在断点处追加)或重新 write 追加剩余 40%(代码实战 → 小结);
  4. 若仍紧张,可分三段(前 40% / 中 40% / 后 20%),每段写完立即 read 回读确认已落盘;
  5. 全程不要重读整份规范与原文(只按需 read 小片段),把上下文留给输出。

9. ipynb 同步规则(扩写 md 完成后进行)

  • ipynb 与扩写后 md 内容一一对应:正文进 markdown cell,Python 代码进 code cell(outputs 空、execution_count null);
  • if __name__ == "__main__": 改写为顶层直接执行;
  • mermaid/json/text 代码块保留在 markdown cell 中(mermaid 前加「该图在 GitHub/VSCode + mermaid 插件中可渲染」说明,输出示意前加「运行上述代码后,预期输出示意:」);
  • notebook JSON 必须合法(nbformat 4);\n、"、正则里的反斜杠正确转义;
  • ipynb 同样存在输出量大的问题:先 write 写 markdown cells 前半,再分块 edit 追加后续 cells 与 code cells,每步 read 回读确认。

教程来源:Akun-python/autumn-recruitment。 MIT 许可证全文。