254 lines
11 KiB
Markdown
254 lines
11 KiB
Markdown
---
|
||
title: 12-Agent Game Rules
|
||
description: AWOOOI 12-agent 新遊戲規則 v1，定義任務自動判型、主責/協作派工與 9 skills 對照
|
||
version: v1.0
|
||
created: 2026-04-24 (台北)
|
||
created_by: Codex
|
||
last_modified: 2026-05-02 (台北)
|
||
last_modified_by: Codex
|
||
---
|
||
|
||
# 12-Agent 新遊戲規則 v1
|
||
|
||
> 目的：把 12 個分工 agent 從「審計與設計概念」落成「日常任務派工規則」。
|
||
|
||
## 定位
|
||
|
||
- `12 agents` 是任務分工角色
|
||
- `.agents/skills/*.md` 9 份是工程守則與實作規範
|
||
- 實際工作模式：先用 12-agent 判型與分工，再落到對應 skill 規範執行
|
||
|
||
## 12 Agents 名單
|
||
|
||
| Agent | 核心職責 |
|
||
|------|----------|
|
||
| `critic` | 架構審查、回歸風險、規範稽核 |
|
||
| `vuln-verifier` | 安全驗證、漏洞風險、權限與 secrets 邊界 |
|
||
| `debugger` | 查斷點、還原 execution path、找根因 |
|
||
| `db-expert` | schema / migration / learning loop / SQL 正確性 |
|
||
| `planner` | 任務拆解、Phase 排程、驗收清單 |
|
||
| `fullstack-engineer` | 前後端串接與功能完整落地 |
|
||
| `frontend-designer` | UI/UX、版面、設計一致性、i18n 呈現 |
|
||
| `refactor-specialist` | God class 拆分、抽層、技術債清理 |
|
||
| `migration-engineer` | 新舊路徑切換、Gitea/CI/CD/GitOps 遷移與回滾 |
|
||
| `onboarder` | 新 session 導覽、脈絡建立、文件地圖 |
|
||
| `tool-expert` | MCP / provider / Prometheus / K8s / SSH 工具整合 |
|
||
| `web-researcher` | 官方規格、外部 API / SDK / 文件事實查核 |
|
||
|
||
## 9 Skills vs 12 Agents
|
||
|
||
| 12-agent | 最接近的 skills |
|
||
|----------|------------------|
|
||
| `frontend-designer` | `01-awoooi-frontend-aesthetics` |
|
||
| `fullstack-engineer` | `01 + 02 + 06` |
|
||
| `debugger` | `02 + 05` |
|
||
| `db-expert` | `02` |
|
||
| `planner` | `06` |
|
||
| `refactor-specialist` | `09 + 02` |
|
||
| `migration-engineer` | `09 + 06 + 04` |
|
||
| `tool-expert` | `07` |
|
||
| `web-researcher` | `07`（外部整合與規格查核側） |
|
||
| `critic` | `05`（加上 ADR / HARD_RULES 審查） |
|
||
| `vuln-verifier` | `04 + 05 + 03` |
|
||
| `onboarder` | `06` |
|
||
|
||
## 模組責任區
|
||
|
||
| Agent | 主要責任區 |
|
||
|------|------------|
|
||
| `critic` | `docs/adr/`, `docs/HARD_RULES.md`, `docs/RED_ZONES.md`, `docs/LOGBOOK.md` |
|
||
| `vuln-verifier` | `apps/api/src/services/telegram_gateway.py`, `auto_approve.py`, `apps/api/src/core/config.py`, `k8s/awoooi-prod/` |
|
||
| `debugger` | `decision_manager.py`, `apps/api/src/api/v1/webhooks.py`, `apps/api/src/jobs/`, `apps/api/src/services/` |
|
||
| `db-expert` | `apps/api/migrations/`, `learning_service.py`, `playbook_service.py`, `repositories/` |
|
||
| `planner` | `docs/superpowers/specs/`, `docs/superpowers/plans/`, `project_current_status.md`, `project_master_workplan.md` |
|
||
| `fullstack-engineer` | `apps/web/`, `apps/api/src/api/v1/`, `docs/api/openapi.yaml` |
|
||
| `frontend-designer` | `apps/web/src/`, `docs/design/`, `docs/guidelines/FRONTEND.md`, `docs/screenshots/` |
|
||
| `refactor-specialist` | `openclaw.py`, `decision_manager.py`, `apps/api/src/api/v1/`, `packages/` |
|
||
| `migration-engineer` | `.gitea/workflows/`, `ADR-039`, `ADR-059`, `gitea_webhook.py` |
|
||
| `onboarder` | `AGENTS.md`, MASTER 藍圖, `docs/LOGBOOK.md`, Memory 索引 |
|
||
| `tool-expert` | `apps/api/src/providers/`, `services/*provider*`, `ADR-001`, `ADR-015` |
|
||
| `web-researcher` | `ADR-093`, `ADR-094`, `ADR-095` 等需要官方規格驗證的設計文檔 |
|
||
|
||
## 自動派工規則
|
||
|
||
### 主責判型
|
||
|
||
| 任務描述關鍵字 | 主責 agent | 預設協作 |
|
||
|---------------|-----------|---------|
|
||
| 壞了、沒反應、查一下、找根因 | `debugger` | `db-expert`, `tool-expert`, `critic` |
|
||
| migration、SQL、playbook、KM、learning | `db-expert` | `debugger`, `refactor-specialist` |
|
||
| 前端、頁面、UI、戰情中心、i18n | `frontend-designer` | `fullstack-engineer`, `critic` |
|
||
| 前後端一起改、API 串 UI、完整落地 | `fullstack-engineer` | `frontend-designer`, `debugger`, `db-expert` |
|
||
| 重構、拆模組、抽層、技術債 | `refactor-specialist` | `migration-engineer`, `critic`, `db-expert` |
|
||
| Gitea、Webhook、CI/CD、部署、GitOps | `migration-engineer` | `tool-expert`, `vuln-verifier`, `critic` |
|
||
| Prometheus、MCP、SSH、K8s 工具、provider | `tool-expert` | `debugger`, `migration-engineer` |
|
||
| Telegram、approval、callback、群組、權限、安全 | `vuln-verifier` | `debugger`, `db-expert`, `critic` |
|
||
| 規劃、拆階段、排優先級、列清單 | `planner` | `critic`, `onboarder` |
|
||
| 盤點專案、看懂脈絡、建立上下文 | `onboarder` | `planner`, `critic` |
|
||
| review、找風險、驗證規範 | `critic` | 依主題加其他 agent |
|
||
| 官方文件、外部規格、SDK/API 事實 | `web-researcher` | `planner`, `critic` |
|
||
|
||
### 強制加簽規則
|
||
|
||
- 碰 `decision_manager.py`、`config.py`、learning loop、Telegram approval 鏈：必加 `critic`
|
||
- 碰 migration、schema、playbook trust、KM 寫入：必加 `db-expert`
|
||
- 碰 CI/CD、secrets、webhook、deployment：必加 `vuln-verifier`
|
||
- 碰大型重構：必加 `migration-engineer`
|
||
|
||
## 常用組隊模板
|
||
|
||
### 1. 告警沒送到 Telegram
|
||
|
||
- 主責：`debugger`
|
||
- 協作：`vuln-verifier`, `db-expert`, `critic`
|
||
|
||
### 2. AI 飛輪沒學到
|
||
|
||
- 主責：`db-expert`
|
||
- 協作：`debugger`, `refactor-specialist`, `critic`
|
||
|
||
### 3. 前端首頁或戰情中心重做
|
||
|
||
- 主責：`frontend-designer`
|
||
- 協作：`fullstack-engineer`, `critic`
|
||
|
||
### 4. Gitea / webhook / deploy 壞掉
|
||
|
||
- 主責：`migration-engineer`
|
||
- 協作：`tool-expert`, `vuln-verifier`, `critic`
|
||
|
||
### 5. 大型重構但怕炸
|
||
|
||
- 主責：`refactor-specialist`
|
||
- 協作：`migration-engineer`, `db-expert`, `critic`
|
||
|
||
## 執行原則
|
||
|
||
1. 不為了形式把 12 個 agent 全部攤開，永遠採「最小必要組隊」
|
||
2. 先定主責，再補 1-3 位必要協作
|
||
3. 所有 agent 的實作仍必須遵守對應 skills、HARD_RULES、MASTER 與 memory
|
||
4. 若任務涉及 AI 自主化、告警、修復、規則、分類、通知，先回到 MASTER §0 / §8 校準
|
||
|
||
## 關聯文件
|
||
|
||
- [ADR-095: 12-Agent Claude SDK 整合 × Telegram 視覺分派](/Users/ogt/awoooi/docs/adr/ADR-095-12agent-sdk-integration.md)
|
||
- [ADR-106: AwoooP Agent Platform 架構](/Users/ogt/awoooi/docs/adr/ADR-106-agent-platform-architecture.md)
|
||
- [ADR-107: AwoooP 控制面儲存策略](/Users/ogt/awoooi/docs/adr/ADR-107-awooop-control-plane-storage.md)
|
||
- [AwoooP Master Workplan（P0 防爆版）](/Users/ogt/awoooi/docs/awooop/MASTER-WORKPLAN.md) — AwoooP 實作前主索引
|
||
- [Skill 06: AWOOOI Monorepo Master](/Users/ogt/awoooi/.agents/skills/06-awoooi-monorepo-master.md)
|
||
- [MASTER 藍圖](/Users/ogt/awoooi/docs/superpowers/specs/2026-04-15-MASTER-ai-autonomous-flywheel-v2.md)
|
||
|
||
## AI 治理告警事件規範（本輪新增）
|
||
|
||
- 目標：把治理告警輸出固定為「可解析」「可追蹤」「可行動」三層結構，並讓 Telegram 與 AI Agent 能直接接力執行。
|
||
- 版本：`governance_event_v1`，適用模組：
|
||
- `governance_agent.py`（`_alert()`）
|
||
- `failover_alerter.py`（告警推送）
|
||
- `ai_slo_watchdog_job.py`（META 告警）
|
||
- JSON Schema：[/Users/ogt/awoooi/docs/schemas/governance_event_v1.schema.json](docs/schemas/governance_event_v1.schema.json)
|
||
|
||
### 1) 通用 Schema
|
||
|
||
```json
|
||
{
|
||
"status": "info|warning|critical",
|
||
"impact": {
|
||
"keys": "...",
|
||
"ratios": "...",
|
||
"counts": "..."
|
||
},
|
||
"remediation": {
|
||
"items": [
|
||
"...",
|
||
"..."
|
||
],
|
||
"next_action": "...",
|
||
"hint": "..."
|
||
},
|
||
"actionable": {
|
||
"items": [
|
||
"人工可直接執行的項目",
|
||
"可自動化接續的項目"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2) 事件清單（核心）
|
||
|
||
| event_type | 來源 | status 規則 | remediation 結構 |
|
||
|---|---|---|---|
|
||
| `trust_drift` | `governance_agent.check_trust_drift` | 風險警示時 `warning`；未超標可不推送 | `auto_deprecated_count/ids`, `playbook_ids` |
|
||
| `knowledge_degradation` | `governance_agent.check_knowledge_degradation` | 過比例時 `warning` | `next_action=run_kb_growth_healthcheck` |
|
||
| `governance_slo_data_gap` | `governance_agent.run_self_check` | 所有 SLO metric 無 emit 時 `warning` | `next_action=run_adr100_slo_emit_playbook` |
|
||
| `llm_hallucination` | `governance_agent.check_llm_hallucination` | 過比例時 `warning` | `next_action=run_knowledge_gap_audit` |
|
||
| `execution_blast_radius` | `governance_agent.check_execution_blast_radius` | 過比例時 `warning` | `next_action=pause_auto_repair_for_top_failing_playbooks` |
|
||
| `governance_slo_<metric>_violation` | `governance_agent.check_slo_compliance` | `status=violation` | `next_action=trigger_flywheel_safeguard` |
|
||
| `slo_*`/`governance_*` | 其他治理事件 | 按事件需求保留最小欄位但建議同 schema |
|
||
|
||
### 3) 收斂與自動化建議
|
||
|
||
- 將所有 AI 治理事件都寫入 `AiGovernanceEvent`（PG）+ Telegram，建立可回放 `event_type` 時序。
|
||
- 對 `governance_slo_data_gap` / `trust_drift` / `knowledge_degradation` 要求必填：
|
||
- `status`
|
||
- `impact`
|
||
- `remediation`
|
||
- `actionable`
|
||
|
||
- W-1~W-6 自健診（`ai_slo_watchdog_job.py`）以 `system_impact` 明確列出異常 KPI 與序號清單，避免 `W-6` 漏報文案誤解。
|
||
|
||
### 4) 快速 Sample（供 AGENT/Parser 套件直接接力）
|
||
|
||
```json
|
||
{
|
||
"event_type": "trust_drift",
|
||
"status": "warning",
|
||
"impact": {
|
||
"drifted_count": 4,
|
||
"total_playbooks": 26,
|
||
"drift_ratio": 0.153,
|
||
"auto_deprecated_count": 0,
|
||
"auto_deprecated_ids": [],
|
||
"playbook_ids": [
|
||
"PB-20260501-27910D",
|
||
"PB-COLD-745C00B9",
|
||
"PB-20260405-1CF853",
|
||
"PB-20260409-B66B1A"
|
||
]
|
||
},
|
||
"remediation": {
|
||
"next_action": "review_trust_drift_candidates",
|
||
"items": [
|
||
"確認各 playbook 最近 14 天執行結果是否含高失敗/高重試",
|
||
"必要時啟用 trial auto-deprecate"
|
||
]
|
||
},
|
||
"actionable": {
|
||
"items": [
|
||
"可自動註記可降級清單",
|
||
"可自動生成 approval-free dry-run 回放報告"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5) 事件處理路徑（非人肉清單）
|
||
|
||
- `trust_drift`：
|
||
- 立即：保留低信任但新近使用 Playbook 清單，輸出 `playbook_ids`
|
||
- 自動：`AUTO_DEPRECATED` 當日 30 天內未更新的 Playbook 自動降級
|
||
- 人工：人工覆核 playbook 風險，決定是否 rollback
|
||
- `knowledge_degradation`：
|
||
- 主責：Hermes 反查 Incident / Sentry / SigNoz / PlayBook，產生 KM 更新草稿與任務
|
||
- 輔責：OpenClaw 提供告警分類、規則匹配與 PlayBook 脈絡摘要
|
||
- 稽核：ElephantAlpha read-only 檢查高影響草稿與風險，不執行寫入或通知
|
||
- 人工：KM owner / SRE owner 審核高影響 KM 後才允許寫入
|
||
- 自動：觸發 `run_kb_growth_healthcheck`
|
||
- 續接：`playbook_evidence` / `kb_rot_cleaner` 補齊缺口
|
||
- `governance_slo_data_gap`：
|
||
- 自動：`run_adr100_slo_emit_playbook`
|
||
- 檢查：所有 API Pod 是否已掛載 `PROMETHEUS_MULTIPROC_DIR`，Prometheus rules 已載入
|
||
- `governance_slo_*_violation`：
|
||
- 自動：暫停高風險 auto-repair 路徑（`flywheel safeguard`）
|
||
- 人工：review 最近 1 小時 self-check 失敗樣本
|