awoooi/docs/operations/HUMAN-IN-THE-LOOP.md

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 不會干預：

# 直接 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 呼叫

curl -X POST https://api.awoooi.internal/api/v1/system/kill-switch \
  -H "Authorization: Bearer {admin_token}" \
  -d '{"enabled": true, "reason": "系統異常，緊急凍結"}'

方法 3：環境變數（重啟後生效）

# 在 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，欄位包含：

{
  "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 + 統帥