awoooi/docs/adr/ADR-029-cicd-ai-integration.md

ADR-029: CI/CD AI 整合架構 (Phase 13.1)

項目	內容
狀態	✅ 已採用
日期	2026-03-26
決策者	首席架構師 + 統帥
Phase	Phase 13.1

背景

Phase 13.1 需要將 GitHub CI/CD 事件整合到 AWOOOI + OpenClaw 系統，實現：

1. PR/Push 自動代碼審查
2. CI 失敗自動診斷
3. 風險分級自動修復

決策

採用 事件驅動 + 風險分級 架構：

GitHub Events
    │
    ├─ pull_request ──→ OpenClaw Code Review
    ├─ push ──────────→ OpenClaw Push Review
    └─ workflow_run ──→ CI Failure Diagnosis
                            │
                            ▼
                    ┌─────────────────┐
                    │ CIAutoRepair    │
                    │ Service         │
                    └─────────────────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
    ┌───────────┐   ┌───────────┐   ┌───────────┐
    │ LOW       │   │ MEDIUM    │   │ HIGH/CRIT │
    │ 自動執行   │   │ TG 確認   │   │ Approval  │
    └───────────┘   └───────────┘   └───────────┘

架構元件

1. GitHub Webhook Handler (github_webhook.py)

# 支援事件類型
- pull_request: opened, synchronize, reopened
- push: refs/heads/main, refs/heads/master
- workflow_run: completed + failure/timed_out

# 安全機制
- HMAC-SHA256 簽名驗證 (X-Hub-Signature-256)
- 倉庫白名單 (GITHUB_ALLOWED_REPOS)
- Fail-closed 策略

2. CI Auto-Repair Service (ci_auto_repair.py)

# 風險等級決策
class ExecutionDecision(Enum):
    AUTO_EXECUTE = "auto_execute"        # LOW 風險
    TELEGRAM_CONFIRM = "telegram_confirm" # MEDIUM 風險
    APPROVAL_REQUIRED = "approval_required" # HIGH 風險
    BLOCKED = "blocked"                   # CRITICAL

# 整合 Phase 13.3 智能路由
- Intent Classifier: 判斷修復意圖
- Complexity Scorer: 評估複雜度

3. SignOz Log Query (signoz_client.py)

# 新增方法
- get_logs(): 查詢日誌 (服務/級別/搜尋)
- get_error_logs_summary(): 錯誤摘要統計

# MCP Tools
- query_logs: 通用日誌查詢
- error_logs_summary: 錯誤摘要

資料流

1. GitHub Webhook → AWOOOI API
   ├─ HMAC 驗證
   └─ 倉庫白名單檢查

2. 背景任務處理
   ├─ 收集失敗資訊
   ├─ 查詢 SignOz 日誌
   └─ 呼叫 OpenClaw 診斷

3. 風險評估
   ├─ Intent Classification
   ├─ Complexity Scoring
   └─ 生成修復建議

4. 執行決策
   ├─ LOW → 自動執行
   ├─ MEDIUM → Telegram 快速確認
   ├─ HIGH → 建立 Approval
   └─ CRITICAL → 禁止自動修復

5. 結果通知
   ├─ Redis 儲存 (7 天 TTL)
   └─ Telegram 通知

錯誤類型映射

錯誤類型	修復動作	風險等級
build	clear_cache, fix_dependency	LOW-MEDIUM
test	retry_workflow, fix_config	LOW-MEDIUM
lint	retry_workflow	LOW
deploy	rollback_commit, fix_config	HIGH
timeout	restart_runner, scale_resource	LOW-MEDIUM
runner	restart_runner	LOW

配置

# config.py
GITHUB_WEBHOOK_SECRET: str  # Webhook 簽名密鑰
GITHUB_ALLOWED_REPOS: str   # 白名單倉庫

# 環境變數 (K8s Secret)
GITHUB_WEBHOOK_SECRET=<secret>
GITHUB_ALLOWED_REPOS=owner/repo1,owner/repo2

後果

正面

• CI 失敗自動診斷，減少人工介入
• 風險分級保護，防止誤操作
• 整合智能路由，決策更精準

負面

• OpenClaw 依賴 (需要 AI 服務可用)
• 額外延遲 (診斷需要 AI 處理時間)

相關文件

• ADR-023: Smart Routing Architecture
• ADR-024: API Layer Architecture
• Skill 07: Tool Integration Expert
• Skill 08: Model Router Expert
• feedback_cicd_aiops_patterns.md