write-manual

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write a manual

编写手册

A manual explains one subject, such as a protocol, a file format, or a runtime, at one exact version. A lesson teaches a concept and moves on. A manual stays with one system until the reader can predict what it does in a case the manual never showed.

This skill gives the full method. It covers research, ranked sources, and a register of conflicts between sources. It also covers an offline capture kit, a fixed section shape, prose limits, and an audit that must report

TOTAL 0

. It works in any repository. Inside the AI Engineering from Scratch repo, the tooling already exists, and

manuals/a2a-101/

is the worked example.

手册讲解一个主题，例如协议、文件格式或 runtime，并且只针对一个确切版本。课程讲解某个概念，讲完便进入下一个主题。手册则持续围绕同一个系统，直到读者能够预测它在本手册未曾展示的案例中会如何运行。

这个 skill 给出了完整方法。它涵盖研究、来源排序和来源冲突登记表，也涵盖离线 capture kit、固定的章节结构、行文限制，以及必须报告

TOTAL 0

的审计。它适用于任何仓库。在 AI Engineering from Scratch 仓库中，相关工具已经存在，

manuals/a2a-101/

是完整的示例。

When to use

何时使用

The reader must predict the behavior of one system, at one version, in cases you did not show.
The subject has a specification, a schema, or a source tree that you can pin to a commit.
You can run the subject, or a faithful stand-in, offline and record its requests and responses.
The result is 60 to 100 pages with figures, and other people will maintain it.

读者必须能够预测一个系统在一个版本下，对于未曾展示的案例会如何运行。
主题具有 specification、schema 或 source tree，可以将其固定到某个 commit。
你可以离线运行该主题，或使用一个忠实可靠的替代实现，并记录其请求和响应。
最终结果为 60 到 100 页，包含插图，并且会由其他人持续维护。

When not to use

何时不要使用

You teach a general concept, such as attention or retrieval. Write a lesson instead.
The subject has no version to pin, or changes every week.
You cannot run the subject and cannot record its output. A manual without captures is an essay.
You want a short how-to. A manual of fewer than about 15 sections does not need this shape.

你要讲授的是 attention 或 retrieval 等通用概念。此时应编写课程。
主题没有可固定的版本，或者每周都在变化。
你无法运行该主题，也无法记录其输出。没有采集内容的手册只是一篇文章。
你只需要一份简短的操作指南。少于约 15 个章节的手册不需要采用这种结构。

Size of a 101 manual

101 手册的规模

Item	Target
pages	60 to 100
parts	6 to 8, plus one reference part
sections	about 25
figures	30 to 40
outcomes in `manual.json`	at least 3
takeaways per section	exactly 1 block, with at least 2 items

The worked example has 7 parts, 28 sections, 7 reference sections, and 31 figures.

项目	目标
页数	60 到 100
部分	6 到 8，另加一个参考部分
章节	约 25
插图	30 到 40
`manual.json` 中的 outcomes	至少 3
每节的 takeaways	恰好 1 个块，至少包含 2 个条目

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

Method

方法

Pin the subject. Record the version, source URL, commit, release date, and verified date.
Rank the sources. List them in authority order: schema or proto, specification, project docs, reference SDK, capture kit.
Vendor what the license allows. Copy each quotable source unchanged into
```
research/sources/
```
, with its license file beside it.
Write the fact brief. Index every rule you will use by section and line number, in
```
research/
```
. See references/research-and-sources.md.
Open the conflict register. Give each disagreement between two sources an id (
```
D1
```
,
```
D2
```
, ...) as you find it.
Build the capture kit. Drive the subject offline and write deterministic files to
```
capture/out/
```
. See references/capture-kit.md.
Plan the contents from the specification. Name each section after one thing the reader can find in the spec.
Write
manual.json
. Fill the pin, outcomes, palette, ranked sources, quote sources, capture commands, and parts. See references/manual-json.md.
Write the front matter. Title it "How to read this manual" and follow the order in "Front matter" below.
Write one section at a time. Use the section shape below. Cut every listing from a capture file.
Draw each figure from a capture. Follow the figure must-haves below and the sibling
```
blueprint-figure
```
skill.
Build and audit. Fix every finding until the audit prints
```
TOTAL 0
```
. See references/audit.md.
Commit one section per commit. Include its figures and the captures it adds.

