# Orkestra：大規模協調 AI 代理

Canonical source: https://maguyva.ai/zh-hant/blog/orkestra-agent-orchestration

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-01-06 · Author: Maguyva Team

> 一個協調器將工作分派給各具專長技能與記憶的專家 AI 代理。以下說明 Orkestra 如何在正式環境中協調 46 個代理與 466 項技能。

> *本文中的數字反映發布當下（2026 年 1 月）的系統狀態。目前最新數字請參見我們的[團隊頁面](/zh-hant/team)。*

當我們開始使用 Claude Code 進行開發時，遇到了每個使用 AI 程式設計助理的團隊終究都會碰上的問題：單一代理無法把每件事都做好。

你可以提示一個代理扮演資料庫專家，或是安全稽核員，或是前端工程師。但只要你同時要求它身兼這三種角色，品質就會下滑：情境被稀釋，指令彼此矛盾，代理變成一個什麼都懂一點、卻什麼都做得平庸的通才。

於是我們打造了 Orkestra。

## 什麼是 Orkestra？

Orkestra 是專為 Claude Code 及類似 AI 程式設計工具打造的代理協調系統。它會在單一協調器之下，統籌多個各具專長的專家代理，並將工作分派給最適合的專家。

可以把它想像成一間專為 AI 代理服務的人力仲介公司：協調器接下任務，判斷該由哪位專家處理，再附上正確的情境資訊進行委派。工作完成後，結果會回流到協調器手上進行整合。

這些數字說明了一切：

| 組成 | 數量 |
|-----------|-------|
| 專家代理 | 46 |
| 可重複使用的技能 | 466 |
| 身份原型 | 27 |
| 思維模式 | 11 |
| 溝通風格 | 10 |
| 知識領域 | 21 |

## 角色系統：代理的 D&D

Orkestra 背後的核心洞察，是代理的行為源自三個可組合的基本元素：

**身份（Identity）** 定義代理「是什麼」。架構師（architect）設計系統結構；除錯者（debugger）追蹤失敗的根本原因；守護者（guardian）落實合規與安全邊界。我們共有 27 種可自由組合的身份原型。

**思維模式（Mindset）** 定義代理「如何思考」。分析型思維會將主張建立在證據之上，並量化不確定性；懷疑型思維會質疑假設、尋找反證；探索型思維則擁抱模糊性，嘗試多種做法。

**風格（Style）** 定義代理「如何溝通」。技術型風格會納入精確數值、引用具體檔案；精簡型風格會去除贅詞、先給出答案；圓融型風格則在誠實與得體之間取得平衡。

一個代理會組合這些基本元素：

```yaml
# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise
```

這樣的組合，會產生一個能設計系統（architect）、跨領域串連知識（knowledge-architect）、設定策略方向（strategist）、以證據與資料思考（analytical）、且溝通不帶贅詞（concise）的代理。

真正的威力來自組合爆炸：27 種身份 × 11 種思維模式 × 10 種風格，可產生近 3,000 種可能的代理人格。但你只需要定義對你的工作真正有意義的那些組合。

## 技能：可重複使用的能力模組

技能是代理可以呼叫的知識與工作流程，依範圍分為分層系統：

| 層級 | 名稱 | 範圍 | 範例 |
|------|------|-------|---------|
| K0 | 基礎 | 通用方法論 | 測試優先原則、以證據為本的完成標準 |
| K1 | 身份 | 依角色劃分的工作流程 | CLI 介面標準、效能作戰手冊 |
| K2 | 領域 | 領域專屬知識 | 資料庫遷移模式、身份驗證機制驗證 |
| K3 | 技術堆疊 | 特定技術專屬 | Cloudflare 部署、Supabase 操作 |
| K4 | 專案 | 僅限本程式碼庫 | 專案專屬的工作流程與慣例 |

技能採懶載入方式：代理在啟動時只會看到技能名稱與說明，完整內容只有在被觸發時才會載入。這讓情境保持精簡，同時使數百項技能都能被發現與運用。

每項技能都包含：
- 明確的觸發條件（例如「遷移資料庫結構描述時使用」）
- 逐步操作指引
- 該工作流程允許使用的工具
- 成功標準與失敗復原路徑

我們登錄檔中的 466 項技能，涵蓋範圍從 git 工作樹隔離、網路研究工作流程，到部署健康驗證，無所不包。

## 為何協調很重要

單一代理架構很快就會撞牆：

**情境稀釋。** 20 萬 token 的情境視窗聽起來很大，但一旦載入資料庫結構描述、API 文件、測試案例與資料，以及領域知識，很快就會吃緊。專家代理則可以只使用目標明確的情境。

**指令衝突。** 同時要求代理「徹底但要快」與「什麼都要驗證但別過度工程」，會產生內在張力。專家代理則因為範圍明確而能化解這類矛盾。

