代理團隊互動模型
架構層 •
Version 1.0 •
概述
SuperPortia 採用 Team Topologies 框架定義 Agent 間的互動模式。每個 Agent 都有明確的合約卡（Contract Card）、輸入/輸出規格、SLA，以及故障模式。這套模型確保 Agent 協作是可預測的、可審計的、可回滾的。
Team Topologies 四種互動模式
1. X-as-a-Service（服務型）
一個 Agent 提供標準化服務，呼叫方只需知道 API，不需了解實作細節。
SuperPortia 範例：
- Cloud UB Worker 對所有 Agent 提供
ingest_fragment / search_brain / promoteAPI - MCP Server 對 Claude Code 提供統一工具介面
- SRE Patrol 對所有服務提供健康狀態查詢
2. Collaboration（協作型）
兩個 Agent 短期緊密合作完成複雜任務，完成後恢復獨立。
SuperPortia 範例：
- Opus + Sonnet subagent 協作完成大型 WO（Opus 設計 + Sonnet 實作）
- Opus + Codex CLI 協作進行架構 Review（Opus 提問 + Codex 分析）
3. Facilitating（促進型）
一個 Agent 協助另一個 Agent 克服技術障礙或知識盲點，完成後退出。
SuperPortia 範例：
- Gemini CLI 對 Opus 提供 PK 研究支援（Opus 問 → Gemini 研究 → Opus 消化並決策）
- SRE Agent 對開發 Agent 提供監控數據（SRE 提供事實，不干涉開發決策）
4. Platform（平台型）
一個 Agent 或系統作為基礎設施，所有其他 Agent 都建立在其之上。
SuperPortia 範例：
- Obsidian Vault — 所有 Agent 的本地知識庫
- Cloud UB (D1 + Vectorize) — 所有 Agent 的雲端知識 SSoT
- GitHub — 所有 Agent 的程式碼 SSoT
Agent 名冊（14 個）
| # | Agent 名稱 | 模型 | Ship | 角色 | 通訊協議 |
|---|---|---|---|---|---|
| 1 | 小克（Mac CLI 小克 2） | Claude Opus 4.6 | SS1 | 首席工程官；Orchestrator | Claude Code CLI session |
| 2 | Sonnet Executor | Claude Sonnet 4.x | SS1/SS2 | 程式碼實作 Executor | Agent tool (subagent) |
| 3 | Haiku Executor | Claude Haiku 3.5 | SS1 | 批次資料操作 Executor | Agent tool (subagent) |
| 4 | Codex Review Agent | GPT-5.4 (OpenAI) | SS1 | 程式碼 Review / 架構第二意見 | codex exec via Bash |
| 5 | Gemini Research Agent | Gemini 3 (Google) | SS1 | PK 研究 / 批次草稿 | echo | gemini via Bash |
| 6 | boiler_grandpa | DeepSeek V3 | SS3 | MTAAA 文字分類（排程） | Python script (launchd) |
| 7 | UB Worker | Cloudflare Workers Runtime | SS3 | Universal Brain API | HTTP REST (MCP tool) |
| 8 | SRE Patrol | Bash script | SS1 | 服務健康巡邏 | launchd (15min cron) |
| 9 | SRE Dispatch | Bash script | SS1 | 異常事件 → WO 建立 | launchd trigger |
| 10 | Email Intake Agent | CF Worker + Claude Haiku | SS3 | 電子郵件分類 → UB | Cloudflare Worker |
| 11 | Portia Scout | CF Worker | SS3 | RSS 監控 → UB ingest | Cloudflare cron trigger |
| 12 | PAM Agent | Claude Sonnet | SS1 | 工單生命週期自動管理 | Phase 1 (in progress) |
| 13 | SS2 Windows 執行者 | Claude Code Sonnet | SS2 | Windows 環境執行 | Claude Code CLI session |
| 14 | KOL Pipeline Agent | Python + Apify | SS1 | Facebook KOL 爬取 → UB | Python script (manual) |
每 Agent 合約卡
合約卡：小克（Opus）— 首席工程官
| 欄位 | 內容 |
|---|---|
| Input | 夏哥指令（WO / chat）、mailbox 消息、compaction summary |
| Output | WO 建立、dispatch 指令、架構決策、完工報告、UB 入庫 |
| SLA | 即時回應（同步 session），任務完成前不結束 |
| 故障模式 | Context 滿 → compaction 後按 Protocol 恢復；API 不可用 → 回報夏哥 |
| 不做的事 | 重複性編碼（→ dispatch Sonnet）、外部 API 研究（→ Gemini） |
| 信任區域 | Zone 1 |
合約卡：Sonnet Executor
| 欄位 | 內容 |
|---|---|
| Input | WO ID + context，在 worktree 內執行 |
| Output | 程式碼變更、CHANGELOG 更新、WO 狀態更新至 review |
| SLA | 120 秒 subagent timeout；無 retry（由 Opus 決定是否重派） |
| 故障模式 | 輸出品質不過 → Opus re-dispatch（max 2 次）；超時 → Opus 升級 |
| 不做的事 | Production deploy（需 HITL）、spawn sub-subagents（不支援） |
| 信任區域 | Zone 2 |
合約卡：Codex Review Agent
| 欄位 | 內容 |
|---|---|
| Input | 程式碼段落 / 架構說明（via stdin） |
| Output | Review comments，建議，架構替代方案 |
| SLA | codex exec 非互動式，30-60 秒 |
| 故障模式 | 輸出可能過時（訓練截止）→ 只作參考，不直接採用 |
| 不做的事 | 重要決策（→ Opus 最終決定）、寫入檔案（exec 模式為 read-only） |
| 信任區域 | Zone 3 |
合約卡：Gemini Research Agent
| 欄位 | 內容 |
|---|---|
| Input | 研究 prompt（via stdin echo | gemini） |
| Output | 研究報告、2026 最新實踐摘要、PK 驗證結果 |
| SLA | 通常 10-30 秒；免費 1000 req/day 限額 |
| 故障模式 | 已知幻覺問題 — 重要決策必須 cross-check；不可單獨使用 |
| 不做的事 | 寫入 repo 檔案（workspace only）、重要決策 |
| 信任區域 | Zone 3 |
合約卡：boiler_grandpa — MTAAA 分類
| 欄位 | 內容 |
|---|---|
| Input | UB Dock 中 status: pending 的 entries（批次拉取） |
| Output | 分類後 promote 到 classified_entries（Topic / Type / Lifecycle） |
| SLA | 每 5 分鐘執行一次；每批最多 50 筆 |
| 故障模式 | DeepSeek API 不可用 → entries 留在 Dock，積壓；fallback 策略 Task #65 |
| 不做的事 | 修改 entry 的 title/content；部署；工單操作 |
| 信任區域 | Zone 4 |
合約卡：UB Worker
| 欄位 | 內容 |
|---|---|
| Input | HTTP REST 請求（ingest_fragment, search_brain, promote, get_entry） |
| Output | JSON 回應（entry ID、搜尋結果、狀態） |
| SLA | Cloudflare Workers p99 < 100ms；D1 讀寫 < 50ms |
| 故障模式 | CF 平台故障（rare）→ 請求排隊，session 結束前補錄 |
| 不做的事 | WO 核准（需 curl PATCH）、部署判斷 |
| 信任區域 | Zone 4 |
Dispatch 決策矩陣
| 任務類型 | 第一選擇 | Fallback | 理由 |
|---|---|---|---|
| 程式碼實作（WO） | Sonnet subagent（worktree） | Codex full-auto | Sonnet 原生 file access，worktree 隔離 |
| 程式碼 Review / 審計 | Codex exec（read-only） | Sonnet subagent | Codex = 免費第二意見，交叉驗證 |
| PK 研究 / 最新實踐 | Gemini CLI | Sonnet subagent | Gemini = 免費，1000 req/day |
| 批次資料操作 | Haiku subagent | Gemini CLI | Haiku 最便宜的 Claude 模型 |
| 架構 Review | Codex exec（high reasoning） | Opus 直接分析 | 跨模型驗證架構決策 |
| Vault note 撰寫 | Sonnet subagent | Haiku subagent | 需要 file write access |
| 外部 API 整合研究 | Gemini CLI | Sonnet subagent | PK 時效性問題；Gemini 最新訓練 |
| UB 知識入庫 | Opus 直接呼叫 | 任何 Agent 均可 | UB ingest 是所有 Agent 的基礎操作 |
| 事故診斷（P0） | Opus 直接執行 | Sonnet subagent | P0 需要最高推理能力 |
| 重複性格式轉換 | Haiku subagent | Gemini CLI | 無需高推理能力，降低成本 |
已知限制
1. 不支援巢狀 Dispatch（No Nested Dispatch）
Subagent（Sonnet/Haiku）不能 spawn 自己的 sub-subagents。所有 dispatch 必須從 Opus（Zone 1）發起。
違反此限制的後果：任務掛起無回應，context 浪費，Opus 無法追蹤子任務狀態。
2. Codex Sandbox 限制
codex exec 預設為 read-only 模式。需要 file write 時，必須加 -c 'approval_mode="full-auto"'，且需要夏哥確認（有安全風險）。
3. Gemini 幻覺問題
Gemini 在重要事實查核上有已知幻覺。規則：
- 可以: 用 Gemini 做初步研究、草稿生成、方向探索
- 不可以: 用 Gemini 的輸出直接作為重要技術決策的唯一依據
- 必須: 交叉驗證（Opus 判斷 + 必要時 Sonnet 確認）
4. 並發限制
SS1 Mac M3 實務並行上限：3-5 個 subagents。超過後系統回應變慢，subagent 輸出延遲。監控方式：
# 監控 Claude API 用量
npx ccusage session --since YYYYMMDD
# 監控跨 Agent 總用量
tokscale models5. Codex / Gemini 無 MCP Tools
codex exec 和 gemini CLI 在非互動模式下無法呼叫 MCP tools（包括 UB Worker）。這些 Agent 只能讀寫本地檔案和呼叫外部 API，不能直接 ingest 到 UB。需要 UB 操作時，必須由 Opus 執行或 Sonnet subagent 執行。