diff --git a/.agents/skills/06-awoooi-monorepo-master.md b/.agents/skills/06-awoooi-monorepo-master.md index d4f566a70..6cbfc3632 100644 --- a/.agents/skills/06-awoooi-monorepo-master.md +++ b/.agents/skills/06-awoooi-monorepo-master.md @@ -10,11 +10,11 @@ | 欄位 | 值 | |------|-----| -| **版本** | v1.5 | +| **版本** | v1.6 | | **建立日期** | 2026-03-20 (台北) | | **建立者** | Claude Code | -| **最後修改** | 2026-03-26 15:40 (台北) | -| **修改者** | Claude Code | +| **最後修改** | 2026-04-24 22:30 (台北) | +| **修改者** | Codex | ### 變更紀錄 @@ -26,6 +26,7 @@ | v1.3 | 2026-03-26 | Claude Code | 首席架構師審查流程 + 審查週期調整 (每週) | | v1.4 | 2026-03-26 | Claude Code | 🔴 新增「封存而非刪除」策略 (統帥裁示) | | v1.5 | 2026-03-26 | Claude Code | **dependency-cruiser 依賴治理整合 (Phase 14.2)** | +| v1.6 | 2026-04-24 | Codex | **新增 12-agent 協作治理：任務判型、主責/協作 agent、9 skills 對照** | --- @@ -140,6 +141,54 @@ Co-Authored-By: Claude Opus 4.5 | 架構變更 | ✅ | | 部署成功 | ✅ | +--- + +## 12-Agent 協作治理 (2026-04-24 新增) + +> 目的：讓專案任務分工有固定語法，不再只靠臨場口頭約定。 + +### 定位 + +- `12 agents` 是任務角色分工 +- `.agents/skills/*.md` 是工程守則 +- 實際工作流：**先判型與派工，再依對應 skills 執行** + +### 最小必要組隊原則 + +1. 每個任務只能有 1 個主責 agent +2. 協作 agent 預設 1-3 位，避免過度編排 +3. 涉及紅區、Telegram、learning loop、deploy 時，自動補 `critic` + +### 常用派工規則 + +| 任務類型 | 主責 agent | 協作 agent | +|----------|-----------|-----------| +| 查 bug / 查斷點 / 找根因 | `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 / deploy | `migration-engineer` | `tool-expert`, `vuln-verifier`, `critic` | +| Telegram / approval / callback / 權限 / 安全 | `vuln-verifier` | `debugger`, `db-expert`, `critic` | +| 規劃 / 拆階段 / 驗收 | `planner` | `critic`, `onboarder` | +| 專案導覽 / 建立上下文 | `onboarder` | `planner`, `critic` | +| 官方規格 / SDK / 外部方案查證 | `web-researcher` | `planner`, `critic` | + +### 與 9 Skills 的關係 + +| 12-agent | 最接近的 skills | +|----------|------------------| +| `frontend-designer` | `01-awoooi-frontend-aesthetics` | +| `fullstack-engineer` | `01 + 02 + 06` | +| `debugger` | `02 + 05` | +| `db-expert` | `02` | +| `refactor-specialist` | `09 + 02` | +| `migration-engineer` | `09 + 06 + 04` | +| `tool-expert` | `07` | +| `critic` | `05` | + +完整規則見 `docs/12-agent-game-rules.md` + ### 格式範例 ```markdown diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..9bf9e38e7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,150 @@ +# AWOOOI Project Configuration + +> Codex 自動載入，定義核心原則 +> 全域工作流程（P7/P9/P10、三紅線、12-agent 委派表）見 `~/.Codex/AGENTS.md` + +--- + +## ⚠️ Session 啟動第一步 + +**在做任何事之前，先讀：** +1. 🔴🔴🔴 **`docs/superpowers/specs/2026-04-15-MASTER-ai-autonomous-flywheel-v2.md`** — AI 自主化飛輪 MASTER 藍圖（進行中） +2. `MEMORY.md` — 記憶索引 +3. `docs/LOGBOOK.md` — 最新進度 +4. `docs/HARD_RULES.md` — 絕對禁止規則 +5. 涉及主題的 `feedback_*.md` + +🔴🔴🔴 **AI 自主化工程進行中** — 任何告警/修復/規則/分類/通知相關變更，必須先讀 MASTER §0 Session Resume Protocol，禁止繞過。 + +🔴🔴 **檢查 `project_current_status.md` 最後更新日期** — 超過 2 天 → 先執行 Memory 清理再開工 + +--- + +## 四大核心原則 + +1. **變更前 → 先讀註解** (理解設計意圖再動手) 🔴 +2. **不可逆操作 → 人工確認** (刪除、logOut、DROP、force push) +3. **有疑問 → 先問統帥** (不確定就停下來) +4. **任務完成 → 更新 Memory** (不等被問) + +--- + +## 🔴 絕對禁止 → [HARD_RULES.md](docs/HARD_RULES.md) + +## 🔴 紅區治理 → [RED_ZONES.md](docs/RED_ZONES.md) +Tier 3 核心檔案 (decision_manager, trust_engine, config 等) 修改需首席架構師授權 + +--- + +## 專案架構 + +- `apps/api/` — FastAPI 後端 +- `apps/web/` — Next.js 前端 +- `k8s/` — Kubernetes 配置 + +## 🔴 Gitea CI/CD (ADR-039) → [reference_gitea_mirror.md](~/.Codex/projects/-Users-ogt-awoooi/memory/reference_gitea_mirror.md) + +從 2026-03-29 起，所有 CI/CD 從 Gitea 執行。推版：`git push gitea main`。GitHub 只讀備份。 + +--- + +## 🛑 修改前必讀 → [HARD_RULES.md](docs/HARD_RULES.md) + +| 檔案/功能 | 必讀章節 | +|----------|---------| +| `.github/workflows/*` | GitHub Billing | +| `*telegram*` | Telegram Token | +| `apps/web/**` | i18n | +| Incident/Approval 流程 | Telegram + DB 鏈路 | +| Alertmanager/NetworkPolicy 🔴🔴 | ADR-025 告警鏈路 E2E | +| AI Provider 路由/Fallback 🔴🔴 | Phase 24 AI Router | + +--- + +## 任務前必讀 Memory + +| 主題 | Memory | +|------|--------| +| 🔴🔴 定期清理 | `feedback_memory_cleanup_schedule.md` | +| 🔴🔴🔴 費用變更 | `feedback_cost_change_approval.md` | +| 變更前必讀 🔴 | `feedback_read_comments_first.md` | +| 變更註解 🔴🔴 | `feedback_change_annotation_standard.md` | +| 重大變更 | `feedback_product_survival_principles.md` | +| Telegram | `feedback_telegram_token_disaster.md` | +| OpenClaw | `feedback_architecture_openclaw_core.md` | +| 命名規範 | `feedback_openclaw_naming.md` | +| i18n | `feedback_i18n_zero_hardcode.md` | +| 防禦性工程/狀態機驗證 | `feedback_defensive_engineering.md` | +| 禁止孤島開發 🔴🔴 | `HARD_RULES.md` → No Island Coding | +| 主動執行與熔斷 🔴🔴 | `feedback_proactive_execution.md` + `HARD_RULES.md` → Circuit Breaker | +| 自循環工作流 🔴🔴 | `HARD_RULES.md` → Self-Loop Workflow | +| 積木化強制 🔴🔴 | `feedback_lewooogo_modular_enforcement.md` | +| API 整合 | `feedback_api_response_verification.md` | +| 構建部署 | `feedback_build_from_git_only.md` | +| 測試 🔴🔴 | `feedback_no_mock_testing.md` | +| API 路徑 🔴 | `feedback_api_path_naming.md` | +| 部署驗證 🔴🔴 | `feedback_deployment_verification.md` | +| 部署層級 🔴🔴🔴 | `feedback_deployment_layer_decision.md` | +| 告警鏈路 🔴🔴🔴 | `feedback_alertchain_e2e_validation.md` | +| Telegram Secrets 🔴🔴🔴 | `feedback_telegram_secrets_injection.md` | +| 前端內網禁令 🔴🔴🔴 | `feedback_frontend_internal_ip_ban.md` | +| AI Router 重構 🔴🔴 | `project_phase24_ai_router.md` | +| AI Fallback 順序 🔴 | `feedback_ai_fallback_order.md` | +| 前端 Icon 規範 🔴 | `feedback_no_emoji_use_icons.md` | +| 設計稿預覽 🔴 | `feedback_ui_collaboration_protocol.md` | + +--- + +## 重要規則摘要（詳情在 Memory） + +- **前端內網 IP 禁令** 🔴🔴🔴 — `NEXT_PUBLIC_*` 禁用內網 IP，用公網域名（build-time 寫死進 JS Bundle） +- **Telegram 告警鏈路** 🔴🔴🔴 — CD 必須自動注入 K8s Secrets；禁止 CHANGE_ME；部署後 E2E 驗證 → ADR-035 +- **leWOOOgo 積木化** 🔴🔴 — 修改 `apps/api/` 前必問 5 題，Router 層禁止直接存取 Redis/DB +- **Phase 24 AI Router** ✅ — ADR-052 完成，Router 只依賴 Protocol，絞殺者開關 `USE_AI_ROUTER` + +--- + +## Skills 載入 + +| 任務類型 | Skill 路徑 | +|---------|-----------| +| 前端 | `.agents/skills/01-awoooi-frontend-aesthetics.md` | +| 後端 | `.agents/skills/02-lewooogo-backend-core.md` | +| AI/決策 | `.agents/skills/03-openclaw-cognitive-expert.md` | +| DevOps | `.agents/skills/04-awoooi-devops-commander.md` | +| 測試 | `.agents/skills/05-awoooi-sre-qa.md` | +| Git | `.agents/skills/06-awoooi-monorepo-master.md` | +| Tool 整合 | `.agents/skills/07-tool-integration-expert.md` | +| 模型路由 | `.agents/skills/08-model-router-expert.md` | +| 絞殺者重構 | `.agents/skills/09-strangler-pattern-expert.md` | + +## Memory 系統 + +- 長期記憶：`~/.Codex/projects/-Users-ogt-awoooi/memory/` +- 索引：`MEMORY.md` +- 進度：`docs/LOGBOOK.md` +- 參考：[SERVICE-ENDPOINTS.md](docs/reference/SERVICE-ENDPOINTS.md) / [K3S-OPTIMIZATION-RUNBOOK.md](docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md) + +## Session 結束前 + +更新相關 Memory → 更新 LOGBOOK → 標記下一步 + +--- + +## 安全架構（ty-ai-standards Global-Local） + +本專案採用 **全域 hooks（`~/.Codex/hooks/`）+ 專案 hooks（`.Codex/hooks/`）疊加執行**。 + +| Hook | 層級 | 觸發點 | 防護內容 | +|------|------|--------|---------| +| `awoooi-guard.js` | 專案 | PreToolUse | 生產環境危險操作阻擋（待建立） | +| `branch-protection.js` | 全域 | PreToolUse | force push + 直接 commit 到 production | +| `commit-quality.js` | 全域 | PreToolUse | debugger + 硬編碼 secrets（含 secrets.local.json 補充 patterns） | +| `large-file-warner.js` | 全域 | PreToolUse | >2MB 阻擋，>500KB 警告 | +| `mcp-health.js` | 全域 | PreToolUse | MCP 冷卻保護 | +| `audit-log.js` | 全域 | PostToolUse | Bash 指令稽核 | +| `suggest-compact.js` | 全域 | PostToolUse | 50 次工具呼叫後建議 /compact | +| `cost-tracker.js` | 全域 | Stop | Token 用量追蹤 | +| `session-summary.js` | 全域 | Stop | 對話快照存檔 | + +專案 secrets pattern（`.Codex/hooks/secrets.local.json`）：Telegram / Gitea / NVIDIA / Gemini / Anthropic / PostgreSQL diff --git a/apps/api/src/agents/solver_agent.py b/apps/api/src/agents/solver_agent.py index fb0f25bde..e8e91b01e 100644 --- a/apps/api/src/agents/solver_agent.py +++ b/apps/api/src/agents/solver_agent.py @@ -317,6 +317,26 @@ def _extract_candidates(parsed: dict[str, Any]) -> list[CandidateAction]: risk_to_blast = {"critical": 60, "high": 40, "medium": 25, "low": 10} blast = risk_to_blast.get(risk_level.lower(), 30) + # 2026-04-24 ogt + Claude Sonnet 4.6: 修復信心度被語意合成硬壓問題 + # 根因：OpenClaw NIM 回傳 action_title（自然語言）+ kubectl_command（完整指令） + # 舊邏輯：action_title 無 kubectl → 語意合成 → min(confidence, 0.5) 壓到 0.5 + # 修法 A：優先採用 kubectl_command 欄位，保留原始 confidence（如 0.9） + kubectl_cmd = str(parsed.get("kubectl_command", "")).strip() + if kubectl_cmd and kubectl_cmd.startswith("kubectl"): + logger.debug( + "solver_nemo_kubectl_command_used", + action_title=action_title[:80], + kubectl_command=kubectl_cmd[:80], + confidence=confidence, + ) + return [CandidateAction( + action=kubectl_cmd[:200], + blast_radius=blast, + rollback_cost=20, + confidence=confidence, + rationale=f"OpenClaw Nemo: {action_title[:80]}", + )] + if "kubectl" in action_title.lower(): if action_title and confidence > 0: return [CandidateAction( diff --git a/apps/api/src/hermes/nl_gateway.py b/apps/api/src/hermes/nl_gateway.py index c962d05cd..3de2126a8 100644 --- a/apps/api/src/hermes/nl_gateway.py +++ b/apps/api/src/hermes/nl_gateway.py @@ -16,6 +16,7 @@ from claude_agent_sdk import query, ClaudeAgentOptions from claude_agent_sdk.types import ResultMessage from sqlalchemy import text +from src.core.config import settings from src.core.redis_client import get_redis from src.db.base import get_db_context from src.hermes.agent_loader import get_agent_system_prompt @@ -225,11 +226,15 @@ async def process_nl_message( success = False error_type: str | None = None try: + sdk_env: dict[str, str] = {} + if settings.CLAUDE_API_KEY: + sdk_env["ANTHROPIC_API_KEY"] = settings.CLAUDE_API_KEY options = ClaudeAgentOptions( system_prompt=system_prompt, max_turns=3, permission_mode="dontAsk", max_budget_usd=_HERMES_BUDGET_USD, + env=sdk_env, ) result_text = "" async for event in query(prompt=prompt_with_ctx, options=options): diff --git a/apps/api/tests/__init__.py b/apps/api/tests/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/apps/api/tests/agents/__init__.py b/apps/api/tests/agents/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/apps/api/tests/agents/test_solver_agent.py b/apps/api/tests/agents/test_solver_agent.py new file mode 100644 index 000000000..a4c508fd3 --- /dev/null +++ b/apps/api/tests/agents/test_solver_agent.py @@ -0,0 +1,159 @@ +""" +solver_agent._extract_candidates 單元測試 + +2026-04-24 ogt + Claude Sonnet 4.6: 修法 A — kubectl_command 優先路徑驗證 +""" + +from __future__ import annotations + +import sys +import os + +# 確保 src 可找到 +sys.path.insert(0, os.path.join(os.path.dirname(__file__), "../../")) + +import pytest + +from src.agents.solver_agent import _extract_candidates + + +class TestExtractCandidatesNemoFormat: + """OpenClaw Nemo 格式解析測試""" + + def test_kubectl_command_field_preserves_confidence(self): + """修法 A 核心：kubectl_command 存在時，confidence 不被壓縮""" + parsed = { + "action_title": "重啟 Crash Looping Pod", + "kubectl_command": "kubectl rollout restart deployment/awoooi-api -n awoooi-prod", + "confidence": 0.9, + "risk_level": "medium", + } + result = _extract_candidates(parsed) + + assert len(result) == 1 + c = result[0] + assert c.confidence == 0.9, f"期望 0.9，實際 {c.confidence}" + assert c.action == "kubectl rollout restart deployment/awoooi-api -n awoooi-prod" + assert "OpenClaw Nemo" in c.rationale + assert "重啟 Crash Looping Pod" in c.rationale + + def test_kubectl_command_field_high_confidence(self): + """kubectl_command 存在，confidence 0.85 仍完整保留""" + parsed = { + "action_title": "Scale Down Pod Count", + "kubectl_command": "kubectl scale deployment/awoooi-api --replicas=2 -n awoooi-prod", + "confidence": 0.85, + "risk_level": "low", + } + result = _extract_candidates(parsed) + + assert len(result) == 1 + assert result[0].confidence == 0.85 + assert result[0].blast_radius == 10 # risk_level=low → blast=10 + + def test_kubectl_command_field_takes_priority_over_synthesis(self): + """kubectl_command 存在時，不走語意合成（不被 min(0.5) 壓）""" + parsed = { + "action_title": "重啟服務", # 若無 kubectl_command，會走語意合成被壓到 0.5 + "kubectl_command": "kubectl rollout restart deployment/api -n awoooi-prod", + "confidence": 0.9, + "risk_level": "medium", + } + result = _extract_candidates(parsed) + + assert len(result) == 1 + assert result[0].confidence == 0.9, "kubectl_command 路徑不應觸發 min(confidence, 0.5)" + + def test_no_kubectl_command_action_title_has_kubectl(self): + """舊路徑向後相容：action_title 本身含 kubectl，無 kubectl_command""" + parsed = { + "action_title": "kubectl rollout restart deployment -n awoooi-prod", + "confidence": 0.8, + "risk_level": "medium", + } + result = _extract_candidates(parsed) + + assert len(result) == 1 + assert result[0].confidence == 0.8 + assert "kubectl rollout restart" in result[0].action + + def test_no_kubectl_command_synthesis_caps_confidence(self): + """語意合成備援路徑：confidence 仍被 min(0.5) 壓制（預期行為）""" + parsed = { + "action_title": "重啟服務", # 無 kubectl_command，觸發語意合成 + "confidence": 0.9, + "risk_level": "medium", + } + result = _extract_candidates(parsed) + + assert len(result) == 1 + assert result[0].confidence == 0.5, "語意合成路徑 confidence 必須被壓到 0.5" + assert "[語意合成]" in result[0].rationale + + def test_kubectl_command_empty_string_falls_through(self): + """kubectl_command 為空字串時，回落到既有邏輯""" + parsed = { + "action_title": "重啟服務", + "kubectl_command": "", + "confidence": 0.9, + "risk_level": "medium", + } + result = _extract_candidates(parsed) + + # 空 kubectl_command → 走語意合成 → confidence 被壓 + assert len(result) == 1 + assert result[0].confidence == 0.5 + + def test_kubectl_command_not_starting_with_kubectl_falls_through(self): + """kubectl_command 非 kubectl 開頭（可能是雜訊），回落到既有邏輯""" + parsed = { + "action_title": "重啟服務", + "kubectl_command": "helm rollback awoooi-api", + "confidence": 0.9, + "risk_level": "medium", + } + result = _extract_candidates(parsed) + + # helm 指令不被採用 → 語意合成 → confidence 被壓 + assert len(result) == 1 + assert result[0].confidence == 0.5 + + def test_no_action_title_no_candidates_uses_standard_path(self): + """標準 candidates 陣列格式不受影響""" + parsed = { + "candidates": [ + { + "action": "kubectl rollout restart deployment/api -n awoooi-prod", + "blast_radius": 25, + "rollback_cost": 20, + "confidence": 0.85, + "rationale": "重啟修復 OOM", + } + ] + } + result = _extract_candidates(parsed) + + assert len(result) == 1 + assert result[0].confidence == 0.85 + assert result[0].blast_radius == 25 + + def test_risk_level_blast_radius_mapping(self): + """risk_level → blast_radius 映射正確""" + cases = [ + ("critical", 60), + ("high", 40), + ("medium", 25), + ("low", 10), + ("unknown", 30), # 預設 + ] + for risk_level, expected_blast in cases: + parsed = { + "action_title": "fix", + "kubectl_command": "kubectl get pods -n awoooi-prod", + "confidence": 0.9, + "risk_level": risk_level, + } + result = _extract_candidates(parsed) + assert result[0].blast_radius == expected_blast, ( + f"risk_level={risk_level} → 期望 blast={expected_blast}，實際 {result[0].blast_radius}" + ) diff --git a/docs/12-agent-game-rules.md b/docs/12-agent-game-rules.md new file mode 100644 index 000000000..87f9b666b --- /dev/null +++ b/docs/12-agent-game-rules.md @@ -0,0 +1,136 @@ +--- +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-04-24 (台北) +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) +- [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)