長任務 Agent 程式開發的耐久控制面

#1 缺口何處失效

問題

Chat 不適合當長任務的控制面

一旦工作跨越多個工作階段、review 回合與可恢復狀態，一般 chat 就不再足夠。真正的缺口主要不在模型能力，而在於缺少耐久的控制面。

人類實務

Chat-native 失效模式

有里程碑的書面計畫

範圍漂移；「完成」被宣稱卻沒有證據。

每個邏輯單元一組變更

多個議題混在一次無差別的編輯爆發裡。

合併前的 code review

寫程式與判斷正確性的是同一個 agent。

CI / 測試關卡

驗證是可選的、被摘要的，或被幻覺出來的。

中斷後恢復

Context 壓縮後任務對齊感消失。

誰可以改什麼

規劃者、實作者、審查者坍縮成同一個工作階段。

設計問題： 最小需要什麼樣的控制面，才能讓本地 coding agent 保持可恢復、可審查、可治理——不需要雲端編排器、不禁止一般 chat 的直接編輯，也不把自由文字當成真相來源？

#2 規則設計原則

設計不變量

這個控制面必須守住什麼

如果長任務 agent 工作要能在中斷之後依然可恢復、可審查、而且邊界清楚，下面這些不變量就必須被保留下來。

01

耐久、外部的 canonical state

Workflow state 必須在對話緩衝區之外，放在貼近 repo、機器可讀的檔案裡，覆蓋過期的 chat 摘要。

02

以 slice 為單位執行

工作應拆成有邊界的 slices：acceptance criteria、宣告的修改面、驗證命令，以及一 commit 紀律。

03

在程式裡強制的角色分離

角色邊界必須在程式裡被強制。只有 implementer 能改產品程式；reviewer 與 auditor 唯讀。

04

結構化 emit 契約

角色應透過版本化 schema 結束，而不是靠帶權責的自由 markdown。文字可以解釋，但不能授權狀態轉移。

05

Fail-closed 驗證

模糊的啟動意圖、格式錯誤的報告與缺失的證據，都應阻擋進度。系統寧可卡住，也不默默降級。

06

顯式 opt-in

Workflow mode 應保持可選。一般 chat 仍適合快速修改、問答，以及不需要 canonical state 的工作。

#3 拓撲架構

扁平、由 driver 主導

一個 driver、一次一個角色

主 agent 工作階段作為 workflow 根節點，每次最多 dispatch 一個專門角色。角色之間不能再巢狀 dispatch。沒有應用伺服器或雲端依賴：一切都在本地、以 repo 為範圍。

Bootstrapper Setup

建立或修復控制面狀態

首次建立 `.agent/` scaffolding，或在 canonical 檔案缺失、損壞時修復。

Regrounder Reconcile

Canonical 對齊與 slice 選擇

依 repo 真實狀態重新對齊 plan 與 active slice；處理 dirty worktree、roadmap 漂移與 stop-wave 對齊。

Implementer Execute

產品修改與 slice commit

唯一可以改產品程式並建立 slice commit 的角色。落地前執行驗證。

Reviewer Evaluate

Per-slice 結構化 review

唯讀結構化 review：契約覆蓋、正確性風險、驗證證據、文件與狀態一致性。

Auditor Evaluate

專案層級 audit

唯讀評估 slice 是否符合更廣的任務與 backlog 完整性。

Stop-judge Close

最終 stop / no-stop 判斷

獨立的唯讀判斷：工作是否可以停止。預設策略可能要求多個 judge 在當前 HEAD 上一致同意。

角色 dispatch 路由

flowchart TB Driver["Workflow driver\n(main session)"] subgraph setup ["Setup 與對齊"] Bootstrapper["Bootstrapper\nscaffolding / repair"] Regrounder["Regrounder\nplan、slice 選擇、對齊"] end subgraph execute ["實作"] Implementer["Implementer\n產品修改 + slice commit"] end subgraph evaluate ["唯讀評估"] Reviewer["Reviewer\nper-slice rubric review"] Auditor["Auditor\n專案層級 audit"] StopJudge["Stop-judge\n最終 stop / no-stop xN"] end Driver -->|"缺少 scaffolding"| Bootstrapper Driver -->|"狀態過期 / 未選 slice / review 後對齊"| Regrounder Bootstrapper --> Regrounder Regrounder -->|"已選 slice、尚未 commit"| Implementer Implementer -->|"slice 已 commit"| Reviewer Reviewer --> Auditor Auditor --> Regrounder Regrounder -->|"所有 slice 完成"| StopJudge StopJudge -->|"一致同意後"| Regrounder Regrounder --> Driver

Dispatch

強制 dispatch 順序

缺少 scaffolding → bootstrapper
狀態過期或模糊 → regrounder
未選 slice → regrounder
已選 slice、尚未 commit → implementer
已 commit、尚未 review → reviewer
尚未 audit → auditor
review 後對齊 → regrounder
所有 slice 完成 → stop-judge（×N）
stop 判斷後 → stop verifier + 最終 regrounder 對齊

