多代理 CLI 協作 — Opus 指揮、Sonnet 執行、Codex 審查

多代理系統在論文裡很美好，在 production 裡卻充滿細節。

這篇文章不是架構願景，是一份操作手冊。SuperPortia 目前在真實工作流程中同時運行 Opus、Sonnet、Haiku、Codex CLI（GPT-5.4）和 Gemini CLI（Gemini 3）。每個引擎都有它的位置，每個位置都有它的代價。

派遣紀律的背後設計參考 Orchestrator 紀律方法論；關於 Thariq 的 Skills 架構如何影響這套設計，詳見 Thariq Agent Skills 完整指南。

團隊組成：五個引擎，各司其職

Claude Code Opus — 首席工程師

Opus 是整個系統的大腦。它負責架構設計、關鍵決策、派遣任務、審查結果。它不寫重複性程式碼、不搜資料、不做格式轉換——這些都是「Opus 的浪費」。

成本是真實的：Opus 每百萬 token 輸入 $15、輸出$ 75（Claude API 定價）。在 SuperPortia 的 cost-awareness.md 規則裡，這條原則是強制行為，不是建議：

「Don’t: Repetitive coding, data searching, format conversion, long explanations of simple concepts.」

Opus 的工作是思考和委派，不是執行。

Claude Sonnet — 主要執行者

Sonnet 處理絕大多數的程式實作工作。它有完整的檔案讀寫權限、可以呼叫 MCP 工具（包括 UB 知識庫搜尋、Obsidian vault 操作），還能以 worktree 隔離的方式平行處理多個任務。

成本： $3 輸入 /$ 15 輸出（每百萬 token）。大約是 Opus 的五分之一。

Sonnet 最適合的場景：複雜的程式實作、Vault 筆記寫作、需要 MCP 工具鏈的任務。每個 Sonnet subagent 在自己的 worktree 裡工作，不互相干擾。

Claude Haiku — 批次處理引擎

Haiku 是最便宜的 Claude 模型（ $1 輸入 /$ 5 輸出），適合大量、低複雜度的操作。知識庫分類、批次資料處理、需要跑很多次的反覆工作——這些是 Haiku 的領域。

在 MTAAA（Multi-dimensional Taxonomy & Auto-classification Architecture）分類管線中，Haiku 就是 boiler_grandpa_v2.py 用來分類 UB Dock 待分類條目的引擎。

Codex CLI（GPT-5.4）— 審查員

Codex CLI 的定位不是主力執行，而是「第二意見」。透過 echo "prompt" | codex exec 的方式非互動執行，Codex 可以對 Claude 的輸出提供跨模型審查。

成本來自 ChatGPT Plus/Pro 訂閱，每月固定費用，不計 token。這讓它特別適合作為代碼審查和架構評估的免費額外把關層——在 token 預算上幾乎沒有額外成本。

Codex 的限制：它不讀 .claude/rules/，不知道 SuperPortia 的內部規範，不能呼叫 MCP 工具。提示裡必須把足夠的 context 帶進去，否則它的回應會是通用建議，而非針對系統的判斷。

Gemini CLI（Gemini 3）— 情報員

Gemini CLI 透過 Google OAuth 免費使用，每天 1000 個請求配額。echo "研究問題" | gemini 的方式非常適合做 PK（Perishable Knowledge）驗證——工具版本、API 異動、生態系現況。

但 Gemini 有已知的幻覺問題。SuperPortia 的規則白紙黑字：絕不用於重要決策，輸出必須事後核實。它是情報員，不是決策者。另一個限制：Gemini CLI 沙箱不允許寫檔案，它的研究結果必須由 Claude subagent 接手才能落地。

實際指令：如何非互動呼叫各引擎

# Gemini CLI — 免費 PK 研究（每日 1000 次）
echo "What is the current Astro 6 content collections API for date fields?" | gemini

# Codex CLI — 非互動架構審查（唯讀沙箱）
echo "Review this dispatch packet design for correctness: $(cat dispatch.md)" | codex exec

# Claude subagent（via Agent tool，embedded prompt）
# objective: 寫 Thariq Skills 總文
# inputs: vault notes Thariq Skills.md
# outputs: src/content/posts/thariq-agent-skills-complete-guide.md
# owner: sonnet | done_criteria: file exists + >800 words + build pass

# tokscale — 跨引擎成本追蹤
tokscale models

# ccusage — Claude session 細粒度成本
npx ccusage session --since 20260318

免費引擎優先原則

每次準備呼叫 Claude subagent 前，先問：Gemini CLI 能做嗎？Gemini 每天 1000 次免費配額，適合 PK 研究、草稿、資料查詢。只有 Gemini 做不到（需要寫檔案、呼叫 MCP 工具）的任務，才升到 Sonnet。Codex 則專門用於程式碼和架構的第二意見審查，不計 token 費用。