固定主题。 记录 version、source URL、commit、release date 和 verified date。
对来源排序。 按权威性顺序列出：schema 或 proto、specification、项目文档、参考 SDK、capture kit。
在许可证允许的范围内 vendor。 将每个可引用来源原样复制到
```
research/sources/
```
，并把许可证文件放在旁边。
编写事实简报。 在
```
research/
```
中按章节和行号为每条将要使用的规则建立索引。参见 references/research-and-sources.md。
建立冲突登记表。 每当发现两个来源之间存在分歧，就为其分配一个 id（
```
D1
```
、
```
D2
```
等）。
构建 capture kit。 离线驱动该主题，并向
```
capture/out/
```
写入确定性文件。参见 references/capture-kit.md。
根据 specification 规划内容。 每个章节都应以读者能够在 spec 中找到的某一项内容命名。
编写
manual.json
。填写 pin、outcomes、palette、排序后的 sources、quote sources、capture 命令和 parts。参见 references/manual-json.md。
编写 front matter。 将其标题设为“如何阅读本手册”，并遵循下文“前置内容”中的顺序。
一次编写一个章节。 使用下文的章节结构。每个 listing 都必须从 capture 文件中截取。
每幅插图都根据 capture 绘制。 遵循插图必备项以及同级
```
blueprint-figure
```
skill。
构建并审计。 修复每个问题，直到审计输出
```
TOTAL 0
```
。参见 references/audit.md。
每个 commit 提交一个章节。 同时包含该章节的插图和新增 captures。

Plan the contents from the specification

根据 specification 规划内容

Build the table of contents from the names the specification uses, then decide what each part proves.

Front matter. One document,
```
front.md
```
, titled "How to read this manual".
Part 1, the subject on one page. Two sections: what the subject standardizes, then one complete exchange from a capture.
Middle parts. One part per layer of the subject, such as discovery, data model, operations, bindings, security, and extensions.
Last part, implementation. Build a client and a server. Test both with the official conformance tools. Explain migration from the previous version.
Reference part. Method tables, objects, states, errors, a glossary, the sources and conflicts, and the figure index.

Each section title names one object, operation, binding, header, error, or extension from the specification. "CancelTask and terminal states" is a good title. "State machines" is not, because no specification defines an object with that name. Put a general idea in the section about the object that has it.

根据 specification 使用的名称构建目录，然后确定每个部分要证明什么。

前置内容。 使用一个文档
```
front.md
```
，标题为“如何阅读本手册”。
第 1 部分：用一页介绍主题。 包含两个章节：先介绍主题标准化了什么，然后展示一次来自 capture 的完整交互。
中间部分。 主题的每一层对应一个部分，例如 discovery、data model、operations、bindings、security 和 extensions。
最后一部分：实现。 构建 client 和 server。使用官方一致性工具测试两者，并说明如何从上一版本迁移。
参考部分。 包含方法表、对象、状态、错误、术语表、来源与冲突，以及插图索引。

每个章节标题都应命名 specification 定义的一个 object、operation、binding、header、error 或 extension。“CancelTask and terminal states”是一个好标题。“State machines”则不是，因为 specification 中没有任何对象使用这个名称。应将通用概念放入讨论相关 object 的章节中。

Front matter

前置内容

front.md

covers these topics, in this order:

Who the manual is for, and what they can do after it.
How it was made, with the ranked sources table.
The capture kit.
The conventions: citation forms, listing cuts, and id shortening.
A first run that the reader can do offline.
How the parts are ordered, as an empty
```
parts
```
block.
Colour in figures, as an empty
```
palette
```
block.
Figure 0.1, which teaches the arrow and colour grammar of this manual.

front.md

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

手册面向哪些读者，以及他们读完后能够做什么。
手册是如何编写的，并附上排序后的来源表。
Capture kit。
约定：引用形式、listing 截取方式和 id 缩写。
读者可以离线完成的首次运行。
各部分的排列顺序，使用空的
```
parts
```
块表示。
插图中的颜色，使用空的
```
palette
```
块表示。
插图 0.1，用于讲解本手册使用的箭头和颜色语法。

Section shape

章节结构

Every section file follows this order. Reference sections and the front matter need a thesis and a sources line, but no outcome sentence and no takeaways.

```
# Title
```
, with the name the specification uses.
```
> Thesis
```
, directly under the title: one sentence of at most 30 words, the claim the section proves.
An opening paragraph that starts from a concrete situation the reader has been in.
The sentence "When you finish this section, you can ..." inside the first two paragraphs.
The body:
```
##
```
subsections, definitions that start with
```
**Term:**
```
, figures, listings, rules, and tables.
Exactly one
```
takeaways
```
block, with two or more actions.
A last paragraph that starts with
```
Sources:
```
and names every file the section was written from.

