---
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 失敗樣本