從零到懂 Agentflow

為什麼需要 Agentflow?

AI 幫你寫程式時,會出錯,也可能唬爛 —— 明明有 bug,卻跟你說「做好了」。而且 session 一斷,脈絡就全丟。

Agentflow 要同時解決兩件事:(1) 讓工作可復原(斷了能接回);(2) 讓「做完」這件事不能靠模型自己說了算。

核心信條:說了不算,要有證據

整套系統就一句話:「一個宣稱,只有在指令輸出或檔案內容證實後,才成為事實。」

模型不能打字說「我審過了、我測過了」就過關。要有證據,證據要是真的能被指令驗出來的東西。

一輪工作長什麼樣

從你打 godev 開始,到裁判放行,是一個「回合」:

首次使用：godev → agf init(建 notebook/ag.json/裝 hook)
已有專案：godev → 讀取既有設定與 notebook（不重跑 init）
      → resume-intake(有界快照)
      → 選路線做事(direct / advisors / full pipeline)
      → 寫 Reply 收尾
      → ⚖ Stop-hook 裁判 → exit 2 擋下(修正一次) / exit 0 不阻擋（不等於驗收完成）

三個保命設計:Fail-open(裁判自己壞掉就放行,不弄死你的 session)、Loop guard(一次修正不會變無限迴圈)、最多擋一次。

兩個判斷,都由「同一個零 AI 裁判」做

一輪裡有兩個是非題,而且都在宿主端裁判做,不是外部 AI:

• 審查判定(review_decision())—— 這輪「要不要審?」看 git 改了什麼。
• 裁判閘門(lint_cross_check())—— 審查報告「過不過?」核對 commit。

外部 AI 負責實質審查，給出 PASS 或 BLOCKING。確定性檢查核對報告格式、必要 verdict 與 commit；coordinator 再獨立驗證證據並決定接受。三者責任不同，機械檢查不能代替實質判斷。

派審流水線:兩個小工人

「別人」= 另一個 AI 模型,不是人。 為什麼要換一個?自己審自己會偏心。而且那個房間是影印本 —— 老師不能偷改你的真作品、減少誤操作原 repo 的機會。

child_process.spawn("codex", ["exec", "<審查指令>"], { cwd: 隔離clone })
//                    ↑ 另一個 AI       ↑ 要它做的事      ↑ 在影印本裡跑

回傳裡有一句很誠實的話:accepted: false —— 「程序跑完 ≠ 通過」。要不要接受,由 coordinator 判斷。

拱心石:commit 核對(最容易卡的一課)

裁判要求:報告的 Reviewed commit 必須位元組相等於本輪的 implementation commit。

出貨 = A · 報告認證 = A   →  PASS ✅
出貨 = B · 報告認證 = A   →  FAIL ❌  (審完又改一行 → 新 commit → 沒人審過)

跟 GitHub「push 新 commit 就作廢舊 approval」同一個道理。目的:保證「被審的」就是「出貨的」。

什麼時候觸發?我要自己設定嗎?

觸發時機:只有你「收尾一輪、而且真的改了程式(source/test/config/文件)」時,這條審查鏈才啟動。純聊天且沒有實作變更，或僅符合豁免條件的內部記錄更新，可能不需要最終審查。修改使用者文件仍屬審查範圍，小型純文件修改通常採 narrow。

要自己設定嗎?幾乎不用。

• 審多深 → 自動算的(看 diff),你不用打字選。
• 想推翻時才出手:stronger(嚴一點)或 skip-review: 理由(授權跳過)。
• 用哪個等級的模型 → 在 ag.json 設一次就好(審核=better、實作=basic、安全=best)。