Rewrite Technical Tutorial

技术教程写作与审校

判断一篇教程是否写清楚，不看它覆盖了多少名词，而看新读者能否沿着同一条因果链，回答“为什么需要、何时发生、数据长什么样、代码怎么推进、失败后怎么办”。

本 Skill 用于把源码分析、实现笔记和已有技术文章整理成工程师真正能读懂、能核对、能照着实现的教程。默认读者没有看过参考仓库、上游教程和作者之前的对话，也不知道某个产品的内部术语。

一、先确定任务模式

开始工作前先判断用户要的是哪一种交付。模式不同，允许执行的动作也不同。

• **只做 Review：**读取全文和必要证据，只报告问题；未经授权不要改文档。
• **直接改写：**完成结构分析后直接编辑用户指定的范围，并在写后重新读取验证。
• **逐条讨论：**一次只处理一处，固定给出“当前文本 → 问题 → 准备怎么改 → 修改后文本”，用户确认后再继续。
• **从零写作：**先建立读者问题、事实边界和章节骨架，再开始写正文；不要从某段代码直接扩写。

**用户要求“整篇重写”时，重新设计全文结构；用户只点名一节时，保留其余内容。**不要把整篇重写退化成同义词替换，也不要借局部修改顺手改动无关章节。

任务模式一旦确定，后文所有“修改、返工、写入和写后验证”要求只适用于直接改写、逐条讨论中已获确认的条目，以及从零写作。只做 Review 时始终保持只读：可以读取、核对证据、预览和报告问题，但禁止 update、insert、delete、overwrite 或替用户修正文档。

二、写作前先建立四张清单

动笔前先把材料整理成四张简短清单。它们不一定出现在成稿中，但必须在写作者脑中明确。

1. 读者问题清单

每章只围绕一个主要运行问题展开。问题要能被实现行为回答，不要只是模块名称。

• 好：模型什么时候会创建任务清单，清单保存在哪里？
• 好：上下文接近预算时，Harness 在下一次请求前做什么？
• 差：介绍任务清单工具。
• 差：深入理解 Context Management。

2. 事实清单

把材料按证据强度分开，写作时不要混用语气。

• **通用机制：**不依赖某个产品版本的设计原理。
• **教学实现：**为了说明机制而写的最小 Harness、示例阈值和辅助函数。
• **真实源码事实：**可以从指定文件、测试或提交直接确认的行为。
• **当前产品行为：**需要当前官方文档或当前版本源码支持的结论。
• **作者推断：**由现象或局部源码推得，必须降低表述强度并说明依据。

3. 状态清单

技术机制只要涉及状态，就必须回答下面五个问题：

1. **谁写入：**模型、Harness、用户、工具还是异步回调？
2. **何时写入：**任务开始、步骤切换、请求前、工具执行后还是异常恢复时？
3. **存在哪里：**当前函数变量、会话内存、消息历史、本地文件、数据库还是对象存储？
4. **能活多久：**是否能跨循环、跨 compact、跨会话、跨进程重启？
5. **怎样恢复：**下一轮通过什么引用、字段或加载逻辑重新拿到？恢复失败会怎样？

“已经保存”不是完整结论。必须同时说明保存位置、生命周期和读取路径。

4. 术语清单

记录第一次出现的产品名、对象、字段和函数。每个术语第一次出现时立刻解释，不要先使用三次，再在后文补定义。默认读者不知道参考项目，也不要用“和上一章一样”“参考项目里也是这样”承担解释责任。

三、先搭整体心智模型，再拆实现细节

如果一个机制包含三个以上连续步骤、三个以上角色，或者存在正常与异常两条路径，先给整体流程。读者先知道自己在地图上的位置，后面的函数和字段才有意义。

推荐的章节顺序

1. **具体问题：**用真实任务或故障说明为什么需要当前机制。
2. **触发入口：**由谁决定启动，满足什么条件时发生。
3. **整体流程图：**只画本章主线、关键判断和返回位置。
4. **图后拆解：**用三到五个并列要点说明每个阶段分别做什么。
5. **数据长相：**先给一份具体请求、状态或结果示例。
6. **核心实现：**按主流程顺序展示代码，不按仓库目录顺序贴文件。
7. **状态与副作用：**解释消息、内存、文件或数据库怎样变化。
8. **失败路径：**说明未知工具、参数错误、超限、重试、降级或中断。
9. **范围边界：**区分教学示例、源码快照和当前产品行为。
10. **结果验证：**直接展示运行后的关键状态或输出，不留下未执行的“试一下”。

