同步四 Agent AI 自動化治理紀錄

2026-04-29 23:36:23 +08:00
parent 162a76b8f9
commit d58e4d0d11
15 changed files with 294 additions and 26 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # EwoooC (MOMO Pro System) — Codex 專案工作規則

-> 版本: V13.0
+> 版本: V13.1
 > 目標: 把專案知識整理成 Codex 可低成本讀取、可持續維護、可安全落地的單一工作入口。

 ## 1. 入口原則
@@ -39,6 +39,7 @@

 - 有新架構決策才新增 ADR。
 - 有長期有效且非架構層的專案知識才更新 memory。
+- 有 AI 自動化閉環、模型分工、告警/自癒行為變更才更新 `docs/AI_INTELLIGENCE_MODULE_SOT.md`。
 - 有全域紅線變更才更新 `CONSTITUTION.md`。
 - 有入口或索引變更才更新 `AGENTS.md` 或對應 README。

@@ -67,6 +68,7 @@
 ### Skills

 - 本專案不再維護 `.claude/skills` 或本地技能腳本作為正式規範。
+- 若使用者要求「更新 Skills」，預設轉譯為更新 `docs/guides/*.md` 的可重複流程與 `AGENTS.md` 索引，不新增私有 skill 真相來源。
 - 若未來需要可重複流程，優先寫成：
  1. `docs/guides/*.md` 的操作手冊
  2. 可執行腳本
@@ -127,10 +129,13 @@

 - 部署 SOP: `docs/guides/deployment_sop.md`
 - DevOps 手冊: `docs/guides/devops_handbook.md`
+- AI 自動化 Session SOP: `docs/guides/ai_automation_session_sop.md`
+- AI 競價情報 SOT: `docs/AI_INTELLIGENCE_MODULE_SOT.md`
 - Agent 角色矩陣: `docs/guides/codex_agent_roles.md`
 - ADR 索引: `docs/adr/README.md`
 - Memory 索引: `docs/memory/README.md`
 - 歷史紀錄: `docs/memory/history_logs.md`
+- AI 自動化閉環記憶: `docs/memory/ai_automation_closure_20260429.md`
 - 憑證手冊: `docs/memory/credentials_passbook.md`

 ## 9. 常用指令
@@ -144,5 +149,5 @@ ssh wooo@192.168.0.110 "ssh ollama@192.168.0.188 \"cd /home/ollama/momo-pro && d

 ## 10. 正式規範結論

- Codex 在本專案的正式工作規則來源只有四個：`AGENTS.md`、`CONSTITUTION.md`、`docs/adr/README.md`、`docs/memory/README.md`。
+- Codex 在本專案的正式治理入口是：`AGENTS.md`、`CONSTITUTION.md`、`docs/adr/README.md`、`docs/memory/README.md`；AI 架構事實以 `docs/AI_INTELLIGENCE_MODULE_SOT.md` 為 SOT。
 - 其他文件預設都視為按需查閱資料，不是 session 開場必讀。
--- a/CONSTITUTION.md
+++ b/CONSTITUTION.md
@@ -2,8 +2,8 @@

 > 本文件定義專案開發的核心準則與不可違反的規範
 > **建立日期**: 2026-01-12
-> **當前版本**: V10.2 (治理與安全重疊整合版)
-> **最後更新**: 2026-04-18
+> **當前版本**: V10.4 (四 AI Agent 自動化治理版)
+> **最後更新**: 2026-04-29

 ---

@@ -305,21 +305,23 @@

 ---

-## 第十三章：AI 三 Agent 自主學習架構規範（2026-04-18 加入）
+## 第十三章：AI 四 Agent 自主學習與自動化架構規範（2026-04-29 修訂）

-### 第 40 條：三 Agent 分工架構（絕對禁止違反）
+### 第 40 條：四 Agent 分工架構（絕對禁止違反）
 - **Hermes（採集層）**: `192.168.0.111` Ollama，負責 embedding、去重、品質分數計算。成本 = $0
 - **NemoTron（處理層）**: NVIDIA NIM Llama 3.1 8B，負責 tool calling 邏輯路由與 DB 寫入。限額 80 次/天
 - **OpenClaw / Gemini（應用層）**: 負責最終 PPT 生成、洞察報告對外輸出。成本最高，最後動用
+- **ElephantAlpha（編排層）**: 負責跨 Agent orchestration、HITL、AutoHeal bridge 與受控執行計畫，不可繞過安全入口
 - ❌ **禁止**：讓 OpenClaw 做 Hermes 層的苦力工作（高算力浪費）
 - ❌ **禁止**：讓 Hermes 直接生成對外報告（品質不足）
