ewoooc/AGENTS.md

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
• PChome 業績成長 UI/UX 守門: docs/guides/pchome_growth_ui_ux_guardrails.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. 常用指令

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 開場必讀。