Teaching Scope
When This Page Helps
What this repo teaches, what it deliberately leaves out, and why.
Best Read Alongside
這份文件不是講某一章，而是說明整個教學倉庫到底要教什麼、不教什麼，以及每一章應該怎麼寫才不會把讀者帶偏。
這份倉庫的目標
這不是一份“逐行對照某份原始碼”的註釋倉庫。
這份倉庫真正的目標是：
教開發者從 0 到 1 手搓一個結構完整、高保真的 coding agent harness。
這裡強調 3 件事：
- 讀者真的能自己實現出來。
- 讀者能抓住系統主脈絡，而不是淹沒在邊角細節裡。
- 讀者對關鍵機制的理解足夠高保真，不會學到不存在的機制。
什麼必須講清楚
主線章節必須優先講清下面這些內容：
- 整個系統有哪些核心模組
- 模組之間如何協作
- 每個模組解決什麼問題
- 關鍵狀態儲存在哪裡
- 關鍵資料結構長什麼樣
- 主迴圈如何把這些機制接進來
如果一個章節講完以後，讀者還不知道“這個機制到底放在系統哪一層、儲存了哪些狀態、什麼時候被呼叫”，那這章就還沒講透。
什麼不要佔主線篇幅
下面這些內容，不是完全不能提，而是不應該佔用主線正文的大量篇幅：
- 打包、編譯、釋出流程
- 跨平臺相容膠水
- 遙測、企業策略、賬號體系
- 與教學主線無關的歷史相容分支
- 只對特定產品環境有意義的接線細節
- 某份上游原始碼裡的函式名、檔名、行號級對照
這些內容最多作為：
- 維護者備註
- 附錄
- 橋接資料裡的平臺擴充套件說明
而不應該成為初學者第一次學習時的主線。
真正的“高保真”是什麼意思
教學倉庫追求的高保真，不是所有邊角細節都 1:1。
這裡的高保真，是指這些東西要儘量貼近真實系統主幹：
- 核心執行模式
- 主要模組邊界
- 關鍵資料結構
- 模組之間的協作方式
- 關鍵狀態轉換
換句話說：
主幹儘量高保真，外圍細節可以做教學取捨。
面向誰來寫
本倉庫預設讀者不是“已經做過複雜 agent 平臺的人”。
更合理的預設讀者應該是：
- 會一點程式設計
- 能讀懂基本 Python
- 但沒有系統實現過 agent
所以寫作時要假設：
- 很多術語是第一次見
- 很多系統設計名詞不能直接甩出來不解釋
- 同一個概念不能分散在五個地方才拼得完整
每一章的推薦結構
主線章節儘量遵守這條順序：
這一章要解決什麼問題先解釋幾個名詞最小心智模型關鍵資料結構最小實現如何接到主迴圈裡初學者最容易犯的錯教學邊界
這條順序的價值在於：
- 先讓讀者知道為什麼需要這個機制
- 再讓讀者知道這個機制到底是什麼
- 然後馬上看到它怎麼落地
這裡把最後一節寫成 教學邊界，而不是“繼續補一大串外圍複雜度清單”，是因為教學倉庫更應該先幫讀者守住：
- 這一章先學到哪裡就夠了
- 哪些複雜度現在不要一起拖進來
- 讀者真正該自己手搓出來的最小正確版本是什麼
術語使用規則
只要出現這些型別的詞，就應該解釋：
- 軟體設計模式
- 資料結構名詞
- 併發與程序相關名詞
- 協議與網路相關名詞
- 初學者不熟悉的工程術語
例如：
- 狀態機
- 排程器
- 佇列
- worktree
- DAG
- 協議 envelope
不要只給名字，不給解釋。
“最小正確版本”原則
很多真實機制都很複雜。
但教學版不應該一開始就把所有分支一起講。
更好的順序是：
- 先給出一個最小但正確的版本
- 解釋它已經解決了哪部分核心問題
- 再講如果繼續迭代應該補什麼
例如：
- 許可權系統先做
deny -> mode -> allow -> ask - 錯誤恢復先做 3 條主恢復路徑
- 任務系統先做任務記錄、依賴、解鎖
- 團隊協議先做 request/response + request_id
文件和程式碼要一起維護，而不是各講各的
如果正文和本地 agents/*.py 沒有對齊，讀者一開啟程式碼就會重新混亂。
所以維護者重寫章節時，應該同步檢查三件事：
- 這章正文裡的關鍵狀態，程式碼裡是否真有對應結構
- 這章正文裡的主迴路，程式碼裡是否真有對應入口函式
- 這章正文裡強調的“教學邊界”，程式碼裡是否也沒有提前塞進過多外層複雜度
最穩的做法是讓每章都能對應到：
- 1 個主檔案
- 1 組關鍵狀態結構
- 1 條最值得先看的執行路徑
如果維護者需要一份“按章節讀本倉庫程式碼”的地圖，建議配合看：
維護者重寫時的檢查清單
如果你在重寫某一章，可以用下面這份清單自檢：
- 這章第一屏有沒有明確說明“為什麼需要它”
- 是否先解釋了新名詞，再使用新名詞
- 是否給出了最小心智模型圖或流程
- 是否明確列出關鍵資料結構
- 是否說明了它如何接進主迴圈
- 是否區分了“核心機制”和“產品化外圍細節”
- 是否列出了初學者最容易混淆的點
- 是否避免製造原始碼裡並不存在的幻覺機制
維護者如何使用“逆向原始碼”
逆向得到的原始碼，在這套倉庫裡應當只扮演一個角色：
維護者的校準參考。
它的用途是：
- 校驗主幹機制有沒有講錯
- 校驗關鍵狀態和模組邊界有沒有遺漏
- 校驗教學實現有沒有偏離到錯誤方向
它不應該成為讀者理解正文的前提。
正文應該做到：
即使讀者完全不看那份原始碼，也能把核心系統自己做出來。
這份教學倉庫應該追求什麼分數
如果滿分是 150 分，一個接近滿分的教學倉庫應同時做到：
- 主線清楚
- 章節順序合理
- 新名詞解釋完整
- 資料結構清晰
- 機制邊界準確
- 例子可執行
- 升級路徑自然
真正決定分數高低的，不是“提到了多少細節”，而是：
提到的關鍵細節是否真的講透，沒提的非關鍵細節是否真的可以安全省略。