Claude Code 的程序外編排

我們正在構建一個名為 Claudeverse 的工具，用於並行執行多個 Claude Code 代理。隨著開發深入，我們發現 Claude Code 中一系列看似不相關的問題都源於同一個架構決策：將編排器作為代理執行在程序內部。

症狀表現

瀏覽 anthropics/claude-code 的問題追蹤器，你會發現大量相似的抱怨：子代理的輸出溢位父會話導致崩潰（#23463，七個並行子代理產生約15萬字元結果，觸發8次連續的“提示過長”錯誤且無恢復機制）；多個子代理共享同一個令牌預算（#10212，所有子代理共用父會話20萬令牌預算，執行五個子代理則全部飢餓）；只有頂層 REPL 能呼叫 Agent()，子代理無法協調自己的子代理（#46424）；重啟後所有上下文丟失（#39663 和 #43696，多小時的除錯會話重啟後消失，--continue 和 --resume 無法恢復）；並行會話爭搶工作目錄（#52051，兩個會話在同一個倉庫中“互相踩踏工作樹”，社群已為此構建工作樹排程工具 Gwt-Claude）。

這些症狀看似五個不同的缺陷，實則同根同源。

共同根源

在 Claude Code 中，編排器本身是一個代理。決定生成子代理的操作是 Claude 會話中的一個回合。因此，編排器協調的一切都侷限於其程序、上下文視窗、工作目錄和會話生命週期內：子代理結果返回父上下文，積累後溢位；子代理消耗父代理的令牌預算，形成競爭；只有頂層 REPL 能排程，無法構建層次結構；狀態儲存在會話中，重啟即丟失；所有代理共享同一個程式碼檢出，並行時發生碰撞。

關鍵不在於某個設計有誤，而在於將編排器置於代理內部，導致協調器與被協調的工作之間毫無隔離。

解決方案：程序外編排

我們的替代方案是：編排器不再是代理，而是一個獨立的程序，它將 Claude Code 代理作為子程序啟動，並從外部協調它們。我們的架構圍繞這一分離設計，從而使上述五種症狀得以分解：

• 上下文隔離：每個代理作為獨立的 Claude CLI 程序執行，擁有自己的會話上下文。子代理的輸出由編排器程序捕獲，不會拼接到父代理的提示中。單個代理上下文填滿隻影響自身，不會導致整個會話崩潰。
• 獨立上下文視窗：每個代理擁有獨立的程序和會話，不再瓜分同一上下文視窗（這是程序級隔離，不涉及 Claude 賬戶配額）。
• 對等排程：沒有“頂層 REPL”。編排器是普通程式碼，它啟動的每個代理都是對等的子程序。代理若要協調自己的子代理，只需啟動更多子程序。
• 程序外狀態：編排器在單個代理程序之外追蹤迴圈和任務狀態。代理程序可丟棄，但記錄得以保留，因此崩潰或重啟可從該狀態恢復，而非從零開始。
• 工作空間隔離：每個代理作為獨立的 CLI 程序啟動，並指定顯式工作目錄，編排器可將代理分配到不同的檢出或工作樹中，避免所有工人共用同一倉庫狀態。這使工作樹衝突變為編排策略問題，而非不可避免的副作用。

誠實的說明

需要坦誠幾個侷限：“程序外狀態”是指迴圈/任務狀態，並非完整的會話回放。重啟後倖存的是結構化記錄——嘗試過什麼、狀態如何、涉及哪些任務——而非代理的整個上下文推理鏈。它能停止重新調查迴圈，但並非時光倒流。

這是一個協調層，而非模型改進。Claudeverse 封裝了 Claude CLI，並不提高模型在單一任務上的能力，而是讓多個任務能夠同時存活執行。

程序外編排也有自身的成本：子程序監督、輸出處理避免無界緩衝、殺死程序組以防後代程序洩漏、崩潰時協調共享資源。我們用上下文隔離問題換來了程序監督問題——我們認為這是一個更優的權衡，因為程序監督是一個相對成熟的領域，而共享上下文視窗則棘手得多。

為何記錄

主要是因為問題追蹤器顯示很多人獨立地撞上同一堵牆，卻將其視為五個單獨的煩惱。值得指出共同的根源：程序內編排將協調器與工作耦合在一起。解決方法並非增加一個標誌位，而是將協調器移到外部。