第二章：Agent 架構 | Chapter 2: Agent Architecture

目錄 | Table of Contents

1. 五層架構概覽
2. 各層角色、職責與觸發條件
3. 三層操作表面的設計理念
4. 調度邏輯
5. Agent 間的協作模式
6. 架構圖

1. 五層架構概覽

系統採用五層（加一個跨層特殊角色）的分層式 Agent 架構，共 39 位 Agent。每一層有明確的職責邊界與 effort 等級，形成「決策 - 協調 - 產品 - 執行 - 驗證」的完整鏈路。

設計理念

這個分層不是行政科層，而是認知分工：

• 決策層問的是「做不做、方向對不對」
• 協調層問的是「誰來做、怎麼串」
• 產品層問的是「使用者需要什麼」
• 執行層問的是「怎麼做到」
• 驗證層問的是「真的做到了嗎、有沒有盲點」

Joker 則是這套體系的安全閥，專門在共識過於順暢時介入打破慣性思維。

各層 Agent 數量與 Effort 等級

2. 各層角色、職責與觸發條件

2.1 決策層 Decision Layer (6 位, effort: max)

決策層的六位 Agent 以歷史上的卓越決策者為原型，各自代表一種不可替代的思維模式。他們不直接執行工作，而是在重大分歧點提供方向性判斷。

觸發條件：當需求涉及重大決策（組合觸發詞 /decision）、方向性分歧、或多個執行層 Agent 出現衝突意見時，由 Orchestrator 提交決策層仲裁。六位聯合審視是最高級別的調度。

Effort 為 max 的理由：決策層處理的是不可逆或高成本的方向性問題。推理深度不足會導致後續所有工作方向偏差，因此一律配置最高推理資源。

2.2 協調層 Coordination Layer (1 位, effort: medium)

Orchestrator 是整個系統的中樞神經。它不產出領域知識，而是確保正確的 Agent 在正確的時機收到正確的資訊。

核心職能：

1. 任務分解 -- 將複雜需求拆解為子任務，識別依賴關係
2. Agent 調度 -- 以最小化原則選擇必要的 Agent
3. 上下文管理 -- 確保每個 Agent 獲得必要且充分的資訊
4. Handoff 管理 -- 監控任務交接品質（大多數「Agent 失敗」實際上是 Handoff 問題）
5. 異常處理 -- 卡住時 escalate、衝突時提交仲裁、資源不足時調整優先級

Effort 為 medium 的理由：Orchestrator 的核心工作是匹配與路由，不需要深度推理。過高的 effort 反而會讓它「想太多」，延遲調度。它需要的是快速、準確的模式匹配，而非深度分析。

模型選擇：使用 Sonnet 而非 Opus。原因同上 -- 調度是高頻低深度任務，Sonnet 的速度 / 成本比在此場景更優。

2.3 產品層 Product Layer (2 位)

產品層夾在協調層與執行層之間，負責將「做什麼」轉化為「怎麼做」。Designer 從使用者體驗角度定義「做成什麼樣」，PM 從專案管理角度確保「按時做出來」。

設計考量：Designer 設為 high 而非 medium，因為設計決策直接影響使用者體驗，需要較深的推理；PM 設為 medium，因為進度追蹤和風險識別更依賴結構化判斷而非深度推理。

2.4 執行層 Execution Layer (24 位)

執行層是系統的主要產能，按專業領域分為七個小組。這是 Agent 數量最多的一層，反映了「方向由少數人決定，工作由專業人做」的原則。

研究院 Research Institute (4 位)

情境分析 Context Analysis (1 位)

Context Analyst 是 v2.0 合併成果（原 Geopolitician + Culturalist），因為地緣政治與文化觀察在實務中經常服務於同一個決策。

策略組 Strategy Group (4 位)

數據組 Data Group (3 位)

開發組 Development Group (3 位)

注意：Technical Architect 是 v2.0 合併成果（原 Architect + Planner），因為架構設計與需求規劃在實務中自然銜接。

品質組 Quality Group (3 位)

Code Auditor 是 v2.0 最大的合併案（原 Code Reviewer + Security Reviewer + Refactor Cleaner），將品質、安全、重構三位一體化。

資安組 Security Group (3 位)

資安組全員 effort 為 max。安全領域的推理深度不足會直接導致漏報，代價極高。

