ewoooc/docs/adr/ADR-012-agent-action-ladder.md

ADR-012: Agent Action Ladder（AI Agent 事件介入與自動修復三級信任邊界）

• Status: Accepted
• Date: 2026-04-19
• Deciders: 統帥
• Related: ADR-001（三 Agent 分工）, ADR-004（NemoTron Fallback）, ADR-007（AI Dual-Write）, ADR-011（跨專案隔離）

Context

P2/P3 Inline Keyboard 降價決策上線後，統帥希望進一步讓 AI Agent（Hermes / NemoTron / OpenClaw）自動接手處理系統事件，而非僅發送原始錯誤訊息給人工讀。

但「AI 全自動執行」存在嚴重風險：

1. AI 幻覺可能做出錯誤判斷（AI 下架正常商品、誤觸發降價）
2. 不可逆操作（刪資料、重啟生產容器）一旦出錯災難級
3. AI 服務本身可能掛掉（NIM quota / Ollama OOM），若無 fallback 會連帶阻斷通知

Decision

① 三級信任邊界（Action Ladder）

建立 L0 直出 → L1 觀察 → L2 診斷 → L3 執行 四級分流，每級限定能做的動作與失效行為：

Level	Agent	能做什麼	不能做什麼	失效降級
L0 Direct	—	模板直出	—	永遠可用（保底）
L1 Observer	Hermes	翻譯 stack trace、摘要、風險等級標註	寫任何資料 / 呼叫外部 API	→ L0 + 🟡 標記
L2 Investigator	NemoTron	寫 ai_insights、執行 5+3 個安全 tool、發 Telegram	動 prod 資料表 / 容器 / 外部系統	→ Hermes 規則引擎（ADR-004）
L3 Operator	OpenClaw	提方案 + HITL 按鈕 → 人批准後執行任意動作	無 HITL 批准前執行	→ 人工 SOP（寄信通知）

② 安全 Action 白名單（L2 NemoTron 可用）

已有（price_threat 流）：

• trigger_price_alert(sku, data) — 發價格告警
• add_to_recommendation(sku, reason) — 加入推薦
• flag_for_human_review(sku, concern) — 升級 L3 HITL
• route_to_km(sku, domain, summary) — KM 歸檔
• mark_for_relearn(sku, reason) — 標記重新訓練

本 ADR 新增（通用事件流）：

• retry_task(task_name, max_attempts=3, backoff=60) — 安全重試（exponential backoff）
• query_km(query, limit=5) — RAG 檢索歷史同類事件
• silence_alert(event_key, duration_min=60) — 靜音抑制，避免告警風暴

③ EventRouter 分類規則

單一入口 services/event_router.py::dispatch(event)，依 severity × event_type 決定 Tier：

event = {
  "source": "Scheduler.AutoImport",     # 來源模組
  "event_type": "db_connection_error",  # 事件類型（供 L2 matching）
  "severity": "warning",                 # P0/alert, P1/alert, P2/warning, info, success
  "title": "...", "summary": "...",
  "trace": "...",                        # 可選
  "payload": {...},                      # 結構化資料
}

分流邏輯：

• severity=success|info → L0 直出
• severity=warning 且 trace 不存在 → L0（已結構化，不需 AI）
• severity=warning 且 trace 存在 → L1（Hermes 翻譯）
• severity=alert(P1) + 符合 L2 白名單 event_type → L2（NemoTron）
• severity=alert(P0) → L2 + 人工標記（雙軌）
• 複雜策略建議 / 週報 → L3 OpenClaw（P3 已實作）

④ 訊息呈現格式（三層式）

所有經 AI 加工的訊息必須保留原始事實，避免 AI 幻覺掩蓋真相：

⚠️ [EwoooC 警告] 自動匯入異常 (Level 1 · Hermes)
🕐 ... 📦 Scheduler.AutoImport

🤖 AI 摘要（Hermes v3）:
資料庫暫時斷線，疑似容器間 DNS 波動。
本週已發生 3 次，系統通常 2-5 分鐘自癒。

📊 原始事實:
• event_type: db_connection_error
• 影響: 當日業績匯入延遲
• 詳細 trace（末段）: ...

🔧 AI 建議行動:
• 等候自動重試
• 30 分鐘仍失敗 → 檢查 momo-pro_default 網路

L2 流程另加 🤖 AI 已執行動作 區塊（retry_task / silence_alert 等）。

⑤ Audit Trail（雙寫強制）

每次 Agent 介入都要：

1. 寫 ai_insights (insight_type='agent_action', metadata 含 tier, agent, action_taken, confidence, latency_ms)
2. Telegram 訊息末尾加隱藏式 source_insight_id 以便追蹤

⑥ Fallback 降級鏈（SLA 保證）

L2 NemoTron 掛 → L1 Hermes（規則模式）→ L0 模板直出
L1 Hermes 掛  → L0 模板直出 + 🟡 「AI 分析暫不可用」
通知通道掛    → 本地 file queue 暫存（ADR-009 pattern）

關鍵 SLA：無論 AI 狀況，通知鏈絕不中斷 — 這是 P0 底線。

⑦ 成本配額（漏斗型，沿用 ADR-001）

Agent	日呼叫上限	超額動作
Hermes（本機 Ollama）	無限制	—
NemoTron（NIM cloud）	80 次/日（現值）	走 Hermes 規則（ADR-004）
OpenClaw（Gemini）	依週期觸發	不適用（離線批次）

Consequences

正面

• 通知從「原始 stack trace 直丟」升級到「AI 摘要 + 原始事實 + 建議行動」
• 已知 known issue（如 DNS 暫斷）可由 NemoTron 自動重試，無需人工介入
• 三級邊界清楚，審計可追溯（ai_insights 雙寫 + tier 標記）
• AI 掛掉有完整降級鏈，通知鏈不會塌

負面 / 風險

• EventRouter 增加一個中間層，延遲 2-15s（依 Tier）
• AI 成本上升（Hermes 本機還好，NIM quota 要盯）
• 新增的 3 個 L2 tool 未實戰測試，前 2 週需觀察
• 若 Hermes prompt 寫不好，AI 摘要可能誤導 → 每月檢視 agent_action insights 的 feedback_down

實施計畫（階段性）

• Phase 1（本 ADR 同步提交）：EventRouter 骨幹 + agent_actions stub + triaged_alert 模板
• Phase 2：Hermes L1 接入 scheduler.run_auto_import_task + run_momo_task 兩個 exception
• Phase 3：NemoTron 擴充 3 個新 tool (retry/query_km/silence)
• Phase 4：依需求擴 L3 HITL 按鈕
• Phase 5：Prometheus metric 接入（agent_action_total{tier,agent,event_type}、agent_latency_seconds）

References

• services/event_router.py — 分流入口（Phase 1）
• services/agent_actions.py — 安全 action 白名單（Phase 1）
• services/telegram_templates.py::triaged_alert() — L1/L2 訊息格式（Phase 1）
• docs/guides/codex_agent_roles.md — Codex 化角色矩陣與派工規則
• docs/memory/history_logs.md — Agent 事件與 Telegram 相關歷史脈絡