A complete template is in references/section-template.md.

每个章节文件都遵循以下顺序。参考章节和 front matter 需要 thesis 和 sources 行，但不需要 outcome 句和 takeaways。

```
# 标题
```
，使用 specification 中的名称。
```
> Thesis
```
，紧接在标题下方：用最多 30 个词写一个句子，陈述该章节要证明的论点。
一个开头段落，从读者曾经遇到过的具体情境切入。
在前两个段落内写明“完成本节后，你将能够……”。
正文：使用
```
##
```
子章节、以
```
**Term:**
```
开头的定义、插图、listings、rules 和 tables。
恰好一个
```
takeaways
```
块，其中包含两个或更多行动项。
最后一段以
```
Sources:
```
开头，并列出该章节所依据的所有文件。

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

Fenced block kinds

围栏代码块类型

Fence	Holds	Required keys
`figure`	one figure, by id	`id` , `kind` , `title` , `claim` , `caption`
`listing`	lines cut from one capture file	`title` , `source` , `lang` , optional `note` , then `---` and the lines
`rule`	one quote, checked word for word	`label` , `source` , then `---` and the quote
`takeaways`	the actions for the section	two or more `- item` lines
`parts` , `palette` , `figure-index` , `contents`	generated tables	no body

Every other fence needs a language tag. A

json

jsonl

http

, or

sse

fence must be a

listing

instead.

围栏	内容	必需键
`figure`	按 id 标识的一幅插图	`id` 、 `kind` 、 `title` 、 `claim` 、 `caption`
`listing`	从一个 capture 文件中截取的行	`title` 、 `source` 、 `lang` 、可选的 `note` ，然后是 `---` 和具体内容
`rule`	逐字校验的一条引用	`label` 、 `source` ，然后是 `---` 和引用内容
`takeaways`	章节的行动项	至少两行 `- item`
`parts` 、 `palette` 、 `figure-index` 、 `contents`	自动生成的表格	无正文

其他每种围栏都需要语言标签。

json

、

jsonl

、

http

或

sse

围栏必须改为

listing

。

Markdown subset

Markdown 子集

Use only these constructs, so every edition renders the same way:

One
```
#
```
title on the first line, and the thesis quote under it.
```
##
```
and
```
###
```
headings, each with an optional
```
{#anchor}
```
.
Paragraphs, and one-level
```
-
```
or
```
1.
```
lists.
Pipe tables with a header row.
Bold, italic, and inline code.
```
{{key ref}}
```
citations,
```
[text](#s-5-3)
```
cross-references, and repository links.

Raw HTML, horizontal rules, nested lists,

####

headings, and other quote blocks fail the build. Section anchors are

s-

plus the id with dots as hyphens, such as

s-1-4

s-r-2

仅使用以下结构，以确保每个版本都以相同方式渲染：

第一行使用一个
```
#
```
标题，其下紧接 thesis 引用。
```
##
```
和
```
###
```
标题，每个标题都可附带
```
{#anchor}
```
。
段落，以及只有一层深度的
```
-
```
或
```
1.
```
列表。
带标题行的管道表格。
粗体、斜体和行内代码。
```
{{key ref}}
```
引用、
```
[text](#s-5-3)
```
交叉引用和仓库链接。

原始 HTML、水平分隔线、嵌套列表、

####

标题和其他引用块都会导致构建失败。章节 anchor 由

s-

加 id 组成，其中 id 内的点替换为连字符，例如

s-1-4

或

s-r-2

。

Listings

Cut every listing from a file in
```
capture/out/
```
. Never type a request or a response from memory.
Each listing line must appear in its source file exactly as written.
Mark a cut with
```
…
```
on its own line or inside a line.
Say what you cut in the
```
note
```
.
Name the source file in
```
source
```
, so the reader can open the full record.

每个 listing 都必须从
```
capture/out/
```
中的文件截取。绝不能凭记忆输入请求或响应。
listing 中的每一行都必须与源文件中的内容完全一致。
使用单独一行或行内的
```
…
```
标记截取位置。
在
```
note
```
中说明截取了哪些内容。
在
```
source
```
中写出源文件名，以便读者打开完整记录。

Sources, quotes, and conflicts

来源、引用和冲突

