From d58e4d0d1171383349fae508e298471d30d1e8a1 Mon Sep 17 00:00:00 2001 From: OoO Date: Wed, 29 Apr 2026 23:36:23 +0800 Subject: [PATCH] =?UTF-8?q?=E5=90=8C=E6=AD=A5=E5=9B=9B=20Agent=20AI=20?= =?UTF-8?q?=E8=87=AA=E5=8B=95=E5=8C=96=E6=B2=BB=E7=90=86=E7=B4=80=E9=8C=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 9 +- CONSTITUTION.md | 25 ++++-- TODO_NEXT_STEPS.txt | 17 +++- app.py | 6 +- config.py | 2 +- docs/AI_INTELLIGENCE_MODULE_SOT.md | 44 ++++++++-- docs/adr/ADR-012-agent-action-ladder.md | 17 +++- docs/adr/ADR-013-aiops-autoheal.md | 13 ++- ...-four-agent-ai-automation-control-plane.md | 86 +++++++++++++++++++ docs/adr/README.md | 1 + docs/guides/ai_automation_session_sop.md | 41 +++++++++ docs/guides/codex_agent_roles.md | 2 + docs/memory/README.md | 1 + docs/memory/ai_automation_closure_20260429.md | 48 +++++++++++ docs/memory/history_logs.md | 8 ++ 15 files changed, 294 insertions(+), 26 deletions(-) create mode 100644 docs/adr/ADR-018-four-agent-ai-automation-control-plane.md create mode 100644 docs/guides/ai_automation_session_sop.md create mode 100644 docs/memory/ai_automation_closure_20260429.md diff --git a/AGENTS.md b/AGENTS.md index b7bd8bb..26663e2 100644 --- 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 開場必讀。 diff --git a/CONSTITUTION.md b/CONSTITUTION.md index 5d8ef46..c1874b2 100644 --- 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 入口為準（強制要求） diff --git a/TODO_NEXT_STEPS.txt b/TODO_NEXT_STEPS.txt index 097b8e5..9559adc 100644 --- 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 匯出。 \ No newline at end of file + * 詳細列表的 Excel 匯出。 diff --git a/app.py b/app.py index 41346b9..2d2109e 100644 --- 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 防護函數 diff --git a/config.py b/config.py index cd67b25..116c131 100644 --- 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 # 用於模板顯示 diff --git a/docs/AI_INTELLIGENCE_MODULE_SOT.md b/docs/AI_INTELLIGENCE_MODULE_SOT.md index 89ce495..8823aad 100644 --- 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。 --- diff --git a/docs/adr/ADR-012-agent-action-ladder.md b/docs/adr/ADR-012-agent-action-ladder.md index 90afa9a..ba41d77 100644 --- 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 自動化閉環修復實況 diff --git a/docs/adr/ADR-013-aiops-autoheal.md b/docs/adr/ADR-013-aiops-autoheal.md index 211aaf4..53c08d9 100644 --- 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 硬編碼） diff --git a/docs/adr/ADR-018-four-agent-ai-automation-control-plane.md b/docs/adr/ADR-018-four-agent-ai-automation-control-plane.md new file mode 100644 index 0000000..18f7a7e --- /dev/null +++ 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` diff --git a/docs/adr/README.md b/docs/adr/README.md index 9a73f71..b4f4244 100644 --- 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 | ## 規範 diff --git a/docs/guides/ai_automation_session_sop.md b/docs/guides/ai_automation_session_sop.md new file mode 100644 index 0000000..4589d93 --- /dev/null +++ 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 到遠端。 diff --git a/docs/guides/codex_agent_roles.md b/docs/guides/codex_agent_roles.md index 533af7b..8d695d9 100644 --- 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` ## 來源註記 diff --git a/docs/memory/README.md b/docs/memory/README.md index 0d67e16..f9ef2ca 100644 --- 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 模組化收尾時 | diff --git a/docs/memory/ai_automation_closure_20260429.md b/docs/memory/ai_automation_closure_20260429.md new file mode 100644 index 0000000..856f6c0 --- /dev/null +++ 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。 diff --git a/docs/memory/history_logs.md b/docs/memory/history_logs.md index e41011d..8780075 100644 --- 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)。