#4 層 Canonical State

Repo-local 檔案系統控制面

貼近 git worktree 的耐久狀態

對本地優先、可檢視的 agent workflow 而言，gitignored 的 `.agent/` 目錄（JSON 與 JSONL）是耐久外部狀態的務實實作。

.agent/
  current/
    state.json                  # Workflow 控制器
    startup-brief.json          # 已確認的 intake（不是 plan）
    plan.json                   # Slice backlog + acceptance criteria
    active-slice.json           # 當前實作契約
    slice-history.jsonl         # 僅追加的角色 transcript
    stop-check-history.jsonl    # Stop-judge 判斷
    verification-evidence.json  # 命令結果 + 覆蓋範圍
    tmp/                        # Repo-local 暫存
  verify_completion_stop.sh
  verify_completion_control_plane.sh

01

Workflow 控制器

`state.json` 驅動自動化：當前階段、continuation policy、下一個強制角色、reground 旗標與 stop-wave epoch。

02

Startup brief ≠ plan

Startup brief 記錄已確認的 intake。Regrounder 在確認後依 repo 真實狀態撰寫 slice plan——散文式任務描述不會默默變成執行契約。

03

Active-slice 契約

目標、acceptance criteria、implementation surfaces、驗證命令、basis commit 與範圍鎖。當 plan 與 active slice 漂移時，verifier 會 fail closed。

#5 單位 Slice 生命週期

核心工作單位

一次一個 slice、一個 slice 一個 commit

每個 plan 項目都需要非空、可驗證的 acceptance criteria。只有當 slice 落地成新的 commit，且其結構化證據寫入 canonical state 後，才算完成。

Slice 狀態轉換

stateDiagram-v2 [*] --> selected: regrounder 選擇 slice selected --> in_progress: implementer 開始 in_progress --> committed: 新 git commit + 證據 committed --> reviewed: reviewer 通過 reviewed --> audited: auditor 通過 audited --> done: acceptance criteria 滿足 done --> [*] in_progress --> reground: 發現 roadmap 漂移 committed --> reground: dirty worktree / 對齊 reground --> selected: regrounder 對齊

01

選擇

Regrounder 選擇 slice，鎖定 acceptance criteria 與 basis commit，並寫入 active-slice 契約。

02

實作

Implementer 依契約工作、執行驗證命令，並建立恰好一個 slice commit。

03

評估

Reviewer 與 auditor 產出結構化 rubric 報告。失敗透過 regrounder 對齊重新打開範圍。

04

對齊

Regrounder 更新 backlog 狀態、處理 dirty worktree，並選擇下一個 slice——或進入 stop 評估。

05

收束

所有 slice 完成後，stop-judge 與 verifier 必須通過，continuation policy 才能變成 done。

當 continuation policy 為 continue 時，driver 會自動 dispatch 必要角色，而不會在每個 slice 之間再問一次「要繼續嗎？」。
進入下一個 slice 前，tracked worktree 必須乾淨。無關變更可在安全時透過可逆 stash 自動保留。
對符合條件的 regression slice，驗證會在鎖定的 basis commit 上於 disposable worktree 重跑——在 workflow 層證明 bug 在 basis 上確實存在。

#6 證據驗證

證據，不是散文

評估、驗證與受治理的收束

驗證證據是耐久的結構化產物，不是 chat 裡的摘要。唯讀評估角色共用一套四維 rubric；每一維都會得到 pass、concern 或 fail。

01

契約覆蓋

實作是否滿足鎖定的 acceptance criteria 與宣告的 surfaces？

02

正確性風險

依當前證據，什麼可能壞掉、回歸或表現異常？

03

驗證證據

決定性檢查是否已執行、記錄，且足夠新鮮以支撐判斷？

04

文件 / 狀態一致性

文件、canonical state 與 repo 真實狀態是否仍一致？

Stop wave： 多個獨立的 stop-judge 子程序可能需要在當前 HEAD 上一致同意，工作才能停止。Stop-wave epoch 讓系統在對齊過程改變 canonical 真相、卻沒有產生合成 commit 時，仍可重新評估。收束時移除 `.agent/` 是預期行為，不是異常。

#7 選擇兩種模式

Workflow mode vs 一般 chat

以顯式 opt-in 保留直接協作

這個設計刻意保留兩種模式。只有在可恢復性、review 軌跡與受治理收束真的值得付出成本時，才啟用 workflow mode。

模式

行為

一般 chat

快速修改、問答、腦力激盪，以及不需要 workflow 開銷的多檔案工作。

允許直接改 repo。不 dispatch 角色。不載入 workflow 協定。

Workflow mode

可恢復的任務、review/audit 回合、canonical state、確認優先的邊界。

顯式進入。Fail-closed 啟動合成。角色 dispatch。在進入停止姿態前持續自動延續。

控制項

