MoAI-ADK：用驗證驅動的 Harness 約束 Claude Code，Factory Mode 以「領隊加多車道」拆分上下文

一、它是什麼

MoAI-ADK 是 modu-ai 團隊開源的一套「以驗證為驅動的智能體編排框架」，業界常把這類東西叫作 harness（外殼或挽具）。它用 Go 編寫，要求 Go 1.26 及以上，採用 Apache-2.0 授權。

專案頁面上標示的發佈版本是 v3.1.3，同時在「What's New」一節預告了 v3.2 的 Factory Mode。它的目標不是再訓練一個編碼模型，而是給 Claude Code 這類編碼智能體套上一層外部結構，讓產出的程式碼值得信任。專案還提供英、韓、日、中四種語言的文件、一本配套的書《Practical Agentic Coding with Claude Code》，以及 Discord 社群，CI、CodeQL 與 Codecov 的徽章也都掛在首頁。

二、核心論斷：把三件事交給外部

專案開篇引用了一句判斷：模型是逐 token 前進的隨機性工作者，它無法在回合之間記住這一輪用了什麼、用了多少，無法判斷結果好不好，也不知道上一個會話推進到了哪裡。對應到工程上，就是三類責任：預算、品質、進度。

MoAI-ADK 的設計立場是，這三件事不能指望模型自覺，必須由 harness 從外部強制執行。這與「提示詞越寫越長」的思路截然不同：它不是去勸模型，而是用確定性的程式碼去限制和檢查模型。

三、Factory Mode 的架構

v3.2 的 Factory Mode 針對的是上下文視窗問題。一個會話只有一個上下文視窗。一份很長的 SPEC 會把視窗填滿，之後每個任務都要揹著前面所有內容。規劃早已結束，卻一直留在視窗裡陪著評審，評審又一直留到寫總結。常見的補救辦法是 /clear，但它連有用的上下文也一併丟掉。

Factory Mode 的做法是把工作拆到「一個領隊會話加若干編號車道會話」上。領隊負責盯住佇列，把任務卡派給空閒的車道。一張卡不會在各個階段之間換會話，而是整張進入某一條車道，由這條車道在自己的會話裡依序完成 plan、run、sync。每個階段都以 Agent() 子代理的形式啟動，車道本身只做編排。這裡並沒有突破任何上限，每個會話的限額依然存在。變化在於：一張卡的歷史只會累積在持有它的車道裡，所以同樣的預算走得更遠，車道處理完一張卡後會清空上下文，再接下一張。

四、運行機制與細節

入口只有兩個參數。moai cc -f 開啟領隊，長寫法是 --factory；moai cc -l 以車道身分加入正在運行的工廠，長寫法是 --lane。兩者都不帶值，車道編號由系統自動分配，操作者不能自選。-f 與 -l 同時出現會報錯，在其後附帶數值（例如 moai cc -l lane-2）也會被拒絕，並給出一行指明正確用法的錯誤。舊的多會話看板模式的 -k 入口已被移除，moai cg 只會輸出遷移提示（可用 moai migrate cg 預覽）。moai gpt 並不存在，GPT 模型透過 moai codex 運行；moai codex 沒有領隊入口，只能作為車道加入。 後端按車道選擇：moai cc -l 是 Claude 車道，moai glm -l 是 GLM 車道，moai codex -l 是 Codex 車道。文件的建議是，領隊的位置不負責下判斷，只負責看佇列和搬運卡片，所以適合用等待成本低的 GLM（moai glm -f）。某個帳號開始頻繁回傳 429 時，可以把車道分散到不同帳號。文件也說明這只是示例，所有會話都用同一個後端同樣可行。 要同時處理多張卡，就再執行一次 -l 增加一條車道。編號只在有存活會話佔用時才被跳過；死亡車道的佔位不再阻塞其編號，但自動分配總是取「現存最高編號加一」，因此不會回填中間的空缺。車道歸屬記錄在 ~/.moai/db/<project-key>/factory/factory.db；當基礎目錄是臨時目錄且沒有絕對路徑的 MOAI_HOME 覆蓋時，則記錄在專案本地的 <base>/.moai/db/<project-key>/factory/ 之下，積壓佇列也遵循同一個例外。舊的 .moai/state/factory/workers.json 只會被匯入一次，並作為回滾證據保留。

單條車道最多同時運行 10 個 Agent() 子代理，具備寫入權限的派生會被隔離在各自的 worktree 裡。文件明確建議不要一次點亮所有車道：先起第一條，確認它確實在產出，再啟動其餘的；同一張卡永遠不會被拆到多條車道上。此外，工廠運行會記錄擁有它的會話的行程身分。領隊已經死亡的運行，會在下一條車道加入時被自動退役，避免加入動作卡在 AMBIGUOUS_FACTORY 上；反過來，如果車道加入時運行記錄缺失或已退役、卻存在存活的領隊會話，加入流程會用行程號加行程啟動指紋去核驗這位領隊。

五、效能與成本：證據在哪裡

需要坦率說明的是，所提供的 README 摘錄裡沒有給出基準資料：沒有吞吐量、沒有 token 成本對比，也沒有缺陷率的前後統計。文件只給出了結構性的論證：卡的歷史只在所屬車道內累積，所以相同預算能走得更遠。

這是一個合理的機制性主張，但在沒有公開度量之前，不應把它當作已驗證的收益。評估時可以關注幾個可測的指標：每張卡的平均上下文佔用、車道清空後的複用效率、429 發生率，以及領隊與車道之間的協調開銷。

六、對開發者與團隊的影響

對個人開發者，Factory Mode 提供了一個不需要自建排程器的並行方案：多開幾個終端，各自運行 moai cc -l 即可。對團隊，資料落在 SQLite 檔案和專案鍵之下，便於稽核和回溯。

多後端支援讓團隊可以按成本與額度靈活搭配，而不是押注單一供應商。更重要的是，它體現了一種趨勢：編碼智能體的競爭點正在從模型本身，轉向包裹模型的流程與驗證層。

七、限制與未來

第一，車道必須由人手動逐個啟動，因為一個會話無法啟動另一個會話，這限制了全自動化。第二，公開資料裡缺少量化基準。第三，複雜的行程身分核驗和歷史狀態匯入說明系統已經為崩潰恢復付出了不小的複雜度，使用者需要理解這些邊界情形。

第四，一張卡不拆分的原則，意味著單張超大任務仍然會撐滿一條車道的視窗。可以期待的方向包括：公開的度量報告、更多後端的接入、以及更細粒度的卡片切分策略。總體而言，MoAI-ADK 值得關注，但在引入生產流程前，應先在小規模真實任務上自行測量。