这是一条依赖顺序，不是要求每章都写十个小节。简单机制可以合并；复杂机制也可以拆章。判断标准是读者是否在遇到细节前已经拥有理解该细节所需的信息。

段落之间必须有真实交接

• 上一段产生一个结果，下一段解释谁消费这个结果。
• 上一段提出一个限制，下一段引出为限制而存在的机制。
• 上一段定义一种数据，下一段展示代码怎样读取或修改它。
• 如果两段只是主题相近，却没有因果、时序或数据关系，就不要用“因此”“接下来”硬接。

删除纯报幕句，如“这一节先看”“接下来继续分析”“到这里完整链路已经形成”。标题已经承担导航作用，正文应直接提供信息。

四、机制解释必须回答的八个问题

写完一个机制后，逐项检查；任何一项缺失，都可能让读者只记住名词而不理解运行行为。

1. **为什么存在：**没有它时会出现什么具体问题？
2. **谁触发：**模型主动调用、Harness 自动判断、用户操作，还是外部事件？
3. **何时触发：**明确阶段、条件和不会触发的情况。
4. **输入长什么样：**给一份最小但真实的数据示例。
5. **内部怎样推进：**按时间顺序说清关键判断和调用。
6. **结果写到哪里：**消息历史、会话状态、文件或持久化存储？
7. **谁继续使用：**下一轮模型、下游工具、主 Agent 还是用户界面？
8. **失败后怎样处理：**报错、重试、回滚、降级、跳过还是保留现场？

先解释“谁决定”，再解释“怎么执行”

Agent 教程常把触发者写混。例如任务清单工具可能由模型决定何时调用，Harness 只暴露工具并保存结果；上下文压缩通常由 Harness 在请求前根据预算判断，不是模型每次主动请求；权限确认可能由 Harness 发起并等待用户决定。把这些行为都写成“系统会调用”会抹掉最重要的控制边界。

先给数据长相，再给抽象函数

读者第一次看到任务项、tool_use、消息历史或压缩摘要时，先展示一个具体对象。抽象代码只有在读者知道字段含义后才容易理解。

[
  {"content": "定位失败测试", "status": "completed"},
  {"content": "修改重试逻辑", "status": "in_progress"},
  {"content": "运行回归测试", "status": "pending"}
]

然后再解释：一次任务清单写入会提交完整数组，Handler 对整份快照做校验和保存；它不是只发送“把第二项改成完成”的增量命令。若真实实现不同，以证据为准。

五、代码讲解规则

**代码不是章节的开场白，也不是事实本身。**代码必须出现在读者已经知道它位于哪一步、由谁调用、输入输出是什么之后。

1. 先标明代码身份

• **可运行示例：**依赖、定义顺序、参数和辅助函数必须完整。
• **真实源码：**注明版本或提交，保留证明结论所需的上下游。
• **行为示意：**明确标为伪代码或简化实现，不要伪装成可直接运行的 API。

2. 每段代码前先交代六件事

1. 它位于整体流程的哪一步；
2. 谁会调用它；
3. 触发条件是什么；
4. 输入对象有哪些关键字段；
5. 返回值或副作用写到哪里；
6. 读者应该重点观察哪个判断、字段或调用。

3. 陌生抽象必须用具体调用展开

不要只写“通过 Handler Map 动态分发”。先给一份映射，再把一次请求展开：

TOOL_HANDLERS = {
    "read_file": run_read,
    "write_file": run_write,
}

# 模型请求：name="read_file", input={"path": "README.md", "limit": 20}
handler = TOOL_HANDLERS.get(block.name)

if handler is None:
    # 工具名不存在时也要返回 tool_result，模型才能看到失败原因并调整下一步
    output = f"Unknown tool: {block.name}"
else:
    # **block.input 把参数字典展开为：run_read(path="README.md", limit=20)
    output = handler(**block.input)

