Mitosis Orchestrator 實作教學：讓 AI 主核專心規劃，子代理分工寫程式與測試

分享是一種日常的美好~

Mitosis Orchestrator 是一個以 MIT 授權釋出的開源編排器外掛，目前版本 1.4.1，同時支援 Google Antigravity（agy）、Anthropic Claude Code 與 OpenAI Codex CLI 等三大 AI 開發工具。它要解決的問題只有一個，就是尖端推理模型的 token 太貴、上下文視窗太珍貴，不應該浪費在找檔案、翻 log、反覆改程式跑測試這類低階勞動上，把這些工作交給比較便宜的子代理才是王道。

專案名稱取自生物學的有絲分裂（mitosis）。使用者選定的尖端模型擔任「主核」（Master Nucleus），只負責架構設計、任務拆解、跨模組不變量的把關與最終整合。其餘工作「分裂」給兩類便宜的子代理，偵察（scout）用最輕量的模型做唯讀查找，執行（worker）用中階模型做多檔案探索、測試與範圍內修改。這個分工不只寫在規則文件裡，而是由一組 hook 在每個工具呼叫前後強制執行，主核想親自讀 log 或一口氣改五個檔案都會被攔下來。

以下先說明設計理念與架構，再逐一走過三個平台的安裝步驟、第一個實際範例、進階調校參數，最後談適用情境與限制。所有價格與效能數字均引自專案文件 2026 年 10 月的記載，實際採用前請以各廠商官方價目為準。

設計理念與架構

整個系統分成三層。主核是使用者在工具裡選定的尖端模型，外掛不會更換它，只會在 session 啟動與每回合檢查它是否屬於支援清單，若被換成 haiku、mini、flash 這類輕量模型就發出警告。偵察與執行兩類子代理則由外掛釘定模型與 effort，三個平台各有對應。

Mitosis 三層架構 · 主核、hook 守衛層、兩類子代理

派遣的箭頭穿過 hook 守衛層，代表每次呼叫都會先被改寫與檢查。回報的箭頭只帶回四標頭摘要，子代理讀過的原始內容不會進入主核的上下文。

主核透過各平台的子代理工具派遣任務，hook 在呼叫送出前改寫參數，把模型釘到對應階層並補上回報格式。子代理完成後必須以四標頭格式回報，由 SubagentStop 檢查，不符的會被退回重寫一次。

在生物學上，「有絲分裂」之所以稱為「有絲」，是因為細胞分裂時會出現由微管組成的「紡錘絲」，這些紡錘絲會精準地綁住染色體，強制將它們拉開、精確定位並平均分配到兩端，確保分裂過程高度規律且不出錯。
在這個 AI 編排器專案中，「有絲」這個概念被轉譯為「強制性的工具守衛（Hook）機制」。它代表的不是溫和的提示詞約束，而是像紡錘絲一樣硬性拉開主核與子代理的職責界線，強制進行精準的管控。

其核心意涵包含以下三個層面：

職責的「硬性拉開」與限制（如同紡錘絲分離染色體）

生物學：紡錘絲將姊妹染色單體強制拉開，分配到兩極。
專案意涵：外掛有一組 Hook 守衛層，主核模型（Master Nucleus）想親自看 Log 或一口氣改很多檔案時，會被 Hook 守衛當場攔下來，強制它必須「派生」出 Scout 或 Worker 子代理去執行。

精準控制的邊界與合約（如同紡錘絲的精確定位）

生物學：每根紡錘絲都精確依附在特定的動粒上，確保染色體不會亂跑、不會多拿或少拿。
專案意涵：專案透過硬性機制限制 Worker 子代理只能修改明確列出的檔案清單，且子代理回報時被限制在 1,600 字元內的「四標頭回報合約」，防止無用資訊回流污染主核的上下文視窗。

高度規律的程序性（如同有絲分裂的嚴格分期）

生物學：有絲分裂必須遵循前期、中期、後期、末期的嚴格順序，若出錯就會觸發細胞凋亡。
專案意涵：透過 /orchestrate 將 AI 的開發行為固定為「平行偵察 > 架構拆解 > 範圍執行 > 統合驗證」四個程序。只要子代理連續失敗 2 次，就會觸發熔斷器（Circuit Breaker），強制停止行為。

四標頭回報合約

每個子代理的最終訊息限制在 1,600 字元以內，NOTES: 最多 10 行清單，狀態為 BLOCKED 或 FAILED 時必須附上 file:// 日誌路徑。這個限制的目的在於保護主核的上下文視窗，子代理讀了多少東西都不會回流到主核。

