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 個問題的答案偏向後者，那大機率不該改。

一句話記住

好的章節順序，不是把所有機制排成一列，而是讓每一章都像前一章自然長出來的下一層。