代码后再补充真正的新信息：这段兜底只处理未知工具名；参数校验、执行异常、权限拒绝和超时仍需要在调用边界单独处理。不要把代码注释逐句翻译成正文。

4. 注释解释“为什么”和“之后发生什么”

优先注释以下信息：

• 为什么此处重新读取状态，而不是沿用旧值；
• 某个判断会让循环继续、停止、重试还是降级；
• 锁、版本号、权限 Hook 或轮数上限在防止什么；
• 请求 ID、tool_use_id 或版本字段怎样把调用与结果对应起来；
• 当前调用产生了什么文件、消息或数据库副作用；
• 下一轮模型或下游模块怎样拿到该结果。

不要写“获取 Handler”“执行函数”这类只复述语法的注释；只有初学者确实无法理解某个语法时，才用一个具体等价调用解释一次。

5. 省略辅助函数时必须显式说明

主流程可以保留 normalize_todos()、render_todos() 等函数名而不展开实现，但代码前必须说明它们是本文省略的辅助函数，并各用一句话交代输入、输出和副作用。不要让读者猜它们来自标准库、SDK 还是作者自定义代码。

6. 代码展示顺序服从运行顺序

• 先展示 Tool Schema 或输入结构，再展示消费它的 Handler。
• 先展示主循环中的调用位置，再展开被调用函数。
• 先展示正常路径，再单独展示异常恢复，不要在开头把所有分支揉成一个大函数。
• 图、正文和代码必须使用同一顺序、同一名称和同一数量的阶段。

7. 结果要直接给出

如果文章展示“运行后会发生什么”，作者应实际执行或通过测试验证，并直接给出关键结果。不要保留 python example.py 之类未经执行、依赖本地目录结构的“试一下”。无法执行时，明确写这是预期输出，不要假装验证过。

六、图示不是装饰，而是阅读顺序的一部分

1. 什么时候必须先画整体图

• 流程有三个以上连续阶段；
• 涉及模型、Harness、工具、用户等三个以上角色；
• 正常路径之外还有恢复、重试或降级路径；
• 状态会在内存、消息、文件或数据库之间迁移；
• 下文将连续解释多个函数，读者需要先知道它们在主链路中的位置。

**整体流程图应放在详细步骤之前，而不是章节末尾用于总结。**先用一两段提出问题并界定范围，随后放图，再用三到五点解释图中的阶段。

2. 图型选择

• **流程图：**展示判断顺序、分支和返回主循环的位置。
• **时序图：**展示模型、Harness、工具和用户之间的请求与返回。
• **状态图：**展示 pending、in_progress、completed 等状态由谁改变。
• **数据边界图：**展示哪些内容留在会话内存，哪些写入消息、文件或持久化存储。
• **架构图：**用于读者已经理解主流程后，再说明模块分层和依赖边界。

3. 每张图写之前先回答三个问题

1. 读者看完图应该回答什么问题？
2. 图中每条箭头代表控制流、数据流还是反馈？
3. 正文和代码在哪里证明这条箭头确实存在？

节点优先写动作和状态变化，不要只堆模块名。图后解释最容易误读的边、状态和边界，不要把每个框重新念一遍。

4. 图文一致性检查

• 图画并行，代码是否真的并发调度？
• 图画持久化，代码是否只是写入会话内存？
• 图画摘要返回，文件副作用是否仍通过共享工作目录保留？
• 图写五个阶段，正文、表格和代码是否也都是五个？
• 图写 200KB，代码比较的究竟是字节、字符还是 token？

插入后必须查看实际渲染效果，检查字号、换行、箭头方向、颜色对比和移动端可读性。DSL 能编译不等于图已经能读。

七、事实、版本与度量单位

1. 不把实现快照写成产品契约

• 工具名称、默认开关、阈值、提醒条件和 Prompt 文本都可能随版本变化。
• 精确内部常量必须附版本、提交或日期；无法定位时删除数字，改写为机制级描述。
• 官方文档能证明公开行为，源码能证明某个版本的实现；二者的证据范围不同。
• 不要因为教学 Harness 没实现某能力，就断言真实产品不支持；也不要把产品当前行为倒推成教学代码已经具备。

2. 单位必须从代码语义出发

