# ADR-028: 失敗自動修復閉環架構 (Failure Auto-Repair Loop) > **狀態**: 📋 Proposed > **提案日期**: 2026-03-26 > **決策者**: 統帥 > **提案者**: 首席架構師 ## Context AWOOOI 行動日誌頁面顯示大量失敗操作，但系統只是「記錄」： ``` 失敗 → 記錄 → 結束 (死路) ``` 這違反了 AIOps 產品的核心價值。作為 AI 產品，應該是： ``` 失敗 → AI 分析 → 自動/人工修復 → 驗證 → 學習 ``` ## Decision 實作「失敗自動修復閉環」架構，包含以下核心元件： ### 1. FailureWatcher Worker ```python class FailureWatcher: """ 監聽 AuditLog 失敗事件的 Worker 消費 Redis Stream: awoooi:audit_logs:failed """ async def handle_failure(self, audit_log: AuditLog): # 1. AI 分析失敗原因 analysis = await self.repair_analyzer.analyze(audit_log) # 2. 建立修復日誌 repair_log = await self.create_repair_log(audit_log, analysis) # 3. 根據風險等級路由 if analysis.risk_level == "LOW": await self.auto_repair(repair_log) else: await self.request_approval(repair_log) ``` ### 2. RepairAnalyzer (OpenClaw 整合) ```python class RepairAnalyzer: """ 使用 OpenClaw 分析失敗原因並生成修復策略 """ async def analyze(self, audit_log: AuditLog) -> RepairAnalysis: prompt = f""" 分析以下 K8s 操作失敗原因： 操作類型: {audit_log.operation_type} 目標資源: {audit_log.target_resource} 命名空間: {audit_log.namespace} 錯誤訊息: {audit_log.error_message} K8s 回應: {audit_log.k8s_response} 請提供： 1. 失敗原因分析 2. 建議修復策略 3. 風險等級 (LOW/MEDIUM/CRITICAL) 4. 是否可自動修復 """ return await self.openclaw.analyze(prompt) ``` ### 3. 資料模型 ```python # 擴展 AuditLog class AuditLog: # ... 現有欄位 ... authorization_channel: Mapped[str | None] # "web" | "telegram" | "auto" authorized_by: Mapped[str | None] authorized_at: Mapped[datetime | None] # 新增 RepairLog class RepairLog(Base): __tablename__ = "repair_logs" id: Mapped[str] = mapped_column(String(36), primary_key=True) original_audit_id: Mapped[str] = mapped_column(ForeignKey("audit_logs.id")) # AI 分析結果 failure_reason: Mapped[str] = mapped_column(Text) repair_strategy: Mapped[str] = mapped_column(Text) repair_command: Mapped[str | None] = mapped_column(Text) # 風險與狀態 risk_level: Mapped[str] = mapped_column(String(20)) # LOW/MEDIUM/CRITICAL auto_repaired: Mapped[bool] = mapped_column(default=False) repair_status: Mapped[str] = mapped_column(String(20)) # pending/executing/success/failed # 時間戳 created_at: Mapped[datetime] completed_at: Mapped[datetime | None] # 關聯 original_audit: Mapped["AuditLog"] = relationship() ``` ### 4. 修復流程 ``` ┌──────────────────────────────────────────────────────────────────┐ │ 失敗自動修復閉環 │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────┐ ┌──────────────┐ ┌─────────────┐ │ │ │ AuditLog│───▶│FailureWatcher│───▶│RepairAnalyzer│ │ │ │ (失敗) │ │ (偵測) │ │ (AI 分析) │ │ │ └─────────┘ └──────────────┘ └──────┬──────┘ │ │ │ │ │ ▼ │ │ ┌───────────────┐ │ │ │ Trust Engine │ │ │ │ (風險評估) │ │ │ └───────┬───────┘ │ │ │ │ │ ┌──────────────────┼──────────────────┐ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌───────────┐ ┌───────────┐ ┌─────────┐│ │ │ LOW │ │ MEDIUM │ │CRITICAL ││ │ │ 自動執行 │ │ 單人授權 │ │Multi-Sig││ │ └─────┬─────┘ └─────┬─────┘ └────┬────┘│ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────────────────────┐ │ │ │AutoRepair │ │ 同步推送 │ │ │ │Executor │ │ • Telegram Bot │ │ │ │(自動修復) │ │ • Web Dashboard (WebSocket) │ │ │ └──────┬──────┘ └────────────┬────────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ 揭露通知 │ │ 等待授權 │ │ │ │ (Dashboard) │ │ (記錄來源) │ │ │ └─────────────┘ └──────┬──────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 執行修復 │ │ │ └──────┬──────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 驗證 │ │ │ └──────┬──────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ Playbook │ │ │ │ 學習萃取 │ │ │ └─────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────┘ ``` ### 5. 授權來源追蹤 | Channel | 說明 | 記錄內容 | |---------|------|---------| | `auto` | AI 自動執行 | `authorized_by: "system"` | | `web` | 前端 Dashboard | `authorized_by: "{user_id}"` | | `telegram` | Telegram Bot | `authorized_by: "{telegram_user_id}"` | ### 6. 前端揭露 在 Dashboard 新增「AI 自動修復報告」區塊： - 過去 24 小時自動修復統計 - 最近自動修復列表 - 修復成功/失敗比例 - 需人工介入的項目 ### 7. API 端點 ``` GET /api/v1/repairs # 修復日誌列表 GET /api/v1/repairs/{id} # 修復詳情 POST /api/v1/repairs/{id}/execute # 人工觸發修復 GET /api/v1/repairs/stats # 統計 (自動/人工比例) ``` ## Consequences ### Positive 1. **AI 真正主動** - 不再等人操作，自動偵測並修復 2. **透明揭露** - 用戶清楚知道 AI 做了什麼 3. **授權可追溯** - 記錄每次授權的來源和時間 4. **降低 MTTR** - 低風險問題秒級自動修復 ### Negative 1. **複雜度增加** - 需要新增 Worker、模型、API 2. **風險** - 自動修復可能造成更大問題 (透過 cooldown 緩解) 3. **成本** - 每次分析需要 OpenClaw API 呼叫 ### Risks | 風險 | 機率 | 影響 | 緩解措施 | |------|------|------|---------| | 自動修復失敗 | 中 | 中 | 失敗自動升級為人工審批 | | 修復風暴 | 低 | 高 | Cooldown: 同資源 5 分鐘 3 次上限 | | AI 誤判風險 | 中 | 中 | 保守分類，有疑問升級為 MEDIUM | ## Integration Feasibility (首席架構師評估 2026-03-26) ### 現有架構相容性: ✅ 95% 相容 調研結論：系統已具備所有必要基礎設施，可無縫整合。 | 組件 | 可復用程度 | 說明 | |------|----------|------| | Redis Stream (XREADGROUP) | ✅ 100% | SignalWorker 模式直接複製 | | Worker 消費循環 | ✅ 100% | 代碼結構完全相同 | | AuditLog 持久化 | ✅ 90% | 只需新增 3 欄位 | | Trace Context | ✅ 100% | restore_trace_context() 可用 | | OpenClaw AI | ✅ 70% | 需新增 analyze_failure() | | Telegram 推送 | ✅ 80% | 改為推送修復卡片 | ### 衝突點與緩解 | 風險 | 緩解方案 | |------|---------| | 重試無限迴圈 | `max_retry_count = 3` | | OpenClaw 過載 | backpressure queue (max 50) | | Telegram 風暴 | 10 秒批量聚合 | | 決策二重性 | DecisionManager 優先 | ### 模組化驗證 ``` ✅ leWOOOgo 積木化原則檢查: ├── Protocol 先行: IFailureWatcher, IRepairAnalyzer ├── Router 層乾淨: /api/v1/repairs/* 只做 HTTP 轉發 ├── Service 注入: get_failure_watcher() Singleton ├── Repository 分離: AuditLogRepository.list_failures() └── Worker 獨立: failure-watcher-worker Deployment ``` ## Implementation Plan (修訂版) | Phase | 內容 | 預估 | 優先級 | |-------|------|------|--------| | 18.1 | AuditLog 表擴展 + Migration | 2h | P0 | | 18.2 | FailureWatcher Service | 6h | P0 | | 18.3 | FailureWatcherWorker (K8s) | 4h | P0 | | 18.4 | OpenClaw 失敗分析方法 | 8h | P1 | | 18.5 | Telegram 修復卡片 | 3h | P1 | | 18.6 | E2E 測試 + 部署驗證 | 6h | P0 | **總計: 29h (~3.6 天)** ### 工作依賴順序 ``` 18.1 (DB) ─┬─→ 18.2 (Service) ─┬─→ 18.3 (Worker) ─→ 18.6 (E2E) │ │ │ └─→ 18.5 (Telegram) │ └─→ 18.4 (OpenClaw) ──────────────────→ 整合到 18.2 ``` ## References - [Memory: Phase 18 Failure Loop](~/.claude/projects/-Users-ogt-awoooi/memory/project_phase18_failure_loop.md) - [AWOOOI Agentic Workspace Roadmap](../AWOOOI_AGENTIC_WORKSPACE_ROADMAP.md) - [ADR-009: OpenClaw Agent Teams](./ADR-009-openclaw-agent-teams.md)