feat(ai-ops): Agent Action Ladder 骨幹(ADR-012 Phase 1)+ 週報套模板
All checks were successful
CD Pipeline / deploy (push) Successful in 1m14s
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:
142
docs/adr/ADR-012-agent-action-ladder.md
Normal file
142
docs/adr/ADR-012-agent-action-ladder.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# 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)
|
||||
- `memory/feedback_agent_action_ladder.md` — 操作規範
|
||||
- `memory/reference_telegram_endpoints_map.md` — 21 個發送點盤點
|
||||
Reference in New Issue
Block a user