多代理人 AI 協作架構教學

多代理人協作架構概覽

四層級代理人分工，Codex 為核心協調者

1

Codex - 主協調者

負責任務拆解、資源排程、影像生成、檔案編輯、驗收與最終交付。保留核心決策權與專案所有權。

2

Antigravity IDE - 並行協調者

處理長時間運行、影片/字幕分析、多代理人並行分解、IDE 可視化進度。GUI 介面支援即時協作。

3

Gemini CLI - 雲端顧問

提供進階推理、網路檢索脈絡、跨工具綜合分析、Antigravity 後備方案。適合研究、規劃、程式碼審查。

4

Ollama - 本地草稿執行者

GPU/NPU 加速本地推論，生成初步草稿、摘要、重寫、翻譯、分類等低風險文字工作。預設模型 gemma3-tw-edu:4b。

架構關係圖

graph TB subgraph User["使用者層"] U[使用者需求] end subgraph Core["Codex 核心層"] C1[任務拆解] --> C2[資源排程] C2 --> C3[驗收交付] C1 -.-> C4[影像生成] C2 -.-> C5[檔案編輯] end subgraph Agents["外部代理人層"] A1[Antigravity IDE
並行協調] A2[Gemini CLI
雲端推理] A3[Ollama
本地草稿] end subgraph Skills["技能包層"] S1[external-agent-orchestrator] S2[skill-registry.yaml] S3[dispatch-task.ps1] S4[detect-tools.ps1] S5[log-event.ps1] end U --> C1 C1 -->|長期/媒體/並行| A1 C1 -->|研究/規劃/審查| A2 C1 -->|草稿/摘要/翻譯| A3 C1 --> S1 S1 --> S2 S1 --> S3 S3 --> S4 S3 --> S5 style Core fill:#dbeafe,stroke:#1e40af style Agents fill:#fef3c7,stroke:#92400e style Skills fill:#d1fae5,stroke:#065f46 style User fill:#e9d5ff,stroke:#6b21a8

工具偵測與路由策略

detect-tools.ps1 自動探測 + dispatch-task.ps1 智能分派

工具偵測流程

flowchart TD A[啟動 detect-tools.ps1] --> B{檢查 PATH} B -->|找到| C[available=true via=PATH] B -->|未找到| D{檢查預設路徑} D -->|找到| E[available=true via=fallback] D -->|未找到| F[available=false] C --> G[輸出 JSON] E --> G F --> G G --> H[回傳 dispatch-task.ps1]

自動路由決策邏輯

flowchart TD Task[任務描述] --> KW{關鍵字匹配} KW -->|圖片/資源| CodexOnly[Codex 獨佔] KW -->|影片/字幕| VR{Antigravity 可用?} VR -->|是| AG1[Antigravity + Gemini] VR -->|否| GM1[Gemini 後備] KW -->|平行/長時間| AR{Antigravity 可用?} AR -->|是| AG2[Antigravity + Gemini] AR -->|否| GM2[Gemini 後備] KW -->|本地/翻譯| OR{Ollama 可用?} OR -->|是| OL[Ollama] OR -->|否| Def{Antigravity 可用?} Def -->|是| AG3[Antigravity] Def -->|否| GM3{Gemini 可用?} GM3 -->|是| GM4[Gemini] GM3 -->|否| OL2{Ollama 可用?} OL2 -->|是| OL3[Ollama] OL2 -->|否| Err[錯誤: 無可用工具] style CodexOnly fill:#dbeafe,stroke:#1e40af style VR fill:#fef3c7,stroke:#92400e style AR fill:#fef3c7,stroke:#92400e style OR fill:#d1fae5,stroke:#065f46

派發模板系統

@(
  "research" = @{ targets=@("gemini","ollama","antigravity"); model="gemma4:e4b"
    gemini="首席研究員：比較方案、建議"; ollama="本地分析師：摘要、清單"; antigravity="分解助手：平行子任務" }
  "agent-collab" = @{ targets=@("antigravity","gemini","ollama")
    gemini="雲端顧問：複雜推理"; ollama="本地執行者：摘要/翻譯"; antigravity="IDE協調者：長期工作" }
  "translation" = @{ targets=@("ollama") }
  "video-analysis" = @{ targets=@("antigravity","gemini") }
  "subtitle" = @{ targets=@("antigravity","gemini") }
)

