86ee013cdf
All checks were successful
CD Pipeline / build-and-deploy (push) Successful in 9m32s
## Hermes NL 補強（nl_gateway.py）
- T1 hermes_dispatch_log DB 寫入（asyncio.create_task 非阻擋）
- T2 Redis 速率限制：per-chat_id 20 req/min，fail-open
- T3 Multi-turn session：hermes:session:{chat_id}:{user_id} TTL=300s，最近 3 輪
## ConsensusEngine（ADR-095 宣告式設計）
- consensus_engine.py: CONSENSUS_WEIGHTS class 屬性
security=0.4 鎖定，9 個 Claude Code agent 分配 0.6
- config.py: ENABLE_12AGENT_CONSENSUS=False feature flag
## ADR 狀態
- ADR-093/094/095: Proposed → 🟡 批准實作中
- 各 ADR 加 v1.1 變更紀錄
## K8s ConfigMap
- prod 04-configmap.yaml: 加 3 個 feature flags（均 false）
- dev 02-configmap.yaml: 同步加入
## LOGBOOK
- 記錄 WS0–WS6 + 補強完成，feature flags 啟用指引
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
163 lines
8.1 KiB
Markdown
163 lines
8.1 KiB
Markdown
# 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 宣告 |
|