awoooi/docs/adr/ADR-092-ai-decision-llm-expansion-layer.md

ADR-092: AI Decision Layer — LLM 擴展架構

狀態: Accepted 日期: 2026-04-19 (台北時區) 作者: ogt + Claude Opus 4.7 (1M context, 亞太) 關聯: ADR-090 盲區治理 / MASTER §3 D1-D6 / feedback_ai_autonomous_direction

---

背景

2026-04-19 session 完成 Phase 7 盲區治理後（14 個新 scanner，8 張 0 writer 表全活化），首席架構師 Review 發現嚴重 Gap：

• AI 層淺：14 個新 scanner 中 8 個純 threshold（rule-based），只 Hermes 1 個真用 LLM 做決策
• autonomy_score 實測：63/100（starter 起步級），ai_diversity 子項僅 6/20
• 統帥鐵律：「朝 AI 自主化方向」— infrastructure 不等於 AI

違反 feedback_ai_autonomous_direction.md 核心原則：「禁寫死規則做最終決策」。

---

決策

1. AI Decision 層的 4 個 LLM Service（本 session 完成）

Service	LLM 判斷 required_key	觸發條件	職責
hermes_rule_quality	recommended_actions	每日 04:00 Taipei	分析 noise_rate > 0.5 rule 的假報真因 + 改進建議
capacity_forecaster	priority_actions	每日 05:00 Taipei（predict_linear 命中）	分析 7d 容量預測高風險 host 的修復策略
compliance_scanner	posture_grade	每日 03:00 Taipei（有 warning/violation）	產整體 compliance posture 評級 + top 3 action
coverage_evaluator	worst_dimension	每 1h（red_ratio > 30% 且 scanned > 50）	分析 7 維 red 缺口 + 補覆蓋建議

2. LLM 調用統一 pattern（services/llm_json_parser.py）

原問題：4 個 LLM scanner 各自重複 3-path JSON parse 邏輯（~80 行 × 4 = 320 行） 新 pattern：parse_llm_json_response(text, required_key, logger_context)

# 統一 3-path fallback
Path 1: 剝 markdown fence + 直接 JSON 含 required_key
Path 2: NemoTron wrapper — description/action_title/reasoning 內嵌 JSON
Path 3: 所有失敗 return None + logger.warning

所有 LLM service 都用此 helper，未來擴加 LLM service 直接呼叫。

3. LLM Service 架構約束（鐵律）

必須遵守：

1. 失敗永不 raise：LLM 掛掉/parse 失敗 → return None → 呼叫者 fallback 硬編規則
2. AI 只建議不動作：所有 LLM 輸出都寫 requires_human_decision=True，推 Telegram 等人工
3. openclaw 統一入口：不直接呼叫 Ollama/NVIDIA/Gemini，走 get_openclaw().call(prompt) 多 provider fallback
4. aol 留痕：LLM 結果進 automation_operation_log.output.llm_analysis
5. 繁中 + JSON schema：prompt 明確 required_key，system prompt 要求 LLM 產純 JSON

禁止：

• 硬編 threshold 做最終決策（只做「觸發討論」）
• LLM 結果直接執行破壞性動作（必過人工）
• 內嵌多 provider 判斷（統一走 openclaw）

4. 觸發條件設計原則

節流避免 token 成本爆炸：

• Daily cron：每日一次（compliance/forecaster/hermes）
• 事件觸發：coverage 只在 red_ratio > 30% 且 scanned >= 50 才跑 LLM
• 避免 bootstrap 首次必觸發的浪費

5. autonomy_score 量化追蹤

新增 GET /api/v1/aiops/kpi 回 5 子項 × 20 分總分（0-100）：

• asset_coverage: green 比例 × 20
• rule_quality: 1 - (noisy/total) × 20
• capacity_health: critical 扣 10 / warning 扣 3
• automation_flow: log10(24h_ops) 標準化 × 20
• ai_diversity: ai_generated rules + op_type 多樣性 × 20

Grade: mature(90+) / in_progress(70-90) / starter(50-70) / initial(<50)

---

實作成果

達成指標

• LLM decision service: 1/9 → 4/9
• autonomy_score: 未量化 → 63/100 (starter) 可持續追蹤
• LLM JSON parse 重複碼: 320 行 → 1 份共用 helper（90 行）

Commits

• ba18ad2 Hermes LLM 升級（Hermes 從 threshold 改 LLM）
• d6b854a Gap 3.1 capacity_forecaster LLM
• f6cb938 Gap 3.2 compliance_scanner LLM
• 2f5cab2 Gap 3.3 coverage_evaluator LLM
• fa643eb P1 重構：llm_json_parser helper + coverage 雙條件

相關檔案

• apps/api/src/services/llm_json_parser.py（共用 helper）
• apps/api/src/services/openclaw.py（多 provider）
• apps/api/src/jobs/{hermes_rule_quality,capacity_forecaster,compliance_scanner,coverage_evaluator}_job.py
• apps/api/src/services/aiops_kpi_service.py（autonomy_score 計算）
• apps/api/src/api/v1/aiops_kpi.py（KPI endpoint）

---

後續工作（下 session）

P1 剩餘優化（首席架構師 Review 指出）

1. Prometheus HTTP helper 抽出 — 5 scanner 重複 httpx + 錯誤處理 pattern
2. 14 scanner first_delay 錯開 — 避免並行啟動搶 DB pool（建議 60/90/120/180 階梯）
3. LLM budget guard — aiops_kpi_service 加 llm_call_count_24h 指標超過閾值 Telegram 告警
4. asset_scanner 918 行拆分 — providers/ + writers/ 兩層

可擴展 LLM 方向