其他 Others (3 位)

2.5 驗證層 Validation Layer (5 位, effort: high)

驗證層是輸出品質的最後防線。五位 Agent 各自從不同的利害關係人視角審視成果。

觸發條件：組合觸發詞 /review 會啟動全部五位驗證層 Agent 聯合審查。日常調度中，Orchestrator 也會根據任務性質選擇性啟動 1-2 位作為品質閘門。

全員 high 的理由：驗證工作需要足夠的推理深度才能發現深層問題，但不需要 max 級別的耗時深思 -- 驗證是有時效性的。

2.6 Joker (1 位, effort: max)

不屬於任何層級，動態介入打破共識陷阱

Joker 是整個架構中唯一不屬於任何層級的 Agent。它的存在是為了對抗群體盲思 (Groupthink)：當所有 Agent 都朝同一方向思考時，Joker 的工作是提出「如果我們全錯了呢？」

設計哲學：一個永遠和你唱反調的聲音不是噪音，而是保險。Joker 的 effort 設為 max，因為有品質的反向思考比順勢思考更難。

3. 三層操作表面的設計理念

問題：39 位 Agent 太多了

39 位 Agent 的完整能力是系統的天花板，但不是日常操作的起點。如果每次都從 39 人清單開始掃描，不僅浪費 token，還會導致調度決策的認知負荷過高。

解法：漸進式展開

系統將 39 位 Agent 分為三層操作表面 (Operating Surface)，以「先窄後寬」的原則控制日常操作的複雜度：

Core Surface (12)        -- 日常高頻，優先從此開始
    |
    v  只有當 skill / brief / 風險類型明確指出需要時
Conditional Surface (13) -- 條件觸發，按需載入
    |
    v  只有當議題明確落到其專業時
Specialist Surface (14)  -- 保留能力，極少主動調用

3.1 Core Surface | 核心表面 (12 位)

Orchestrator, Deep Researcher, Strategist, Storyteller,
Context Analyst, Consumer, Skeptic, Marketer,
Technical Architect, Code Auditor, Security Expert, Joker

選入標準：涵蓋「研究 - 策略 - 產出 - 驗證 - 安全」完整鏈路的最小集合。任何一個典型任務（研究報告、技術規劃、內容產出）都能在這 12 位之內完成核心工作。

設計考量：

• Orchestrator 必選（調度樞紐）
• Deep Researcher + Strategist + Storyteller 構成「研究到產出」的主幹
• Context Analyst 處理任何涉及外部環境的分析
• Consumer + Skeptic + Marketer 覆蓋最常見的驗證面向
• Technical Architect + Code Auditor + Security Expert 覆蓋技術品質
• Joker 作為反共識安全閥永遠在場

3.2 Conditional Surface | 條件表面 (13 位)

Business Intel, Survey Architect, Creative Council, CFO, Lawyer,
White Hat, Black Hat, PM, Frontend, Backend, Operator,
Data Scientist, Insight Analyst

觸發條件：當 skill 定義、任務 brief、或風險分析結果明確指出需要該領域時，才從此表面載入。

典型觸發場景：

• 任務涉及財務估算 -> 載入 CFO
• 任務涉及法規合規 -> 載入 Lawyer
• 任務涉及滲透測試 -> 載入 White Hat / Black Hat
• 任務需要問卷設計 -> 載入 Survey Architect
• 任務進入開發實作 -> 載入 Frontend / Backend / Operator

3.3 Specialist Surface | 專家表面 (14 位)

Jobs, Gates, Musk, Popovich, Hassabis, Tech Scout, Economist,
DBA, Visualizer, Designer, Diagnostician, AI Engineer,
TDD Guide, E2E Runner

設計理念：這些 Agent 的能力是存在的，但不是日常的起手式。決策層六位大師級 Agent（Jobs, Gates, Musk, Popovich, Hassabis + Creative Council 已在 Conditional）只有在重大戰略決策時才需要；Tech Scout、Economist 等只有在議題明確落入其專業時才有價值。

Token 經濟學

三層操作表面的核心價值在於 token 節省：

預載 39 位完整定義 = ~15,000 tokens
查 REGISTRY.md (~1,000 tokens) + 僅載入 1-5 位 = ~1,500 tokens
節省：約 85-90%