STATUS: COMPLETED | BLOCKED | FAILED
FILES_CHANGED: <以逗號分隔的檔案路徑或 NONE>
VERIFICATION: <一句話說明執行的驗證命令與結果>
NOTES: <精簡摘要，BLOCKED/FAILED 時附 file:// log URI>

`/orchestrate` 四階段流程

外掛內建一個 /orchestrate skill，把前述分工固定成四個階段。

平行偵察。主核同時派出多個唯讀 scout，蒐集檔案路徑、符號位置與設定檔結構。
架構設計與拆解。主核彙整偵察結果，設計介面契約，切分成互不重疊的工作單元。
範圍執行與測試。多個 worker 平行實作，每個 worker 只能修改明確列出的檔案清單，並自行執行驗證命令。
統合驗證與分支清理。主核審查 diff、確認整合無誤，並清理 worker 留下的分支工作樹。

安裝與環境準備

三個平台的共同需求只有 Python 3.11 以上與 git，外掛本身零外部依賴，hook 引擎只用標準函式庫。各平台的版本門檻依 README 記載為 Antigravity agy 1.4 以上、Claude Code 2.1.292 以上、Codex CLI 0.134 以上（已於 0.154.0 與 0.163.0 驗證）。

Claude Code

這個 repo 本身就是一個單一外掛的 marketplace（.claude-plugin/marketplace.json），可以直接從 GitHub 安裝。

claude plugin marketplace add ivanusto/mitosis-orchestrator
claude plugin install mitosis-orchestrator@mitosis-orchestrator
claude plugin list         # mitosis-orchestrator@mitosis-orchestrator  ✔ enabled

之後更新用 claude plugin marketplace update mitosis-orchestrator && claude plugin update mitosis-orchestrator@mitosis-orchestrator。若要在本機修改外掛再載入，可以把本機目錄加為 marketplace，或只在單次 session 載入。

claude --plugin-dir /path/to/mitosis-orchestrator

驗證方式是開一個新 session，應看到 [Mitosis Orchestrator Active] Primary model is 'opus'. 這類橫幅，且 /orchestrate 出現在指令清單中。

Google Antigravity（agy）

git clone https://github.com/ivanusto/mitosis-orchestrator.git ~/mitosis-orchestrator
agy plugin install ~/mitosis-orchestrator
agy plugin list            # mitosis-orchestrator (enabled, 1.4.1)

也可以直接 clone 到 ~/.gemini/config/plugins/ 底下，agy 會自動載入該目錄下的每個外掛，再用 agy plugin validate <路徑> --strict 檢查。若之前裝過前身 argon-orchestrator，務必先用 agy plugin uninstall argon-orchestrator 移除，兩者的 skill 與 agent 同名，同時啟用會跑兩套 hook。

OpenAI Codex CLI

git clone https://github.com/ivanusto/mitosis-orchestrator.git ~/mitosis-orchestrator
python3 ~/mitosis-orchestrator/scripts/setup-codex.py
codex exec --profile mitosis-scout "Locate where parse_token is defined"

setup-codex.py 可重複執行，依序完成六件事。

備份 $CODEX_HOME/config.toml 為 config.toml.bak（$CODEX_HOME 預設 ~/.codex）。
複製 rules/AGENTS.md 到 $CODEX_HOME/AGENTS.md。
安裝角色檔到 $CODEX_HOME/agents/，包含 explorer.toml、flash-lite-scout.toml（gpt-5.6-luna，low）與 worker.toml、flash-worker.toml（gpt-5.6-terra，medium）。
安裝 mitosis-scout.config.toml 與 mitosis-worker.config.toml 兩個 profile 檔（Codex 0.134 起 --profile <n> 改讀 $CODEX_HOME/<n>.config.toml，舊的 [profiles.*] 區段已失效）。
在 config.toml 寫入 [mcp_servers.mitosis]，指向 scripts/mitosis-mcp-server.py。
校驗所有 TOML 並確認檔案存在。

Codex 端的 MCP server 執行 scout 時使用 --sandbox read-only，worker 使用 --sandbox workspace-write。只有刻意設定 MITOSIS_CODEX_YOLO=1 才會改用 --dangerously-bypass-approvals-and-sandbox，一般情況不建議。

快速上手：第一個範例

以下以 Claude Code 為例，其他平台的流程相同，只是子代理工具名稱不同。

步驟一，確認外掛生效

在專案目錄啟動 claude，第一行應出現 [Mitosis Orchestrator Active] Primary model is 'opus'. 橫幅。若 /model 設成 haiku 這類輕量模型，橫幅會改成警告，提醒主核不應由輕量模型擔任。此時 Agent 工具多了兩個型別可用。

