# 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（跨專案隔離）, ADR-018（四 AI Agent 自動化控制面）
- **Note**: [ADR-020](ADR-020-code-review-full-autoheal.md) 局部覆寫本 ADR 對「post-deploy code review pipeline」場景的 L3 HITL 規定 — 該場景改採全自動修復 + Git/CI/CD 回滾安全網。本 ADR 對 schema migration / 流量切換 / customer-facing 廣播 / AIOps prod SSH 等其他 L3 場景仍生效。
- **2026-07-10 Sunset**: [ADR-038](ADR-038-security-governance-automation-control-plane.md) 覆寫 generic owner/manual/HITL terminal gate。low/medium/high 改採 risk-based controlled apply；critical break-glass 類型仍保留外部授權。

## 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 / ElephantAlpha | OpenClaw 提策略方案；ElephantAlpha 做 orchestration + HITL + AutoHeal bridge | 無 HITL 批准前執行高風險動作；不可繞過 ADR-011/013 | → 人工 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)` — 靜音抑制，避免告警風暴

**2026-04-29 實作狀態：**
- `flag_for_human_review`、`route_to_km`、`mark_for_relearn` 已從 stub 改為 OpenClaw memory 寫入，並保留 audit trail。
- EventRouter 僅會執行 `SAFE_ACTIONS`，且需 action plan 明確 `auto_execute` 或 `dispatch_to=safe_action`。
- Telegram 發送失敗會寫入 file queue，後續成功送出時 replay。

### ③ 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 接入（`momo_ai_event_router_dispatch_total`、`momo_ai_event_router_latency_ms_*`）

## 2026-04-29 Implementation Update

- Phase 1~3 核心已落地：EventRouter 分流、L2 safe action、NemoTron fallback、OpenClaw memory 寫入與通知 replay 已具測試覆蓋。
- L3 已擴展為 OpenClaw + ElephantAlpha：OpenClaw 負責策略/記憶，ElephantAlpha 負責 orchestration/HITL/AutoHeal bridge。
- 2026-04-29 已補 `/metrics` 匯出：EventRouter dispatch、L2 safe action、Telegram replay、AutoHeal action 與 latency/duration。
- 2026-04-29 已補 `/ai_automation_smoke` 與 `/api/ai-automation/smoke`：EventRouter、AutoHeal、NemoTron fallback、OpenClaw embedding queue、ElephantAlpha HITL 線上快檢。
- 2026-04-29 已補 smoke 結果 JSONL 保存與 dashboard 趨勢視覺化。
- 2026-04-29 已補 smoke history JSONL 匯出、清理與每日摘要。
- 2026-04-29 已補 smoke 每日摘要 Telegram 手動推播與 momo-scheduler 09:10 排程入口。
- 2026-04-29 已補 Grafana provisioning dashboard：`MOMO AI Automation Overview` 覆蓋 EventRouter、L2 safe action、Telegram replay 與 AutoHeal Prometheus 指標。
- 2026-04-30 已補 active monitoring scrape：Prometheus `momo-app` job 讀取 `momo-pro-system:80/metrics`，供 Grafana AI dashboard 使用。
- 尚未完成：Superset 視覺化面板、AI event 發生後的 `momo_ai_*` 時間序列觀察與 Smoke 摘要推播成效觀察。

## 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/guides/ai_automation_session_sop.md` — AI 自動化 session 與收尾 SOP
- `docs/memory/history_logs.md` — Agent 事件與 Telegram 相關歷史脈絡
- `docs/memory/ai_automation_closure_20260429.md` — 2026-04-29 AI 自動化閉環修復實況