Rank
```
sources
```
by authority. When two sources disagree, the higher one wins and the text says so.
Quote a rule word for word, then cite its key:
```
"quoted text" {{spec §3.1.5}}
```
.
Declare every citation key in
```
quoteSources
```
. Map it to a vendored file, or to
```
null
```
when the source cannot be vendored.
Paraphrase sources with a
```
null
```
key, such as an SDK. Never quote them.
When sources disagree, quote both sides in the section, say which one the manual follows, and link the register entry.
Keep the register in the sources reference section. Give it five columns: id, sources, choice, sections, and upstream status.
Never name or cite another guide, course, or book. Cite specifications, source code, papers, and the subject's own documentation.

按权威性对
```
sources
```
排序。当两个来源存在分歧时，以权威性更高者为准，并在正文中说明这一点。
逐字引用规则，然后引用其 key：
```
"quoted text" {{spec §3.1.5}}
```
。
在
```
quoteSources
```
中声明每个引用 key。将其映射到一个 vendored 文件；如果来源无法 vendored，则映射为
```
null
```
。
使用
```
null
```
key 对来源进行转述，例如 SDK。不要直接引用这类来源。
当来源存在分歧时，在章节中同时引用双方，说明手册采用哪一方，并链接到登记表条目。
将登记表放在 sources 参考章节中。设置五列：id、sources、choice、sections 和 upstream status。
绝不能提及或引用其他指南、课程或书籍。只引用 specifications、source code、papers 和主题自身的 documentation。

Prose limits

行文限制

Limit	Value
words in a sentence	at most 25
words in a thesis	at most 30, one sentence
words in a figure claim	at most 28, one sentence ending with a period
words in a takeaway	at most 20, an instruction in imperative mood
sentences in a paragraph	at most 6

Write in the second person, about the mechanism. Define a term once, use it the same way everywhere, and add it to the glossary. Quotes, code, and citations are exempt from the limits.

Use no semicolons, no contractions, and no em or en dashes. Never write the word

may

. Use "can", or state the condition. Avoid the banned words in references/prose-rules.md.

限制	数值
一个句子中的词数	最多 25
thesis 中的词数	最多 30，且只能有一个句子
插图 claim 中的词数	最多 28，且只能有一个以句号结尾的句子
takeaway 中的词数	最多 20，使用祈使语气
一个段落中的句子数	最多 6

使用第二人称，专注于机制。每个术语只定义一次，全程保持一致，并将其加入术语表。引用、代码和引文注释不受这些限制。

不要使用分号、缩写式词，也不要使用 em dash 或 en dash。绝不能使用

may

一词。使用

can

，或者直接说明条件。避免使用 references/prose-rules.md 中列出的禁用词。

Figure must-haves

插图必备项

Use the sibling

blueprint-figure

skill to draw the figures. Every figure in a manual must also meet these rules:

Use one of nine kinds:

sequence

structure

flow

comparison

timeline

tree

state

decision

layers

Show the real system: real ids, field names, method names, and sequence numbers from a capture.
Make one claim of at most 28 words. The caption says how to read the figure, then names its capture file.
Never draw generic boxes such as "Component A", stat cards, or progress bars.
Compare two behaviors of the subject. Never compare against an earlier build.
Give each hue one meaning per manual.
```
rose
```
is failure,
```
grey
```
is outside the subject,
```
amber
```
is lifecycle,
```
teal
```
is durable state.
Draw exchanges with the eight arrow styles below. Figure 0.1 teaches the ones the manual uses.
Use
```
viewBox="0 0 640 H"
```
with H at most 760, text at least 11 units, and a file of at most 40 KB.
Put a
```
<title>
```
and a
```
<desc>
```
of at least 40 characters on the root, which has
```
role="img"
```
.
Start every
```
id
```
in the SVG with the figure id, because all figures share one page.
Write colours only as
```
var(--m-<token>, #hex)
```
, with the light value of the token as the hex.

Arrow style	Means
solid ink	a call or request
dashed ink	a reply
solid teal	a durable write
dashed amber	a state change
solid plum	a model call or compute
dashed olive	an effect outside the system
dotted indigo	a stream or an event
dashed rose	a failure

使用同级

blueprint-figure

skill 绘制插图。手册中的每幅插图还必须满足以下规则：

使用以下九种 kind 之一：

sequence

、

structure

、

flow

、

comparison

、

timeline

、

tree

、

state

、

decision

、

layers

。

