# EwoooC (MOMO Pro System) — Codex 專案工作規則

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

## 1. 入口原則

- `AGENTS.md` 是本專案給 Codex 的唯一入口索引。
- `CONSTITUTION.md` 是紅線與不可違反規則。
- `docs/adr/` 保存重大架構決策。
- `docs/memory/README.md` 保存「要讀哪份記憶」的輕量索引。
- `CLAUDE.md` 僅保留為舊文件相容入口，不再作為正式規範來源。

## 2. Token 節流原則

- 先讀索引，再讀必要文件，禁止每次任務全文掃描所有 Markdown。
- 預設只讀與當前任務直接相關的 1 到 3 份文件。
- ADR 只讀 `docs/adr/README.md` 與命中的單篇 ADR，不整包展開。
- Memory 只讀 `docs/memory/README.md` 與命中的單篇記憶，不整包展開。
- 大型歷史文件、考古文、外部存檔只在任務明確需要時才開啟。
- 若規則已存在於 `CONSTITUTION.md`，不要再到其他文件尋找重複版本。

## 3. Codex Session SOP

### 開始前

1. 先讀 `AGENTS.md`。
2. 再讀 `CONSTITUTION.md` 中與本次任務直接相關的章節。
3. 讀 `docs/adr/README.md`，只打開命中的 ADR。
4. 讀 `docs/memory/README.md`，只打開命中的 memory。

### 進行中

- 先看程式碼與實際行為，再回頭補讀文件。
- 若文件與程式碼衝突，以程式碼、部署實況、已接受 ADR 為準，並回補文件。
- 修改時優先維持最小變更面，避免為了整理而擴大 diff。

### 結束前

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

## 4. 文件分層

### `AGENTS.md`

- 只放 Codex 工作方式、入口索引、環境摘要、必讀路徑。
- 保持短，不放長篇歷史、細節 SOP、逐步教學。

### `CONSTITUTION.md`

- 只放不可違反規則、跨任務穩定成立的硬性約束。
- 避免放會頻繁變動的操作細節。

### `docs/adr/`

- 只放重大架構決策與後果。
- 新 ADR 需包含 Context、Decision、Alternatives、Consequences。

### `docs/memory/`

- 只放高重用、非決策型、跨 session 容易遺忘但值得保存的資訊。
- 每篇 memory 應短小、單主題、可被索引命中。

### Skills

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

## 4.1 Agent 角色原則

- 本專案保留歷史上的 12 角色分工思維，但改用 Codex 官方建議的「按需分工」模式。
- 角色矩陣不作為 session 開場必讀，詳細說明放在 `docs/guides/codex_agent_roles.md`。
- 預設由單一 Codex 直接完成任務；只有高風險、大規模、或明確可並行時才分角色思考。
- 最小心法：先 `planner`，出問題先 `debugger`，做完一定經過 `critic`。

## 4.2 一頁式 Dispatch 表

| 如果任務是… | 先用哪個角色思維 | 第二角色 | 收尾 |
|---|---|---|---|
| 一般功能開發 | `planner` | `fullstack-engineer` | `critic` |
| 線上 bug / 排程異常 / Telegram 故障 | `debugger` | `fullstack-engineer` | `critic` |
| 大型重構 / 拆大檔 / Blueprint 清理 | `planner` | `refactor-specialist` | `critic` |
| DB schema / ORM / 漏表 / migration | `db-expert` | `migration-engineer` | `critic` |
| 安全修補 / 權限邊界 / secret 防護 | `vuln-verifier` | `fullstack-engineer` | `critic` |
| 外部 API / SDK / 平台規格更新 | `web-researcher` | `tool-expert` | `fullstack-engineer` |
| 接手舊模組 / 新 session 重新進場 | `onboarder` | `explorer` | `planner` |
| 工具、CI、hook、部署流程選型 | `tool-expert` | `planner` | `critic` |

最小決策規則：

- 不確定先 `planner`
- 有錯先 `debugger`
- 動 DB 先 `db-expert`
- 動安全先 `vuln-verifier`
- 要上線前一定有 `critic`

## 5. 環境摘要

