# 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 + 統帥*