+- ❌ **禁止**：讓 ElephantAlpha 直接繞過 EventRouter / AutoHeal / ADR-011 執行高風險副作用

 ### 第 41 條：AI 學習數據雙寫（絕對禁止違反）
- ✅ **正確**：所有 AI 產出（PPT 洞察、競品分析、對話記錄）必須**雙寫** PostgreSQL `ai_insights` + pgvector embedding
+- ✅ **正確**：所有 AI 產出（PPT 洞察、競品分析、對話記錄、Agent action、自癒紀錄）必須**雙寫** PostgreSQL `ai_insights` + pgvector embedding
 - ❌ **禁止**：只寫 DB 不寫 KM（RAG 無法語意搜尋）
 - ❌ **禁止**：只寫 KM 不寫 DB（精確 period/sku 查詢無法命中）
 - **理由**：DB 是精準命中，KM 是語意搜尋，兩者互補缺一不可（ADR-007）
- **入口**：NemoTron `store_insight` tool call → 同步寫 DB → 異步排隊給 Hermes 做 embedding
+- **入口**：`store_insight()` 或 raw insert + `enqueue_insight_embedding()` → 同步寫 DB → 異步排隊給 Hermes 做 embedding

 ### 第 42 條：KM 向量庫技術選型（絕對禁止違反）
 - ✅ **唯一選擇**：pgvector（與現有 PostgreSQL `192.168.0.188` 同一 DB）
@@ -332,7 +334,7 @@
 - **維度**：1024 dim（`vector(1024)` 欄位）（ADR-003）

 ### 第 44 條：NemoTron 配額 Fallback 機制（強制要求）
- ✅ **正確**：當 NIM 回傳 HTTP 429 時，立刻 fallback 至 `_hermes_rule_fallback()` rule-based 派發
+- ✅ **正確**：當 NIM 缺 API key、HTTP 429、timeout、network/HTTP error 或 0 tool call 時，立刻 fallback 至 `_hermes_rule_fallback()` rule-based 派發
 - ❌ **禁止**：配額耗盡時讓告警管線中斷
 - **標記**：降級模式告警須帶 `🟡` 前綴，讓統帥識別（ADR-004）

@@ -341,6 +343,14 @@
 - **decay_rate**：`0.005`（預設）；`decay_exempt=True` 用於結構性/憲法類知識
 - **理由**：確保 RAG 優先抓取最新、最適用的洞察，避免歷史偏誤（ADR-005）

+### 第 45.1 條：AI 自動化安全閉環（絕對禁止違反）
+- ✅ **正確**：EventRouter 是告警、降級、去重、通知 replay 與 L2 safe action 的入口
+- ✅ **正確**：AutoHeal 是自癒副作用入口，失敗時必須安全降級為 alert / log / file queue
+- ✅ **正確**：L2 safe action 必須可審計、可回放、低副作用
+- ❌ **禁止**：自動 restart / stop / recreate `momo-db` 或 `momo-postgres`
+- ❌ **禁止**：AI 分析失敗導致 Telegram 告警完全不送出
+- **依據**：ADR-012、ADR-013、ADR-018
+
 ---

 ## 第十四章：Codex 工作規則（2026-04-29 修訂）
@@ -374,6 +384,7 @@

 ### 第 49 條：本專案不以本地 Skills 作為正式治理層（強制要求）
 - ✅ **正確**：重複流程優先寫成 `docs/guides/*.md`、腳本、測試或 ADR
+- ✅ **正確**：AI 自動化重複流程以 `docs/guides/ai_automation_session_sop.md` 維護
 - ❌ **禁止**：把 `.claude/skills`、私有 agent 腳本、外部平台工作流當成本專案正式規範來源

 ### 第 50 條：角色派工以 AGENTS 入口為準（強制要求）
--- a/TODO_NEXT_STEPS.txt
+++ b/TODO_NEXT_STEPS.txt
@@ -1,4 +1,19 @@

+================================================================================
+                      AI 自動化閉環治理同步 (2026-04-29) [DONE]
+================================================================================
+
+【已完成】
+   - ADR-018：四 AI Agent 自動化控制面立案。
+   - Memory：新增 `docs/memory/ai_automation_closure_20260429.md`。
+   - Guide/Skills 替代：新增 `docs/guides/ai_automation_session_sop.md`。
+   - SOT：更新 `docs/AI_INTELLIGENCE_MODULE_SOT.md` 至 V10.4 AI Automation 架構。
+   - Codex 規則：更新 `AGENTS.md`、`CONSTITUTION.md`、ADR/memory 索引。
+
+【下次待辦】
+   - Prometheus / Superset 指標化 `agent_action_total`、`agent_latency_seconds`、notification replay count。
+   - 補線上 smoke dashboard：EventRouter、AutoHeal、NemoTron fallback、OpenClaw embedding queue、ElephantAlpha HITL。
+
 ================================================================================
                      品牌資產最終處理與維護 (Phase 7) [DONE]
 ================================================================================