| 主機 | IP | 角色 |
|---|---|---|
| 110 | `192.168.0.110` | Gateway、Nginx、Gitea、n8n、Superset |
| 188 | `192.168.0.188` | App、DB、生產容器、AutoHeal target（不可作為 Ollama 節點） |
| GCP-SSD-1 | `34.87.90.216` | Primary Ollama (High Performance SSD, All Models) |
| GCP-SSD-2 | `34.21.145.224` | Secondary Ollama (SSD Optimized, Redundancy) |

## 6. 核心服務

| 容器 | 角色 | 入口 |
|---|---|---|
| `momo-pro-system` | Flask/Gunicorn 主應用 | `app.py` |
| `momo-scheduler` | 排程任務 | `run_scheduler.py` |
| `momo-telegram-bot` | Telegram Bot | `run_telegram_bot.py` |
| `momo-db` | PostgreSQL + pgvector | `momo-postgres` service |

## 7. 生產安全紅線

- 禁止使用 `docker compose ... --remove-orphans`。
- 禁止影響 `momo-db` 的資料與容器生命週期。
- 跨專案資源邊界以 ADR-011 為準。
- 部署、容器、SSH 類操作先看 `docs/adr/ADR-011-cross-project-resource-isolation.md`。
- `gunicorn.conf.py` 必須透過 `docker-compose.yml` bind mount 進 `momo-app`；除救急外，不以 `docker cp` 當常態部署方式。
- CD rebuild 應先完成 image build，再短暫 recreate 三應用容器；禁止把 no-cache build 時間變成長時間 502。
- HTTP health / Blackbox / CD 探測必須打 `/health`，不可打 Dashboard 首頁 `/`，避免監控流量觸發重型查詢造成 worker starvation。
- 所有 AI Agent / LLM / embedding 呼叫必須 Ollama-first，且只允許 GCP-A `34.87.90.216:11434` → GCP-B `34.21.145.224:11434` → 111 `192.168.0.111:11434` 三主機級聯；Gemini 只能作為備援或 ADR-028 鎖定場景，且預設由 `GEMINI_API_HARD_DISABLED=true` 硬封鎖，188 不可作為 Ollama 節點。

## 8. 常用入口

- 部署 SOP: `docs/guides/deployment_sop.md`
- DevOps 手冊: `docs/guides/devops_handbook.md`
- 模組化治理: `docs/guides/modularization_governance.md`
- 前端更版路線圖: `docs/guides/frontend_upgrade_roadmap.md`
- AI 觀測台 UI 治理: `docs/guides/observability_ui_governance.md`
- AI 自動化 Session SOP: `docs/guides/ai_automation_session_sop.md`
- Browse.sh 爬蟲診斷手冊: `docs/guides/browse_sh_crawler_playbook.md`
- Webcrumbs 共用 UI Runtime: `docs/guides/webcrumbs_shared_runtime.md`
- 外部專業 Benchmark: `docs/guides/external_professional_benchmark.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`
- 程式碼模組化盤點: `docs/memory/code_modularization_inventory_20260430.md`
- AI 自動化閉環記憶: `docs/memory/ai_automation_closure_20260429.md`
- AI 觀測台 UI QA 記憶: `docs/memory/observability_ui_qa_guardrails_20260505.md`
- 憑證手冊: `docs/memory/credentials_passbook.md`

## 9. 常用指令

```bash
source venv/bin/activate && python app.py
git push origin main
./scripts/quick_review.sh --sync-observability-css
./scripts/quick_review.sh --observability-qa
ssh wooo@192.168.0.110 "ssh ollama@192.168.0.188 \"docker ps --format '{{.Names}} | {{.Status}}' | grep momo-; docker exec momo-scheduler env | grep -iE 'TELEGRAM|NVIDIA'; docker logs momo-scheduler --since 1h | grep -E 'Telegram|Error' | tail -10\""
ssh wooo@192.168.0.110 "ssh ollama@192.168.0.188 \"cd /home/ollama/momo-pro && docker compose up -d --no-deps --force-recreate <service>\""
```

## 10. 正式規範結論

- Codex 在本專案的正式治理入口是：`AGENTS.md`、`CONSTITUTION.md`、`docs/adr/README.md`、`docs/memory/README.md`；AI 架構事實以 `docs/AI_INTELLIGENCE_MODULE_SOT.md` 為 SOT。
- 其他文件預設都視為按需查閱資料，不是 session 開場必讀。