286 lines
9.7 KiB
Markdown
286 lines
9.7 KiB
Markdown
# AWOOOI Human-in-the-Loop 規格書
|
||
|
||
> **文件類型**: 人工介入標準操作程序（Human-in-the-Loop Specification）
|
||
> **版本**: v1.0
|
||
> **建立日期**: 2026-04-14（台北時間）
|
||
> **建立者**: Claude Sonnet 4.6（首席架構師）+ 統帥確認
|
||
> **核心問題**: AI 判斷錯了、超時沒決定、或系統失控時，人類如何接管？
|
||
|
||
---
|
||
|
||
## 0. 設計哲學
|
||
|
||
> **AI 是副駕駛，統帥是機長。**
|
||
|
||
AWOOOI AIOps 的設計原則：
|
||
|
||
- AI **永遠可以被人類覆蓋**，任何時候
|
||
- **高風險操作**（P0/P1）必須人工確認，不例外
|
||
- AI 超時或信心不足時，系統**主動交還控制權**，不沉默失敗
|
||
- **Kill Switch** 永遠可用，一鍵讓 AI 停止所有自動操作
|
||
|
||
---
|
||
|
||
## 1. 人工介入觸發條件（When）
|
||
|
||
### 觸發矩陣
|
||
|
||
| 情況 | 觸發條件 | 系統行為 | 介入方式 |
|
||
|------|---------|---------|---------|
|
||
| **HITL-1** | 風險等級 P0（CRITICAL） | 強制人工審核 | Telegram 審核卡 |
|
||
| **HITL-2** | 風險等級 P1（HIGH） | 強制人工審核 | Telegram 審核卡 |
|
||
| **HITL-3** | AI 信心度 < 0.65 | 無法自動執行 | TYPE-4 通知，等人決定 |
|
||
| **HITL-4** | LLM 超時（> 25s） | 降級 Expert System | Expert System 決策，低信心 → 人工 |
|
||
| **HITL-5** | 破壞性操作檢測 | 強制升級為人工 | TYPE-3 審核卡，含警告標示 |
|
||
| **HITL-6** | 審核逾時（> 30 分鐘）| 自動升級通知 | P0 告警發至統帥 + SRE 群組 |
|
||
| **HITL-7** | 自動修復連續失敗 2 次 | 停止重試 | TYPE-4 通知，等人接手 |
|
||
| **HITL-8** | SLO-1 < 50%（連續 2h） | 飛輪異常 | TYPE-8M 告警，建議暫停自動修復 |
|
||
| **HITL-9** | Kill Switch 啟動 | 立即凍結所有自動操作 | 無自動行為，等人工重啟 |
|
||
|
||
### 破壞性操作關鍵字（HITL-5 觸發清單）
|
||
|
||
以下任一 kubectl 命令出現 → 強制人工審核，不論信心度：
|
||
|
||
```
|
||
scale ... --replicas=0 ← 縮容至零（服務停止）
|
||
delete pod ← 刪除 Pod（短暫中斷）
|
||
delete deployment ← 刪除部署（資料風險）
|
||
delete pvc ← 刪除持久磁碟（資料永久消失）
|
||
delete namespace ← 刪除命名空間（災難性）
|
||
rm -rf ← 主機層刪除（絕對禁止）
|
||
DROP TABLE ← 資料庫破壞性操作（絕對禁止）
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 誰來介入（Who）
|
||
|
||
### 介入層級
|
||
|
||
```
|
||
Level 1 — 統帥（最終決策者）
|
||
角色: ogt（系統擁有者）
|
||
Telegram: AwoooI SRE戰情室群組（SRE_GROUP_CHAT_ID）
|
||
負責: 所有 P0/P1 審核、Kill Switch、重大策略決定
|
||
|
||
Level 2 — SRE On-call
|
||
角色: SRE 戰情室成員
|
||
Telegram: SRE 群組（SRE_GROUP_CHAT_ID）
|
||
負責: P2 例行審核、監控告警響應
|
||
|
||
Level 3 — AI 系統（降級自動處理）
|
||
角色: OpenClaw + Expert System
|
||
負責: P3（低風險）自動執行，無需人工
|
||
```
|
||
|
||
### 當前實際狀態（2026-04-14）
|
||
|
||
```
|
||
統帥 = Level 1 + Level 2（一人承擔所有層級）
|
||
AI = Level 3（P3 自動，P0/1/2 部分自動）
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 怎麼介入（How）
|
||
|
||
### 3.1 Telegram 審核卡操作
|
||
|
||
當系統發送 TYPE-3 審核卡到 AwoooI SRE戰情室群組：
|
||
|
||
```
|
||
╔══════════════════════════════════════╗
|
||
║ 🔧 需要您的決策 ║
|
||
║ ║
|
||
║ 告警: KubePodCrashLooping ║
|
||
║ 目標: awoooi-api @ awoooi-prod ║
|
||
║ 風險: 🟡 MEDIUM ║
|
||
║ AI信心: 82% ║
|
||
║ 建議動作: kubectl rollout restart ║
|
||
║ deployment/awoooi-api ║
|
||
║ 影響估計: ~30s 服務中斷 ║
|
||
║ ║
|
||
║ [ ✅ 批准執行 ] [ ❌ 拒絕 ] ║
|
||
║ [ 🔍 查看詳情 ] [ 📋 Postmortem ] ║
|
||
╚══════════════════════════════════════╝
|
||
```
|
||
|
||
**批准後**：系統立即執行，並發送執行結果通知
|
||
**拒絕後**：Incident 標記為 `human_rejected`，不再自動重試
|
||
**不操作**：30 分鐘後觸發 HITL-6（逾時升級）
|
||
|
||
### 3.2 Fail-safe 逾時行為（HITL-6 細節）
|
||
|
||
```
|
||
審核卡發出後：
|
||
|
||
0 分鐘: 審核卡發送到 SRE 戰情室群組
|
||
15 分鐘: 提醒訊息（同一個群組）:
|
||
"⚠️ 此審核已等待 15 分鐘，請盡快處理"
|
||
30 分鐘: 升級告警發送到 SRE 戰情室群組:
|
||
"🔴 審核逾時！Incident #XXX 已等待 30 分鐘未處理
|
||
若不處理，系統將在 5 分鐘後自動標記為 ESCALATED"
|
||
35 分鐘: Incident 狀態 → ESCALATED
|
||
記錄到 alert_operation_log（事後可查）
|
||
不執行任何破壞性操作（Fail-safe：寧可不動也不亂動）
|
||
```
|
||
|
||
**重要**：AWOOOI 的 Fail-safe 預設行為是**不執行**，而非自動執行。
|
||
若 AI 不確定或人類沒有回應，系統**保持現狀**，不主動改變任何東西。
|
||
|
||
### 3.3 人工直接操作（繞過 AI）
|
||
|
||
統帥可以隨時直接操作，AI 不會干預：
|
||
|
||
```bash
|
||
# 直接 kubectl 操作（AI 不知道，但 AWOOOI 不阻擋）
|
||
kubectl rollout restart deployment/awoooi-api -n awoooi-prod
|
||
|
||
# 透過 AWOOOI API 手動觸發（有記錄）
|
||
POST /api/v1/approvals/{id}/manual-execute
|
||
Authorization: Bearer {token}
|
||
Body: {"reason": "AI 判斷錯誤，手動修復"}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Kill Switch（緊急停止）
|
||
|
||
### 4.1 Kill Switch 是什麼
|
||
|
||
Kill Switch = 立即凍結 AWOOOI 所有自動操作的緊急機制。
|
||
|
||
啟動後：
|
||
- ✅ 繼續接收告警（不停止監控）
|
||
- ✅ 繼續發送通知（讓統帥知道發生什麼）
|
||
- ❌ 停止所有自動執行（kubectl / SSH）
|
||
- ❌ 停止所有自動批准（AutoApprovePolicy 凍結）
|
||
- ❌ 停止新 DecisionToken 進入執行階段
|
||
|
||
### 4.2 如何啟動 Kill Switch
|
||
|
||
**方法 1：Telegram 指令**（推薦，最快）
|
||
```
|
||
在 SRE 戰情室群組或授權對話輸入：
|
||
/kill_switch enable
|
||
|
||
系統回應：
|
||
🛑 KILL SWITCH 已啟動
|
||
- 所有自動執行已凍結
|
||
- 現有 pending 審核不受影響
|
||
- 統帥可手動批准個別操作
|
||
- 輸入 /kill_switch disable 解除
|
||
```
|
||
|
||
**方法 2：API 呼叫**
|
||
```bash
|
||
curl -X POST https://api.awoooi.internal/api/v1/system/kill-switch \
|
||
-H "Authorization: Bearer {admin_token}" \
|
||
-d '{"enabled": true, "reason": "系統異常，緊急凍結"}'
|
||
```
|
||
|
||
**方法 3：環境變數（重啟後生效）**
|
||
```bash
|
||
# 在 K8s ConfigMap 設定
|
||
AIOPS_AUTO_EXECUTE_ENABLED=false
|
||
```
|
||
|
||
### 4.3 Kill Switch 啟動場景
|
||
|
||
| 場景 | 建議行動 |
|
||
|------|---------|
|
||
| AI 連續執行錯誤動作 | 立即啟動，調查根因 |
|
||
| 生產環境重大變更前 | 啟動 Kill Switch，變更完成後解除 |
|
||
| SLO-1 連續 4h < 30% | 評估啟動（飛輪嚴重異常） |
|
||
| 不明告警風暴（10 分鐘 > 50 個） | 啟動 + 調查聚合引擎是否失效 |
|
||
| 週末/假日不在線 | 可啟動，讓系統進入純監控模式 |
|
||
|
||
---
|
||
|
||
## 5. 人工接管標準流程（SOP）
|
||
|
||
### 情境 A：收到 TYPE-3 審核卡
|
||
|
||
```
|
||
Step 1: 閱讀審核卡（告警類型、目標、AI 建議動作、風險評估）
|
||
Step 2: 若不確定，點擊「查看詳情」查看完整 AI 分析
|
||
Step 3: 判斷：
|
||
- AI 建議合理 + 風險可接受 → 批准
|
||
- AI 建議有疑慮 → 拒絕，手動研究後再決定
|
||
- 看不懂 → 拒絕，kubectl describe 自己看
|
||
Step 4: 不論批准或拒絕，系統都會記錄到 alert_operation_log
|
||
```
|
||
|
||
### 情境 B：自動修復失敗，AI 交還控制
|
||
|
||
```
|
||
Step 1: 收到 TYPE-4 通知（AI 無法判斷或已重試 2 次）
|
||
Step 2: 查看 Incident 詳情（/api/v1/incidents/{id}）
|
||
Step 3: 手動分析根因（kubectl logs / describe）
|
||
Step 4: 手動執行修復命令
|
||
Step 5: 確認服務恢復後，在 AWOOOI UI 標記 Incident 為 RESOLVED
|
||
```
|
||
|
||
### 情境 C：發現 AI 判斷持續錯誤
|
||
|
||
```
|
||
Step 1: 啟動 Kill Switch
|
||
Step 2: 查看最近 N 個錯誤 DecisionToken 的 reasoning
|
||
Step 3: 識別根因（Prompt 問題？LLM 模型切換？規則配置錯誤？）
|
||
Step 4: 修復根因（可能需要更新 alert_rules.yaml 或 Playbook）
|
||
Step 5: 在 staging 環境驗證（用 DRY_RUN=true）
|
||
Step 6: 解除 Kill Switch，觀察 1 小時
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 人工介入記錄規範
|
||
|
||
所有人工介入必須記錄到 `alert_operation_log`，欄位包含：
|
||
|
||
```python
|
||
{
|
||
"event_type": "human_intervention",
|
||
"action": "approved" | "rejected" | "manual_execute" | "kill_switch",
|
||
"actor": "統帥",
|
||
"actor_role": "owner",
|
||
"reason": "string（人工填寫）",
|
||
"approval_id": "uuid（若有）",
|
||
"incident_id": "string（若有）",
|
||
"timestamp": "2026-04-14T08:00:00+08:00", # 台北時間
|
||
}
|
||
```
|
||
|
||
這些記錄用於：
|
||
- Postmortem 自動組裝時間軸
|
||
- SLO 計算（區分 AI 自動 vs 人工介入）
|
||
- 飛輪學習（識別 AI 哪裡判斷錯，更新 Playbook）
|
||
|
||
---
|
||
|
||
## 7. 與系統各層的接點
|
||
|
||
| 系統層 | Human-in-the-Loop 接點 |
|
||
|-------|----------------------|
|
||
| `webhooks.py` | Kill Switch 檢查（進入決策前） |
|
||
| `auto_approve.py` | P0/P1 強制人工路由 |
|
||
| `decision_manager.py` | LLM 超時 → Expert System → 信心不足 → TYPE-4 |
|
||
| `approval_execution.py` | 重試失敗 → TYPE-4 交還人工 |
|
||
| `telegram_gateway.py` | 審核卡 + 逾時提醒 + Kill Switch 指令接收 |
|
||
| `incident_service.py` | 人工標記 RESOLVED / ESCALATED |
|
||
|
||
---
|
||
|
||
## 8. 未來擴充計畫
|
||
|
||
| 功能 | 說明 | 時程 |
|
||
|------|------|------|
|
||
| 審核逾時自動降級（保守） | 超過 60 分鐘 → 自動執行最低風險操作 | Phase 3 後評估 |
|
||
| 多人簽核（Multi-Sig） | P0 需要 2 人確認 | 待統帥指示 |
|
||
| 行動 App 通知 | iOS 通知支援 | 低優先 |
|
||
| SRE On-call 輪值 | 第二個人類接管層 | 未來需求 |
|
||
|
||
---
|
||
|
||
*最後更新: 2026-04-14 台北時間 | 建立者: Claude Sonnet 4.6 + 統帥*
|