• len(text) 通常不是 KB，也不等于 token。
• 字符数、编码后的字节数和模型 token 数必须分别命名。
• 上下文预算使用 token 时，图、公式、正文和日志都保持 token 口径。
• 估算 token 与 API 返回的实际 usage 是两种数据，不能混为同一指标。

3. 强结论必须满足完整条件

• **“无损”：**原始内容仍存在、引用仍保留、权限可用、保留期未过且恢复路径实际可达。否则只能写“在这些条件下可恢复”。
• **“隔离”：**分别说明上下文隔离、进程隔离、文件系统隔离和权限隔离。独立消息历史不等于独立工作目录。
• **“并行”：**必须存在并发调度或重叠执行证据；多个任务依次循环仍是串行。
• **“幂等”：**说明幂等键、冲突处理、状态条件和重复请求返回结果。
• **“自动恢复”：**说明触发条件、重试边界、保留状态和最终失败出口。

八、分点与流程图讲解

技术内容不是越密越好。**一段话同时出现多个步骤、条件或结果时，先拆结构，再润色句子。**读者应该能快速看出内容是在讲执行顺序、并列条件，还是背景原因。

1. 先判断使用编号还是项目符号

1. **存在先后顺序：**使用 1. 2. 3.。适用于调用流程、状态变化、异常恢复和操作步骤。
2. **内容彼此并列：**使用项目符号。适用于触发条件、字段说明、约束、风险和检查项。
3. **需要解释因果：**保留短段落。背景、原因和结论不要为了排版强行拆成列表。

2. 长段落必须拆开

一段中出现三个以上动作、条件或对象时，优先改成“引导句 + 列表”。

• 引导句只说明下面这组内容的共同主题。
• 每一点只讲一个步骤或一个判断维度。
• 同一组列表保持相同句式和抽象层级。
• 单个列表项通常控制在一到两句话；仍然很长时，再拆成子项。
• 不要在一个项目中同时解释触发条件、内部实现、存储位置和失败处理。

如果一句话需要连续使用“然后、同时、如果、最后”才能讲完，通常已经应该拆成编号步骤。

3. 流程图后必须按顺序解释

流程图不能独自承担正文。图片后紧接编号说明，默认按下面四个问题展开：

1. **入口：**谁触发流程，输入是什么。
2. **主路径：**各阶段按什么顺序执行，每一步改变了什么数据或状态。
3. **分支：**在哪个条件下走向不同路径，失败后回到哪里。
4. **结果：**最终产物写到哪里，下一轮由谁继续使用。

如果图中已经标出步骤编号，图后的说明必须沿用同一编号、名称和顺序。不要把图里的框逐字念一遍；重点解释为什么进入下一步、状态发生了什么变化，以及哪条边最容易被误解。

4. 代码流程也使用同一套编号

一段代码包含多个阶段时，代码前先列出整体步骤；代码后再按相同编号解释关键实现。图、正文和代码中的步骤名称必须一致。

1. 代码前说明本段覆盖哪些步骤。
2. 代码注释标出关键状态变化和分支原因。
3. 代码后只解释会改变行为的实现，不重复注释。
4. 发现异常路径时单独分组，不要塞进正常流程的一段话里。

5. 分点之后仍要检查可读性

• 列表中的项目是否真正并列，还是混入了背景和结论？
• 编号是否表达真实先后关系，还是为了整齐强行编号？
• 是否出现一个项目远长于其他项目，需要继续拆分？
• 流程图后是否有编号解释，且与图中的顺序完全一致？
• 读者只扫标题、加粗内容和列表首句时，能否还原主流程？

九、写得像工程师，而不是像生成器

删除这些写法

• “一个 AI Agent 的全部秘密，就是一个 while 循环。”
• “第二行藏着一句要命的话。”
• “图上的两根箭头画得云淡风轻。”
• “三种机制回答的是同一个问题——Agent 的连续性。”
• “看似简单，背后却隐藏着复杂机制。”

这些句子有语气，没有新增事实，或者为了概括而把不同故障模式揉成一个抽象词。改成具体对象、动作和结果：模型返回什么，Harness 接下来检查什么，哪一步会修改磁盘或消息历史。

自然表达的判断标准

