Why This Chapter Order

这份文档不讲某一个机制本身。
它专门回答一个更基础的问题：

为什么这套仓库要按现在这个顺序教，而不是按源码目录顺序、功能热闹程度，或者“哪里复杂先讲哪里”。

先说结论

当前这套 s01 -> s19 的主线顺序，整体上是合理的。

它最大的优点不是“覆盖面广”，而是：

• 先建立最小闭环
• 再补横切控制面
• 再补持久化工作层
• 最后才扩成多 agent 平台和外部能力总线

这个顺序适合教学，因为它遵守的不是“源码文件先后”，而是：

机制依赖顺序。

也就是：

• 后一章需要建立在前一章已经清楚的心智之上
• 同一层的新概念尽量一起讲完
• 不把高阶平台能力提前压给还没建立主闭环的读者

如果要把这套课程改到更接近满分，一个很重要的标准不是“加更多内容”，而是：

让读者始终知道这一章为什么现在学，而不是上一章或下一章。

这份文档就是干这件事的。

这份顺序到底按什么排

不是按这些排：

• 不是按逆向源码里文件顺序排
• 不是按实现难度排
• 不是按功能看起来酷不酷排
• 不是按产品里出现得早不早排

它真正按的是四条依赖线：

1. 主闭环依赖
2. 控制面依赖
3. 工作状态依赖
4. 平台边界依赖

你可以先把整套课粗暴地看成下面这条线：

先让 agent 能跑
  -> 再让它不乱跑
  -> 再让它能长期跑
  -> 最后让它能分工跑、隔离跑、接外部能力跑

这才是当前章节顺序最核心的逻辑。

一张总图：章节之间真正的依赖关系

s00 总览与地图
  |
  v
s01 主循环
  ->
s02 工具执行
  ->
s03 会话计划
  ->
s04 子任务隔离
  ->
s05 按需知识注入
  ->
s06 上下文压缩

s06 之后，单 agent 主骨架成立
  |
  v
s07 权限闸门
  ->
s08 生命周期 Hook
  ->
s09 跨会话记忆
  ->
s10 Prompt / 输入装配
  ->
s11 恢复与续行

s11 之后，单 agent 的高完成度控制面成立
  |
  v
s12 持久任务图
  ->
s13 运行时后台槽位
  ->
s14 时间触发器

s14 之后，工作系统从“聊天过程”升级成“可持续运行时”
  |
  v
s15 持久队友
  ->
s16 协议化协作
  ->
s17 自治认领
  ->
s18 worktree 执行车道
  ->
s19 外部能力总线

如果你记不住所有章节，只记住每段结束后的“系统里多了什么”：

• s06 结束：你有了能工作的单 agent
• s11 结束：你有了更稳、更可控的单 agent
• s14 结束：你有了能长期推进工作的运行时
• s19 结束：你有了接近完整的平台边界

为什么 s01-s06 必须先成一整段

s01 必须最先

因为它定义的是：

• 这套系统的最小入口
• 每一轮到底怎么推进
• 工具结果为什么能再次进入模型

如果连这一条都没建立，后面所有内容都会变成“往空气里挂功能”。

s02 必须紧跟 s01

因为没有工具，agent 只是会说，不是真的会做。

开发者第一次真正感受到“harness 在做什么”，往往就是在 s02：

• 模型产出 tool_use
• 系统找到 handler
• 执行工具
• 回写 tool_result

这是整个仓库第一条真正的“行动回路”。

s03 放在 s04 前面是对的

很多人会直觉上想先讲 subagent，因为它更“高级”。

但教学上不该这样排。

原因很简单：

• s03 先解决“当前 agent 自己怎么不乱撞”
• s04 再解决“哪些工作要交给别的执行者”

如果主 agent 连本地计划都没有，就提前进入子 agent，读者只会觉得：

• 为什么要委派
• 委派和待办到底是什么关系
• 哪些是主流程，哪些是探索性流程

都不清楚。

所以：

先有本地计划，再有上下文隔离委派。

s05 放在 s06 前面是对的

这两个章节很多人会低估。

实际上它们解决的是同一类问题的前后两半：

