From d32d494320a69fa85dc0743b284ea868e2478075 Mon Sep 17 00:00:00 2001 From: OG T Date: Sun, 12 Apr 2026 13:30:37 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=9B=E9=9A=8E=E6=AE=B5=E7=B4=B0?= =?UTF-8?q?=E5=8C=96=E5=AF=A6=E6=96=BD=E6=AD=A5=E9=A9=9F=20+=20=E6=9E=B6?= =?UTF-8?q?=E6=A7=8B=E8=BD=89=E5=9E=8B=E6=88=AA=E5=9C=96=E5=AE=9A=E6=A1=88?= =?UTF-8?q?=20+=20=E9=98=B2=E5=81=8F=E5=B7=AE=E5=AE=88=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 規格書 v2.0 新增： - §十一 四階段細化實施步驟（階段1~4各含驗收清單） - 階段1: CD解鎖+debounce+alertname+冷啟動Playbook+KM向量化（9步） - 階段2: DB Migration+classify_alert_early+outcome寫入（5步） - 階段3: 分診站+SSH路由+TYPE-1/E/F+action解析+risk_level（Tier3，7步） - 階段4: KMConversionService+手動修復記錄（4步） - §十二 防偏差守則（不跳步驟/Tier3授權/不改範圍/異常立刻報告） ADR-073 更新：架構轉型截圖定案（舊架構中斷→新架構分診飛輪） Co-Authored-By: Claude Sonnet 4.6 --- docs/LOGBOOK.md | 2 + docs/adr/ADR-073-flywheel-full-audit.md | 21 ++++- ...2-aiops-complete-flywheel-repair-design.md | 80 ++++++++++++++++++- 3 files changed, 99 insertions(+), 4 deletions(-) diff --git a/docs/LOGBOOK.md b/docs/LOGBOOK.md index 46d681a0..2355503a 100644 --- a/docs/LOGBOOK.md +++ b/docs/LOGBOOK.md @@ -38,6 +38,8 @@ | 2026-04-12 | fix(test): integration 測試排除（pytest addopts），618 單元測試全通過 | 6e0ee8b | | 2026-04-12 | docs(spec): AIOps 飛輪全面修復整合規格書 v1.0（四層方案+監控缺口+ADR-074）| 77771c1 | | 2026-04-12 | docs(adr): ADR-073 補充 ADR-071 整合工作序 + ADR-074 Sprint | f2b427d | +| 2026-04-12 | docs(spec): v2.2 §15 Subsystem 1 四階段路線圖（截圖定案）| d3ddaaf | +| 2026-04-12 | docs(spec): 規格書 v2.0 — 四階段細化實施步驟 + 防偏差守則（等待批准）| — | --- diff --git a/docs/adr/ADR-073-flywheel-full-audit.md b/docs/adr/ADR-073-flywheel-full-audit.md index c47f8136..a05550d2 100644 --- a/docs/adr/ADR-073-flywheel-full-audit.md +++ b/docs/adr/ADR-073-flywheel-full-audit.md @@ -1,9 +1,26 @@ # ADR-073: AIOps 飛輪完整盤點 — 問題根因 + 長期解決方案 -**狀態**: Accepted — 等待實作批准 +**狀態**: Accepted — 等待統帥批准實作（細化步驟已完成） **日期**: 2026-04-12 (台北時間) +**更新**: 2026-04-12 晚 — 加入架構轉型截圖定案 + 四階段細化實施步驟 **作者**: Claude Sonnet 4.6 + 首席架構師 -**觸發**: 資料庫審計顯示飛輪從未真正運轉 +**觸發**: 資料庫審計顯示飛輪從未真正運轉 +**完整規格**: `docs/superpowers/specs/2026-04-12-aiops-complete-flywheel-repair-design.md`（§十一 細化步驟、§十二 防偏差守則） + +### 架構轉型核心（2026-04-12 截圖定案） + +``` +舊架構（中斷路徑）： + 告警 → LLM 瞎目（alertname=NULL）→ 目標不明 Unknown → KM 空白 + +新架構（飛輪 V2.2）： + 告警 → 分診工作站（decision_manager 入口） + ├─ TYPE-1（資訊）→ 純文字通知，不進修復流程 + ├─ TYPE-4D（Drift）→ Drift 卡片，不進修復流程 + └─ TYPE-3（需修復）→ MCP 上下文 → LLM 推理 → 自動執行 → KM 向量化 +``` + +**關鍵洞察**：分診工作站從 telegram_gateway 前移至 decision_manager 入口，是防止「HostBackupFailed 產生 kubectl scale deployment unknown」的架構根治。 --- diff --git a/docs/superpowers/specs/2026-04-12-aiops-complete-flywheel-repair-design.md b/docs/superpowers/specs/2026-04-12-aiops-complete-flywheel-repair-design.md index 91cd7ed8..5767e456 100644 --- a/docs/superpowers/specs/2026-04-12-aiops-complete-flywheel-repair-design.md +++ b/docs/superpowers/specs/2026-04-12-aiops-complete-flywheel-repair-design.md @@ -1,10 +1,11 @@ # AWOOOI AIOps 全面修復與長期解決方案 ## 飛輪修復 + 監控補全 + 前端即時化 — 完整整合規格書 -> **文件版本**: v1.0 +> **文件版本**: v2.0 > **建立日期**: 2026-04-12（台北時間） +> **更新日期**: 2026-04-12 晚（台北時間）— 加入四階段細化實施步驟 + 架構轉型截圖定案 > **狀態**: 🔴 等待統帥批准後實作 -> **整合來源**: ADR-073（飛輪盤點）+ v2.2 規格書 §14.11（ADR-071 工作序）+ 監控覆蓋盤點 + 飛輪截圖定案 + MCP 角色分析 +> **整合來源**: ADR-073（飛輪盤點）+ v2.2 規格書 §14.11（ADR-071 工作序）+ 監控覆蓋盤點 + 飛輪截圖定案 + MCP 角色分析 + 架構轉型對比截圖 > **作者**: Claude Sonnet 4.6 --- @@ -552,3 +553,78 @@ C4（人工介入路徑視覺化） --- *文件版本 v1.0（2026-04-12 台北時間）— 整合 ADR-073 飛輪盤點 + v2.2 規格書 §14.11 ADR-071 工作序 + 監控覆蓋缺口盤點 + 飛輪截圖定案架構 + MCP 角色分析。所有實作等待統帥批准。* + +--- + +## 十一、四階段細化實施步驟（2026-04-12 截圖定案版） + +> **架構轉型核心**（截圖定案）： +> - 舊架構（中斷）：告警 → LLM 瞎目 → 目標不明 Unknown → KM 空白 +> - 新架構（飛輪 V2.2）：告警 → **分診工作站（decision_manager 入口）** → TYPE-1/TYPE-4D 分流 + MCP 上下文 → LLM 推理 → 自動執行 → KM 向量化 + +### 階段 1：CD 阻塞清除（解鎖所有後續階段） + +**解鎖條件**：無，立刻可做。Tier 2。 + +| 步驟 | 操作 | 驗收 | +|------|------|------| +| 1-1 | 確認 Harbor 有 `8be87b0` image：`curl -u admin:PWD http://192.168.0.110:5000/v2/awoooi/api/tags/list` | 輸出包含 "8be87b0" | +| 1-2 | 更新 `k8s/awoooi-prod/kustomization.yaml` newTag → `8be87b0` | `grep newTag` 顯示 8be87b0 | +| 1-3 | `git push gitea main` 觸發 ArgoCD | ArgoCD 同步完成 | +| 1-4 | 驗證 Pod image：`kubectl get pods -n awoooi-prod -o wide` | Pod 包含 8be87b0 | +| 1-5 | 驗證 `_collect_mcp_context` 存在於 Pod | grep 有輸出 | +| 1-6 | `webhooks.py` debounce TTL 300 → 1800（5→30 分鐘）| 相同告警 30 分鐘內只建 1 個 Incident | +| 1-7 | `webhooks.py` signal 建立時確保 `alertname` 正確寫入 JSONB | 新 Incident alertname 不為 NULL | +| 1-8 | 執行 `scripts/cold_start_playbooks.py`（從 2 筆 SUCCESS + 20 筆 APPROVED 生成）| `count(playbooks)` ≥ 15 | +| 1-9 | 執行 `scripts/batch_vectorize_km.py`（690 筆批次向量化，batch=50）| `count(KE WHERE vectorized=False)` = 0 | + +### 階段 2：數據完整性（ADR-071-A/A0） + +**解鎖條件**：階段 1 Pod 驗收通過。Tier 1。 + +| 步驟 | 操作 | 驗收 | +|------|------|------| +| 2-1 | DB Migration：incidents +9 欄位（alertname/notification_type/alert_category/context_bundle/metrics_before/metrics_after/verification_result/manual_fix_steps/manual_fix_by）| `\d incidents` 顯示新欄位 | +| 2-2 | PgEnum 補充 5 個 event_type（獨立 transaction）| enum 有新值 | +| 2-3 | `classify_alert_early()` 函數：在 webhooks.py 建 Incident 後立即注入 alert_category + notification_type | Backup 告警 → TYPE-1；HostHighCpu → TYPE-3 | +| 2-4 | outcome 寫入點：`_auto_execute()` 完成後寫 SUCCESS/FAILED/SKIPPED | 新 approval_record 的 incident 有 outcome | +| 2-5 | 補填現有 132 筆 NULL alertname（從 signals JSONB 反查）| `count(incidents WHERE alertname IS NULL)` = 0 | + +### 階段 3：路由與用戶體驗（ADR-071-B/C/E/F） + +**解鎖條件**：階段 2 DB Migration 完成。**Tier 3 — 需首席架構師授權**。 + +| 步驟 | 操作 | 驗收 | +|------|------|------| +| 3-1 | `decision_manager._analyze()` step 4.5 插入類別守衛：TYPE-1→send_info_notification()；TYPE-4D→send_drift_card()；TYPE-3→繼續 | HostBackupFailed → 純文字無按鈕 | +| 3-2 | `_auto_execute()` 路由層：`Docker*/Host*` alertname → SSH MCP；其餘 → K8s MCP | DockerContainerUnhealthy → SSH 執行 | +| 3-3 | 新增 `send_info_notification()`：純文字，無 reply_markup | TYPE-1 告警無按鈕 | +| 3-4 | `_build_inline_keyboard()` 依 alert_category 動態選按鈕組合 | database 告警無 [重啟][擴容] | +| 3-5 | action 字串清理：`action.split("|")[0].strip()` | 新 approval_records 無「未知操作\|」 | +| 3-6 | risk_level：YAML rule_match 有值時優先，否則 fallback LLM | HostHighCpuLoad 顯示 MEDIUM | +| 3-7 | TYPE-4D `send_drift_card()`：Diff ≤500 直接顯示；>500 回傳 Web 連結 | ConfigDrift 只有 [查看Diff][採納][回滾][忽略] | + +### 階段 4：知識引擎（ADR-071-G/H） + +**解鎖條件**：階段 3 outcome 寫入點確認正常。Tier 2。 + +| 步驟 | 操作 | 驗收 | +|------|------|------| +| 4-1 | 新增 `km_conversion_service.py`：Incident RESOLVED → 建立 KnowledgeEntryRecord + Playbook draft + embed() + vectorized=True | RESOLVED → KE 自動新增 + vectorized=True | +| 4-2 | `incident_service.resolve()` 呼叫 `KMConversionService.convert()`（非同步，不阻塞主流程）| 觸發不影響 RESOLVED 回應時間 | +| 4-3 | 每日 03:00 cron：補掃 `vectorized=False AND status=RESOLVED` | 每日清零 | +| 4-4 | `handle_callback()` 新增 `log_manual_fix` 動作：Redis 緩衝 → `/done` → `record_manual_fix()` → draft Playbook | 點擊 [手動修復後記錄] → Bot 對話 → 草稿建立 | + +--- + +## 十二、防偏差守則（本次工作） + +> 統帥明確要求：任何調整偏差立刻提出討論，不可自行決定。 + +| 守則 | 說明 | +|------|------| +| **不得跳步驟** | 階段 2 必須等階段 1 Pod 驗收通過才開始 | +| **Tier 3 必須授權** | 階段 3 整個是 Tier 3，不得在統帥批准前動 decision_manager 核心邏輯 | +| **不得自行改範圍** | 本次不碰 ADR-074 監控補全、前端 ADR-073-C，那是下一波 | +| **遇到異常立刻報告** | Harbor 無 8be87b0 image、DB Migration 失敗、KM 向量化 error rate > 10%，立刻停下報告 | +| **不得合併步驟** | DB Migration 和應用程式更新分開 commit，不合一送 |