# [P9-COMPLETION-v2] 三 AI NLP 修復 + P9-1 合併 Sprint 總報告

> 日期：2026-04-24  
> 統籌者：planner（P9 模式）  
> 前身：`docs/p9_completion_report_20260424.md`（P9-1）  
> 本報告合併：P9-1 遺留 + P9-2 三 AI NLP 全斷修復成果，給出完整 Sprint 時程與部署批次建議。  
> **鐵律**：本報告只做規劃，不含任何程式碼修改。

---

## 0. Executive Summary

P9-2 六階段跑完（A 診斷 → B DB 覆核 → C 外部文件覆核 → D 實作 → E 暫停等 KEY → F critic 審查中），合計 **13 個檔案 / +985 / -227 行**（含 P9-1 既有變動）。

核心成果：
- **三 AI NLP 全斷根因鎖定並修正**：Hermes/NemoTron 方法補齊、ai_orchestrator SQL 加 `text()`、OpenClaw 接入 telegram_ai_integration、繁中化回應。
- **AIOps/KM 真問題重新定義**：db-expert 推翻 Phase 1-E 誤判，指出 `AIOps writer 從未實作`（incidents/heal_logs 表從頭沒人寫入），ai_insights 63/70 旁路繞過 `_enqueue_embedding`。
- **外部風險警報**：Gemini 2.0 Flash **2026-06-01 EOL**（僅剩 5 週），NVIDIA NIM 40 RPM 硬牆未加限流，Ollama `/api/embeddings` 已 deprecated。
- **Sprint 0 阻斷項**：`.env` 完全沒有 `GEMINI_API_KEY`（三容器都沒），**必須統帥親手提供**才能推進 Sprint 1。

---

## 1. Git 變更全景（git diff --stat）

```
 .claude/hooks/commit-quality.js         | 134 +++++++++++------
 .claude/settings.json                   |  80 +++++++++-
 .env.example                            |   8 +
 config.py                               |  10 ++
 docker-compose.yml                      |  10 +-
 routes/openclaw_bot_routes.py           | 251 ++++++++++++++++++--------------
 services/ai_orchestrator.py             |  14 +-
 services/hermes_analyst_service.py      | 126 ++++++++++++++++
 services/nemoton_dispatcher_service.py  |  57 ++++++++
 services/openclaw_strategist_service.py |  51 +++++++
 services/telegram_bot_service.py        | 221 +++++++++++++++++++++++++---
 services/telegram_templates.py          | 154 +++++++++++++++++++-
 telegram_ai_integration.py              |  96 ++++++++----
 13 files changed, 985 insertions(+), 227 deletions(-)
```

分類：
| 類別 | 檔案 |
|------|------|
| Hook + 本地設定 | `.claude/hooks/commit-quality.js`, `.claude/settings.json` |
| 環境 / 配置 | `.env.example`, `config.py`, `docker-compose.yml` |
| P9-1 Telegram runtime | `routes/openclaw_bot_routes.py`, `services/telegram_bot_service.py`, `services/telegram_templates.py` |
| P9-2 三 AI NLP 修復 | `services/ai_orchestrator.py`, `services/hermes_analyst_service.py`, `services/nemoton_dispatcher_service.py`, `services/openclaw_strategist_service.py`, `telegram_ai_integration.py` |
| 新檔（staged） | `services/mcp_context_service.py` |
| Untracked（待決）| `sqlite:/`, `scripts/diagnose_env.py`, `scripts/cleanup_harbor_data.sh`, `scripts/setup_harbor_cleanup_cron.sh`, `n8n-workflows/27-*.json`, `docs/guides/DISK_EXPANSION_GUIDE.md`, `docs/refactor/` |

---

## 2. 合併 Sprint 時程（P9-1 + P9-2）

### Sprint 0 — 本日（統帥親操，Agent 無法代勞）

| # | 動作 | 負責 | 阻斷 |
|---|------|------|------|
| S0-1 | BotFather `/revoke` 吊銷 `OpenClawAwoooI_Bot` 既有 Token，取得新 Token | 統帥 | 三專案共用 Bot，revoke 後三個 `.env` 都要換 |
| S0-2 | 提供 `GEMINI_API_KEY`（Google AI Studio 申請 / Vault 取出）| 統帥 | P9-2-E 暫停點，無此 KEY 則 OpenClaw L3 全斷 |
| S0-3 | 裁定三容器注入策略：`momo-pro-system` / `momo-scheduler` / `momo-telegram-bot` 各自是否需 `GEMINI_API_KEY` | 統帥 | 影響 docker-compose env 段與 `.env` 檔 |
| S0-4 | 重啟三容器（`docker compose up -d --no-deps --force-recreate`，**禁 --remove-orphans**）| 統帥/Agent | ADR-011 |

### Sprint 1 — 48 小時內（Agent 推進，commit + 部署 + smoke test）

