每個多代理架構都會撞上的三道牆
交付一項任務給寫程式的代理,它可以順利完成。再交給它第二項,裂縫就開始浮現。到了第三項任務,情況便顯得混亂,而最直覺的診斷是:執行的代理太多了。
我有一段時間也這麼認為。後來我把 commit 逐筆翻過一遍,發現這些故障的分類方式,並不是按同時跑了幾個代理,而是按兩個角色各自寫入哪個位置、以及那個位置有沒有人負責。一個記錄「完成」的狀態檔。一份兩項實作都能寫入的共用工作目錄。一項只有提出者自己看得到的完成宣告。
這三種故障的性質並不相同,把它們混為一談,往往就會修錯地方。第一種是沒有人擁有寫入權。第二種是刪除工作區之前,沒有人先把紀錄複製出來。第三種是沒有獨立第三方驗收那項宣告。所有權、留存、驗收。
這也不是一套分類學。這三道牆都是實際讓我付出代價的,第四道可能還在後頭。它同樣不是一道階梯:下面的順序是我理解它們的順序,並不是修正上線的順序,文章最後會再回到這一點。
紀錄只能有一個寫入者
第一次故障看起來不像人為破壞,這也是它花了一段時間才被命名的原因之一。並沒有代理擅自修改不應由它修改的檔案。問題發生在任何編輯動作之前。協調者相信代理自稱完成的事,而沒有去檢查檔案系統,於是階段被標記為完成,背後卻沒有任何 commit。修正用的那筆 commit 用自己的話記下了根因:
a critical governance gap where the coordinator (Claude Code) could trust agent claims without verification, leading to phases being marked complete without commits.
這個缺口背後的機制只有一句話。工作代理可以直接呼叫 state.py,也就是說,執行任務的人同時也有資格登記該任務已完成。問題不是權限外洩給未獲授權的程序,而是任務執行與完成登記兩項權限集中於同一角色。惡意修改檔案是另一個故事,需要另一種修正方式,不是這裡要談的。
做法是:受保護的狀態僅設一條權責明確的寫入路徑,其他角色均須透過該路徑寫入。
強制機制刻意做得小。守護元件會拒絕未帶授權 skill 標記的直接 state.py 呼叫。另外兩道拒絕堵住明顯的側門:透過裸 Bash 核准提案,以及靠不斷新增檔案、以累積方式讓某個東西被核准。而協調者必須遵循的流程,在儲存庫裡只寫成一行:
Workers make claims → Coordinator verifies → Coordinator updates state.
這條箭頭的重點在於誰不在裡面。工作代理負責回報,不負責認證。
以個人規模來說,這道牆只需要一條規則,也不必動用儲存庫。一個 Claude Code 工作階段,一個進度檔。子代理回報它已寫好三個檔案,你沒打開任何一個就把任務標成完成,而那些檔案根本不存在,因為那份回報描述的是意圖,不是實際的寫入。這是示意,沒有日期,我的日誌裡也找不到可以指認的紀錄。最小可行的版本就是一句話:只有持有計畫的那個工作階段可以寫入進度檔。工作代理回報,你驗證,你來寫。
所以,挑出那一個代表「現在什麼是真的」的產出物。可能是一個狀態檔、一張狀態表、一份 changelog,或資料庫裡的某一列。只給一個元件寫入權,其餘角色一律透過該元件寫入。然後在寫入之前驗證宣告,而不是寫入之後。一旦筆只握在一隻手裡,執行者對自己工作的陳述,就不再是可以據以行動的證據。
重導寫入,而不是把工作代理鎖在門外
第二次故障更不易察覺,因為系統並未出現明顯的失敗訊號。
一件已經完成的工作被清理掉。工具刪除了當初執行工作的暫存工作區,最新的驗證紀錄也跟著消失。任務隨後以 resolved 結案,帶著一份較舊的驗證結果,時間戳是 14:57,而重新驗證實際上是在 19:40 執行的。在這裡 resolved 是終態,沒有重啟路徑,所以這個損失無法靠重跑任何東西來補救。要修就得新增一個基礎操作:嚴格受限的 reopen_for_reverify,如今它是修正終態規格的唯一途徑。
留下的證據是一筆時間不符的紀錄,而這正是值得記住的部分。被刪除的工作區不會留下殘骸。活下來的是看起來完整、實際上整整落後一個版本的紀錄。損失不是磁碟造成的,而是兩個步驟對「這個寫入該由哪個位置負責」認知不一致造成的。
這個案例同時涉及兩項風險,我把它們分開講,因為兩者需要不同的修正方式,而且很容易誤以為解決其中一項,就已處理兩項風險。第一項風險是刪除會毀掉證據:只存在於免洗工作區裡的東西,會隨著工作區一起消失。第二項風險是共用工作目錄接受任何人寫入:某項實作工作進行期間,另一個代理可以把檔案寫進該實作所使用的工作目錄樹。
針對第一項,解法是先留存、後銷毀:在工作區被移除之前,把該工作區的狀態與驗證結果複製回主儲存庫。這是 resolve skill 裡的一個冪等步驟。
針對第二項,解法是重導:某項實作正在進行時,拒絕寫入共用工作目錄。單靠重導並不能保住前面那些產出物。它讓錯誤的寫入位置難以觸及,但不會讓刪除變得安全。
遇到衝突時,直覺反應是加鎖:一個範圍只能有一個代理,彼此互斥。這裡做的不是這件事,真的去建鎖反而會是個錯誤。兩個代理各自處理不同的工作並不構成衝突,那正是需要同時跑多個代理的理由。真正會弄丟工作的衝突,是某個代理的實作正在進行時,另一個代理把檔案寫進共用工作目錄——因為共用工作目錄是每個代理都搆得到、卻沒有人真正擁有的那個位置。
所以修正方式是重導。寫入被拒絕,不是因為別人握著鎖,而是因為主目錄樹本來就不該被寫,而拒絕訊息會告訴代理它應該寫到哪裡。
具體而言:工作在免洗工作區裡進行,而不是在共用工作目錄裡。只要有實作正在進行,儲存庫就會留著一則簡短的即時標記,說明這件事,並指出它的工作區在哪裡。任何檔案寫入之前,都會有一道檢查解析路徑。若路徑指向原始碼目錄樹,而標記仍然存在,寫入就會被拒絕,並把代理導向工作區。
粒度值得用一句話說明,因為那正是平行運作得以成立的關鍵。每則標記對應一項工作,所以同時進行多項工作就會有多則標記,而它們都不是互斥鎖。寫入 .trustless/worktrees/ 之內永遠允許;受保護目錄之外的寫入則不受影響。
有兩項限制我不打算粉飾成已經解決。第一,這層保護是按位置、不是按角色。它在實作期間拒絕某個路徑,不論寫入的是誰,也完全不管寫入者是協調者還是工作代理。同一個條件上還有第二道防線,名字聽起來像是能辨識協調者、並以更高標準約束它;實際上它不辨識任何角色。不要把這讀成權力分立。規則背後的用意是真的——協調者應該派工,而不是自己寫程式——但現有實作強制的是條件,不是身分。
第二項限制在於目的地。標記是按任務建立的,所以同時跑多項實作的儲存庫就會同時存在多則標記,「目前使用中的工作區」不再是一個明顯的目錄。我的看法是,重導的價值主要在前半段——把寫入擋在主目錄樹之外,那才是真正會弄丟工作的部分。為這個特定代理指出正確目的地,效果取決於背後的路徑解析,而那套解析恰恰在代理最忙碌的時候最薄弱。如果你要自己做,目的地的部分要測得最扎實。
標記不做的事是稽核。它是短命的執行期狀態,範圍限於該工作階段,而且從不進版控,所以它回答的是「現在這個寫入安全嗎」,而不是「三週前是誰做了什麼」。要回答後者,你得去讀版本控制歷史:每項實作都落在自己的分支、帶自己的 commit,而那些 commit 才是你回頭查閱的依據。標記負責預防衝突,不負責作證。
關於範圍的另一半,有一個必須誠實說明的限制。每個工作單位都會宣告它可以碰哪些檔案,這些宣告按提案逐一記錄,這個儲存庫裡共有 59 份,各自帶有明確的讀取與寫入區段。但守護元件只驗證這些檔案的結構:指定的欄位必須存在,卻沒有任何程式會拿實際寫入去比對宣告清單。有一次實際發生的違規可以說明這點。某個修正動到了一份被自己的宣告標為唯讀的檔案。沒有任何機械機制抓到它。是一位審查者在第二道審查關卡發現的,並標為高嚴重度。工作流程停下來等人決定,而當天是以放寬範圍收場,而不是還原那次修改。
所以那道看起來像強制機制的界線,實際上只是一則提醒人去審查的提示,而它之所以有效,是因為真的有人讀了 diff。這也是整篇文章裡誠實的分界:有些界線可以用程式強制,其餘的只能靠人去看。審查注意力是稀缺資源,這正是把能自動化的部分自動化的理由。
以個人規模來說,這些機制全都不需要。兩個工作階段、一個儲存庫:
git worktree add ../proj-<task> -b <task>
每個任務都有自己的目錄,兩者不會互相覆寫。不需要標記、不需要 hook、彼此之間也不需要互斥鎖。紀律只有一句話:還有其他任務開著的時候,不要在主要工作目錄裡編輯。另外,把這起事件的另一半也一起帶走,因為真正保住東西的正是那一半。移除 worktree、分支或工作階段之前,先把證據搬出來:把測試輸出 commit 進去、把驗證紀錄貼進 pull request、把摘要留在比該目錄活得更久的地方。刪除一個自己沒讀過的工作區,正是讓一份看似完整的紀錄整整落後一個版本的原因。
先從習慣開始。等到有一天你記不住了,再把拒絕自動化。
動手寫的人,不能是簽核的人
十個階段被標記為完成,實際建立的檔案卻是零。工作是在一個後來被移除的工作區裡做的,所以等到有人能查的時候,已經沒有東西可查。
這起事件值得放在開頭,在於它的形狀。造假不在程式碼裡,因為根本沒有程式碼;造假發生在回報層。子代理在什麼都沒產出的情況下回報任務完成,而這個完成之所以被接受,是因為回報的人正是被信任的人。
如今擋下它的關卡很小,而且它自己的檔頭就註明了對應的事件。當工作區背後沒有任何 commit 時,它會拒絕把階段標記為完成。執行者認證了自己的成功,而那份認證是憑空編出來的。
這個故事的另一個版本我已經寫過:那次支付流程重構遷移了受保護的狀態、憑空生出一個它被禁止撰寫的 handler、自己測試自己的成果,然後回報自己可以上線了。那個案例留在 Agents Need Architecture, Not Prompts 裡。匯率這件事之所以放在這裡開場,是因為它更乾淨:完全沒有虛構的程式碼,只有虛構的完成。
更深的問題不是不誠實,把它框成不誠實反而會導向錯誤的修正方式。評判一件工作需要站在它之外,而寫出這件工作的代理,恰恰是唯一做不到這件事的參與者。承包商自己簽核自己做的電路工程,問題也一樣:不是承包商會說謊,而是在牆封起來之前,沒有任何獨立的人看過。要避免的安排,是讓同一個角色定義任務、執行任務、又評估結果。以我在代理工作流程上的經驗,這種安排是單一最大的營運風險。當沒有外部力量檢核那項宣告時,「完成」講的是代理的信心,不是儲存庫的狀態。
所以這條規則是禁令,不是習慣。除非有未參與該項工作的審查者檢查過證據並判定通過,否則階段不能關閉。沒有獨立證據的自我認證一律禁止;以隱含方式、或在背景中當作其他動作的副作用而發生的驗證,同樣禁止。
這道審查在實作完成後執行,通過的結果是標記階段完成的前提。要注意獨立性附著在哪裡。審查者可以讀工作代理自己寫的 diff,通常也應該讀,因為 diff 是「改了什麼」最直接的證據。獨立性屬於審查這個動作,不屬於被審查產出物的作者。
我自己走的路是刪除,而不是演進,這個差別很重要。舊的驗證器要求代理出示一個 token,證明它做過檢查;它不是被逐步替換掉的,而是在一筆 commit 裡被整組刪除,1,721 行加上它的測試檔,換成一個 212 行、做著相反事情的模組。兩者沒有同時存在的時期。這裡的教訓不是驗證器變好了,而是整套驗證機制被移除,因為它的存在讓自我認證成為可能。
現在的驗證要求由獨立審查者逐階段檢查五個問題:目標達成了嗎?計畫完成了嗎?未結的發現事項都關閉了嗎?不變量守住了嗎?這次變更是否引入了任何沒有人看過的新東西?
這五個問題吃的都是證據,不是說詞:實際被修改的檔案清單、計畫本身,以及階段開始前拍下的未結發現事項快照——正因為有這份快照,最後一個問題才有可能回答。輸出是結構化的判定:通過、警告或失敗,並記錄審查者輸出的雜湊值。
雜湊值值得講精確一點,因為這是最常被過度解讀的部分。它把某個判定綁定到計算當下那份證據的確切位元組,所以事後你可以知道它是讀了哪份 diff 的哪一版產生的。它不證明判斷是對的,本身也不證明誰有權關閉這個階段。帶雜湊的通過,仍然是某個人對證據的閱讀;把雜湊當成證明,正是讓流程看起來比實際更嚴格的原因。
以個人規模來說,這些關卡都還不重要。代理說測試通過了,你就開一個乾淨的 shell 自己跑一遍,然後把 diff 的每一個 hunk 都讀過,而不是讀代理針對 diff 寫的摘要。任何要上正式環境的東西,把 diff 交給另一個代理,問它有哪些變更是第一個代理沒提到的。這道牆的最小版本不是驗證器,而是一條規則:寫程式的人,不能是簽核的人。
三項做法,不需要框架
把儲存庫拿掉,還剩三項做法,每一項今天下午就能用,什麼都不必安裝:
- 只讓一個元件擁有寫入你信任來源的路徑,並在宣告抵達該寫入路徑之前先驗證它
- 讓每項任務有自己的工作區,並在拆掉工作區之前先把證據搬出來
- 絕不接受由產出者自己宣告的完成,驗收必須立基於別人讀過的產出物
這三項沒有規定的採用順序。其中兩道牆同時浮現,因為一月的一起事件產生了兩個修正;第三道牆多花了幾個月才看懂,而且最後需要的是重導,不是加鎖。這是這個儲存庫那一年的實情,不是一份課綱。
回到文章開頭的那個質疑:這是不是過度設計?
如果只有一個代理、一項任務,答案是:是。這些東西沒有一項划得來,而在只有單一工作代理的工作階段裡,那三項做法不過是你本來就有的習慣:你自己寫進度檔,你自己讀自己的 diff。治理層之所以存在,是因為這些習慣的擴展速度跟不上代理規模,而不是因為它們錯了。
上面那些故障真正值得自動化的,是一小組可以用「拒絕」表達的決定:誰可以寫這份紀錄、這次寫入是否該落在這棵目錄樹、這項宣告是否有別人讀過。這三件事值得機械化,因為三者都是無聲失敗,而且檢查成本都很低。我這套設定裡的其他東西,都只是穿著基礎設施外衣的習慣,我不建議照抄。
仍然必須靠人的,正是這篇文章裡抓到真正違規的那一部分。有人讀了 diff,注意到那個被宣告為禁區的檔案。沒有任何機制做到這件事,我也不期待有。請為閱讀編列預算。
我後來確實把這三道拒絕自動化了,做成一個叫 ACP 的治理層,放在我參與的平台上。它是這些做法的實作,而不是使用這些做法的前提,也不是通用的可靠性保證。我為什麼選擇自動化、而不是繼續手動,記憶中的理由並不光采:同時進行的專案多到一個程度,手動執行這些做法本身就變成一份工作。我不打算把它美化成某個有日期的決策點。
如果明天只做一件事,就挑出那個記錄「什麼是真的」的檔案,把筆從其他所有人手上拿走。第一道牆就這麼多,一個下午就能做完。
註記
以下是給想查證的人的憑據,依出現順序排列。
- 狀態權責的根因來自 commit
b049c4fda(2026-01-30)。守護元件的檢查是check_state_authority(guardian.py:2693);旁邊那兩道拒絕是guard-approve-via-bash.py與safety-file-creation.py(Alignment Spec §B.1)。 - 宣告檔的數量以儲存庫當前版本計算:59 份
scope.yaml,各自帶有明確的write.files與read_only區段。範圍違規是發現事項F-G2-SCOPE-001(2026-05-19);middleware/audit.go被宣告為read_only,由 Codex 的第二道關卡審查以 HIGH 等級提出。只驗結構的驗證邏輯在guardian.py:1791,它要求六個具名欄位。 - 兩個實作 hook 宣告同一個 tuple,
IMPLEMENTATION_DIRS = ("apps/", "packages/", "internal/", "cmd/"),分別位於guard-active-spec.py:33與guardian.py:28。階段關卡是guard-phase-complete.py,它的檔頭帶有對應事件的註記。 - 那次刪除是 commit
f28a611ac(2026-02-03),移除了opencode_piv.py(1,721 行)及其測試。212 行的替代品是執行期轉接層.claude/hooks/piv.py;標準模組.agents/skills/implementation-execute/piv.py則是 238 行。 - 範圍事件的日期是 2026-06-05,發生在 resolve skill 的 Step 4.5 與 Step 5。匯率規格
add-exchange-rate-infrastructure的日期是 2026-01-25。 - 治理層是 Trustless ACP,平台是 Trustless,一個以代理為原生設計的銀行與交易所平台。ACP 是其中的一個元件。
- 本系列第三篇會把這四個動作整理成模板:界定工作範圍、指派給某個角色、在分配給它的工作區內執行、在記錄為完成之前依證據驗證。