後備策略

✓ Antigravity 不可用 → 回退 Gemini CLI
✓ 影片/字幕雙方不可用 → 停止，不路由給 Ollama
✓ 明確指定工具不可用 → 記錄錯誤並中止
✓ 僅一工具可用 → 最高價值階段使用，整合留給 Codex
✓ 需即時資訊/高風險 → 記錄例外並升級

技能包管理與版本控管

skill-registry.yaml 統一註冊、依賴關係宣告、SHA-256 驗證

技能註冊結構

schema_version: 1
audited_at: "2026-07-23"
policy: "Codex owns implementation and validation; Ollama is a reviewed low-risk draft option."
skills:
  - name: external-agent-orchestrator
    short_description: "Auditable cross-tool coordination"
    applies_to: "Cross-tool, long-running, or evidence-logged work"
    excludes: "Ordinary simple questions"
    dependencies: ollama-simple-answer-review
    version: "2"
  - name: crossref-apa-bibliography
    dependencies: documents, spreadsheets
    version: "1"
  - name: journal-manuscript-writer
    dependencies: crossref-apa-bibliography, documents, pdf
    version: "1"
  - name: ena-network-figure
    dependencies: journal-manuscript-writer
    version: "1"
  - name: pd-survey-analysis-report
    dependencies: spreadsheets, documents, ena-network-figure
    version: "1"

依賴關係圖（箭頭指向依賴項）

graph TD subgraph Core[核心協調] EAO[external-agent-orchestrator v2] OSAR[ollama-simple-answer-review v2] end subgraph Research[研究文獻] CAB[crossref-apa-bibliography v1] CIPD[crossref-indigenous-proposal-docx v1] end subgraph Writing[寫作出版] JMW[journal-manuscript-writer v1] ENA[ena-network-figure v1] end subgraph Analysis[分析報告] PDS[pd-survey-analysis-report v1] end subgraph Media[媒體處理] CHAV[create-html-animation-video v1] EYVS[edit-youtube-vertical-shorts v1] VAP[video-automation-pipeline v1] end subgraph Teaching[教學教材] TPTS[textbook-photo-to-teaching-slides v1] PFTS[photo-folder-to-slides v1] end EAO --> OSAR OSAR --> EAO CIPD --> CAB JMW --> CAB ENA --> JMW PDS --> ENA CHAV --> VAP EYVS --> CHAV EYVS --> VAP VAP --> CHAV VAP --> EYVS style EAO fill:#dbeafe,stroke:#1e40af style JMW fill:#fef3c7,stroke:#92400e style PDS fill:#d1fae5,stroke:#065f46 style VAP fill:#e9d5ff,stroke:#6b21a8

版本控管與驗證

Git 版本控管

• 獨立 Git repo 或 monorepo
• Semantic versioning
• CHANGELOG.md 記錄破壞性變更

SHA-256 驗證

• quick_validate.py 計算雜湊
• 對照 registry 記錄值
• 損壞時自動封鎖

依賴解析

1. 拓樸排序依賴圖
2. 先載入無依賴基礎技能
3. 循環依賴檢測報錯

實作範例與最佳實踐

dispatch-task.ps1 實戰派發、日誌記錄、雙語報告產出

範例 1：研究型派發

powershell -ExecutionPolicy Bypass -File ".\scripts\dispatch-task.ps1" 
  -Task "比較三種 RAG 架構優劣並推薦" 
  -Template research -Target auto 
  -ContextFiles @("docs/rag-options.md") 
  -OutputRoot "C:\Projects\outputs\rag-research"

輸出：.external-agent-orchestrator/logs/runs/20260728-XXXXX/ 含 request.txt、gemini.md、ollama.md、antigravity-launch.md、manifest.json

範例 2：多代理人協作