• s05 解决：知识不要一开始全塞进来
• s06 解决：已经塞进来的上下文怎么控制体积

如果先讲压缩，再讲技能加载，读者容易误会成：

• 上下文膨胀主要靠“事后压缩”解决

但更合理的心智应该是：

1. 先减少不必要进入上下文的东西
2. 再处理已经进入上下文、且必须继续保留的东西

所以 s05 -> s06 的顺序很合理。

为什么 s07-s11 应该成一整段“控制面加固”

这五章看起来分散，实际上它们共同在回答同一个问题：

主循环已经能跑了，但要怎样才能跑得稳、跑得可控、跑得更像一个完整系统。

s07 权限必须早于 s08 Hook

因为权限是在问：

• 这件事能不能做
• 这件事做到哪一步要停
• 这件事要不要先问用户

Hook 是在问：

• 系统这个时刻要不要额外做点什么

如果先讲 Hook，再讲权限，读者很容易误会：

• 安全判断也只是某个 hook

但实际上不是。

更清楚的教学顺序应该是：

1. 先建立“执行前必须先过闸门”的概念
2. 再建立“主循环周围可以挂扩展点”的概念

也就是：

先 gate，再 extend。

s09 记忆放在 s10 Prompt 前面是对的

这是整套课程里很关键的一条顺序。

很多人容易反过来讲，先讲 prompt，再讲 memory。

但对开发者心智更友好的顺序其实是现在这样：

• s09 先讲“长期信息从哪里来、哪些值得留下”
• s10 再讲“这些来源最终怎样被组装进模型输入”

也就是说：

• memory 先回答“内容源是什么”
• prompt pipeline 再回答“这些内容源怎么装配”

如果反过来，读者会在 s10 里不断追问：

• 为什么这里会有 memory block
• 这块内容到底是谁准备的
• 它和 messages、CLAUDE.md、skills 的边界在哪里

所以这一条顺序不要乱换。

s11 放在这一段结尾很合理

因为恢复与续行不是单独一层业务功能，而是：

• 对前面所有输入、执行、状态、权限、压缩分支的总回收

它天然适合做“控制面阶段的收口章”。

只有当读者已经知道：

• 一轮输入怎么组装
• 执行时会走哪些分支
• 发生什么状态变化

他才真正看得懂恢复系统在恢复什么。

为什么 s12-s14 必须先讲“任务图”，再讲“后台运行”，最后讲“定时触发”

这是后半程最容易排错的一段。

s12 必须先于 s13

因为 s12 解决的是：

• 事情本身是什么
• 依赖关系是什么
• 哪个工作节点已完成、未完成、阻塞中

而 s13 解决的是：

• 某个执行单元现在是不是正在后台跑
• 跑到什么状态
• 结果怎么回流

也就是：

• task 是工作目标
• runtime task 是执行槽位

如果没有 s12 先铺开 durable work graph，读者到了 s13 会把后台任务误当成任务系统本体。

这会直接导致后面：

• cron 概念混乱
• teammate 认领概念混乱
• worktree lane 概念混乱

所以这里一定要守住：

先有目标，再有执行体。

s14 必须紧跟 s13

因为 cron 本质上不是又一种任务。

它只是回答：

如果现在不是用户当场触发，而是由时间触发一次执行，该怎么接到现有运行时里。

也就是说：

• 没有 runtime slot，cron 没地方发车
• 没有 task graph，cron 不知道在触发什么工作

所以最合理顺序一定是：

task graph -> runtime slot -> schedule trigger

为什么 s15-s19 要按“队友 -> 协议 -> 自治 -> 隔离车道 -> 外部能力”排

这一段如果顺序乱了，读者最容易开始觉得：

• 队友、协议、任务、worktree、MCP 全都像“高级功能堆叠”

但其实它们之间有很强的前后依赖。

s15 先定义“谁在系统里长期存在”

这一章先把对象立起来：

• 队友是谁
• 他们有没有身份
• 他们是不是可以持续存在

如果连 actor 都还没清楚，协议对象就无从谈起。

s16 再定义“这些 actor 之间按什么规则说话”

协议层不应该早于 actor 层。

因为协议不是凭空存在的。

它一定是服务于：

