write-manual

编写手册

手册会在某个确切版本下讲解一个主题，例如协议、文件格式或运行时。课程讲解一个概念，然后继续下一个。手册则会持续讲解一个系统，直到读者能够预测该系统在手册未展示过的情况下会如何运行。

本技能提供完整的方法，涵盖研究、来源排序以及来源冲突登记表，也包括离线采集套件、固定的章节结构、行文限制，以及必须报告 TOTAL 0 的审查。它适用于任何代码仓库。在 AI Engineering from Scratch 仓库中，所需工具已经就绪，manuals/a2a-101/ 是一个完整示例。

适用场景

• 读者必须能够预测某个系统在某个版本下的行为，包括你未展示过的情况。
• 主题有规范、架构或可固定到某个提交的源代码树。
• 你可以离线运行该主题或忠实替代实现，并记录其请求和响应。
• 最终成果包含图示，共 60 至 100 页，并且会由其他人维护。

不适用场景

• 你要讲解一个通用概念，例如注意力机制或检索。请改写成课程。
• 主题没有可固定的版本，或每周都在变化。
• 你无法运行该主题，也无法记录其输出。没有采集记录的手册只是篇文章。
• 你想写一篇简短的操作指南。少于约 15 个章节的手册不需要采用这种结构。

101 手册的规模

项目	目标
页数	60 至 100
部分	6 至 8 个，另加一个参考部分
章节	约 25 个
图示	30 至 40 幅
manual.json 中的学习成果	至少 3 项
每个章节的要点	恰好 1 个区块，至少包含 2 项

完整示例包含 7 个部分、28 个章节、7 个参考章节和 31 幅图示。

方法

1. 固定主题版本。 记录版本、来源 URL、提交、发布日期和验证日期。
2. 按权威性排列来源。 按优先顺序列出：架构或 proto、规范、项目文档、参考 SDK、采集套件。
3. 按许可允许的范围纳入来源。 将每个可引用来源原样复制到 research/sources/，并将其许可证文件放在旁边。
4. 编写事实简报。 在 research/ 中按章节和行号索引你将使用的每条规则。参见 references/research-and-sources.md。
5. 建立冲突登记表。 发现两个来源之间的分歧时，为其分配一个 ID（D1、D2……）。
6. 构建采集套件。 离线运行主题，并将确定性文件写入 capture/out/。参见 references/capture-kit.md。
7. 根据规范规划目录。 以读者可以在规范中查到的一项内容命名每个章节。
8. 编写 manual.json。 填写版本固定信息、学习成果、配色方案、排序后的来源、引用来源、采集命令和各部分。参见 references/manual-json.md。
9. 编写前置内容。 将标题定为“如何阅读本手册”，并遵循下文“前置内容”中的顺序。
10. 一次编写一个章节。 使用下文的章节结构。所有清单都应从采集文件中截取。
11. 根据采集记录绘制每幅图示。 遵循下文的图示必备要求以及同目录的 blueprint-figure 技能。
12. 构建并审查。 修复所有问题，直到审查结果显示 TOTAL 0。参见 references/audit.md。
13. 酌情确定提交规模。 将一个章节及其图示和新增采集记录作为一个合适的提交单元。

根据规范规划内容

按照规范使用的名称构建目录，然后确定每个部分要证明什么。

• 前置内容。 一份文档，front.md，标题为“如何阅读本手册”。
• 第 1 部分，主题一页概览。 两个章节：主题标准化的内容，然后是从一次捕获中选取的完整交互。
• 中间各部分。 主题的每一层各设一部分，例如发现、数据模型、操作、绑定、安全和扩展。
• 最后一部分，实现。 构建一个客户端和一个服务端。使用官方一致性工具测试两者。说明如何从上一版本迁移。
• 参考部分。 方法表、对象、状态、错误、术语表、来源与冲突，以及插图索引。

每个章节标题都要命名规范中的某个对象、操作、绑定、标头、错误或扩展。“CancelTask 和终止状态”是个好标题。“状态机”则不合适，因为规范没有定义一个名为“状态机”的对象。应在包含该概念的对象章节中介绍通用概念。