subagent_type: "mitosis-orchestrator:flash-lite-scout"，釘定 haiku，effort low
subagent_type: "mitosis-orchestrator:flash-worker"，釘定 sonnet，effort medium

步驟二，用 `/orchestrate` 下達任務

直接在 /orchestrate 後面接上任務描述即可，例如要在既有的 REST API 加上分頁參數（以下任務內容為示意）。

/orchestrate 為 /api/items 端點加上 page 與 page_size 查詢參數，更新 OpenAPI 文件並補上測試

主核會依四階段流程運作。第一階段先派出數個 scout 平行找出端點定義、現有測試與 OpenAPI 檔案位置，每個 scout 只回傳四標頭摘要。第二階段主核根據摘要決定介面與工作切分。第三階段派出 worker，各自拿到一份檔案允許清單，實作後自行跑測試並回報。第四階段主核審查 diff 並清理分支。

步驟三，觀察 hook 的介入

外掛的價值在於主核「想偷懶」時會被攔下。常見的幾種情況如下。

主核直接 Read 一個 .log 或 transcript.jsonl，會被 Context Hygiene 守衛擋下，提示改派 scout 切片。
主核在同一回合直接 Edit 第 4 個不同檔案，會被 Fast-Path Budget 擋下。
主核直接改完檔案又在同回合跑測試框架，同樣會被擋下，要求交給 worker。
Bash 或子代理連續失敗 2 次，Circuit Breaker 觸發，該回合不再允許重試。
對 scout 送出含程式碼修改或超過 3 個編號步驟的追加指令，SendMessage 會被攔截。

步驟四，用成本報表確認分工是否成立

跑完任務後執行成本報表，看主核占了多少 token 與費用。

python3 scripts/mitosis-cost-report.py            # 目前專案最新的 session
python3 scripts/mitosis-cost-report.py --last 2   # 最新兩個 session 並排比較

README 給的經驗法則是主核若占三分之二以上的 token，代表有子代理該做的事落到了主核身上，應先修正委派方式再考慮換模型。若想在不花太多錢的情況下驗證 hook 是否正確釘定，python3 scripts/smoke-claude.py 會做一次 headless 實跑，確認 scout 被釘到 haiku 與 effort low，README 記載花費約幾美分。

進階用法與設定

主核模型的選擇，Fable 5.1 或 Opus 5.5

外掛只釘定子代理，主核仍由使用者的 /model 決定，在 Claude Code 上通常是 fable 或 opus。README 整理了撰寫當時（2026 年 10 月）的 Anthropic API 牌價，單位為美元／百萬 token，實際採用前請以官方價目頁為準。

階層	模型	輸入	輸出	快取讀取	相對 Opus 5.5	預設 effort
主核	`fable`（Claude Fable 5.1）	10.00	50.00	0.25	2.5 倍	`high`
主核	`opus`（Claude Opus 5.5）	4.00	20.00	0.20	1 倍	`medium`
Worker	`sonnet`（Claude Sonnet 5.5）	2.00	10.00	0.20	0.5 倍	`high`，外掛釘為 `medium`
Scout	`haiku`（Claude Haiku 5.5）	0.10	0.50	約 0.01	0.025 倍	`medium`，外掛釘為 `low`

在 Mitosis 架構下，2.5 倍的價差只作用在主核負責的規劃、拆解、審查與整合，scout 與 worker 的費用在兩種主核下相同。README 公布的兩場實測（不同任務，不可直接比較）顯示主核占總費用 70% 到 85%，其中一個未釘定而繼承 fable 的子代理，費用約為 13 個 haiku scout 的 40 倍。這正是 hook 刻意不碰內建 Explore、general-purpose 型別與明確指定 model 之呼叫的原因，使用者要自己避開繼承模型的陷阱。

README 的建議如下，外掛在 Claude Code 上的預設釘定目標也因此選了 opus。

情境	主核	Effort
日常編排、規格明確的任務（預設）	`opus`	`medium`，架構為主的回合用 `high`
對成本敏感的大量例行任務	`opus`	`low` 或 `medium`
數小時無人看管的自主長跑	`fable`	`medium`，只有最難的部分用 `high`
需求模糊，需要主核自行釐清	`fable`	`medium`
牽涉不變量、並行或安全性的跨模組重構	`fable`	`high`
大型 diff 的深度審查或 repo 歷史追查	`fable`	`medium`

調整子代理的模型與 effort

