feat(ai-ops): Agent Action Ladder 骨幹(ADR-012 Phase 1)+ 週報套模板
All checks were successful
CD Pipeline / deploy (push) Successful in 1m14s

ADR-012 核心設計:
- 4 級信任邊界:L0 直出 / L1 Hermes 觀察 / L2 NemoTron 診斷執行 / L3 OpenClaw HITL
- 通知鏈絕不中斷:每級失敗立即降級,保底 L0 模板 + 🟡 標記
- Audit Trail:每次 dispatch 自動寫 ai_insights (insight_type=agent_action)
- 安全白名單:L2 可呼叫 6 個安全 action(retry/query_km/silence + 3 個既有 NemoTron tool)

新增檔案:
- services/event_router.py — 事件分流入口,按 severity × event_type 分 Tier
- services/agent_actions.py — 安全 action 白名單(Phase 1 stub + 完整介面)
- docs/adr/ADR-012-agent-action-ladder.md — 完整設計 + 分階段計畫

Phase 1 狀態:
- L0 直出完整可用 
- L1 Hermes / L2 NemoTron 為 stub(Phase 2/3 填實作)
- Fallback 降級鏈已完整 
- 靜音檢查(is_silenced)+ Audit Trail 已就緒 

處理既有 TODO:
- services/openclaw_strategist_service.py::_notify_telegram_group()
  改用 telegram_templates.report() 統一週報格式

全景盤點(新 memory):
- reference_telegram_endpoints_map.md — 21 個 Telegram 發送點
- feedback_agent_action_ladder.md — 操作規範
  (+ 既有 ADR-011 跨專案隔離規範一併生效)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
ogt
2026-04-19 12:46:51 +08:00
parent 528a6c0468
commit 0b4f80ee8a
4 changed files with 626 additions and 19 deletions

View File

@@ -0,0 +1,142 @@
# ADR-012: Agent Action LadderAI Agent 事件介入與自動修復三級信任邊界)
- **Status**: Accepted
- **Date**: 2026-04-19
- **Deciders**: 統帥
- **Related**: ADR-001三 Agent 分工), ADR-004NemoTron Fallback, ADR-007AI Dual-Write, ADR-011跨專案隔離
## Context
P2/P3 Inline Keyboard 降價決策上線後,統帥希望進一步讓 AI AgentHermes / 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` 存在 → L1Hermes 翻譯)
- `severity=alert(P1)` + 符合 L2 白名單 event_type → L2NemoTron
- `severity=alert(P0)` → L2 + 人工標記(雙軌)
- 複雜策略建議 / 週報 → L3 OpenClawP3 已實作)
### ④ 訊息呈現格式(三層式)
所有經 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| 無限制 | — |
| NemoTronNIM cloud | 80 次/日(現值) | 走 Hermes 規則ADR-004 |
| OpenClawGemini | 依週期觸發 | 不適用(離線批次) |
## 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
- `memory/feedback_agent_action_ladder.md` — 操作規範
- `memory/reference_telegram_endpoints_map.md` — 21 個發送點盤點