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. **结果验证：**直接展示运行后的关键状态或输出，不留下未执行的“试一下”。

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