這不是能力刪減，而是認知與資源的分配最佳化。

4. 調度邏輯

4.1 雙軌調度系統 | Dual-Track Dispatch

Orchestrator 運行雙軌調度系統，根據任務複雜度選擇不同的執行軌道：

4.2 調度決策流程

需求進入
    |
    v
[1] Orchestrator 接收需求
    |
    v
[2] 分析任務類型（關鍵字匹配 + 語義判斷）
    |
    +---> 研究類 --> 研究院 + Context Analyst --> Strategist --> Storyteller
    +---> 數據類 --> Data Scientist --> Visualizer --> Insight Analyst
    +---> 開發類 --> Technical Architect --> Engineers --> Code Auditor --> Operator
    +---> 商業類 --> Strategist + Business Intel + CFO/Marketer
    +---> 內容類 --> Storyteller + Creative Council
    +---> 調研類 --> Survey Architect --> Context Analyst --> Insight Analyst
    +---> 資安類 --> Security Expert --> White Hat/Black Hat --> Technical Architect
    +---> AI 類  --> Hassabis --> AI Engineer --> Data Scientist
    +---> 診斷類 --> Diagnostician --> Backend/Frontend --> Operator
    +---> 重大決策 -> 決策層 6 位聯合審視
    |
    v
[3] 識別所需 Agent（最小化原則）
    |
    v
[4] 定義 Agent 間依賴關係
    |
    v
[5] 設定交付標準與 effort level
    |
    v
[6] 調度執行（選擇並行或串行模式）
    |
    v
[7] 監控進度，處理異常
    |
    v
[8] 整合結果，驗證交付

4.3 Effort 等級如何影響推理深度

Effort 是分配給每位 Agent 的推理資源預算，直接影響模型的思考深度與 token 消耗：

設計原則：

• Effort 不是 Agent 的「重要程度」，而是該角色典型任務所需的推理深度
• Operator 的 effort 為 low 不代表運維不重要，而是部署操作更需要精確執行而非深度推理
• 資安組全員 max 是因為安全分析的漏報代價極高，必須窮盡推理

4.4 語義補充機制

關鍵字匹配完成後，Orchestrator 會自問：「用戶需求是否有隱含維度？」

限制：每次最多補充 1-2 位，避免過度調度。

4.5 預設路由原則

主控先在 Core Surface (12 位) 內完成判斷
    |
    v  只有當 skill / evidence / risk profile 明確要求時
向 Conditional Surface 擴張
    |
    v  只有當議題明確落到其專業時
向 Specialist Surface 擴張

這確保了每次調度的 token 成本都是最優的，同時不犧牲覆蓋面。

5. Agent 間的協作模式

Orchestrator 支援五種協作模式，根據任務特性選擇最適合的模式：

5.1 串行模式 | Sequential Pattern

Agent A -----> Agent B -----> Agent C
         handoff        handoff

適用場景：有明確先後依賴的任務。例如「研究 -> 策略 -> 文案」的管線。

典型案例：品牌調研（Deep Researcher -> Strategist -> Context Analyst -> Business Intel）

關鍵要求：每次 Handoff 必須攜帶完整的上下文協議（scope, input, expected_output, open_risks）。

5.2 並行模式 | Parallel Pattern

           +---> Agent A ---+
           |                |
需求 ------+---> Agent B ---+----> 整合
           |                |
           +---> Agent C ---+

適用場景：多個 Agent 可以獨立執行、互不依賴的子任務。

典型案例：驗證層聯合審查（Consumer + CFO + Lawyer + Marketer + Skeptic 同時從不同角度審視同一份成果）

效益：大幅縮短總執行時間，特別適合審查類工作。

5.3 審查模式 | Review Pattern (Producer-Reviewer-Publisher)

Producer -----> Reviewer -----> Publisher
   產出            審查            定稿

適用場景：高風險產出，需要第二雙眼睛把關。

關鍵設計：Reviewer 必須與 Producer 使用不同的 prompt / 風格，並有明確的接受標準 (acceptance criteria)。如果 Reviewer 只是用相同邏輯重跑一遍，審查就失去意義。

典型案例：

• 代碼開發（Backend -> Code Auditor -> 定稿）
• 安全架構（Technical Architect -> Security Expert -> 定稿）

