# ADR-095: 12-Agent Claude SDK 整合 × Telegram 視覺分派

> **狀態**: 🟡 批准實作中
> **日期**: 2026-04-24
> **決策者**: 統帥 + 12-Agent 全景分析團隊

## 背景

AWOOOI 已有兩套 agent 系統：

1. **ADR-009 OpenClaw Agent Teams**（內部 Python class，`src/agents/critic_agent.py` 等）
   - 3 核心 agent：SecurityAgent (weight=0.4) / BlastRadiusAgent (0.3) / ActionPlannerAgent (0.3)
   - ConsensusEngine 加權投票
   - 用於 incident 決策自動化

2. **ADR-082 Phase 2 Multi-Agent Collaboration**（5-agent 辯證）
   - Diagnostician / Solver / Reviewer / Critic / Coordinator
   - `agent_orchestrator.py` 編排，走 `ai_router.py` (Ollama/NIM)
   - 用於 alert → incident 決策鏈

**第三套 agent 系統**：Claude Code `.claude/agents/*.md` 12 份檔案定義（critic / debugger / db-expert / planner / fullstack-engineer / frontend-designer / refactor-specialist / migration-engineer / onboarder / tool-expert / web-researcher / vuln-verifier）。原本只供 Claude Code CLI 使用，**後端 AWOOOI API 未曾調用**。

使用者需求：把這 12 位 Claude Code agent 透過 **Hermes NL 介面**（ADR-094）暴露給 Telegram 群組使用者，以視覺化方式呈現「12 位專家協作」。

## 決策

**視覺分派模式（非多 bot）**，三層共存：

| 系統 | 用途 | 後端 | 狀態 |
|------|------|------|------|
| ADR-009 3 核心 agent | Incident 決策自動化 | Python class | 保留 |
| ADR-082 5-agent 辯證 | Alert → incident 鏈 | `ai_router.py` → Ollama/NIM | 保留 |
| **本 ADR-095 12 Claude Code agent** | Hermes NL 對話回覆 | **`claude-agent-sdk` → Anthropic API** | **新增** |

### 日常工作模式（Game Rules v1）

除 Hermes 對外視覺分派外，12-agent 也定義為專案內部的任務協作模型：

- `12 agents` = 任務分工角色
- `.agents/skills/*.md` 9 份 = 工程守則與落地規範
- 實際工作流 = **先用 12-agent 判型與派工，再落到對應 skill 執行**

對照原則：

| 類型 | 用途 |
|------|------|
| `debugger / db-expert / vuln-verifier / migration-engineer` | 問題診斷與高風險鏈路處理 |
| `frontend-designer / fullstack-engineer / refactor-specialist` | UI、功能落地與重構 |
| `planner / onboarder / critic / web-researcher / tool-expert` | 規劃、導覽、審查、查證、工具整合 |

常設派工規則：

| 任務 | 主責 | 預設協作 |
|------|------|---------|
| 查根因 / 查斷點 | `debugger` | `db-expert`, `tool-expert`, `critic` |
| learning / migration / SQL | `db-expert` | `debugger`, `refactor-specialist` |
| UI / 戰情中心 / i18n | `frontend-designer` | `fullstack-engineer`, `critic` |
| 前後端完整落地 | `fullstack-engineer` | `frontend-designer`, `debugger`, `db-expert` |
| 重構 / 抽層 / 技術債 | `refactor-specialist` | `migration-engineer`, `critic`, `db-expert` |
| Gitea / CI/CD / deploy | `migration-engineer` | `tool-expert`, `vuln-verifier`, `critic` |
| Telegram / approval / callback / 權限 | `vuln-verifier` | `debugger`, `db-expert`, `critic` |

正式規則文件見：`docs/12-agent-game-rules.md`

### 視覺規格（單 bot，用文字前綴模擬 12 分身）

| Agent | Emoji | Hashtag | 中文短稱 | TG handle（文字 prefix，非真 bot）|
|-------|-------|---------|---------|--------------------------------|
| critic | 🔍 | #審查 | 找碴專家 | @hermes-critic |
| vuln-verifier | 🎯 | #漏洞驗證 | 漏洞驗證官 | @hermes-verifier |
| debugger | 🐛 | #除錯 | 除錯偵探 | @hermes-debugger |
| db-expert | 💾 | #資料庫 | DB 軍師 | @hermes-db |
| planner | 📋 | #拆解 | 任務拆解官 | @hermes-planner |
| fullstack-engineer | 🛠️ | #工程 | 全端工程師 | @hermes-engineer |
| frontend-designer | 🎨 | #設計 | 前端設計師 | @hermes-designer |
| refactor-specialist | ♻️ | #重構 | 重構專家 | @hermes-refactor |
| migration-engineer | 🚚 | #升級 | 升級工程師 | @hermes-migration |
| onboarder | 🗺️ | #導覽 | 領航員 | @hermes-onboarder |
| tool-expert | 🧰 | #工具 | 工具專家 | @hermes-tools |
| web-researcher | 📚 | #文檔 | 文獻研究員 | @hermes-web |

### ADR-009 ConsensusEngine weights 擴充（向後相容）