Gemini 幻覺不能直接用於決策

SuperPortia 在 2026-03-17 的 PK 驗證工作中，Gemini 回報了錯誤的 CLI 預設模型（顯示免費版預設，而非付費訂閱版的實際模型）。規則是：Gemini 輸出必須與本地環境或已知文件交叉核實後才能使用。它是情報員，不是決策者。

調度矩陣：什麼任務給誰

SuperPortia 的 orchestrator-baseline.md 裡有一張經過實戰驗證的派遣決策表：

任務類型	首選	備選	理由
程式實作	Sonnet subagent（worktree 隔離）	Codex full-auto	Sonnet 有原生檔案存取權限
代碼審查／審計	Codex exec（唯讀）	Sonnet subagent	Codex = 免費的第二意見
PK 研究	Gemini CLI	Sonnet subagent	Gemini = 免費，每日 1000 次
批次資料操作	Haiku subagent	Gemini CLI	Haiku 是最便宜的 Claude 模型
架構評審	Codex exec（高推理模式）	—	跨模型交叉驗證
Vault 筆記寫作	Sonnet subagent	Haiku subagent	需要完整的檔案寫入權限

這張表有一個核心原則：免費引擎優先。在選 Claude subagent 之前，先問：Gemini 能做嗎？能的話就用 Gemini。同樣地，Codex 審查和 Haiku 批次操作都比 Opus 親自下場便宜得多。

另一個核心原則是平行化。如果多個任務不共享檔案，就同時派遣，不要等待。一個 Opus 可以同時派遣三個 Sonnet、一個 Gemini、一個 Codex——只要它們的工作範圍不重疊。

實戰範例：部落格改版任務的流動

2026-03-18 的部落格改版（superportia-agentic-v2 網站重建）是一個具體例子，展示這套流程如何在真實工作中運作。

夏哥給出需求：Astro 網站改版，需要新的配色主題、字型規範、部落格側欄、留言元件。

Opus 拆解計劃：

調度 Gemini CLI 做 PK 驗證——確認 Astro 6 的 content collections API 現況
同時派遣三個 Sonnet subagent：
- Sonnet-1 負責主題色系和 CSS 變數（worktree: agent-theme-001）
- Sonnet-2 負責部落格側欄元件（worktree: agent-blog-001）
- Sonnet-3 負責本地化字串 53 條英翻中（worktree: agent-i18n-001）
三個 subagent 完成後，Codex exec 審查 CSS 架構
Opus 整合結果，與夏哥確認視覺效果

品質關卡：每個 subagent 回來後，Opus 逐項驗證：輸出檔案是否存在？檔案大小合理嗎？內容有具體數值還是模糊描述？Wikilink 指向真實的筆記嗎？有沒有修改到被指定範圍外的檔案？

任何一項不過，就重新派遣——這次帶更清晰的指令，或升級到更強的模型。

這個流程比「Opus 自己做完所有事」快了大約三倍，成本大約是五分之一。

踩過的坑：四個真實限制

坑一：不能有巢狀 subagent

Sonnet subagent 不能再派遣自己的 subagent。整個系統是扁平的：Opus 派遣，subagent 執行，回報給 Opus，僅此而已。如果一個任務需要多層協調，Opus 必須親自承擔那個協調角色，不能把它轉包給 Sonnet。

這個限制在設計任務拆解時必須牢記：每個派遣單元必須是可以獨立完成的原子任務。

坑二：Codex exec 預設唯讀

codex exec 的預設模式是唯讀沙箱。如果需要 Codex 寫檔案，必須加上 -c 'approval_mode="full-auto"' 參數。這個細節很容易忽略，結果 Codex 跑完一輪什麼都沒有寫到磁碟——任務看起來成功了，但輸出不見了。

SuperPortia 的實踐是：Codex 只做審查，不做寫入。寫入工作交回 Sonnet subagent 處理。

坑三：Gemini 的幻覺不能信任

Gemini 在 PK 研究上很有用，但它的輸出不能直接作為決策依據。這不是理論擔憂——SuperPortia 在 2026-03-17 的 PK 驗證工作中，Gemini 回報了 Codex CLI 和 Gemini CLI 各自的預設模型，結果和實際登入後的付費訂閱版本不一樣。原因是：公開文件顯示的是免費版預設值，付費訂閱版本在登入後有不同的預設——Gemini 看不到登入後的狀態。

規則是：Gemini 的輸出必須與本地環境、已知文件、或其他來源交叉核實後才能使用。

坑四：Worktree 隔離的邊界

每個 Sonnet subagent 在自己的 git worktree 裡工作，確保它們不會互相踩到對方的修改。但 worktree 有一個容易踩的坑：.claude/ 設定目錄的路徑。