展示真实系统：使用来自 capture 的真实 id、字段名、方法名和序号。
表达一个最多包含 28 个词的 claim。caption 先说明如何阅读插图，然后指出其 capture 文件。
绝不能绘制“Component A”、统计卡片或进度条等通用方框。
比较主题的两种行为。绝不能与旧版本构建结果进行比较。
每种色相在整本手册中只能表达一种含义。
```
rose
```
表示失败，
```
grey
```
表示主题范围之外，
```
amber
```
表示生命周期，
```
teal
```
表示持久状态。
使用下表中的八种箭头样式绘制交互。插图 0.1 讲解手册使用的样式。
使用
```
viewBox="0 0 640 H"
```
，其中 H 最大为 760；文字至少为 11 个单位，文件最大为 40 KB。
在根元素上放置至少 40 个字符的
```
<title>
```
和
```
<desc>
```
，并将根元素的
```
role
```
设置为
```
img
```
。
SVG 中的每个
```
id
```
都以 figure id 开头，因为所有插图都位于同一页面。
颜色只能写为
```
var(--m-<token>, #hex)
```
，其中 hex 是该 token 的浅色值。

箭头样式	含义
ink 实线	一次调用或请求
ink 虚线	一次回复
teal 实线	持久写入
amber 虚线	状态变更
plum 实线	模型调用或计算
olive 虚线	系统外部的影响
indigo 点线	流或事件
rose 虚线	失败

Build and audit

构建与审计

Inside the AI Engineering from Scratch repo, run these from the repository root:

bash

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>

Outside the repo, build your own audit from references/audit.md. It lists each check, so you can write it as one script. Fix the text, never the limit. A manual does not merge until the audit prints

TOTAL 0

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

bash

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

时，手册才能合并。

Commit rules

Commit 规则

Commit one section per commit, with its figures and the captures it adds.
Use the message
```
feat(manual/<id>): <section slug>
```
.
Never commit generated output. Inside the repo, that is
```
site/manual-<id>.html
```
,
```
site/manuals.html
```
, and
```
site/manuals-data.js
```
.
Keep
```
status
```
at
```
draft
```
until the manual is complete. A
```
ready
```
manual needs a
```
README.md
```
.
Update vendored sources only together with the
```
pin
```
in
```
manual.json
```
.

每个 commit 提交一个章节，并包含其插图和新增 captures。
使用消息
```
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。

Check before you finish

完成前检查

```
manual.json
```
validates, and
```
pin
```
has subject, version, source, commit, date, and verified.
Every section title names one thing that the specification defines.
Every section has a thesis, an outcome sentence in its first two paragraphs, one takeaways block, and a
```
Sources:
```
line.
Every
```
json
```
,
```
jsonl
```
,
```
http
```
, and
```
sse
```
block is a
```
listing
```
with a capture source.
The capture check runs offline and reports no drift.
Every quote of 24 or more characters is found word for word in its vendored file.
Every conflict has a register id, and each section that meets it links that id.
Every figure SVG is used by a document and matches its source script.
The audit prints
```
TOTAL 0
```
.
Each commit holds one section, with the message
```
feat(manual/<id>): <section slug>
```
.

```
manual.json
```
通过验证，且
```
pin
```
包含 subject、version、source、commit、date 和 verified。
每个章节标题都命名了 specification 定义的一项内容。
每个章节都有 thesis、前两个段落内的 outcome 句、一个 takeaways 块和一行
```
Sources:
```
。
每个
```
json
```
、
```
jsonl
```
、
```
http
```
和
```
sse
```
块都是带 capture source 的
```
listing
```
。
Capture 检查可离线运行，并且未报告 drift。
每段长度不少于 24 个字符的引用，都能在其 vendored 文件中逐字找到。
每个冲突都有 register id，每个涉及该冲突的章节都链接该 id。
每幅插图 SVG 都被某个文档使用，并且与其 source script 匹配。
审计输出
```
TOTAL 0
```
。
每个 commit 仅包含一个章节，消息为
```
feat(manual/<id>): <section slug>
```
。

Files

文件

references/manual-json.md: every field of
```
manual.json
```
, with a starter file.
references/section-template.md: a section skeleton with each fence kind.
references/research-and-sources.md: the fact brief, vendoring, quotes, and the conflict register.
references/capture-kit.md: how to record deterministic captures and check them for drift.
references/prose-rules.md: the limits and the full banned word list.
references/audit.md: every audit rule, and how to reproduce the audit outside the repo.

Inside the AI Engineering from Scratch repo, also see

manuals/AUTHORING.md

manuals/manual.schema.json

, and

manuals/a2a-101/

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