Start / resume — 進入或從已存狀態繼續
Park — 暫停以進行一般直接編輯；恢復時強制 reground
Cancel — 關閉已停止或已 park 的 workflow

#8 落地實作

從規格到實作

這套設計如何在 Pi 中實作

這一頁以抽象層次描述 control-plane 架構；@linimin/pi-letscook 則把這套架構變成 Pi 中可運作的長任務 workflow mode。

設計與實作的關係： control plane 是架構模型；@linimin/pi-letscook 是它的一個具體落地版本。核心不變量不變，但命令命名、檔案布局與 host 整合細節仍屬於當前實作選擇。

快速開始

pi install npm:@linimin/pi-letscook
/reload
/cook add login redirect handling and the missing redirect tests

設計面向

pi-letscook 實作

顯式 workflow 入口

受治理的長任務模式應該是 opt-in，而且在啟動前先確認。

`/cook` 進入 workflow mode，並先根據當前 context 合成 startup brief，再提供 Start / Cancel。

恢復、暫停與關閉

生命週期控制應該是顯式的，而不是藏在對話動能裡。

`/cook resume`、`/cook park` 與 `/cook cancel` 讓續跑、暫停與收束都保持顯式。

耐久 canonical state

Workflow 狀態必須能穿越 context 壓縮與工作階段重啟，而不是只存在對話記憶中。

Repo-local 的 `.agent/` 檔案會把 startup brief、plan、active slice、evidence 與 stop 狀態保存在 worktree 旁邊。

角色分離的執行

實作、評估與收束不該坍縮成單一權責面。

bootstrapper、regrounder、implementer、reviewer、auditor 與 stop-judge 會以分離的 completion roles 執行，並受到權責邊界約束。

受治理的驗證與收束

完成應建立在結構化證據與明確 stop 條件上，而不是對話中的自信語氣。

內建的 control-plane verifier、stop verifier、結構化 evidence，以及 fail-closed 的 review / audit / stop 回合共同把關完成條件。

哪些屬於設計不變量

耐久外部狀態、slice 化執行、顯式 workflow 入口、角色分離與 fail-closed 驗證，都是這套設計的核心不變量。它們是架構本體，不只是 package 細節。

哪些屬於當前實作選擇

`/cook` 命令、目前的 `.agent/` 檔案布局、Pi extension 打包方式，以及 Cursor 整合細節，屬於 pi-letscook 的當前實作選擇，而不是抽象設計本身。

實作導覽

應該先看哪裡

不同讀者需要不同入口。你可以依照自己是想使用套件、檢查協定，還是了解 host 整合細節，選擇對應的實作資料。

如果你想直接使用它

先讀套件 README。它會說明什麼情況適合用 `/cook`、workflow mode 和一般 chat 的差別，以及如何把套件安裝進 Pi。

如果你想看 runtime contract

讀 protocol notes。裡面記錄 canonical `.agent/**` 狀態、workflow 指令、verifier 行為、calibration gates，以及 release parity 的要求。

如果你需要 Cursor 整合

看 Cursor handoff 與 Cursor backend 文件。pi-letscook 同時支援 Cursor → Pi 的 workflow handoff，以及可選的 Cursor-backed role execution。

具體細節

這個實作比架構圖走得更遠。

套件本身提供了真實命令、repo-local 狀態、verifier scripts、角色 prompts 與 maintainer protocol notes。它也支援 Cursor handoff，以及可選的 Cursor role backend，讓抽象的 control-plane 模型能在實務上被直接檢視。

查看 GitHub 實作閱讀套件 README 查看 protocol notes 查看 Cursor 整合文件

#9 誠實取捨

這是什麼、又不是什麼

只在漂移代價高時付出額外開銷

Workflow mode 會增加延遲、token 開銷與認知負擔。只有當工作跨越多個工作階段、review 軌跡重要、錯誤的「完成」代價高，或 chat-only 嘗試已出現任務漂移時，這些成本才值得。

不是雲端編排器

一切本地、以 repo 為範圍、由套件擁有。

不是 chat 的替代品

當 workflow 開銷不必要時，直接實作仍然有效。

不是正確性保證

角色與 verifier 降低風險與漂移；不能證明形式上的正確性。

預設不 host-agnostic

具體實作會綁定特定 agent runtime、子程序隔離與工具生態。

單一 agent 一直做

開銷低，但沒有可恢復的控制面、權責模糊、收束薄弱。

人類 PR workflow

Review 文化強，但不是 agent-native——沒有自動 dispatch 或壓縮後恢復。

雲端任務佇列

可擴展的編排，但有外部依賴，且較不貼近 git。

只靠提示詞的多 agent

角色扮演靈活，但沒有 tool 強制與 canonical state 時角色會坍縮。

可執行規格

協定行為本身就是 release gate 的一部分，不是附屬的 CI 衛生工作。

Regression suite 應涵蓋 schema 一致性、evaluator 校準、stop-wave 語意、dirty worktree 政策、worktree-root 邊界、helper 權責，以及公開文件與 runtime 行為的一致性。