• 请求谁
• 谁审批
• 谁响应
• 如何回执

所以：

先有队友，再有协议。

s17 再进入“队友自己找活”

自治不是“又多一种 agent 功能”。

自治其实是建立在前两章之上的：

• 前提 1：队友是长期存在的
• 前提 2：队友之间有可追踪的协作规则

只有这两个前提都建立了，自治认领才不会讲成一团雾。

s18 为什么在 s19 前面

因为在平台层里，worktree 是执行隔离边界，MCP 是能力边界。

对开发者自己手搓系统来说，更应先搞清：

• 多个执行者如何不互相踩目录
• 一个任务与一个执行车道如何绑定

这些是“本地多执行者平台”先要解决的问题。

把这个问题讲完后，再去讲：

• 外部 server
• 外部 tool
• capability route

开发者才不会把“MCP 很强”误解成“本地平台边界可以先不管”。

s19 放最后是对的

因为它本质上是平台边界的最外层。

它关心的是：

• 本地系统之外的能力如何并入
• 外部 server 和本地 tool 如何统一纳入 capability bus

这个东西只有在前面这些边界都已经清楚后，读者才真的能吸收：

• 本地 actor
• 本地 work lane
• 本地 task / runtime state
• 外部 capability provider

分别是什么。

五种最容易让课程变差的“错误重排”

错误 1：把 s04 提到 s03 前面

坏处：

• 读者先学会“把活丢出去”
• 却还没学会“本地怎么规划”

最后 subagent 只会变成“遇事就开新 agent”的逃避按钮。

错误 2：把 s10 提到 s09 前面

坏处：

• 输入装配先讲了
• 但输入源的边界还没立住

结果 prompt pipeline 会看起来像一堆神秘字符串拼接。

错误 3：把 s13 提到 s12 前面

坏处：

• 读者会把后台执行槽位误认成工作任务本体
• 后面 cron、自治认领、worktree 都会越来越混

错误 4：把 s17 提到 s15 或 s16 前面

坏处：

• 还没定义持久队友
• 也还没定义结构化协作规则
• 就先讲自治认领

最后“自治”会被理解成模糊的自动轮询魔法。

错误 5：把 s19 提到 s18 前面

坏处：

• 读者会先被外部能力系统吸引注意力
• 却还没真正看清本地多执行者平台怎么稳定成立

这会让整个课程后半程“看起来很大”，但“落到自己实现时没有抓手”。

如果你自己手搓，可以在哪些地方先停

这套课不是说一定要一次把 s01-s19 全做完。

更稳的实现节奏是：

里程碑 A：先做到 s06

你已经有：

• 主循环
• 工具
• 计划
• 子任务隔离
• 技能按需注入
• 上下文压缩

这已经足够做出一个“能用的单 agent 原型”。

里程碑 B：再做到 s11

你多了：

• 权限
• Hook
• Memory
• Prompt pipeline
• 错误恢复

到这里，单 agent 系统已经接近“高完成度教学实现”。

里程碑 C：做到 s14

你多了：

• durable task
• background runtime slot
• cron trigger

到这里，系统开始脱离“只会跟着当前会话走”的状态。

里程碑 D：做到 s19

这时再进入：

• persistent teammate
• protocol
• autonomy
• worktree lane
• MCP / plugin

这时你手里才是接近完整的平台结构。

维护者在重排章节前该问自己什么

如果你准备改顺序，先问下面这些问题：

1. 这一章依赖的前置概念，前面有没有已经讲清？
2. 这次重排会不会让两个同名但不同层的概念更容易混？
3. 这一章新增的是“目标状态”“运行状态”“执行者”还是“外部能力”？
4. 如果把它提前，读者会不会只记住名词，反而抓不到最小实现？
5. 这次重排是在服务开发者实现路径，还是只是在模仿某个源码目录顺序？
6. 读者按当前章节学完以后，本地代码到底该按什么顺序打开，这条代码阅读顺序有没有一起讲清？

如果第 5 个问题的答案偏向后者，那大概率不该改。

一句话记住

好的章节顺序，不是把所有机制排成一列，而是让每一章都像前一章自然长出来的下一层。