前置内容

front.md 按以下顺序涵盖这些主题：

1. 本手册面向哪些读者，以及读者读完后能做什么。
2. 本手册的编写方式，包括按优先级排列的来源表。
3. 捕获工具包。
4. 约定：引用格式、列表截取和 ID 缩短。
5. 读者可以离线完成的首次运行。
6. 各部分的排列顺序，使用空的 parts 块。
7. 插图中的颜色，使用空的 palette 块。
8. 图 0.1，介绍本手册中的箭头和颜色规则。

章节结构

每个章节文件都遵循以下顺序。参考章节和前置内容需要有论点和来源行，但不需要结果句或要点。

1. # 标题，使用规范中的名称。
2. > 论点，紧接标题下方：一句不超过 30 个词的论断，即本章节要证明的内容。
3. 开篇段落，从读者经历过的具体情境入手。
4. 在前两个段落中写入句子 “When you finish this section, you can ...”。
5. 正文：## 子章节、以 **术语：** 开头的定义、插图、列表、规则和表格。
6. 恰好一个 takeaways 块，包含两项或更多行动。
7. 最后一段以 Sources: 开头，并列出编写本章节所依据的每个文件。

完整模板见 references/section-template.md。

围栏代码块类型

围栏	内容	必需键
figure	一幅插图，按 ID 标识	id、kind、title、claim、caption
listing	从一个捕获文件中截取的若干行	title、source、lang，以及可选的 note，然后是 --- 和内容行
rule	一段逐字核对的引文	label、source，然后是 --- 和引文
takeaways	本章节的行动项	两行或更多 - item
parts、palette、figure-index、contents	生成的表格	无正文

其他所有围栏代码块都需要语言标签。json、jsonl、http 或 sse 围栏必须使用 listing。

Markdown 子集

只使用以下结构，以确保每个版本的呈现方式相同：

