awoooi/docs/adr/ADR-095-12agent-sdk-integration.md

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 擴充（向後相容）

# 保留 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-082
• 平行：ADR-093 / ADR-094
• 設計：/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 宣告