5.4 對抗模式 | Adversarial Pattern

           +---> 提案者 Proposer ---+
           |                        |
需求 ------+                        +----> 仲裁
           |                        |
           +---> 挑戰者 Challenger --+

適用場景：需要壓力測試的重要決策。刻意讓兩個 Agent 站在對立面，通過辯論暴露盲點。

常見搭配：

• Strategist (提案) vs Skeptic (挑戰)
• 任何 Agent (提案) vs Joker (挑戰)

仲裁機制：當雙方僵持不下時，提交決策層 (Jobs / Gates / 相關決策者) 仲裁。

5.5 階層模式 | Hierarchical Pattern

         Orchestrator
            |
    +-------+-------+
    |               |
Team Lead A     Team Lead B
    |               |
 Workers         Workers

適用場景：大型複雜任務，需要多個子團隊並行協作。

典型案例：全面研究任務 -- 研究院 4 位 + Context Analyst 作為一個子團隊，策略組作為另一個子團隊，各自有 lead 角色。

5.6 協作模式選擇矩陣

5.7 Handoff 協議

每次 Agent 間的任務交接都必須遵循結構化 Handoff 協議：

handoff:
  track: task_tool | agent_teams
  background: "為什麼做、前置任務、商業/技術背景"
  scope: "本次只處理什麼，不處理什麼"
  input: "已有資訊、數據、成果"
  inspected_artifacts: "本輪必須查看的檔案/頁面/端點/日誌"
  expected_output: "交付物與格式"
  effort_level: low | medium | high | max
  constraints: "時間、資源、風險、不可做事項"
  evidence_required: "哪些主張需要證據"
  quality_gate: "如何才算通過"
  next_agent: "完成後交給誰"
  open_risks: "尚未驗證的風險"

Handoff 紀律：

• 每次 handoff 必須明示 scope 與 evidence_required
• 不允許只交「幫我 review 一下」這種低資訊 handoff
• open_risks 用於追蹤跨 Agent 的未驗證風險，防止風險在交接中遺失

5.8 異常處理

6. 架構圖

6.1 系統全景圖

┌─────────────────────────────────────────────────────────────────────────┐
│                         決策層 (6) effort: max                          │
│   Jobs (產品/UX) . Gates (技術/規模) . Creative Council (行銷/文案)     │
│   Musk (第一性原理) . Popovich (團隊建構) . Hassabis (AI/ML 前瞻)      │
├─────────────────────────────────────────────────────────────────────────┤
│                         協調層 (1) effort: medium                       │
│                    Orchestrator（雙軌調度）                              │
├─────────────────────────────────────────────────────────────────────────┤
│                         產品層 (2)                                       │
│                 Designer (high) . PM (medium)                           │
├─────────────────────────────────────────────────────────────────────────┤
│                         執行層 (24)                                      │
│  ┌───────────────────────────────────────────────────────────────────┐ │
│  │ 研究院 (4)              │ 策略組 (4)            │ 數據組 (3)      │ │
│  │ Tech Scout (med)       │ Storyteller (high)    │ Data Sci (high) │ │
│  │ Business Intel (high)  │ Strategist (high)     │ Visualizer (med)│ │
│  │ Economist (high)       │ Insight Analyst (high) │ DBA (med)      │ │
│  │ Deep Researcher (high) │ Survey Architect (high)│                │ │
│  ├───────────────────────────────────────────────────────────────────┤ │
│  │ 開發組 (3)             │ 品質組 (3)            │ 資安組 (3)      │ │
│  │ Tech Architect (high)  │ Code Auditor (high)   │ Security Expert │ │
│  │ Frontend (med)         │ TDD Guide (med)       │ White Hat (max) │ │
│  │ Backend (med)          │ E2E Runner (low)      │ Black Hat (max) │ │
│  ├───────────────────────────────────────────────────────────────────┤ │
│  │ Diagnostician (med) │ AI Engineer (high) │ Operator (low)        │ │
│  │ Context Analyst (high) -- 地緣政治 + 文化觀察                    │ │
│  └───────────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────┤
│                         驗證層 (5) effort: high                         │
│            Consumer . CFO . Lawyer . Marketer . Skeptic                │
└─────────────────────────────────────────────────────────────────────────┘
         Joker (max) -- 不屬於任何層級，動態介入打破共識陷阱