自 1.3.2 起，Claude Code 的 hook 改寫 Agent 呼叫時會同時釘定 model 與 effort。呼叫端自帶的合法 effort 會被尊重。以下是幾個常用的覆寫方式。

export CLAUDE_MITOSIS_WORKER_MODEL=opus      # fable 主核搭配較強的 worker（haiku|sonnet|opus|fable）
export CLAUDE_MITOSIS_SCOUT_EFFORT=medium    # low|medium|high|xhigh|max
export CLAUDE_MITOSIS_PIN_EFFORT=0           # 不再加 effort，模型仍會釘定

環境變數一覽

所有變數都接受 AGY_MITOSIS_*、CLAUDE_MITOSIS_*、CODEX_MITOSIS_* 三種前綴，舊版 AGY_ARGON_* 仍相容。下表節錄最常用的項目，完整清單見 README。

環境變數	預設值	功能
`*_MITOSIS_PIN_SETTINGS`	`0`	設為 `1` 時 session 啟動自動把設定檔改寫為指定的主核模型
`*_MITOSIS_PRIMARY_MODEL`	`opus`（Claude Code）	啟用自動釘定時的目標主核模型
`CLAUDE_MITOSIS_PIN_SUBAGENTS`	`1`	設為 `0` 時完全不改寫 `Agent` 呼叫
`CLAUDE_MITOSIS_SCOUT_MODEL` / `WORKER_MODEL`	`haiku` / `sonnet`	各階層釘定的模型
`CLAUDE_MITOSIS_SCOUT_EFFORT` / `WORKER_EFFORT`	`low` / `medium`	各階層釘定的 effort
`CLAUDE_MITOSIS_ENFORCE_REPORT`	`1`	設為 `0` 時不再退回未用四標頭回報的子代理
`*_MITOSIS_MAX_DIRECT_EDITS`	`3`	主核單回合可直接修改的檔案數上限
`*_MITOSIS_ALLOW_DIRECT_LOGS`	`0`	設為 `1` 時允許主核直接讀 `.log` 與 `transcript.jsonl`
`*_MITOSIS_ALLOW_DIRECT_FASTPATH`	`0`	設為 `1` 時解除直接修改數量與「改完就跑測試」的限制
`*_MITOSIS_CIRCUIT_BREAKER`	`1`	設為 `0` 時停用連續 2 次失敗熔斷
`*_MITOSIS_AUTO_ALLOW`	`0`	設為 `1` 時工作區內的檔案與命令自動放行，跨出工作區或危險指令改為詢問
`*_MITOSIS_DEBUG`	`0`	設為 `1` 時在狀態檔旁寫入 `mitosis_orchestrator_debug.log`
`MITOSIS_CODEX_YOLO`	`0`	設為 `1` 時 Codex 子代理繞過沙箱

開發與測試

外掛附 176 個單元測試，涵蓋 hook 引擎與成本報表。

python3 -m unittest discover -s tests -v
agy plugin validate . --strict

適用情境、限制與結語

適合誰用

這個外掛最有價值的情境，是當你的程式碼 repo 大到主核光是找檔案就會把上下文塞滿，或是任務需要多個檔案平行修改並各自驗證的情境。團隊若已在 Claude Code、Antigravity 或 Codex CLI 之間切換，三平台共用一套規則與角色定義也能減少重複維護。從資安與治理的角度看，worker 的檔案允許清單、scout 的唯讀沙箱、工作區範圍守衛與熔斷器，等於把「AI 代理可以動什麼」寫成可稽核的設定，而非只靠提示詞約束。

本專案的基本限制

主核模型仍由使用者自行選擇，外掛只會警告不會強制更換，除非開啟 *_MITOSIS_PIN_SETTINGS=1。
hook 刻意不改寫內建型別與明確指定 model 的子代理呼叫，繼承主核模型的子代理會以主核價格計費，需靠成本報表自行發現。
Codex 平台沒有 ask 權限模式，工作區守衛遇到跨出範圍的操作只能 deny。
成本報表目前只讀取 Claude Code 的 transcript 格式，Antigravity 與 Codex 的 session 需另行估算。
模型價格與版本門檻會隨廠商更新而變動，文中數字僅反映 2026 年 10 月的文件記載。

誰該負責什麼? 寫在工具呼叫層級來管控

Mitosis Orchestrator 把多代理協作裡最容易被忽略的一件事做成了機制，就是「誰該做什麼」不能只寫在規則文件裡等模型自律，而要在工具呼叫這一層強制執行。

對於已經在用 AI CLI 工具、又開始在意帳單與上下文品質的開發者，這是一個安裝成本很低、可逐項開關、且附帶量測工具的起點。