diff --git a/docs/12-agent-game-rules.md b/docs/12-agent-game-rules.md index 87f9b666..69dfacbc 100644 --- a/docs/12-agent-game-rules.md +++ b/docs/12-agent-game-rules.md @@ -4,7 +4,7 @@ description: AWOOOI 12-agent 新遊戲規則 v1,定義任務自動判型、主 version: v1.0 created: 2026-04-24 (台北) created_by: Codex -last_modified: 2026-04-24 (台北) +last_modified: 2026-05-02 (台北) last_modified_by: Codex --- @@ -134,3 +134,60 @@ last_modified_by: Codex - [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) + +## AI 治理告警事件規範(本輪新增) + +- 目標:把治理告警輸出固定為「可解析」「可追蹤」「可行動」三層結構,支援 telegram + PG + AI 決策。 +- 版本:`governance_event_v1`,適用模組: + - `governance_agent.py`(`_alert()`) + - `failover_alerter.py`(告警推送) + - `ai_slo_watchdog_job.py`(META 告警) + +### 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` | 舊有 payload(待重構) | +| `execution_blast_radius` | `governance_agent.check_execution_blast_radius` | 舊有 payload(待重構) | +| `governance_slo__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` 漏報文案誤解。 diff --git a/docs/LOGBOOK.md b/docs/LOGBOOK.md index 05a8cb27..97ff538d 100644 --- a/docs/LOGBOOK.md +++ b/docs/LOGBOOK.md @@ -6,6 +6,22 @@ --- +## 2026-05-02 | AI治理告警 Schema 與收斂規範定稿(本輪) + +承接剛完成的治理輸出優化需求,這一輪把 `governance` 告警抽象成可治理事件格式,讓報告從「看得懂」變「可自動化處理」。 + +### 完成 +- 在 [12-Agent 規則](/Users/ogt/awoooi/docs/12-agent-game-rules.md) 新增「AI治理告警事件規範(governance_event_v1)」: + - 統一事件欄位:`status / impact / remediation / actionable` + - 覆蓋事件:`trust_drift`、`knowledge_degradation`、`governance_slo_data_gap`、`governance_slo_*_violation` + - 明示 `governance_slo_data_gap` 的下一步 `run_adr100_slo_emit_playbook` 與 `PROMETHEUS_MULTIPROC_DIR` 前置檢查 +- 設定 `docs/12-agent-game-rules.md` 中的治理事件收斂規範為後續各模組輸出的預設 schema。 +- `ai_slo_watchdog_job.py` 系統影響文案已同步修正為 `W-1~W-6`,與實際檢查清單一致。 +- 將 2026-05-02 的治理告警整合結果登錄,作為下一輪「是否可自動化修復」判斷依據,不再只靠臨時文字觀測。 + +### 驗證 +- 代碼改動已在上一輪 commit 寫入(含 `governance_agent.py`、`ai_slo_watchdog_job.py`、`webhooks.py`)並推送到 `gitea main`。 + ## 2026-05-02 | trust_drift 飛輪自治:低信任未使用 playbook 自動 deprecate 承接統帥對 governance 類告警的全面授權。trust_drift 過去只發 Telegram 告警,4 個低信任 playbook 一直在告警表內噴噪音。 @@ -238,6 +254,41 @@ Claude Code 成本評估指出真正瓶頸不是外部 AI 費用,而是同一 - Prod 手動套用 `adr105_mcp_audit_snapshots.sql` 通過,確認四表存在,且 `mcp_audit_log` 含 `agent_role` 欄位。 - 修復 Gitea migration workflow:將 `postgresql+asyncpg://` 轉成 `postgresql://` 再交給 `psql`,避免 migration CI 退成 local socket。 +## 2026-05-02 | CD ArgoCD 部署流程:跳過 deploy marker 對正式流程的阻斷 + +**觸發**:`post-deploy-checks` 有機會在 deploy marker commit(`chore(cd): deploy ... [skip ci]`)的併發情境中被卡為 skipped/blocked,缺少部署完成證據回報。 + +### 修復 + +- `.gitea/workflows/cd.yaml` + - 將 `concurrency.cancel-in-progress` 調整為:對 `chore(cd): deploy` / `[skip ci]` 類 marker commit 不做取消;避免其打斷既有主跑流程。 + - 為 `tests` 與 `build-and-deploy` 加上條件,marker commit 不重跑主部署路徑(僅保留實際 commit 的建置/部署)。 + - `post-deploy-checks` 改為 `always()` + 以 marker/成功主流程條件 gate,避免因上游 skipped 導致證據階段不執行。 + - 新增 `Emit On-Call CD Deployment Checklist` step,將 5+項一致性檢核輸出到 Job 內並附加到 Telegram 成功/失敗訊息,值班直接複製貼上即可。 + - Telegram 成功/失敗通知加入固定標記 `[CD-Checklist]`,便於值班訊息快速篩選與關聯。 + +### 驗證 + +- workflow 變更已落盤至 `cd.yaml`,並與前次 `deploy`/`post-deploy` 狀態偏移原因對齊。 +- 待你下次推送實際 `main` 變更後,核對 Gitea Actions:`build-and-deploy` 成功時 `post-deploy-checks` 應有執行紀錄且可回寫狀態。 + +### 推送前後檢核清單(CD 狀態一致性) + +1. 觸發前: + - 確認這次推送的 commit 訊息**不是** `chore(cd): deploy ... [skip ci]`(若是,為 marker commit,正常不重跑建置)。 +2. 觸發後(同一次 `main` push)在 Actions 觀察: + - `tests` 為 `success`。 + - `build-and-deploy` 為 `success`。 + - `post-deploy-checks` 有 `in_progress -> success`(不要停在 `skipped`)。 +3. `build-and-deploy` 內部檢核: + - `Deploy to K8s (ArgoCD GitOps)` 需有 `✅ 部署完成` 或對應 rollout 完成訊息。 + - `HEALTH` 檢查需可見 `✅ API 健康檢查通過`。 +4. `post-deploy-checks` 內部檢核: + - `Alert Chain Smoke Test`、`Monitoring Coverage Check`、`E2E Smoke Test` 的步驟結果可讀且有輸出(即使 smoke 以 continue-on-error 規格失敗也要能看到告警訊息)。 +5. 狀態回寫一致性: + - 若 `post-deploy-checks` 任一步失敗,應觸發對應 failure 通知。 + - 不應再出現「`build-and-deploy` 成功、但 `post-deploy-checks` 留存為 `skipped`」的長期現象。 + ## 2026-05-01 | HostBackupFailed rule-first e2e 補洞 Live e2e 用 `HostBackupFailed` 打 Alertmanager 後發現 aged backup 告警會被分類成 `backup_failure`,未命中原本只允許 `host_resource` 的 rule-first gate,導致又進 OpenClaw LLM。