awoooi/docs/adr/ADR-028-failure-auto-repair-loop.md

ADR-028: 失敗自動修復閉環架構 (Failure Auto-Repair Loop)

狀態: 📋 Proposed 提案日期: 2026-03-26 決策者: 統帥 提案者: 首席架構師

Context

AWOOOI 行動日誌頁面顯示大量失敗操作，但系統只是「記錄」：

失敗 → 記錄 → 結束 (死路)

這違反了 AIOps 產品的核心價值。作為 AI 產品，應該是：

失敗 → AI 分析 → 自動/人工修復 → 驗證 → 學習

Decision

實作「失敗自動修復閉環」架構，包含以下核心元件：

1. FailureWatcher Worker

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 整合)

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. 資料模型

# 擴展 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
• AWOOOI Agentic Workspace Roadmap
• ADR-009: OpenClaw Agent Teams