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，並不提高模型在單一任務上的能力，而是讓多個任務能夠同時存活運行。

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

為何記錄

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