```python
# 保留 SecurityAgent weight=0.4（資安永遠最高）
# 其餘 11 agent 分配 0.6
CONSENSUS_WEIGHTS = {
    "SecurityAgent": 0.4,      # 保留 (ADR-009)
    "BlastRadiusAgent": 0.15,  # 原 0.3 → 0.15
    "ActionPlannerAgent": 0.15, # 原 0.3 → 0.15
    # 新增 9 個 Claude Code agent（只有「核心 3 Consensus + 9 按需」模式下才參與投票）
    "critic": 0.06,
    "debugger": 0.06,
    "db-expert": 0.04,
    "vuln-verifier": 0.04,
    "planner": 0.02,
    "fullstack-engineer": 0.02,
    "refactor-specialist": 0.02,
    "migration-engineer": 0.02,
    "tool-expert": 0.02,
    # onboarder / frontend-designer / web-researcher 不參與投票（諮詢型）
}
# sum = 1.0
```

## 理由

### 為什麼視覺分派而非多 bot
- Telegram API 硬性封鎖 bot-to-bot 訊息（ADR-094 §web-researcher 查證）
- 單人維運 12 token 違反最小憑證面（`reference_secrets_architecture_v2`）
- 視覺識別可達成 80% 多 bot 效果（文字 prefix + emoji + hashtag 三件套）
- 未來若真要多 bot 化，本方案是**前向相容**的（加 token 即可）

### 命名隔離（P0-D3 修）
- `.claude/agents/critic.md`（Claude Code subagent）與 `src/agents/critic_agent.py`（ADR-082 內部 dataclass）**同名不同物**
- 對外 TG 統一呈現為 `@hermes-critic`，內部程式碼名稱不改
- 映射表：`apps/api/src/hermes/display_names.py`

### Claude Agent SDK 整合範式
- SDK 版本：`claude-agent-sdk>=0.1.50`（已裝）→ 0.1.65（最新，升級決策待 T1.2）
- Loader：`apps/api/src/hermes/agent_loader.py` 解析 frontmatter → `AgentDefinition`（camelCase 鍵）
- Hooks：`hermes_hooks.py` **完整複製** `.claude/hooks/awoooi-guard.js` 9 條 DENY 正則（Node hook 對 SDK subprocess 無效，必須 Python 重做）
- MCP：registry 加 `asyncio.Semaphore(5)` 防併發過載

## 後果

### 優點
- 12 位 Claude Code agent 完整對外，覆蓋 SRE 戰情室 80% 諮詢情境
- 視覺分派直觀（`🔍 找碴專家 @hermes-critic #審查`）
- Agent `.md` 定義可熱更新（watch mtime）

### 缺點
- **命名衝突風險**：`.claude/agents/critic.md` vs `src/agents/critic_agent.py` 未來新人易混淆 → 強制 `display_names.py` 單點映射
- **Anthropic API 費用**：每個 NL 回覆 ~$0.01-0.05（Sonnet），濫用需 budget 管控
- **SDK subprocess**：每個 `ClaudeSDKClient` = 一個 subprocess，建議 pool 5 個 client 複用

### 風險
- **12 agent `.md` 變更守門**：需加 CODEOWNERS 強制 PR review，否則誰都能改 system prompt
- **Consensus weights 重分配對現有 incident 決策的回歸影響**：security=0.4 鎖定可緩解，其他 weights 需單元測試覆蓋
- **subagent 無法 spawn 自己的 subagent**（SDK 官方限制）→ 12 agent 不能互相調用，必須由 Hermes router 統一編排

## Rollback

- Feature flag `HERMES_12AGENT_ENABLED=off` → 全部 NL 回覆走 `debugger` 預設 agent
- ConsensusEngine 如有回歸：`ENABLE_12AGENT_CONSENSUS=false` 退回 ADR-009 原 3 agent
- 12 agent `.md` 檔案如有污染：從 `backup/pre-migration-*` tag 還原

## 參考

- 上位：[ADR-009](ADR-009-openclaw-agent-teams.md) / [ADR-082](ADR-082-multi-agent-collaboration.md)
- 平行：[ADR-093](ADR-093-telegram-group-migration.md) / [ADR-094](ADR-094-hermes-nl-interface.md)
- 設計：`/Users/ogt/awoooi/docs/design/hermes-telegram-flows/hermes-flows.html`（Flow 4/5）
- Memory: `feedback_no_ghost_buttons.md` / `project_phase7_round3_telegram_subsystem.md`
- SDK docs: https://code.claude.com/docs/en/agent-sdk/subagents

## 變更紀錄

| 版本 | 日期 | 執行者 | 變更內容 |
|------|------|--------|---------|
| v1.0 | 2026-04-24 | 12-Agent 全景分析 | 初版 Proposed |
| v1.1 | 2026-04-24 | Codex | 補入 12-agent 日常工作模式（Game Rules v1）與 9 skills 對照 |
| v1.2 | 2026-04-25 | Claude Sonnet 4.6 | WS4-WS5 實作完成：display_names.py + agent_loader + safety_hooks + ConsensusEngine weights 宣告 |