@@ -852,4 +867,4 @@ gcloud compute ssh momo-server --zone=asia-east1-a \
     * 主畫面所有圖表 (趨勢圖、圓餅圖、長條圖)。
     * Top 3 商業洞察卡片。
     * 點擊卡片後的詳細列表 (Modal)。
-     * 詳細列表的 Excel 匯出。
+     * 詳細列表的 Excel 匯出。
--- a/app.py
+++ b/app.py
@@ -95,9 +95,9 @@ except Exception as e:
    sys_log.error(f"無法檢測磁碟空間: {e}")

 # 🚩 系統版本定義 (備份與顯示用)
-# 🚩 2026-04-19 V10.3: 技術債清零 — Migration 010/011、retry queue 持久化、
-#                  NemoTron store_insight 雙寫、import 前置欄位防禦、時間衰減 RAG
-SYSTEM_VERSION = "V10.3"
+# 🚩 2026-04-29 V10.4: 四 AI Agent 自動化閉環 — EventRouter / AutoHeal /
+#                  OpenClaw Memory / ElephantAlpha bridge 文件與安全規則同步
+SYSTEM_VERSION = "V10.4"

 # ==========================================
 # 🔒 SQL Injection 防護函數
--- a/config.py
+++ b/config.py
@@ -253,7 +253,7 @@ YOUTUBE_API_KEY = os.getenv('YOUTUBE_API_KEY', '')
 # ==========================================
 # 系統版本與路徑
 # ==========================================
-SYSTEM_VERSION = "V10.3"
+SYSTEM_VERSION = "V10.4"
 LOG_FILE_PATH = os.path.join(BASE_DIR, 'logs/system.log')
 public_url = PUBLIC_URL  # 用於模板顯示

--- a/docs/AI_INTELLIGENCE_MODULE_SOT.md
+++ b/docs/AI_INTELLIGENCE_MODULE_SOT.md
@@ -1,12 +1,12 @@
 # MOMO PRO — AI 競價情報模組 Single Source of Truth

-> **最後更新**: 2026-04-17 深夜 (台北時間)
-> **狀態**: 🟢 188 生產容器實彈驗證完成 — Hermes 19s + NIM 1206 tokens + Telegram message_id=282 全通
-> **適用版本**: V10.2 AIOPS 架構
+> **最後更新**: 2026-04-29 (台北時間)
+> **狀態**: 🟢 四 AI Agent 自動化閉環已落地 — EventRouter / AutoHeal / OpenClaw Memory / ElephantAlpha bridge 具測試覆蓋
+> **適用版本**: V10.4 AI Automation 架構

 ---

-## 一、三模型路由架構
+## 一、四 AI Agent 路由架構

 ```
 SQL漏斗(~300筆)
@@ -19,15 +19,41 @@ SQL漏斗(~300筆)
  模型: meta/llama-3.1-8b-instruct @ NVIDIA NIM
  任務: Tool Calling → Telegram 告警 / DB 寫入
     ↓
-[Gemini] — 策略師 (每週, 費用審批制)
-  任務: 週策略報告 (尚未實作)
+[OpenClaw / Gemini] — 策略師 (費用審批制)
+  任務: 週策略報告、洞察報告、L3 HITL 建議
+     ↓
+[ElephantAlpha] — 編排者 (L3 Orchestrator)
+  任務: 跨 Agent orchestration、HITL、AutoHeal bridge、受控 log scan
 ```

 | 角色 | 模型 | 主機 | 成本 | 每日限額 |
 |------|------|------|------|---------|