**專業深度。** 通才型代理對每件事都略知一二；而由正確的身份與技能組成的專家代理，則能對自己的領域有深入理解。

Orkestra 採用扁平化協調：一個協調器統籌多個專家代理，專家代理不能再衍生出子專家。這能避免複雜度失控，同時仍支援平行作業。

協調器可運用的有效容量高達 220 萬個 token：自身 20 萬 token 的視窗，加上最多 10 個並行子代理、各自擁有 20 萬 token。足以耗盡單一代理情境容量的工作量，在整支艦隊中卻能從容完成。

## 渲染管線

代理定義存放於 YAML 中，而 Claude Code 讀取的是 Markdown。Orkestra 以一套確定性的渲染管線，銜接這道落差：

```
YAML Registries → Jinja Templates → .claude/agents/*.md
```

操作者編輯 YAML 原始檔，執行 `orkestra sync`，渲染後的 Markdown 就會出現在 `.claude/agents/` 中，Claude Code 隨即讀取到這些變更。

這樣的區分服務於不同對象：
- **YAML 原始檔** 包含生命週期中繼資料、標籤、驗證規則，以及供工具使用的淘汰通知
- **渲染後的 Markdown** 只包含模型真正需要的內容：描述、工具、技能與行為指引

這套管線會將身份、思維模式、風格與技能，組合成單一且連貫一致的提示。即使共享部分底層技能，architect-analytical-concise 型代理所得到的系統提示，也會與 debugger-skeptical-technical 型代理截然不同。

## 領域知識：四檔案模式

每個知識領域都遵循一致的結構：

```
domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes
```

這種結構是為了服務代理的情境載入：處理身份驗證相關工作的代理，會載入 `authentication/patterns.md` 取得指引，並載入 `authentication/anti-patterns.md` 以避開已知陷阱。這些檔案的大小經過調整，以利高效載入——夠聚焦、才有用；夠全面，才具權威性。

我們維護 21 個頂層領域，涵蓋分析、身份驗證、資料科學、基礎架構、機器學習、效能、安全等等。每個領域都可以再細分出子領域，以取得更細緻的粒度。

## 價值觀：作業系統

所有代理都共用一套定義其運作方式的基礎價值觀：

**簡潔優先。** 使用有效的最簡方案，只有在有正當理由時才增加複雜度。

**修正根本原因。** 絕不繞過失敗打補丁。若管線失敗，就除錯管線；若測試失敗，就修正程式碼或測試本身。

**以證據為本。** 將主張標示為「已驗證」（附上基準測試）或「估計」（附上假設）。偵測到模式，不等於問題已獲確認。

**情境經濟學。** MCP 工具僅耗用 0.1% 的情境，每次讀取檔案則耗用 2%。在探索程式碼之前，先運用領域專業知識。

這些價值觀會透過渲染管線傳遞給每一位專家代理，任何代理都無法透過組合方式繞過它們。

## CLI：控制平面

Orkestra 隨附一套用於管理代理生態系的 CLI：

```bash
# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"
```

這套 CLI 是「有哪些代理存在」「它們擁有哪些技能」「系統是否健康」等資訊的唯一真實來源，並會在同步前執行驗證，及早揪出問題。

## 開源方面的考量

我們打造 Orkestra，是為了解決自己的問題：在複雜的程式碼庫中大規模協調 AI 代理。但我們發現的這些模式，並不侷限於我們自己的領域。

角色組合系統（身份 + 思維模式 + 風格）適用於任何需要定義代理人格的團隊。

技能分層系統（K0 至 K4）提供了一套按範圍組織可重複使用能力的心智模型。

渲染管線模式（YAML 原始檔 + 範本 + 生成產物）將工具面的關注點與供模型讀取內容的關注點區分開來。

扁平化協調模型（一個協調者、多個專家）在支援平行作業的同時避免了複雜度爆炸。

Orkestra 是否會走向開源，取決於這些模式對其他使用 Claude Code 開發的人是否有價值。如果你也正撞上我們所描述的那些牆，這套架構或許能幫上忙。

## 我們學到的事

打造 Orkestra 讓我們明白，協調的重點不在於讓代理變得更聰明，而在於讓它們變得更專注。

即使指令再完美，單一代理終究會耗盡情境；即使擁有所有技能，單一代理依然會搞不清楚該套用哪一項；一個試圖包辦一切的單一代理，只會在每件事上都做得平庸。

四十位各自在自己領域表現出色的專家，由一個懂得何時該委派的協調器統籌——這正是我們得以持續交付的方式。

數字本身沒有架構重要。你可能需要五個代理，也可能需要五十個。原則始終如一：組合勝過單一能力，專精勝過通才，協調勝過單打獨鬥的英雄主義。

---

*Orkestra 驅動著 Maguyva（我們的程式碼智慧平台）背後的代理生態系。想進一步了解嗎？歡迎聯絡我們的團隊。*