# 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。
- EventRouter / AutoHeal 變更必須更新 `services/ai_automation_metrics.py` 指標或確認既有指標已覆蓋。
- AI 自動化閉環變更必須確認 `/api/ai-automation/smoke` 與 `/ai_automation_smoke` 仍能反映新狀態。
- 外部 MCP / RAG 能力導入內部治理時，必須確認 `/api/ai-automation/external-mcp-rag-integration`
  或 `python scripts/ops/report_external_mcp_rag_integration.py` 可讀回每個能力的內部落點、狀態、資料邊界與下一個機器動作。
- PixelRAG 視覺 receipt 導入內部 RAG 時，必須確認 `/api/ai-automation/pixelrag-rag-candidate-replay`
  或 `python scripts/ops/report_pixelrag_rag_candidate_replay.py` 可讀回 eligible / blocked / invalid receipts，且 blocked page 不得被視為商品資料。
- PixelRAG 視覺 receipt 進入 OCR/VLM 自動化前，必須確認 `/api/ai-automation/pixelrag-ocr-vlm-replay`
  或 `python scripts/ops/report_pixelrag_ocr_vlm_replay.py` 可讀回 ready / blocked / invalid replay contracts、field schema、validation rules 與 Ollama-first 下一步，且目前不執行 OCR/VLM、不寫正式價格。
- PixelRAG 可整合/可運用場景盤點必須確認 `/api/ai-automation/pixelrag-application-portfolio`
  或 `python scripts/ops/report_pixelrag_application_portfolio.py` 可讀回 area、priority、status、use cases、next machine action 與 forbidden guardrails；不得只存在聊天結論。
- PixelRAG VLM replay worker 必須確認 `/api/ai-automation/pixelrag-vlm-replay-worker`
  或 `python scripts/ops/run_pixelrag_vlm_replay_worker.py` 可讀回 dry-run/execute、model_call、artifact receipt、blocked/ready 分流、DB write=0 與 primary human gate=0；execute 結果仍只是 candidate evidence。
- PixelRAG VLM route readiness 必須確認 `/api/ai-automation/pixelrag-vlm-route-readiness`
  或 `python scripts/ops/report_pixelrag_vlm_route_readiness.py` 可讀回 approved Ollama hosts、configured model 是否安裝、candidate model、自動選模下一步、model_call=false、DB write=0；缺模型不得等 execute 才暴露。
- PixelRAG platform probe worker 必須確認 `/api/ai-automation/pixelrag-platform-probe-worker`
  或 `python scripts/ops/run_pixelrag_platform_probe_worker.py` 可讀回 dry-run/execute、public-context capture、structured-source/backoff receipt、network_call、artifact receipt、DB write=0 與 primary human gate=0；Shopee interstitial 可 execute capture，Coupang 403 必須自動落 structured fallback，不得要求人工主流程。
- AI automation smoke 必須包含 external MCP/RAG integration、PixelRAG RAG candidate replay、PixelRAG OCR/VLM replay contract、PixelRAG VLM route readiness、PixelRAG VLM replay worker、PixelRAG platform probe readiness 與 PixelRAG platform probe worker family，避免 registry 已完成但 runtime flag / receipt replay / VLM route / VLM worker / platform probe worker 未完成時被誤報為全自動閉環。
- AI 自動化 Prometheus 指標變更必須同步檢查 `docker/grafana/provisioning/dashboards/json/ai-automation-overview.json` 是否需要新增 panel 或查詢。
- 188 線上 active monitoring stack 以 `monitoring/prometheus.yml` 為準；110 gateway 另有 `/home/wooo/monitoring/prometheus.yml`。若 dashboard 無資料，先確認 Prometheus `momo-app` target 與 `momo-network` 連線；所有 Blackbox HTTP target 必須打 `/health`，不可打 Dashboard 首頁 `/`。
- Smoke dashboard 會保存 JSONL 趨勢；若新增檢查項目，要確保 history compact record 仍保持小而可讀。
- Smoke history 管理只能操作 `MOMO_AI_AUTOMATION_SMOKE_HISTORY` 指向的 JSONL，不得清理 DB 或 EventRouter queue。
- Smoke 每日摘要推播只讀 history，不得重新執行 smoke，也不得把完整 details 寫進 Telegram。
- 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、AI automation metrics、AI automation smoke。
- 若有架構決策，新增 ADR 並更新 `docs/adr/README.md`。
- 若有長期實況，更新 `docs/memory/*.md` 與 `docs/memory/README.md`。
- 若 AI 架構事實改變，更新 `docs/AI_INTELLIGENCE_MODULE_SOT.md`。
- 若 AI 自動化可觀測性改變，更新 Grafana provisioning JSON 與對應測試。
- 若 Codex 工作規則改變，更新 `AGENTS.md`；若紅線改變，更新 `CONSTITUTION.md`。
- 提交前跑 `git diff --check` 與相關 pytest。
- 使用者要求推版時，commit 後 push 到遠端。