• rule_catalog_sync: 新規則 import 時 LLM 驗證 expr 合理性
• asset_change_tracker: 重大 lifecycle 變化時 LLM 評估爆炸半徑
• drift_interpreter (既有): 升級更精細 prompt

---

回滾計畫

若 LLM service 造成成本或穩定性問題，可分層關閉：

1. 改 config AIOPS_LLM_ENABLED=false（需新增，目前未實作）
2. 或 kubectl exec 進 Pod kill 單個 loop task
3. 各 LLM try/except return None → fallback 原設計保護主流程不受影響

---

相關 ADR

• ADR-067 Phase 30 AI 五大應用（OpenClaw + drift_narrator + runbook_generator 等原 LLM service）
• ADR-081 PreDecisionInvestigator + EvidenceSnapshot
• ADR-083 學習閉環重建
• ADR-090 監控盲區治理 + 自動化覆蓋矩陣（11 張 + 8 張新表）

---

附錄 A：2026-04-20 四修（B1-B4）— 全流程斷鏈緊急修復

觸發：統帥截圖 Telegram 顯示「採納失敗」+ 兩天無任何告警。 指令：全景、全流程、全節點、全架構比對，找到所有斷點再修。

Root Cause 鏈

症狀	斷點	根因
Playbook 學習失敗 163次/48h	playbook_service.update_with_validation	evolver 傳 .value（str）→ setattr 不觸發 Pydantic → .value 炸
Telegram 永久靜默 2 天	approval_db.find_by_fingerprint	PENDING = 「已發 TG」謊言；TG 失敗後 approval 永 PENDING → 永遠收斂跳過
採納變更失敗	telegram_gateway._handle_drift_action	呼叫 DriftAdoptService.adopt_drift() 但方法不存在（AttributeError）
AI 無法感知自身故障	main.py 無 background watchdog	MASTER §1.1 盲區：SLO 計算只是 API endpoint

修復（6 檔 / 230 行 / commit 156a52f）

1. B1 playbook_service.py — update_with_validation setattr 前強制 enum 轉型
2. B2a approval_db.py — find_by_fingerprint debounce 窗外 PENDING 必須 Redis tg_sent:{fp} 確認；新 mark_telegram_confirmed()
3. B2b webhooks.py — _push_to_telegram_background 成功後 setex tg_sent:{fp} 24h；3 call site 傳 fingerprint
4. Drift drift_adopt_service.py — 新 adopt_drift(report_id) wrapper
5. B3 jobs/ai_slo_watchdog_job.py — 新建：每 15 分鐘 W-1/W-2/W-3 → TYPE-8M
6. B3 main.py lifespan 註冊 watchdog loop

---

附錄 B：2026-04-20 C1-C4 — Playbook 鏈路結構性斷點修復

觸發：統帥全景盤查後，發現 Playbook 自動修復鏈路有 3 個結構性斷點。

#	斷點	根因	修復	commit
C1	evolver 封存 yaml_rule playbooks	無 YAML_RULE source guard	playbook_evolver.py 兩處加 if source == YAML_RULE: continue	de2d34d
C2	seeder 不復活 DEPRECATED yaml_rule	idempotency SQL 包含 DEPRECATED	AND status != 'deprecated'	de2d34d
C3	AI 新規則不即時建立 Playbook	_append_rule_to_yaml 後無 seeder 呼叫	create_task(seed_playbooks_from_rules())	de2d34d
C4	watchdog 不偵測鏈路斷裂	W-4 缺失	_count_approved_playbooks()；為 0 → TYPE-8M	de2d34d

架構鐵律：PlaybookSource.YAML_RULE playbooks 是自動修復鏈路的「基礎設施」，evolver 的 trust-based 退場邏輯不得觸及此類 playbooks。

---

附錄 C：2026-04-21 — BUTTON_DATA_INVALID 根治 + Gitea Code Review 修復

觸發：Telegram 所有 devops_tool 類別告警卡片發送失敗（HTTP 400 BUTTON_DATA_INVALID）+ Gitea PR Code Review 顯示「AI 分析失敗」。

Root Cause 鏈

症狀	斷點	根因
Telegram 400 BUTTON_DATA_INVALID	generate_callback_nonce	UUID(36) + action(20) + ts(10) + rand(8) + colons = 77B > 64B Telegram 限制
Gitea PR "AI 分析失敗"	_call_openclaw_code_review	OpenClaw 只有 /analyze/incident 和 /analyze/error；/analyze/code-review 從未實作（404）
Push review AttributeError	_call_openclaw_push_review	local_code_review_service.review_push() 回傳 dict，呼叫端對 dict 做屬性訪問（analysis.issues）

修復

1. nonce 壓縮 security_interceptor.py — generate_callback_nonce 用 base64url encode UUID bytes（36→22 chars）；parse_callback_data 對應 decode；host_restart_service nonce = 63B
2. code review 改 local gitea_webhook_service.py — _call_openclaw_code_review 改用 local_code_review_service.review_pr()（Ollama + Gemini fallback）
3. push review dict→model gitea_webhook_service.py — _call_openclaw_push_review 加 dict→CodeReviewResult 轉換

E2E 驗證（2026-04-21 21:57 台北）

• host_restart_service nonce = 63B ✓，所有 7 個 actions ≤ 64B ✓
• UUID round-trip decode = True ✓
• telegram_approval_card_sent message_id=25045（SignOzDown devops_tool）✓ 無 BUTTON_DATA_INVALID

Commits

• acab1cd fix(gitea): code-review 改 local service + push review dict→CodeReviewResult
• bd73548 fix(telegram): BUTTON_DATA_INVALID nonce 超 64B 根因修復
• 8fd31ec fix(telegram): nonce UUID base64url 壓縮（徹底解決）