awoooi/docs/adr/ADR-100-ai-autonomous-slo.md

ADR-100: AI 自主化飛輪 SLO

狀態：Active（2026-04-27）

背景

plan_complete_v3.0 P3.4 要求為 AI 自主化飛輪定義可量測的 SLO（Service Level Objectives）， 以便持續追蹤飛輪健康度，並在 SLO 違反時自動降級行為，防止錯誤決策擴散。

4 個 SLO

---

SLO 1 — 自主化率 ≥ 80%

定義：AI 自動執行的操作佔全部處理操作（含人工審核）的比例

SLI 計算式:

sum(rate(automation_operation_log_total{outcome="auto_executed"}[5m]))
/
sum(rate(automation_operation_log_total{}[5m]))

Recording rule: sli:autonomy_rate:5m

目標值（SLO）: ≥ 0.80

Error budget（28d）: 20%（即 28d × 20% = 5.6d 容許人工審核比例偏高）

Burn rate alerts:

視窗	消耗閾值	動作
Fast (1h)	budget × 14.4 = 2.88	page（critical）
Medium (6h)	budget × 6 = 1.2	ticket（warning）
Slow (3d)	budget × 1 → 累積 10%	review（info）

SLO 違反降級行為:

• < 0.70（硬紅線）：降低 fusion auto-execute 閾值要求，發送 Telegram P0 告警
• < 0.75：governance_agent 加強監控頻率（30min → 15min）

---

SLO 2 — 決策準確率 ≥ 90%

定義：自動執行後，verifier 驗證通過的比例

SLI 計算式:

sum(rate(post_execution_verification_total{outcome="success"}[5m]))
/
sum(rate(automation_operation_log_total{outcome="auto_executed"}[5m]))

Recording rule: sli:decision_accuracy:5m

目標值（SLO）: ≥ 0.90

Error budget（28d）: 10%（比自主化率更嚴格）

Burn rate alerts:

視窗	消耗閾值	動作
Fast (1h)	budget × 14.4 = 1.44	page（critical）
Medium (6h)	budget × 6 = 0.6	ticket（warning）
Slow (3d)	budget × 1 → 累積 10%	review（info）

SLO 違反降級行為:

• < 0.85（硬紅線）：凍結 auto_execute，全部降級為 human_required， 直到滑動窗口回到 ≥ 0.90 才解凍
• < 0.88：增加 verifier 嚴格度（多一輪二次驗證）

---

SLO 3 — 信心校準準確度 ≥ 80%

定義：AI 信心值 ≥ 0.8 的決策中，實際驗證通過的比例（高信心不能亂說）

SLI 計算式:

sum(rate(approval_records_high_confidence_success_total[1h]))
/
sum(rate(approval_records_high_confidence_total[1h]))

Recording rule: sli:confidence_calibration:1h

目標值（SLO）: ≥ 0.80

Error budget（28d）: 20%

Burn rate alerts:

視窗	消耗閾值	動作
Fast (1h)	budget × 14.4 = 2.88	page（critical）
Medium (6h)	budget × 6 = 1.2	ticket（warning）
Slow (3d)	budget × 1 → 累積 10%	review（info）

SLO 違反降級行為:

• < 0.70（硬紅線）：觸發 P3.3 fine-tune 重訓流程，Telegram 通知人工介入
• < 0.75：將高信心閾值從 0.8 上調至 0.85（更嚴格的信心要求）

---

SLO 4 — KM 增長率 ≥ +20 筆/day

定義：每 24h 新增的知識條目數，衡量飛輪學習輸出是否健康

SLI 計算式:

increase(knowledge_entries_total[24h])

Recording rule: sli:km_growth_rate:24h

目標值（SLO）: ≥ 20 筆/day

Error budget：不適用標準 burn rate（絕對值 SLO），改用閾值告警

告警閾值:

值	動作
< 20/day	warning：調查 KM 寫入路徑
< 5/day	critical：疑似 KM 鏈斷裂，Telegram P0 告警
= 0 (持續 2h)	emergency：governance_agent 立即執行診斷

SLO 違反降級行為:

• < 5/day（硬紅線）：告警，疑似 KM 鏈又斷，自動觸發 check_knowledge_degradation
• = 0 持續 2h：立即執行 governance_agent.run_self_check()

---

SLO 違反時的降級行為矩陣

SLO	輕度違反	硬紅線違反	降級行為
SLO 1 自主化率	< 0.75	< 0.70	降低 fusion 閾值 + Telegram
SLO 2 決策準確率	< 0.88	< 0.85	凍結 auto_execute
SLO 3 信心校準	< 0.75	< 0.70	觸發 fine-tune + 提高信心閾值
SLO 4 KM 增長率	< 20/day	< 5/day	告警 + 觸發 KM 診斷

與 governance_agent 整合

GovernanceAgent.check_slo_compliance() 實作（apps/api/src/services/governance_agent.py）：

• 每 1h 執行（與既有 4 項自檢合併為第 5 項）
• 從 Prometheus Recording rules 讀取 SLI 值（PROMETHEUS_URL from settings）
• 違反硬紅線時呼叫 self._alert() 寫 PG + 推 Telegram
• 異常隔離：任一 SLO 查詢失敗不阻斷其他項目

實作檔案

檔案	用途
ops/monitoring/slo-rules.yml	Prometheus recording rules + 12 burn rate alerts
ops/monitoring/tests/test_slo_rules.yaml	promtool 單元測試
ops/monitoring/grafana/dashboards/ai-slo-dashboard.json	Grafana SLO Dashboard
apps/api/src/services/governance_agent.py	check_slo_compliance() 整合

決策理由

1. Recording rules 優先：SLI 計算複雜，先存 recording rule 避免 Grafana/alert 重複計算
2. 3 窗口 burn rate：參考 Google SRE 書 6.5 節，fast/medium/slow 三層防禦
3. SLO 4 用絕對值：KM 增長率是累積計數，burn rate 模型不適用
4. governance_agent 整合：SLO 違反直接觸發降級行為，閉合飛輪的自我修復迴圈