| # | 動作 | 執行 |
|---|------|------|
| S1-1 | critic 審查 P9-2-D 的 5 檔實作（P9-2-F 完成後） | critic |
| S1-2 | 分四批次 commit（詳見 §3） | fullstack-engineer |
| S1-3 | 推送 `main` 觸發 Gitea Actions sync 部署 | Git push |
| S1-4 | Smoke test：`/health`、Telegram `cmd:ppt:daily`、L1/L2/L3 三路 NLP 對話 | 統帥 + Agent |
| S1-5 | 建立 P9-1 Hook 對主機 Compose 指令白名單測試 | tool-expert |

### Sprint 2 — 一週內（基礎建設補強）

| # | 動作 | 執行 | 來源 |
|---|------|------|------|
| S2-1 | **AIOps writer 實作**（incidents / heal_logs 表） | db-expert + fullstack | P9-2-B P0 |
| S2-2 | `ai_insights` 旁路寫入改走 `_enqueue_embedding`（code_review / elephant_alpha 兩處） | db-expert + fullstack | P9-2-B P1 |
| S2-3 | M4 module-level dict 改為 Redis / worker-safe store | fullstack | P9-1 |
| S2-4 | NVIDIA NIM 40 RPM rate limiter（`token bucket`）+ 429 退避 | fullstack | P9-2-C P1 |
| S2-5 | Embedding worker 從「import 時啟動」改為獨立 service / scheduler 任務 | db-expert | P9-2-B P2 |
| S2-6 | KM 雙寫斷鏈驗證：隨機抽 10 筆 ai_insights 確認 embedding 補齊 | db-expert | P9-1 |

### Sprint 3 — 兩週內（架構決策與重構）

| # | 動作 | 執行 | 來源 |
|---|------|------|------|
| S3-1 | **Gemini 2.5 遷移**（Flash 或 Pro；2.0 於 2026-06-01 EOL，剩 5 週） | fullstack + web-researcher | P9-2-C P0 |
| S3-2 | Callback prefix 統一（方案 C：308 按鈕加 `momo:`） | refactor-specialist | P9-1 |
| S3-3 | `telegram_bot_service.py` 5969 行拆分（H1，地圖已有，45h） | refactor-specialist | P9-1 |
| S3-4 | 雙 Bot 架構決策（繼續共用 `OpenClawAwoooI_Bot` vs 獨立 `MomoProBot`） | 統帥 + 架構會議 | P9-1 |
| S3-5 | `config.py` / `docker-compose.yml` / `sqlite:/` 落地處置（裁定留存 or 刪除） | 統帥 | P9-1 |

### Sprint 4 — 監控期（效能調校與 Deprecation 清理）

| # | 動作 | 執行 | 來源 |
|---|------|------|------|
| S4-1 | Ollama `/api/embeddings` → `/api/embed` 全域遷移 | fullstack | P9-2-C P1 |
| S4-2 | `OLLAMA_KEEP_ALIVE=-1` 設定（bge-m3 常駐記憶體） | 運維 | P9-2-C P2 |
| S4-3 | 三 AI NLP 成本與延遲指標儀表板（Superset） | fullstack | 新增 |
| S4-4 | Gemini 2.5 遷移後 7 日對比觀察（成本、token、延遲） | 統帥 + AI | S3-1 收尾 |

---

## 3. 部署批次建議

為避免一次性大改（違反「保守迭代切入」鐵律），分四批 push：

### 批次 A：Hook + 散落檔清理（風險最低）
**檔案**：`.claude/hooks/commit-quality.js`、`.claude/settings.json`、`.env.example`  
**Smoke test**：
- 本機 `git commit` 嘗試塞入假 Token，Hook 應阻擋
- Claude Code 重新啟動，settings.json 能正常載入
- `.env.example` diff 內容不含真實 KEY

### 批次 B：Telegram Runtime 主修（P9-1 BLOCKER）
**檔案**：`routes/openclaw_bot_routes.py`、`services/telegram_bot_service.py`、`services/telegram_templates.py`  
**Smoke test**：
- Telegram 發送 `cmd:ppt:daily`、`cmd:ppt:weekly`，按鈕回應正常
- `EventRouter.dispatch()` 發出的六類模板各選一筆檢視格式
- 308 個 callback_data 不跨專案衝突（momo:/openclaw:/awoooi: 隔離）
- `/health` 200

### 批次 C：三 AI NLP（P9-2 主修，Sprint 0 完成後）
**檔案**：`services/ai_orchestrator.py`、`services/hermes_analyst_service.py`、`services/nemoton_dispatcher_service.py`、`services/openclaw_strategist_service.py`、`telegram_ai_integration.py`  
**前置**：`GEMINI_API_KEY` 已注入並重啟三容器  
**Smoke test**：
- L1 路：Telegram 問 "昨天業績怎樣" → Hermes 回繁中摘要
- L2 路：Telegram 問 "下禮拜要不要漲價" → NemoTron 分派
- L3 路：Telegram 問 "幫我規劃 Q2 策略" → OpenClaw（Gemini）回繁中策略
- `ai_orchestrator.py` 的 SQL 查詢不再丟 `ProgrammingError: text() required`
- `ai_insights` 表新增紀錄，embedding 欄位有值（走 `_enqueue_embedding`）

