170 lines
8.0 KiB
Markdown
170 lines
8.0 KiB
Markdown
# 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.143.170.20` | 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.143.170.20: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 開場必讀。
|