多 Agent 團隊治理升級計畫
核心問題
我們的 11 agent 系統目前有三個結構性缺口:
- Agent 間資料流是間接的 — blog-writer 自己讀 explorer 的報告檔案,不是程式化傳遞
- 沒有結構化輸出驗證 — 信心評估是啟發式的,沒有 schema 強制
- 沒有團隊概念 — 11 個 agent 是扁平池,沒有角色、階段、治理結構
設計哲學
取各家精華,適配我們的規模(自託管、8 worker slot、TypeScript):
1 | CrewAI 的 YAML 宣告式定義 → soul/teams/*.json |
不做的事(研究後刻意排除):
- Temporal/Prefect 企業級編排器 — 超出規模
- A2A 跨組織協議 — 我們有 agent-bus
- 動態角色湧現 — 需大規模訓練
- Market-based 任務分配 — 11 agent 不需要拍賣
- 巢狀團隊 — 連 Claude Code Teams 都禁止
Phase 1:宣告式定義層(無引擎改動)
Team Templates — soul/teams/*.json
為三個常見工作流定義團隊模板:
| 團隊 | 成員 | 工作流 |
|---|---|---|
| content-pipeline | explorer → blog-writer | Sequential:研究 → 寫作 |
| market-intelligence | hackernews-digest + crypto-analyst → summarizer | Mixed:並行收集 → 綜合 |
| security-patrol | security-scanner + github-patrol → deep-researcher | Mixed:並行掃描 → 深入調查 |
每個模板定義:
- members — 角色(researcher/writer/reviewer)+ 目標 + 背景(CrewAI 式)
- workflow.stages — 多階段定義,含
inputFrom依賴和inputFilter - budget — 團隊總預算上限 + 每階段上限
- governance — 最低信心分、失敗策略(retry/skip/abort)
Output Schemas — src/agents/output-schemas.ts
用 zod 為每個 agent 定義預期輸出格式:
1 | export const ExplorerOutputSchema = z.object({ |
無 schema 的 agent 自動通過驗證(向後相容)。
Governance Skill
Markdown skill 注入 worker system prompt,讓 agent 知道自己的團隊角色和治理規則。
Phase 2:Pipeline 引擎(核心改動)
Pipeline Engine — src/agents/pipeline-engine.ts
核心設計:pipeline 不直接執行 agent,而是透過現有的 enqueueTask() 排入佇列。
1 | startPipeline("content-pipeline", "寫一篇關於 AI 治理的文章") |
這保證了預算、kill-switch、circuit-breaker 等安全機制自動適用。
Inter-Agent Result Passing
AgentTask 加入 pipelineContext 欄位。buildWorkerSystemPrompt() 將上游輸出組裝為「上游階段輸出」段落注入 system prompt。
Input Filters
命名過濾器:summary-only、findings-only、truncate-1000、json-only、blog-source-material。Team template 的 stage 指定過濾器名。
Phase 3:安全強化
Task-Scoped Permission Narrowing
受 Oso/Auth0 啟發。Pipeline 任務的權限從 role-level 收窄到 task-level:
1 | Before: explorer 可讀 soul/**, src/** |
Graduated Response
正式化四級漸進回應:
| 級別 | 閾值 | 行動 |
|---|---|---|
| WARN | 2 failures/24h | 記錄警告 |
| THROTTLE | 4 failures/24h | 降低排程頻率 |
| PAUSE | 6 failures/24h | 暫停 2 小時 |
| DISABLE | 10 failures/24h | 停用,需手動重啟 |
補充現有的 agent-tuner(週級排程優化)和 kill-switch(系統級 binary),填補中間的「個別 agent 近即時回應」空白。
Trust Boundary
Pipeline handoff 時強制驗證上游輸出。Phase 2 是 advisory(記錄但不阻擋),Phase 3 是 hard gate。信心分低於 governance.minConfidence 時觸發 escalateOnFailure 策略。
檔案清單
| 動作 | 檔案 | Phase | 行數 |
|---|---|---|---|
| CREATE | soul/teams/content-pipeline.json |
1 | ~40 |
| CREATE | soul/teams/market-intelligence.json |
1 | ~40 |
| CREATE | soul/teams/security-patrol.json |
1 | ~40 |
| CREATE | src/agents/team-config.ts |
1 | ~120 |
| CREATE | src/agents/output-schemas.ts |
1 | ~150 |
| CREATE | soul/skills/agent-governance.md |
1 | — |
| MODIFY | src/core/event-bus.ts |
1 | +7 events |
| CREATE | src/agents/pipeline-engine.ts |
2 | ~300 |
| CREATE | src/agents/input-filters.ts |
2 | ~80 |
| MODIFY | src/agents/worker-scheduler.ts |
2 | +context +validation |
| CREATE | src/agents/graduated-response.ts |
3 | ~200 |
| MODIFY | src/agents/agent-permissions.ts |
3 | +narrowing |
| MODIFY | src/agents/agent-config.ts |
3 | +pauseUntil |
總新增:~970 行 TypeScript + 3 JSON 模板 + 1 Skill
總修改:4 個現有檔案(全部向後相容)
設計原則
- 向後相容 — 所有新欄位都是 optional,現有 11 agent 不改設定也能正常運作
- 複用現有基礎 — pipeline 透過
enqueueTask()排任務,複用 budget/safety 機制 - 宣告式優先 — 團隊結構在 JSON 定義,不硬編碼在 TypeScript
- 漸進式部署 — 三個 Phase 獨立部署,每個都有回滾方案
- 適配規模 — 不照搬企業級框架,取設計原則而非實作細節
計畫由一見生財生成,基於五大框架調研和治理模式研究 | 2026-02-21