-| 分析師 | hermes3:latest | 192.168.0.111:11434 | 零 | 無限 |
-| 派發器 | meta/llama-3.1-8b-instruct | NVIDIA NIM | 免費 80/天 | 80 (保留20給AWOOOI) |
-| 策略師 | Gemini | 雲端 | 需審批 | — |
+| Hermes 分析師 | hermes3:latest / embedding model | 192.168.0.111:11434 或 188 Ollama | 零 | 無限 |
+| NemoTron 派發器 | meta/llama-3.1-8b-instruct | NVIDIA NIM | 免費 80/天 | 80 |
+| OpenClaw 策略師 | Gemini | 雲端 | 需審批 | — |
+| ElephantAlpha 編排者 | ElephantAlpha | 依部署環境 | 受控 | HITL / 任務制 |
+
+---
+
+## 一之一、AI 自動化閉環實況（2026-04-29）
+
+```text
+事件 / 排程失敗 / code review finding
+  → EventRouter 分流、去重、降級
+  → Hermes L1 摘要或 NemoTron L2 tool calling
+  → L2 SAFE_ACTIONS / AutoHeal / OpenClaw memory
+  → Telegram 通知，失敗則 file queue，成功後 replay
+  → ai_insights + embedding_retry_queue
+  → OpenClaw / ElephantAlpha 後續策略與 HITL
+```
+
+硬性邊界：
+
+- EventRouter 是告警與 L2 safe action 的入口。
+- AutoHeal 是自癒副作用入口。
+- `momo-db` / `momo-postgres` 不可被 AI 自動 restart / stop / recreate。
+- raw `ai_insights` insert 必須接 `enqueue_insight_embedding()` 或可被 backfill。
+- ElephantAlpha 只做編排與 bridge，不可繞過 ADR-011 / ADR-012 / ADR-013。

 ---

--- a/docs/adr/ADR-012-agent-action-ladder.md
+++ b/docs/adr/ADR-012-agent-action-ladder.md
@@ -3,7 +3,7 @@
 - **Status**: Accepted
 - **Date**: 2026-04-19
 - **Deciders**: 統帥
- **Related**: ADR-001（三 Agent 分工）, ADR-004（NemoTron Fallback）, ADR-007（AI Dual-Write）, ADR-011（跨專案隔離）
+- **Related**: ADR-001（三 Agent 分工）, ADR-004（NemoTron Fallback）, ADR-007（AI Dual-Write）, ADR-011（跨專案隔離）, ADR-018（四 AI Agent 自動化控制面）

 ## Context

@@ -25,7 +25,7 @@ P2/P3 Inline Keyboard 降價決策上線後，統帥希望進一步讓 AI 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（寄信通知）|
+| **L3 Operator** | OpenClaw / ElephantAlpha | OpenClaw 提策略方案；ElephantAlpha 做 orchestration + HITL + AutoHeal bridge | 無 HITL 批准前執行高風險動作；不可繞過 ADR-011/013 | → 人工 SOP（寄信通知）|

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