主 checkout 的 .claude/hooks/ 和 worktree 裡的 .claude/hooks/ 是不同的。如果一個 subagent 修改了「它所在的 worktree」的 hook，主 checkout 不會看到這個改動。反過來也是如此——在主 checkout 裡修改 hook，worktree 裡跑的 subagent 可能還在用舊版本。

解法：任何影響執行中服務的修改，先用 ps aux | grep <service> 確認哪個路徑在跑，再去那個路徑修改。

Thariq 的啟發：Anthropic 工程師的現場課

Thariq（@trq212，Anthropic 工程師）在 2026-03-17 發布的 “How We Use Skills” 和稍早的 “Seeing like an Agent”，直接對應了 SuperPortia 多代理系統的幾個設計決策。

漸進式揭露是系統架構，不只是技巧

Thariq 描述了 Claude Code 的 context 演進過程：從把所有文件塞進 system prompt（「context rot」），到讓 Claude 自己用 grep 找 context，再到透過 skills 的巢狀引用結構讓 Claude 主動發現所需內容。

SuperPortia 的 L1（CLAUDE.md）→ L2（Rules，每次都載入）→ L3（Skills，按需載入）架構，正是這個 Progressive Disclosure 模式的實踐。

但 Thariq 指出了一個 SuperPortia 尚未做到的層次：技能內部的 Hub + Spoke 結構。目前大多數 SP skills 都是單一扁平的 SKILL.md 檔案。Thariq 建議的做法是：SKILL.md 作為入口點，細節拆分到子檔案——例如 task-dispatch/dispatch-matrix.md 和 task-dispatch/gotchas.md。Agent 在需要時才讀入細節，而不是一次載入所有內容。

Gotchas 區塊是 skill 裡信號最高的內容

Thariq 明確說：「Gotchas 區塊是任何 skill 中信號最高的內容。每次 Claude 踩坑就加一行，持續累積。」

這個原則在多代理系統裡尤其重要。每次 Codex 的沙箱限制讓任務失敗、每次 Gemini 的幻覺導致重工、每次 worktree 路徑搞混——這些都應該變成 gotchas.md 裡的一行，讓下一次的 agent 不用重新踩同一個坑。

SuperPortia 的 corrections.md 規則扮演了類似角色，但它是全域的（所有 agent 都載入）。Thariq 的模式更細粒度——每個 skill 有自己的 gotchas，只有使用那個 skill 的 agent 才需要載入。

工具是模型能力的鏡子

Thariq 在 “Seeing like an Agent” 裡提出的核心洞見：工具設計必須跟上模型能力的進化。他的例子是 TodoWrite 工具——在舊模型上是必要的輔助，在新模型上反而成了限制，讓 agent 以為自己必須嚴格遵守而不敢調整計劃。

對應到 SuperPortia：boiler_grandpa_v2.py 的「每五輪插入 system reminder」機制，在當時的 Haiku 版本上是必要的。但新版模型是否還需要這個？這是一個需要實驗驗證的問題，不能靠假設回答。

同樣地，每次引入新版 Claude（Sonnet → Sonnet 4.5 → Sonnet 4.6），都應該重新評估：哪些現有的 scaffolding 已經成了限制而非輔助？

成本追蹤：量化多代理的實際花費

理論上多代理節省成本，但「節省」需要量化。SuperPortia 用三個工具追蹤：

/usage：Claude Code 內建指令，顯示當周使用量百分比。Sonnet 在週配額的 3% 是健康水位；超過 50% 就要放慢。
tokscale models：本地工具，跨引擎匯總——Claude（各型號）+ Gemini + Codex 的使用量都在同一個視圖裡。
npx ccusage session --since YYYYMMDD：Claude 的細粒度 session 成本，適合在大量派遣後做事後核算。

這些工具配合使用，能讓 Opus 在一次重度派遣後快速判斷：這輪的成本結構是否合理？下次應該更多用 Gemini 替換 Sonnet，還是反過來？

結語：扁平艦隊，不是層級體系

多代理系統很容易演變成複雜的層級——orchestrator 指揮 sub-orchestrator，sub-orchestrator 再指揮 worker。理論上彈性，實際上脆弱。

SuperPortia 目前的實踐是保持扁平：Opus 是唯一的指揮層，所有執行者直接向它回報。這不是因為更深的層級不可能，而是因為目前沒有驗證它的必要性——而「verified capability」是 SuperPortia 的設計原則之一。

Thariq 說：「Experiment often, read your outputs, try new things. See like an agent.」

這句話的關鍵在後半段：read your outputs。每一次派遣的結果都是系統的學習資料。每一個 gotcha 都應該變成 skill 裡的一行。每一次模型升級都是重新校準工具假設的機會。

多代理協作不是一次性的架構決策，而是一個持續進化的操作實踐。