Teaching Scope

这份文档不是讲某一章，而是说明整个教学仓库到底要教什么、不教什么，以及每一章应该怎么写才不会把读者带偏。

这份仓库的目标

这不是一份“逐行对照某份源码”的注释仓库。

这份仓库真正的目标是：

教开发者从 0 到 1 手搓一个结构完整、高保真的 coding agent harness。

这里强调 3 件事：

1. 读者真的能自己实现出来。
2. 读者能抓住系统主脉络，而不是淹没在边角细节里。
3. 读者对关键机制的理解足够高保真，不会学到不存在的机制。

什么必须讲清楚

主线章节必须优先讲清下面这些内容：

• 整个系统有哪些核心模块
• 模块之间如何协作
• 每个模块解决什么问题
• 关键状态保存在哪里
• 关键数据结构长什么样
• 主循环如何把这些机制接进来

如果一个章节讲完以后，读者还不知道“这个机制到底放在系统哪一层、保存了哪些状态、什么时候被调用”，那这章就还没讲透。

什么不要占主线篇幅

下面这些内容，不是完全不能提，而是不应该占用主线正文的大量篇幅：

• 打包、编译、发布流程
• 跨平台兼容胶水
• 遥测、企业策略、账号体系
• 与教学主线无关的历史兼容分支
• 只对特定产品环境有意义的接线细节
• 某份上游源码里的函数名、文件名、行号级对照

这些内容最多作为：

• 维护者备注
• 附录
• 桥接资料里的平台扩展说明

而不应该成为初学者第一次学习时的主线。

真正的“高保真”是什么意思

教学仓库追求的高保真，不是所有边角细节都 1:1。

这里的高保真，是指这些东西要尽量贴近真实系统主干：

• 核心运行模式
• 主要模块边界
• 关键数据结构
• 模块之间的协作方式
• 关键状态转换

换句话说：

主干尽量高保真，外围细节可以做教学取舍。

面向谁来写

本仓库默认读者不是“已经做过复杂 agent 平台的人”。

更合理的默认读者应该是：

• 会一点编程
• 能读懂基本 Python
• 但没有系统实现过 agent

所以写作时要假设：

• 很多术语是第一次见
• 很多系统设计名词不能直接甩出来不解释
• 同一个概念不能分散在五个地方才拼得完整

每一章的推荐结构

主线章节尽量遵守这条顺序：

1. 这一章要解决什么问题
2. 先解释几个名词
3. 最小心智模型
4. 关键数据结构
5. 最小实现
6. 如何接到主循环里
7. 初学者最容易犯的错
8. 教学边界

这条顺序的价值在于：

• 先让读者知道为什么需要这个机制
• 再让读者知道这个机制到底是什么
• 然后马上看到它怎么落地

这里把最后一节写成 教学边界，而不是“继续补一大串外围复杂度清单”，是因为教学仓库更应该先帮读者守住：

• 这一章先学到哪里就够了
• 哪些复杂度现在不要一起拖进来
• 读者真正该自己手搓出来的最小正确版本是什么

术语使用规则

只要出现这些类型的词，就应该解释：

• 软件设计模式
• 数据结构名词
• 并发与进程相关名词
• 协议与网络相关名词
• 初学者不熟悉的工程术语

例如：

• 状态机
• 调度器
• 队列
• worktree
• DAG
• 协议 envelope

不要只给名字，不给解释。

“最小正确版本”原则

很多真实机制都很复杂。

但教学版不应该一开始就把所有分支一起讲。

更好的顺序是：

1. 先给出一个最小但正确的版本
2. 解释它已经解决了哪部分核心问题
3. 再讲如果继续迭代应该补什么

例如：

• 权限系统先做 deny -> mode -> allow -> ask
• 错误恢复先做 3 条主恢复路径
• 任务系统先做任务记录、依赖、解锁
• 团队协议先做 request/response + request_id

文档和代码要一起维护，而不是各讲各的

如果正文和本地 agents/*.py 没有对齐，读者一打开代码就会重新混乱。

所以维护者重写章节时，应该同步检查三件事：

1. 这章正文里的关键状态，代码里是否真有对应结构
2. 这章正文里的主回路，代码里是否真有对应入口函数
3. 这章正文里强调的“教学边界”，代码里是否也没有提前塞进过多外层复杂度

最稳的做法是让每章都能对应到：

• 1 个主文件
• 1 组关键状态结构
• 1 条最值得先看的执行路径

如果维护者需要一份“按章节读本仓库代码”的地图，建议配合看：

• s00f-code-reading-order.md

维护者重写时的检查清单

如果你在重写某一章，可以用下面这份清单自检：

• 这章第一屏有没有明确说明“为什么需要它”
• 是否先解释了新名词，再使用新名词
• 是否给出了最小心智模型图或流程
• 是否明确列出关键数据结构
• 是否说明了它如何接进主循环
• 是否区分了“核心机制”和“产品化外围细节”
• 是否列出了初学者最容易混淆的点
• 是否避免制造源码里并不存在的幻觉机制

维护者如何使用“逆向源码”

逆向得到的源码，在这套仓库里应当只扮演一个角色：

维护者的校准参考。

它的用途是：

• 校验主干机制有没有讲错
• 校验关键状态和模块边界有没有遗漏
• 校验教学实现有没有偏离到错误方向

它不应该成为读者理解正文的前提。

正文应该做到：

即使读者完全不看那份源码，也能把核心系统自己做出来。

这份教学仓库应该追求什么分数

如果满分是 150 分，一个接近满分的教学仓库应同时做到：

• 主线清楚
• 章节顺序合理
• 新名词解释完整
• 数据结构清晰
• 机制边界准确
• 例子可运行
• 升级路径自然

真正决定分数高低的，不是“提到了多少细节”，而是：

提到的关键细节是否真的讲透，没提的非关键细节是否真的可以安全省略。