• 第一行是一个 # 标题，其下方是论点引用。
• 使用 ## 和 ### 标题，每个标题可带可选的 {#anchor}。
• 段落，以及一层 - 或 1. 列表。
• 带表头行的管道表格。
• 粗体、斜体和行内代码。
• {{key ref}} 引用、[text](#s-5-3) 交叉引用和仓库链接。

原始 HTML、水平分隔线、嵌套列表、#### 标题和其他引用块都会导致构建失败。章节锚点由 s- 加上以连字符替换句点的 ID 构成，例如 s-1-4 或 s-r-2。

条目

• 从 capture/out/ 中的文件逐条摘录。绝不要凭记忆编写请求或响应。
• 每行条目都必须与源文件中的内容完全一致。
• 用单独一行的 … 标记删节，或将它放在行内。
• 在 note 中说明删去了什么。
• 在 source 中注明源文件名，让读者可以打开完整记录。

来源、引文与冲突

• 按权威性排列 sources。如果两个来源存在分歧，以较高优先级的来源为准，并在文中说明。
• 逐字引用规则，然后注明其键："quoted text" {{spec §3.1.5}}。
• 在 quoteSources 中声明每个引文键。将其映射到随附的文件；如果来源无法随附，则映射到 null。
• 对键为 null 的来源（例如 SDK）进行转述。绝不要引用这类来源。
• 来源存在分歧时，在对应章节引用双方的说法，说明手册遵循哪一方，并链接到登记表中的条目。
• 在来源参考章节中保留登记表。登记表必须有五列：id、sources、choice、sections 和 upstream status。
• 绝不要提及或引用其他指南、课程或书籍。只引用规范、源代码、论文和主题自身的文档。

正文限制

限制	数值
句子中的单词数	最多 25 个
论点中的单词数	最多 30 个，且为一个句子
图示中的主张单词数	最多 28 个，且为以句号结尾的一个句子
总结中的单词数	最多 20 个，使用祈使语气
段落中的句子数	最多 6 个

使用第二人称，围绕机制展开。每个术语只定义一次，并在全文保持一致用法，然后将其加入术语表。引文、代码和引用不受这些限制约束。

不要使用分号、缩写形式或破折号。绝不要写 may 一词。使用 “can”，或说明条件。避免使用 references/prose-rules.md 中的禁用词。

图示必备要求

使用同级目录中的 blueprint-figure 技能绘制图示。手册中的每个图示还必须符合以下规则：

• 使用九种类型之一：sequence、structure、flow、comparison、timeline、tree、state、decision、layers。
• 展示真实系统：来自捕获记录的真实 id、字段名、方法名和序号。
• 只提出一个不超过 28 个单词的主张。图注先说明如何阅读图示，再注明其捕获文件。
• 绝不要绘制“组件 A”之类的通用方框、统计卡片或进度条。
• 比较主题的两种行为。绝不要与早期版本比较。
• 每种色调在每本手册中只代表一种含义。rose 表示失败，grey 表示主题之外，amber 表示生命周期，teal 表示持久状态。
• 使用下方列出的八种箭头样式绘制交互。图示 0.1 会介绍手册中使用的样式。
• 使用 viewBox="0 0 640 H"，其中 H 不超过 760，文字至少为 11 个单位，文件不超过 40 KB。
• 在根元素上设置 role="img"，并添加 <title> 和至少包含 40 个字符的 <desc>。
• SVG 中的每个 id 都以图示 id 开头，因为所有图示共用一个页面。
• 颜色只能写作 var(--m-<token>, #hex)，其中 hex 必须是该 token 的浅色值。

箭头样式	含义
实线墨色	调用或请求
虚线墨色	回复
实线青绿色	持久写入
虚线琥珀色	状态变化
实线李子色	模型调用或计算
虚线橄榄色	系统外部的效果
点线靛蓝色	流或事件
虚线玫瑰色	失败

构建与审计

在 AI Engineering from Scratch 仓库中，从仓库根目录运行以下命令：

node --test site/test_manuals.js
node site/build-manuals.js
node manuals/_shared/figkit.js build manuals/<id>
node scripts/audit_manuals.js --manual <id>

在仓库之外，根据 references/audit.md 构建你自己的审计流程。其中列出了每项检查，因此你可以将其写成一个脚本。修改文本，绝不要修改限制。只有审计输出 TOTAL 0 后，手册才能合并。

提交规则

• 根据判断确定提交大小。包含其图示和新增抓取内容的一个章节，是合适的提交单元。跨章节的小修复可以合并为一次提交。
• 使用提交信息 feat(manual/<id>): <section slug>。
• 切勿提交生成的输出。在仓库中，这些文件是 site/manual-<id>.html、site/manuals.html 和 site/manuals-data.js。
• 在手册完成前，将 status 保持为 draft。ready 状态的手册必须包含 README.md。
• 仅在更新 manual.json 中的 pin 时，才更新 vendored sources。

完成前检查

• manual.json 验证通过，且 pin 包含 subject、version、source、commit、date 和 verified。
• 每个章节标题都指明规范所定义的一项内容。
• 每个章节都有一个论点、在前两段中的一句结果陈述、一个要点区块，以及一行 Sources:。
• 每个 json、jsonl、http 和 sse 区块都是带有抓取来源的 listing。
• 抓取检查可离线运行，且报告无偏差。
• 每条长度为 24 个或更多字符的引文，都能在其 vendored file 中逐字找到。
• 每个冲突都有一个 register id，且每个涉及该冲突的章节都链接到该 id。
• 每个图示 SVG 都被文档使用，并与其源脚本一致。
• 审计输出 TOTAL 0。
• 根据判断确定提交大小，提交信息示例：feat(manual/<id>): <section slug>。

文件

• references/manual-json.md：manual.json 的所有字段，以及一个起始文件。
• references/section-template.md：包含各种 fence 类型的章节骨架。
• references/research-and-sources.md：事实简介、vendoring、引文和冲突登记表。
• references/capture-kit.md：如何记录确定性抓取并检查是否存在偏差。
• references/prose-rules.md：限制和完整的禁用词列表。
• references/audit.md：所有审计规则，以及如何在仓库之外复现审计。
• 在 AI Engineering from Scratch 仓库中，还请参阅 manuals/AUTHORING.md、manuals/manual.schema.json 和 manuals/a2a-101/。