6.2 調度流程圖

                        ┌─────────────┐
                        │   需求進入    │
                        └──────┬──────┘
                               │
                               v
                     ┌─────────────────┐
                     │  Orchestrator   │
                     │  (協調層)        │
                     └────────┬────────┘
                              │
                    ┌─────────┴─────────┐
                    │                   │
                    v                   v
          ┌────────────────┐  ┌────────────────┐
          │  Track 1       │  │  Track 2       │
          │  Task Tool     │  │  Agent Teams   │
          │  (單一聚焦)     │  │  (多視角協作)   │
          └───────┬────────┘  └───────┬────────┘
                  │                   │
                  │         ┌─────────┴─────────────┐
                  │         │                       │
                  │         v                       v
                  │  ┌──────────────┐    ┌──────────────────┐
                  │  │  Core Surface │    │  按需擴張         │
                  │  │  (12 位)      │    │  Conditional (13) │
                  │  │  優先調度     │    │  Specialist (14)  │
                  │  └──────┬───────┘    └────────┬─────────┘
                  │         │                     │
                  │         └──────────┬──────────┘
                  │                    │
                  v                    v
          ┌──────────────────────────────────┐
          │         選擇協作模式               │
          ├──────────────────────────────────┤
          │  串行 │ 並行 │ 審查 │ 對抗 │ 階層  │
          └───────────────┬──────────────────┘
                          │
                          v
                ┌──────────────────┐
                │    執行與監控      │
                │  (進度追蹤/異常)   │
                └────────┬─────────┘
                         │
               ┌─────────┴──────────┐
               │                    │
               v                    v
      ┌──────────────┐    ┌──────────────┐
      │  驗證層審查    │    │  決策層仲裁   │
      │  (品質閘門)    │    │  (衝突/重大)  │
      └──────┬───────┘    └──────┬───────┘
             │                   │
             └────────┬──────────┘
                      │
                      v
             ┌──────────────┐
             │  整合交付      │
             │  (Handoff 協議)│
             └──────────────┘

6.3 Context 載入策略圖

Layer 1   -- 根層指令（永遠載入）
              ~/.claude/CLAUDE.md

Layer 1.5 -- Workspace 專案層（永遠載入於 /home/ubuntu）
              ~/CLAUDE.md

Layer 1.8 -- 子目錄規則（僅進入對應目錄時載入）
              ~/.claude/projects/CLAUDE.md

Layer 2   -- 調度層（首次調度時載入）
              REGISTRY.md（本架構的權威來源）

Layer 3   -- Agent 定義層（按需載入，觸發詞匹配後才載入）
              ~/.claude/agents/<name>.md
              僅載入 1-5 位，避免預載全部 39 個定義

Layer 4   -- 知識底層 Skills Substrate（JIT 檢索，從不預載）
              library/reference/   可複用的程序性知識
              library/sources/     可信來源清單
              library/watchlist/   監控列表
              skills/              工作流技能
              memory/              跨 session 記憶
              logs/                品質追蹤

Agents 是 OS 層；library + skills 是 App 層。Agent 定義提供「怎麼思考」，knowledge substrate 提供「用什麼知識思考」。

6.4 組合觸發對照圖

/research    研究院 4 + Context Analyst --> Strategist --> Storyteller
/brand-research  Deep Researcher --> Strategist --> Context Analyst --> Business Intel
/marketing   Strategist --> Context Analyst --> Creative Council --> Storyteller --> Marketer
/security    Security Expert --> White Hat --> Black Hat
/decision    Jobs + Gates + Musk + Popovich + Hassabis + Creative Council
/review      Consumer + CFO + Lawyer + Marketer + Skeptic
/brainstorm  Musk + Jobs + Creative Council
/plan        Technical Architect --> Engineers --> Code Auditor --> Operator

附錄：v2.0 合併紀錄

為控制系統複雜度，v2.0（Opus 4.6 升級）將原始 45 位 Agent 合併為 39 位。合併依據是「實務中經常同時需要」的角色：

原始 9 個被合併的定義已歸檔於 ~/.claude/agents/archive.tar.gz。

本章權威來源：~/.claude/agents/REGISTRY.md v3.0 協調層詳細定義：~/.claude/agents/orchestrator.md 系統架構模式參考：~/.claude/library/reference/frameworks/architecture-patterns.md