powershell -ExecutionPolicy Bypass -File ".\scripts\dispatch-task.ps1" 
  -Task "設計教學網站架構文件" 
  -Template agent-collab -Target all 
  -ContextFiles @(
    "skills/external-agent-orchestrator/SKILL.md",
    "skills/external-agent-orchestrator/scripts/dispatch-task.ps1",
    "skills/skill-registry.yaml"
  ) 
  -OutputRoot "C:\Projects\opencodex\teaching-site"

日誌格式 (JSONL)

{
  "timestamp": "2026-07-28T07:05:38.329+08:00",
  "actor": "ollama",
  "event": "run-complete",
  "status": "ok",
  "summary": "Ollama dispatch completed with model gemma3-tw-edu:4b.",
  "task": "教學網站架構文件設計",
  "outputs": ["<project-root>\outputs\<run-id>\ollama.md"],
  "cwd": "<project-root>"
}

最佳實踐檢查清單

任務分派前

☐ 執行 detect-tools.ps1 確認工具可用性
☐ 根據任務類型選擇適當模板
☐ 準備 ContextFiles（絕對路徑）
☐ 設定 OutputRoot 至專案專屬目錄

執行中與事後

☐ 每關鍵步驟呼叫 log-event.ps1
☐ 保留 manifest.json 供審計追蹤
☐ 產出雙語 HTML/DOCX 過程報告
☐ 視覺化圖表經人工目視 QA 後交付

視覺化流程圖 (Mermaid)

完整派發生命週期、工具選擇決策樹、技能依賴拓撲

開啟中英文 SVG 圖集

派發生命週期

sequenceDiagram participant U as 使用者 participant C as Codex participant D as detect-tools participant P as dispatch-task participant L as log-event participant T as 目標工具 participant M as manifest U->>C: 提交任務 C->>D: 偵測工具 D-->>C: JSON 對應表 C->>P: 呼叫派發 P->>L: tool-selection P->>P: 解析模板 P->>P: 建立 run 目錄 P->>P: 寫入 request.txt loop 每個目標 P->>L: run-start P->>T: 執行工具 T-->>P: 結果 P->>L: run-complete/failure P->>P: 儲存輸出 end P->>M: 產生 manifest P->>L: artifact-created M-->>C: 執行清單 C->>U: 交付成果

工具選擇決策樹

flowchart TD S([開始]) --> TM{有模板?} TM -->|是| UT[使用模板目標] TM -->|否| AT[分析關鍵字] AT --> IK{圖片關鍵字?} IK -->|是| CO[Codex 獨佔] IK -->|否| VK{影片關鍵字?} VK -->|是| CA1{Antigravity?} CA1 -->|是| TA1[Antigravity + Gemini] CA1 -->|否| CG1[Gemini] VK -->|否| PK{平行關鍵字?} PK -->|是| CA2{Antigravity?} CA2 -->|是| TA2[Antigravity + Gemini] CA2 -->|否| CG2[Gemini] CG2 -->|否| CO1{Ollama?} CO1 -->|是| TO1[Ollama] CO1 -->|否| ER2[錯誤] PK -->|否| LK{本地關鍵字?} LK -->|是| CO2{Ollama?} CO2 -->|是| TO2[Ollama] CO2 -->|否| CA3{Antigravity?} CA3 -->|是| TA3[Antigravity] CA3 -->|否| CG3{Gemini?} CG3 -->|是| TG3[Gemini] CG3 -->|否| ER3[錯誤] LK -->|否| DR{預設路由} DR --> CA4{Antigravity?} CA4 -->|是| TA4[Antigravity] CA4 -->|否| CG4{Gemini?} CG4 -->|是| TG4[Gemini] CG4 -->|否| CO3{Ollama?} CO3 -->|是| TO3[Ollama] CO3 -->|否| ER4[錯誤] style CO fill:#dbeafe,stroke:#1e40af style TA1 fill:#fef3c7,stroke:#92400e style TA2 fill:#fef3c7,stroke:#92400e style TO1 fill:#d1fae5,stroke:#065f46 style TO2 fill:#d1fae5,stroke:#065f46 style ER2 fill:#fee2e2,stroke:#dc2626 style ER3 fill:#fee2e2,stroke:#dc2626 style ER4 fill:#fee2e2,stroke:#dc2626