• **主语明确：**少用“它、这里、这一步”，写清是模型、Harness 还是 Handler。
• **动作具体：**少写“完成处理”“形成闭环”，说明校验、保存、重建或回填了什么。
• **转折有因果：**只有前后真的存在限制与应对关系时才用“但”“因此”。
• **不靠悬念：**直接说问题，不用反问和“真正关键的是”连续吊胃口。
• **不写作者旁白：**不要告诉读者“本文参考了哪一章”，除非来源本身是主题。
• **不重复免责声明：**教学实现与产品行为在首次出现和关键差异处说明即可。
• **朗读检查：**一句话在口语里显得做作、没有主语或需要读两遍，就重写。

十、重点、列表与排版

重点不是把术语全部加粗，而是帮助读者抓住后文持续依赖的判断。

• **加粗：**用于关键结论、触发条件、边界和第一次定义的核心术语。
• **黄色高亮：**用于如果漏读就会误解整章的结论；一章通常一到三处。
• **Callout：**用于风险、版本边界、关键提醒，不承载大段正文。
• **列表：**仅用于真正并列的步骤、条件、字段和检查项。
• **段落：**用于背景、因果、解释和过渡；不要把全文拆成“粗体短语：一句解释”。
• **表格：**用于多个对象的固定维度对比；两三个简单结论用列表更清楚。

写完后缩小页面快速扫一遍：如果满屏都是粗体，说明没有选择重点；如果连续多屏没有任何视觉锚点，说明读者很难复位。

十一、Reviewer：先审逻辑，再审表达

写完不等于完成。写作模式下，每节写完先做一次局部 Review，全文完成后再从标题开始做一次整体 Review；发现问题必须先改，再继续交付。只做 Review 时只记录问题和建议，不修改原文。

第一遍：内容与逻辑

• **读者门禁：**不知道参考项目的人能否理解本节？
• **问题门禁：**开头提出的问题，结尾是否真正回答？
• **顺序门禁：**是否先整体、后细节，先数据、后函数，先正常、后异常？
• **触发门禁：**是否说清谁决定、何时触发、什么情况下不触发？
• **状态门禁：**是否说清写入者、存储位置、生命周期和恢复方式？
• **代码门禁：**是否存在未定义变量、省略函数、伪造 API 或错误定义顺序？
• **事实门禁：**教学实现、源码快照、当前产品和推断是否分开？
• **单位门禁：**字符、字节、KB、token、轮次和时间单位是否一致？
• **图文门禁：**图、正文、表格和代码的顺序、名称、数量与分支是否一致？
• **边界门禁：**同步与并行、上下文与文件、摘要与可恢复是否被混写？

第二遍：表达与版式

• 是否还有口号、悬念、反问或作者旁白？
• 每段是否只有一个主要意思，主语是否明确？
• 是否在图前、图后、表格和总结里重复同一结论？
• 列表内容是否真正并列，还是把一段完整解释硬拆碎？
• 加粗和黄色高亮是否指向最重要的判断？
• 标题层级、编号、术语和代码变量是否前后一致？
• 用户后面提出的通用反馈是否已经同步应用到前文？

审稿问题按严重程度排序

1. **P0 事实错误：**会让读者形成错误实现或产品认知。
2. **P1 逻辑断裂：**流程顺序矛盾、关键触发或状态缺失、代码不可解释。
3. **P2 表达与版式：**重复、僵硬、重点不清、图文位置不佳。

Review 结果必须引用具体标题、原句、图或代码位置，并给出可执行的修改方向。不要只写“逻辑不够顺”“内容不够深入”。

十二、一个可复用的改写示例

原文：

这段循环说明了工具调用如何连续进行，但没有展开工具是如何执行的。模型返回的 tool_use 只是一段结构化调用请求，Harness 还需要完成工具匹配、参数解析、权限校验、实际执行和结果回传。

问题：

• 第一句在评论文章结构，而不是解释系统行为；
• “还需要完成”一次堆出五个动作，没有说明顺序；
• 读者仍不知道 tool_use 长什么样，也不知道结果回到哪里。

改写：

模型返回 tool_use 时，里面只有工具名、参数和本次调用的 ID。Harness 先用工具名找到对应的 Handler，再校验参数与权限；检查通过后，Handler 才会真正读取文件或执行命令。执行结果连同原来的调用 ID 被封装成 tool_result，写回消息历史，模型在下一轮据此决定继续调用工具还是结束任务。