@@ -41,6 +41,11 @@ P2/P3 Inline Keyboard 降價決策上線後，統帥希望進一步讓 AI Agent
 - `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：
@@ -134,9 +139,17 @@ L1 Hermes 掛  → L0 模板直出 + 🟡 「AI 分析暫不可用」
 - **Phase 4**：依需求擴 L3 HITL 按鈕
 - **Phase 5**：Prometheus metric 接入（`agent_action_total{tier,agent,event_type}`、`agent_latency_seconds`）

+## 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。
+- 尚未完成：Prometheus metrics 與完整線上 smoke dashboard。
+
 ## 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 自動化閉環修復實況
--- a/docs/adr/ADR-013-aiops-autoheal.md
+++ b/docs/adr/ADR-013-aiops-autoheal.md
@@ -43,7 +43,9 @@ Exception → Incident(DB) → PlayBook 匹配 → Auto-Heal 執行 → HealLog(

 ### 安全設計

- SSH 指令白名單：僅允許 `docker restart *`, `docker compose restart *`, `docker start *`
+- SSH 指令白名單：2026-04-29 起僅允許明確列入 allowlist 的 read-only 診斷指令；高副作用容器操作需走受控 PlayBook 與保護清單
+- `momo-db` / `momo-postgres` 永遠是 protected resource，不得被自動 restart / stop / recreate
+- DB / DNS 類離線 playbook 若無法安全修復，降級為 `ALERT_ONLY` 或 `WAIT_RETRY`
 - 冷卻機制：同 PlayBook 在 `cooldown_min` 內不重複觸發
 - 升級機制：達到 `max_retries` 後 incident.status = `escalated` 並通知人工

@@ -98,6 +100,15 @@ result=success duration=3110ms  # DNS_FAIL → docker restart momo-db 成功

 heal_log 在 restart momo-db 後因 DB 瞬斷無法寫入 DB（id=7~9 遺失）屬設計邊界，Telegram 通知仍正常推播。

+### 2026-04-29 安全修訂
+
+上述 `DNS_FAIL → docker restart momo-db` 屬早期實測紀錄，現在不再允許作為自動修復策略。最新規則：
+
+- `momo-db` / `momo-postgres` 是資料層 protected resource。
+- AutoHeal 寫 DB 失敗時不可讓自癒流程 crash，需保留 Telegram / log / fallback 記錄。
+- `CODE_FIX`、resource action 與 ElephantAlpha orchestration 必須橋接 AutoHeal，不得直接執行危險副作用。
+- raw `ai_insights` 寫入後必須 enqueue embedding，讓自癒知識進入 RAG。
+
 ### 新增 DB 表

 - `migrations/014_telegram_users.sql` — EventRouter 推播對象（替代 .env 硬編碼）
--- a/docs/adr/ADR-018-four-agent-ai-automation-control-plane.md
+++ b/docs/adr/ADR-018-four-agent-ai-automation-control-plane.md
@@ -0,0 +1,86 @@
+# ADR-018: 四 AI Agent 自動化控制面（Hermes / NemoTron / OpenClaw / ElephantAlpha）
+
+- **Status**: Accepted
+- **Date**: 2026-04-29
+- **Deciders**: 統帥
+- **Related**: ADR-001, ADR-004, ADR-007, ADR-009, ADR-011, ADR-012, ADR-013
+
+## Context
+
+ADR-001 定義 Hermes / NemoTron / OpenClaw 三 Agent 自主學習分工，ADR-012 定義事件介入的 L0/L1/L2/L3 信任邊界，ADR-013 定義 AIOps 自癒閉環。
+
+2026-04-29 的 AI 自動化盤點與修復後，系統實作已超出原本三 Agent 學習分工：
+
+- `services/event_router.py` 已成為告警、降級、去重、通知重放與安全 L2 action 的共同入口。
+- `services/auto_heal_service.py` 已承擔 incident / playbook / heal log / KM 沉澱的自癒閉環，但必須保護 `momo-db`。
+- `services/openclaw_learning_service.py` 已成為 raw `ai_insights` 寫入與 embedding queue 的橋接層。
+- `services/elephant_alpha_autonomous_engine.py` 已接入 HITL、AutoHeal bridge、Telegram 通知與受控 SSH log scan。
+
+因此需要把 ElephantAlpha 正式納入 MOMO PRO / EwoooC 的 AI 自動化控制面，避免文件仍停留在三 Agent 舊模型。
+
+## Decision
+
+採用「四 AI Agent + EventRouter + AutoHeal」控制面：
+
+| 角色 | 層級 | 主要責任 | 不可越界 |
+|---|---|---|---|
+| Hermes | L1 Observer / Embedding | 摘要、規則降級、embedding、品質分數、RAG 輔助 | 不直接做外部副作用，不生成最終策略報告 |
+| NemoTron | L2 Investigator | tool calling、事件路由、低風險安全 action、DB/KM 寫入派發 | 不動 prod 容器與外部系統，不做不可逆操作 |
+| OpenClaw | L3 Strategist | 高品質策略、報告、長期洞察、人工核准後的高風險建議 | 無 HITL 不直接執行高風險動作 |
+| ElephantAlpha | L3 Orchestrator | 跨 Agent 編排、HITL 決策、AutoHeal bridge、受控執行計畫 | 不繞過 EventRouter / AutoHeal / ADR-011 邊界 |
+
+控制面規則：
+
+1. EventRouter 是告警與 L2 action 的唯一入口；通知鏈不可因 AI 失敗中斷。
+2. AutoHeal 是自癒副作用的唯一入口；`momo-db` / `momo-postgres` 永遠不得被自動 restart / stop / recreate。
+3. OpenClaw learning 是 AI 記憶落點；raw `ai_insights` 寫入者必須同步 enqueue embedding 或具備可回補機制。
+4. ElephantAlpha 只能編排與橋接，不可直接跳過 HITL、安全白名單或跨專案隔離規則。
+5. L2 安全 action 只允許保守、可審計、可回放的動作，例如 `retry_task`、`query_km`、`silence_alert`、`flag_for_human_review`、`route_to_km`、`mark_for_relearn`。
+
+## Alternatives Considered
+
+| 方案 | 不採用原因 |
+|---|---|
+| 維持 ADR-001 三 Agent 模型 | 無法解釋 ElephantAlpha 的 orchestration / HITL / AutoHeal bridge 實況 |
+| 讓 ElephantAlpha 取代 OpenClaw | 會混淆策略報告與執行編排責任，成本與風險邊界不清 |
+| 讓 NemoTron 直接執行所有自癒 | L2 不應具備高副作用權限，與 ADR-012 信任邊界衝突 |
+| 導入外部 Agent framework | 黑盒程度高，難審計，不符合本專案 FinOps 與安全透明原則 |
+
+## Consequences
+
+正面：
+
+- 四個 AI Agent 都有明確位置，避免重疊工作與越權。
+- 告警、自癒、通知、記憶沉澱形成可測試閉環。
+- NemoTron / OpenClaw / ElephantAlpha 失敗時仍可降級到 Hermes / L0 模板。
+- AI 記憶不再只依賴單一路徑，raw insert 也能排入 embedding queue。
+
+風險與約束：
+
+- 文件與實作必須同步維護，否則新 session 容易回到三 Agent 舊心智模型。
+- ElephantAlpha 的「編排」很容易被誤解成「全權執行」，所有 bridge 必須走既有安全入口。
+- AutoHeal 若找不到 DB 或 PlayBook，必須安全降級為 alert / file / log，不可因記錄失敗而中斷通知。
+
+## Implementation Notes
+
+2026-04-29 已落地的關鍵 commit：
+
+- `779b27f` 修復 P0 告警自癒鏈與測試收集
+- `0875dd8` 補強 5.5 自癒安全回看
+- `1c2dc6c` 補強 AI 自動化閉環與安全降級
+- `f0e044a` 補齊自癒稽核與 OpenClaw 記憶閉環
+- `0c2e9bb` 串接 AI 洞察向量化與漏通知入口
+- `78eebfb` 加入告警去重與洞察向量回補
+- `d486598` 補強 ElephantAlpha 執行與通知閉環
+- `5b25f55` 補齊 EventRouter 失敗通知回放
+- `162a76b` 落地 L2 安全記憶動作
+
+## References
+
+- `docs/AI_INTELLIGENCE_MODULE_SOT.md`
+- `docs/memory/ai_automation_closure_20260429.md`
+- `docs/guides/ai_automation_session_sop.md`
+- `services/event_router.py`
+- `services/auto_heal_service.py`
+- `services/openclaw_learning_service.py`
+- `services/elephant_alpha_autonomous_engine.py`
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -39,6 +39,7 @@
 | [015](ADR-015-telegram-bot-menu-restoration.md) | Telegram Bot 完整菜單系統恢復 | Accepted | 2026-04-20 |
 | [016](ADR-016-daily-sales-cache-fingerprint.md) | daily_sales cache fingerprint（gunicorn 多 worker 一致性） | Accepted | 2026-04-29 |
 | [017](ADR-017-modularization-cleanup-roadmap.md) | 模組化收尾路線圖（Phase 3f） | Accepted | 2026-04-29 |
+| [018](ADR-018-four-agent-ai-automation-control-plane.md) | 四 AI Agent 自動化控制面（Hermes/NemoTron/OpenClaw/ElephantAlpha） | Accepted | 2026-04-29 |

 ## 規範

--- a/docs/guides/ai_automation_session_sop.md
+++ b/docs/guides/ai_automation_session_sop.md
@@ -0,0 +1,41 @@
+# AI 自動化 Session SOP
+
+> 本文件是「可重複流程 guide」，用來取代本地 Skills / 私有 agent 腳本作為正式規範來源。若使用者要求更新 Skills，優先更新本 guide、相關 ADR、memory 與測試。
+
+## 入口讀取
+
+1. 讀 `AGENTS.md`。
+2. 讀 `CONSTITUTION.md` 第十三章與第十四章。
+3. 讀 `docs/adr/README.md`，命中後只開必要 ADR。
+4. AI 自動化任務預設命中：ADR-012、ADR-013、ADR-018。
+5. 讀 `docs/memory/README.md`，命中後讀 `ai_automation_closure_20260429.md`。
+6. 需要當前架構事實時讀 `docs/AI_INTELLIGENCE_MODULE_SOT.md`。
+
+## 四 Agent 分工
+
+| Agent | 任務 | 安全邊界 |
+|---|---|---|
+| Hermes | L1 摘要、規則降級、embedding、品質分數 | 不做外部副作用 |
+| NemoTron | L2 tool calling、低風險 action、DB/KM 派發 | 不動 prod 容器、不做不可逆操作 |
+| OpenClaw | L3 策略、報告、長期洞察、HITL 後建議 | 無人工核准不執行高風險動作 |
+| ElephantAlpha | Orchestration、HITL、AutoHeal bridge、受控 log scan | 不繞過 EventRouter / AutoHeal / ADR-011 |
+
+## 實作檢查
+
+- EventRouter 失敗時必須降級到 Hermes rule / L0 template，不可中斷通知。
+- Telegram 失敗必須可暫存與 replay。
+- L2 action 必須在 `SAFE_ACTIONS` 且可審計、可回放、低副作用。
+- AutoHeal 不得 restart / stop / recreate `momo-db` 或 `momo-postgres`。
+- raw `ai_insights` 寫入後必須 enqueue embedding；若 enqueue 失敗，必須可 backfill。
+- ElephantAlpha 的 code/resource action 必須橋接 AutoHeal，不直接執行危險副作用。
+- Code review auto-fix 預設關閉；critical/high 走 HITL。
+
+## 收尾 checklist
+
+- 相關測試至少覆蓋 EventRouter、AutoHeal、NemoTron fallback、OpenClaw embedding bridge、ElephantAlpha engine、agent_actions。
+- 若有架構決策，新增 ADR 並更新 `docs/adr/README.md`。
+- 若有長期實況，更新 `docs/memory/*.md` 與 `docs/memory/README.md`。
+- 若 AI 架構事實改變，更新 `docs/AI_INTELLIGENCE_MODULE_SOT.md`。
+- 若 Codex 工作規則改變，更新 `AGENTS.md`；若紅線改變，更新 `CONSTITUTION.md`。
+- 提交前跑 `git diff --check` 與相關 pytest。
+- 使用者要求推版時，commit 後 push 到遠端。
--- a/docs/guides/codex_agent_roles.md
+++ b/docs/guides/codex_agent_roles.md
@@ -9,6 +9,7 @@
 - 只有在任務明確分流、風險高、或需要獨立驗證時，才套用角色分工思維。
 - 角色說明用於規劃與 reviewer 心智模型，不代表一定要建立 12 個常駐子代理。
 - 若任務可以由一位 Codex 在單一上下文完成，優先不要切分。
+- AI 自動化任務若使用 12 角色思維，收尾必須至少經過 `critic`，並更新 ADR / memory / SOT / guide 的必要索引。

 ## 12 角色矩陣

@@ -92,6 +93,7 @@
 - 上線前一定要有 `critic`
 - 涉及安全加 `vuln-verifier`
 - 需要最新外部事實才叫 `web-researcher`
+- AI 自動化閉環任務收尾讀 `docs/guides/ai_automation_session_sop.md`

 ## 來源註記

--- a/docs/memory/README.md
+++ b/docs/memory/README.md
@@ -13,6 +13,7 @@
 | 檔案 | 用途 | 何時閱讀 |
 |---|---|---|
 | `history_logs.md` | 重大里程碑與歷史脈絡 | 要理解演進背景、排查「為何變成這樣」時 |
+| `ai_automation_closure_20260429.md` | 四 AI Agent 自動化閉環與 2026-04-29 修復實況 | 接續 AI 自動化、EventRouter、AutoHeal、OpenClaw memory、ElephantAlpha 編排時 |
 | `credentials_passbook.md` | 伺服器、帳密、埠位對照 | 需要維運、部署、憑證核對時 |
 | `feedback_db_metadata_import.md` | SQLAlchemy metadata / `create_all()` 漏表鐵律 | 新增 model、修 schema、排查 fresh env 漏表時 |
 | `project_phase3f_cleanup_roadmap.md` | ADR-017 執行矩陣與階段紅線 | 正在做 3f 模組化收尾時 |
--- a/docs/memory/ai_automation_closure_20260429.md
+++ b/docs/memory/ai_automation_closure_20260429.md
@@ -0,0 +1,48 @@
+# AI 自動化閉環記憶（2026-04-29）
+
+> 用途：讓新 Codex session 快速掌握 2026-04-29 這輪「AI 自動化」修復後的實況，不必重讀整串對話與所有 commit。
+
+## 核心結論
+
+- AI 自動化控制面已從三 Agent 擴展為四 Agent：Hermes、NemoTron、OpenClaw、ElephantAlpha。
+- EventRouter 是告警與 L2 安全 action 的入口；AI 掛掉時必須降級，不可中斷通知。
+- AutoHeal 是自癒副作用入口；`momo-db` / `momo-postgres` 受保護，不可自動 restart / stop / recreate。
+- OpenClaw learning 是 AI 記憶與 embedding queue 的橋接層；raw `ai_insights` 寫入者必須 enqueue embedding 或可回補。
+- ElephantAlpha 只負責 orchestration / HITL / AutoHeal bridge，不可繞過 ADR-011、ADR-012、ADR-013。
+
+## 已落地範圍
+
+- EventRouter 增加同步 dispatch、AI 失敗降級、Telegram 失敗 file queue、成功後 replay、去重冷卻、靜音檢查、L2 SAFE_ACTIONS 限制。
+- NemoTron 在缺 API key、quota、timeout、network/HTTP error、0 tool call 時 fallback 到 Hermes 規則。
+- Code review pipeline 預設關閉 auto-fix，高風險只走 HITL/action_plan，內部 webhook token 預設必填。
+- AutoHeal 補 incident / heal log / KM 沉澱，DB 不可用時安全降級，SSH_CMD 限 read-only allowlist。
+- OpenClaw learning 補 raw insert embedding bridge、stale processing reset、missing embedding backfill、pgvector semantic RAG fallback。
+- Scheduler 重要失敗路徑接入 EventRouter，減少裸 exception 漏通知。
+- ElephantAlpha 執行引擎補 sync timeout、HITL reply_markup、未知 step fail fast、code/resource action 走 AutoHeal bridge。
+- L2 `agent_actions.py` 的 `flag_for_human_review`、`route_to_km`、`mark_for_relearn` 已從 stub 改為可審計 OpenClaw memory 寫入。
+
+## 驗證紀錄
+
+- 2026-04-29 最後一批：`24 passed`。
+- collect-only：`48 tests collected`。
+- `git diff --check` 已通過。
+
+## 相關 commit
+
+- `779b27f` 修復 P0 告警自癒鏈與測試收集
+- `0875dd8` 補強 5.5 自癒安全回看
+- `1c2dc6c` 補強 AI 自動化閉環與安全降級
+- `f0e044a` 補齊自癒稽核與 OpenClaw 記憶閉環
+- `0c2e9bb` 串接 AI 洞察向量化與漏通知入口
+- `78eebfb` 加入告警去重與洞察向量回補
+- `d486598` 補強 ElephantAlpha 執行與通知閉環
+- `5b25f55` 補齊 EventRouter 失敗通知回放
+- `162a76b` 落地 L2 安全記憶動作
+
+## 下次進場先看
+
+- ADR-018：四 AI Agent 自動化控制面。
+- ADR-012：Action Ladder 與 L2 SAFE_ACTIONS。
+- ADR-013：AutoHeal 安全邊界。
+- `docs/AI_INTELLIGENCE_MODULE_SOT.md`：目前 AI 架構事實。
+- `docs/guides/ai_automation_session_sop.md`：AI 自動化 session 執行與收尾 SOP。
--- a/docs/memory/history_logs.md
+++ b/docs/memory/history_logs.md
@@ -1,6 +1,7 @@
 # EwoooC 專案歷史紀錄 (History Logs)

 ## 📌 重大里程碑
+- **2026-04-29**: ADR-018 四 AI Agent 自動化控制面立案，Hermes / NemoTron / OpenClaw / ElephantAlpha 的告警、自癒、記憶與 HITL 邊界完成文件化。
 - **2026-04-29**: ADR-017 Phase 3f 模組化收尾立案，啟動 DB metadata、路由雙註冊、cache、scheduler、模板與死碼清理六線收斂。
 - **2026-04-18**: 專案正式正名為 **EwoooC**，AI 治理架構 Phase 4 結案（V10.3）。
 - **2026-02-13**: WOOO AIOps SaaS 核心模組完成。
@@ -17,6 +18,13 @@
 - **啟動自檢**: `app.py` 啟動時檢查 34 張 expected metadata tables，缺表直接 fail fast，防止「看似啟動成功但 create_all 漏表」。
 - **路線校正**: 12-Agent 盤點確認 3f-1 需先處理 API shadow 與 `system_bp` prefix 分裂，3f-3 需先補 EventRouter 同步告警 facade，再改 scheduler 裸 `except`。

+### 2026-04-29：AI 自動化閉環與四 Agent 控制面
+- **ADR-018 立案**: 正式把 ElephantAlpha 納入 Hermes / NemoTron / OpenClaw 之外的 L3 Orchestrator，形成四 AI Agent 自動化控制面。
+- **通知鏈補強**: EventRouter 補 AI 失敗降級、Telegram file queue、成功後 replay、去重冷卻與 silence 檢查。
+- **自癒安全回看**: AutoHeal 保護 `momo-db` / `momo-postgres`，DB/DNS 無法安全修復時降級為 alert / wait retry。
+- **記憶閉環**: raw `ai_insights` insert 路徑補 embedding enqueue；OpenClaw learning 支援 stale reset 與 missing embedding backfill。
+- **L2 action 落地**: `flag_for_human_review`、`route_to_km`、`mark_for_relearn` 改為可審計 OpenClaw memory 寫入。
+
 ### 2026-04-28~29：Phase 3e 重構大戰 + daily_sales cache 隱形 bug 根除
 - **app.py 縮減 -10.8%**: 7,386 → 6,590 行，11 commits 全綠零 502。
 - **抽 Blueprint**: `/api/categories` → `category_routes.py` (8fce73b)；`/api/test_url` + `/brand_assets` → `misc_routes.py` (e676840)。