### 批次 D：compose + docs（最後收尾）
**檔案**：`docker-compose.yml`、`config.py`、`services/mcp_context_service.py`、`docs/*`  
**Smoke test**：
- Gitea Actions rebuild 模式觸發（因 compose 變動）
- 三容器重啟後 `docker ps` 皆 healthy
- `momo-db` 未被動到（ADR-011 防線）
- ADR / 新文件可在 Gitea 瀏覽

> **批次 A/B 可於 Sprint 1 前半併行推進（不等 S0-2 KEY）；批次 C 強制等 Sprint 0 完成；批次 D 收尾。**

---

## 4. 統帥決策點 Checklist

本次累計共 9 項需統帥裁定，**打勾才能進下一階段**：

### Sprint 0（阻斷項，本日必決）
- [ ] **D1**：是否立即 BotFather `/revoke` `OpenClawAwoooI_Bot`？（影響三專案 Token 同步換）
- [ ] **D2**：提供 `GEMINI_API_KEY`（P9-2-E 暫停點，無此 KEY 則 L3 全斷）
- [ ] **D3**：`GEMINI_API_KEY` 注入策略 — 僅 `momo-telegram-bot`？或三容器全注入？（影響 docker-compose）

### Sprint 1（部署階段）
- [ ] **D4**：四批次 commit 順序是否依 §3 推進？是否同意批次 A/B 併行、C 等 KEY、D 收尾？
- [ ] **D5**：P9-2-F critic 若出 🔴/🟠 finding，是否沿用 ADR-014「finding 一律 auto_fix=true」？

### Sprint 2-3（中期決策）
- [ ] **D6**：Gemini 2.5 Flash vs Pro 選型（成本 vs 效能，web-researcher 已列比較表）
- [ ] **D7**：Callback prefix 方案 C（全 308 按鈕加 `momo:`）是否同意？
- [ ] **D8**：`telegram_bot_service.py` H1 拆分 45h 工時，是否排入 Sprint 3？還是延後？
- [ ] **D9**：雙 Bot 架構 — 繼續共用 vs 獨立 `MomoProBot`（影響 2 個兄弟專案，需跨專案協調）

### 散落檔裁定（隨時可決）
- [ ] **D10**：`sqlite:/`、`telegram_*_fix.py`、`fix_*.py`、`patch_tc.py`、`simple_fix.py` 等 untracked 雜檔 — 留存或批量刪除？

---

## 5. 風險雷達

| # | 風險 | 嚴重度 | 應對 | Sprint |
|---|------|--------|------|--------|
| R1 | Gemini 2.0 Flash 2026-06-01 EOL | 🔴 P0 | 5 週內完成 2.5 遷移 | S3-1 |
| R2 | AIOps writer 從未實作，incidents/heal_logs 空表 | 🔴 P0 | db-expert 立即補 writer | S2-1 |
| R3 | `.env` 無 `GEMINI_API_KEY` 導致 L3 全斷 | 🔴 P0 | 統帥手動提供 | S0-2 |
| R4 | NVIDIA NIM 40 RPM 硬牆未加限流，尖峰會 429 | 🟠 P1 | token bucket + 退避 | S2-4 |
| R5 | ai_insights 63/70 筆繞過 embedding | 🟠 P1 | 旁路改走 `_enqueue_embedding` | S2-2 |
| R6 | Ollama `/api/embeddings` deprecated | 🟡 P2 | 改 `/api/embed` | S4-1 |
| R7 | 三專案共用 Bot Token 未 revoke | 🔴 P0 | BotFather 立即吊銷 | S0-1 |
| R8 | M4 module-level dict 多 worker 不一致 | 🟡 P2 | 遷 Redis | S2-3 |

---

## 6. 完成標準（Definition of Done）

### P9-2 本批次
- [x] P9-2-A ~ D 完成，5 檔實作落地
- [ ] P9-2-E：統帥提供 `GEMINI_API_KEY`
- [ ] P9-2-F：critic 審查無 🔴/🟠 遺留
- [ ] 部署後三路 NLP smoke test 全綠

### 整體 P9-1 + P9-2 合併
- [ ] 四批次 commit 依序部署完成
- [ ] `https://mo.wooo.work/health` 持續 200
- [ ] Telegram 三路對話繁中化正確
- [ ] 統帥決策點 D1-D5 全打勾
- [ ] 下一輪 Sprint 2（AIOps writer + KM 補寫）Task Prompts 出齊

---

## 7. 附錄：本報告相關檔案絕對路徑

- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/docs/p9_completion_report_20260424.md`（P9-1 原報告）
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/docs/p9_completion_report_v2_20260424.md`（本報告）
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/services/ai_orchestrator.py`
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/services/hermes_analyst_service.py`
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/services/nemoton_dispatcher_service.py`
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/services/openclaw_strategist_service.py`
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/telegram_ai_integration.py`
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/services/telegram_bot_service.py`
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/services/telegram_templates.py`
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/routes/openclaw_bot_routes.py`
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/docker-compose.yml`
- `/Users/ooo/Library/Mobile Documents/com~apple~CloudDocs/momo-pro-system/.env.example`

> 報告終。Sprint 0 卡在統帥 D1/D2/D3 三項決策，其餘 Agent 可備戰但不推進。