改写没有增加口号，只补齐了对象、顺序、副作用和下一轮的消费关系。

十三、操作飞书文档

本 Skill 只负责教程的内容判断、结构设计和改写编排。输入是飞书文档 URL 或 token 时，**REQUIRED SUB-SKILL：使用 lark-doc 读取和编辑，并遵循 lark-shared 的认证与写入安全规则。**不要在本 Skill 内复制一套可能随 CLI 版本漂移的命令参数。

• 已有画板的查询和修改使用 lark-whiteboard。
• 评论、云盘文件和 Drive 权限使用 lark-drive。
• 文档中的 Sheet、Base 等资源先提取 token，再路由到 lark-sheets、lark-base 等对应 Skill。

执行飞书写入时遵守以下约束：

1. **按模式决定权限：**只做 Review 时只 fetch 和预览，禁止任何写命令。进入写作模式前确认用户授权的文档与范围。
2. **按范围完整读取：**局部修改读取目标章节的 full 内容；全文重写读取整篇。记录 revision_id、标题层级、代码块，以及 cite user/doc、图片、附件、画板、Sheet、Base、同步引用、资源 token 和 reference_map。
3. **保护并发修改：**写入必须携带刚读取的 revision_id。发生版本冲突时停止，重新 fetch 并基于新内容重算修改；禁止用最新版本 -1 静默覆盖。
4. **优先精确操作：**局部修改使用最小 block 范围。全文重写也先判断能否通过 block 操作保留资源；只要存在图片、评论或不可重建资源的丢失风险，就默认不用 overwrite。确需 overwrite 时，必须向用户明确列出会丢失的对象并取得针对该损失的确认，同时准备历史版本、备份或可验证的重建方案；缺少任一条件就停止写入。
5. **原样保留资源：**不在目标范围内的资源块不得改变；目标范围内仍需保留的标签、属性、token、引用和 reference_map 必须原样回放。删除旧图前确认它已不服务新结构。
6. **串行写同一文档：**每次写入后重新 fetch，使用返回的新 revision 和新 block ID 继续；禁止并行修改同一文档。
7. **写后验证身份而非只数数量：**核对标题、代码、样式、残留关键词、资源 token、引用对象和 revision；再查看图、代码、高亮与表格的实际渲染。

十四、常见失败与立即返工信号

• 第一屏只有宏大概括，没有具体问题、触发条件或对象。
• 整体流程图出现在所有详细函数之后。
• 读者先看到代码，几段后才知道输入数据长什么样。
• 正文说五步，图、表或代码只有四步。
• 同一概念在字符、KB 和 token 之间切换。
• 用“无损、隔离、并行、幂等、自动恢复”却没有条件和证据。
• 代码调用了未解释的辅助函数，或者示例无法独立运行却未标注。
• 图中箭头没有语义，图后只是逐框复述。
• 整页没有重点，或每句话都被加粗、高亮。
• 正文不断说“本文将、这一节、前文、参考项目”，却很少说系统实际做了什么。
• 用户指出一种通用问题后，只改被点名的一句，其他章节仍保留同类问题。
• 写入命令成功后没有重新读取和检查渲染结果。

十五、完成定义

写作或改写模式只有同时满足下面这些条件，任务才算完成：

• 新读者不依赖参考仓库或上一轮对话，也能理解文章；
• 每章先建立问题和整体流程，再出现局部实现；
• 触发者、触发条件、输入、输出、状态位置和失败路径已经交代；
• 代码身份明确、定义顺序成立、注释解释运行语义，并有直接验证结果；
• 每张图回答一个问题，位置正确，且与正文和代码一致；
• 教学实现、源码事实、当前产品行为和推断没有混写；
• 单位、术语、阶段数量和执行顺序全文一致；
• 重点通过克制的加粗与高亮可快速扫描；
• 全文没有明显口号、写作旁白、僵硬转折和重复结论；
• 局部 Review、全文 Review 和写后重新读取均已完成，发现的问题已经实际修正。

只做 Review 的完成条件不同：目标范围和必要证据已经读取；P0/P1/P2 问题均引用具体位置并给出可执行建议；没有执行任何写操作；不把“尚未修正”误报为任务失败。