技能依賴拓撲

graph LR subgraph L0[Layer 0: 核心與基礎技能] EAO[EAO] OSAR[OSAR] BKN[BKN] HZT[HZT] ERG[ERG] HP[HP] end subgraph L1[Layer 1: 應用技能] CAB[CAB] CHAV[CHAV] EYVS[EYVS] TPTS[TPTS] PFTS[PFTS] PDS[PDS] VAP[VAP] end subgraph L2[Layer 2: 研究與寫作] CIPD[CIPD] JMW[JMW] end subgraph L3[Layer 3: 分析延伸] ENA[ENA] end EAO --> OSAR OSAR --> EAO CIPD --> CAB JMW --> CAB ENA --> JMW PDS --> ENA CHAV --> VAP EYVS --> CHAV EYVS --> VAP VAP --> CHAV VAP --> EYVS classDef l0 fill:#dbeafe,stroke:#1e40af classDef l1 fill:#fef3c7,stroke:#92400e classDef l2 fill:#e9d5ff,stroke:#6b21a8 classDef l3 fill:#d1fae5,stroke:#065f46 class EAO,OSAR,BKN,HZT,ERG,HP l0 class CAB,CHAV,EYVS,TPTS,PFTS,PDS,VAP l1 class CIPD,JMW l2 class ENA l3

讀圖提醒：先處理循環依賴

目前註冊表中的 external-agent-orchestrator 與 ollama-simple-answer-review，以及部分媒體技能，存在雙向依賴。圖中保留這些關係作為稽核訊號；若載入器要求嚴格的有向無環圖，應先調整註冊表，再執行拓樸排序。

參考檔案與配置說明

專案實際檔案路徑與關鍵配置摘要

核心檔案清單

檔案路徑	用途	關鍵內容
skills/external-agent-orchestrator/SKILL.md	技能主文件	路由政策、日誌規範、報告生產、派發模板
skills/external-agent-orchestrator/scripts/detect-tools.ps1	工具偵測	PATH + fallback 路徑解析，輸出 JSON
skills/external-agent-orchestrator/scripts/dispatch-task.ps1	任務派發	模板系統、自動路由、Manifest 產生、DryRun
skills/external-agent-orchestrator/scripts/log-event.ps1	結構化日誌	JSONL 格式、重試寫入、actor/event/status
skills/external-agent-orchestrator/scripts/read-log.ps1	日誌查閱	Tail/JSON/表格輸出、過濾器
skills/skill-registry.yaml	技能註冊表	版本、依賴、適用/排除範圍、政策聲明
.external-agent-orchestrator/logs/agent-events.jsonl	執行日誌	所有派發事件的不可變記錄
.external-agent-orchestrator/logs/runs/	執行成果	每次派發的獨立目錄含 manifest.json

環境路徑配置

SKILL_ROOT = "<user-home>\.codex\skills\external-agent-orchestrator"
PROJECT_STATE = "<project-root>\.external-agent-orchestrator"
EVENT_LOG = "<project-root>\.external-agent-orchestrator\logs\agent-events.jsonl"
RUNS_ROOT = "<project-root>\.external-agent-orchestrator\logs\runs"

gemini: <user-profile>\AppData\Roaming\npm\gemini.ps1
ollama: <user-profile>\AppData\Local\Programs\Ollama\ollama.exe
antigravity: <install-root>\Antigravity IDE\bin\antigravity-ide.cmd

Ollama 模型清單

模型	大小	用途	備註
gemma3-tw-edu:4b	3.3 GB	教學/繁中優化	預設首選 ✓
gemma4:e4b	9.6 GB	高品質通用	dispatch-task fallback
gemma3n:e4b	7.5 GB	新架構實驗
qwen3:4b	2.5 GB	中文/多語言	輕量備選
minicpm-v:latest	5.5 GB	視覺模型	圖文混合任務

多代理人 AI 協作架構教學 基於 external-agent-orchestrator Skill v2 實作