diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b7bd8bb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,148 @@ +# EwoooC (MOMO Pro System) — Codex 專案工作規則 + +> 版本: V13.0 +> 目標: 把專案知識整理成 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。 +- 有全域紅線變更才更新 `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` 或本地技能腳本作為正式規範。 +- 若未來需要可重複流程，優先寫成： + 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、Ollama、生產容器 | + +## 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`。 + +## 8. 常用入口 + +- 部署 SOP: `docs/guides/deployment_sop.md` +- DevOps 手冊: `docs/guides/devops_handbook.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/credentials_passbook.md` + +## 9. 常用指令 + +```bash +source venv/bin/activate && python app.py +git push origin main +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 \"" +``` + +## 10. 正式規範結論 + +- Codex 在本專案的正式工作規則來源只有四個：`AGENTS.md`、`CONSTITUTION.md`、`docs/adr/README.md`、`docs/memory/README.md`。 +- 其他文件預設都視為按需查閱資料，不是 session 開場必讀。 diff --git a/CLAUDE.md b/CLAUDE.md index ec160af..4f383c7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,106 +1,12 @@ -# EwoooC (MOMO Pro System) — 核心索引 +# Legacy Notice -> **版本**: V12.0 | **目標**: AI 驅動 MOMO 商品監控、業績分析、策略自動化與 AIOps 自愈 -> **全域工作流程**（P7/P9/P10、三紅線、委派表、PUA/Loop）見 `~/.claude/CLAUDE.md` +`CLAUDE.md` 已退役，不再是本專案的正式規範入口。 -## 治理 -- **憲法**: [CONSTITUTION.md](CONSTITUTION.md) — 所有開發必須遵守 -- **ADR**: [docs/adr/](docs/adr/) -- **AI 策略師**: `services/openclaw_strategist_service.py` (Gemini 2.0) +請改讀以下文件： -## 環境 -| 主機 | IP | 角色 | -|------|----|------| -| 110 (Gateway) | `192.168.0.110` | Nginx, Gitea, n8n, Superset | -| 188 (App/AI) | `192.168.0.188` | EwoooC App, DB, Ollama（多專案共存，見 ADR-011） | +1. `AGENTS.md`：Codex 專案工作規則與入口索引 +2. `CONSTITUTION.md`：不可違反的硬性規則 +3. `docs/adr/README.md`：架構決策索引 +4. `docs/memory/README.md`：輕量記憶索引 -## 核心容器（三動一 DB，缺一不可） -| 容器 | 角色 | 啟動入口 | -|------|------|---------| -| `momo-pro-system` | Flask/Gunicorn 主應用 | `app.py`（手動 docker run 歷史債，見 ADR-011） | -| `momo-scheduler` | 13 個排程任務（爬蟲/AI/備份/通知） | `run_scheduler.py` | -| `momo-telegram-bot` | Telegram 互動 + 每日 09:00 推播 | `run_telegram_bot.py`（根目錄副本） | -| `momo-db` | PostgreSQL + pgvector | compose service `momo-postgres` | - -## 常用指令 -```bash -# 本地開發 -source venv/bin/activate && python app.py - -# 部署（標準）→ push 即自動部署（Gitea Actions），同時重啟三容器 -git push origin main - -# 🔍 診斷黃金三句（任何 Telegram/排程異常先跑） -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\"" - -# 🆘 緊急重建單容器（不影響 momo-db 資料） -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 \"" -# ⚠️ 禁用 --remove-orphans（會清掉 momo-db！見 ADR-011） -``` - -## CI/CD -| 項目 | 說明 | -|------|------| -| Gitea Repo | `http://192.168.0.110:3001/wooo/ewoooc` (Public) | -| CD Pipeline | `.gitea/workflows/cd.yaml` | -| 部署模式 | sync（Python 變動 ~30s）/ rebuild（Dockerfile 變動） | -| 健康檢查 | `https://mo.wooo.work/health` | -| Runner | `wooo-runner`（user-level，服務所有 wooo/* repo） | -| 通知 | Telegram（部署開始/成功/失敗） | -| 參考 | ADR-010 | - -## 文檔索引 -| 類型 | 路徑 | -|------|------| -| 部署 SOP | [docs/guides/deployment_sop.md](docs/guides/deployment_sop.md) | -| DevOps 手冊 | [docs/guides/devops_handbook.md](docs/guides/devops_handbook.md) | -| Google Drive | [docs/guides/google_drive_setup.md](docs/guides/google_drive_setup.md) | -| 歷史日誌 | [docs/memory/history_logs.md](docs/memory/history_logs.md) | -| 憑證對照表 | [docs/memory/credentials_passbook.md](docs/memory/credentials_passbook.md) | -| AIOps 存檔 | [docs/external/aiops_saas.md](docs/external/aiops_saas.md) | -| 跨專案隔離（**必讀**）| [docs/adr/ADR-011-cross-project-resource-isolation.md](docs/adr/ADR-011-cross-project-resource-isolation.md) -* **ADR-011: Docker --remove-orphans 危險停用決策**（避免 Gitea Action 刪除非 Compose 管理的容器，如資料庫） -* **ADR-012: Elephant Alpha 模型整合**（三智能體核心決策大腦，具備防爆走護欄與 Telegram 稽核通知） -* **ADR-013: AIOps 自動修復服務**（實作 `AutoHealService` 處理容器異常關閉與效能瓶頸，通過 SSH Jump Executor 在跳板機隔離操作機制） -* **ADR-014: Autonomous Code Repair**（結合 Elephant Alpha 進行系統錯誤日誌Traceback掃描，自動觸發 110 主機上 Aider 自動化執行程式碼修復，並依賴 Git + Gitea CI/CD 回滾防線進行安全發布） -* **ADR-015: Telegram Bot Menu 復活**（OpenClawAwoooI_Bot 三專案共用、cmd:/menu:/await: callback prefix） -* **ADR-016: daily_sales cache fingerprint**（gunicorn 多 worker cache 失效改 DB MAX/COUNT 指紋；棄用 N-POST 9.4% 命中 hack；3971fd4 已落地） | -* **ADR-017: Phase 3f 模組化收尾**（DB metadata、路由雙註冊、cache、scheduler、模板與死碼清理收斂路線圖） | -| **PPT 簡報系統 V2（ADR-014）** | [docs/adr/ADR-014-ppt-report-system-v2.md](docs/adr/ADR-014-ppt-report-system-v2.md) | - -## PPT 簡報系統（9 種，V2） -| 類型 | 頁數 | Telegram 指令 | 核心圖表 | -|------|------|-------------|---------| -| daily 日報 | 4 | `cmd:ppt:daily` | 近7日業績柱狀圖 | -| weekly 週報 | 5 | `cmd:ppt:weekly` | 7日走勢+TOP10 | -| monthly 月報 | 5 | `cmd:ppt:monthly` | 品類橫條+TOP10 | -| strategy 策略 | 5 | `cmd:ppt:strategy [範圍]` | 策略矩陣分佈+行動清單 | -| competitor 競品 | 4 | `cmd:ppt:competitor [範圍]` | 橫條圖+比較表 | -| promo 促銷 | 5 | `await:promo_range` | 雙層KPI+雙柱業績對比 | -| **growth** 成長趨勢 | **6** | `cmd:ppt:growth` | 月營收+MoM+AOV+毛利率 | -| **vendor** 廠商業績 | **5** | `cmd:ppt:vendor [YYYY/MM]` | TOP20廠商2024/2025對比 | -| **bcg** 品牌矩陣 | **5** | `cmd:ppt:bcg [YYYY/MM]` | BCG象限表+區域分佈 | - ---- - -## momo 安全架構（bypassPermissions） - -本專案採用 `permissions.defaultMode: "bypassPermissions"` + Hook 自動政策替代人工確認對話框。 -安全防線由 [.claude/hooks/](.claude/hooks/) 的 Hook 自動執行，覆蓋範圍： - -| Hook | 觸發點 | 防護內容 | -|------|--------|---------| -| `momo-prod-guard.js` | PreToolUse | 阻擋 --remove-orphans、force push、遠端 docker rm momo-db、生產 SSH 稽核 | -| `commit-quality.js` | PreToolUse | 阻擋 hardcoded Token/API Key（含 Telegram/Gemini/Gitea 模式）| -| `large-file-warner.js` | PreToolUse | >2MB 阻擋讀取，>500KB 警告 | -| `mcp-health.js` | PreToolUse | MCP 伺服器 cooldown 保護 | -| `audit-log.js` | PostToolUse | 所有 Bash 指令稽核，自動 redact Token | -| `suggest-compact.js` | PostToolUse | 50 次工具呼叫後建議 /compact | -| `cost-tracker.js` | Stop | Token 用量與成本追蹤 | -| `session-summary.js` | Stop | 對話快照存檔 | - -全域 Hook（`~/.claude/hooks/`）同時生效：`branch-protection.js`（main 分支保護已透過 `.claude/hooks/branch-protection.local.json` 設為僅保護 `production`）。 +此檔僅作為舊文件、舊連結、舊工作流的相容轉址頁。 diff --git a/CONSTITUTION.md b/CONSTITUTION.md index 2281f31..5d8ef46 100644 --- a/CONSTITUTION.md +++ b/CONSTITUTION.md @@ -14,7 +14,7 @@ ### 第 0.2 條：文檔規範 - 所有文檔使用 Markdown 格式。 - 檔案名稱優先使用英文大寫加底線（例：`CONSTITUTION.md`）。 -- 重要變更需記錄在 `CLAUDE.md` 或 `walkthrough.md` 中。 +- 重要變更需記錄在對應正式文件中：入口變更寫 `AGENTS.md`，架構決策寫 ADR，長期專案知識寫 `docs/memory/README.md` 對應條目。 --- @@ -343,36 +343,45 @@ --- -## 第十四章：Claude Code 官方遊戲規則（2026-04-18 加入） +## 第十四章：Codex 工作規則（2026-04-29 修訂） -### 第 46 條：記憶架構四層必須完整（絕對禁止違反） -- **Memory**：`~/.claude/projects/.../memory/*.md` — 跨 Session 持久記憶 +### 第 46 條：正式規範來源必須精簡且唯一（絕對禁止違反） +- **入口**：`AGENTS.md` — Codex 專案工作入口與讀取順序 +- **紅線**：`CONSTITUTION.md` — 不可違反規則 - **ADR**：`docs/adr/ADR-XXX-*.md` — 架構決策，只增不刪 +- **Memory**：`docs/memory/README.md` + 單篇 memory — 跨 session 的高重用記憶 - **SOT**：`docs/AI_INTELLIGENCE_MODULE_SOT.md` — 當前架構事實 -- **Skills**：`.claude/skills/*.py` — 執行 SOP checklist -- ❌ **禁止**：任何一層缺失，都會導致後續 Session 失憶或決策矛盾 +- ❌ **禁止**：讓多份文件同時扮演正式入口，造成規則重複與 token 浪費 -### 第 47 條：Session 開始 SOP（強制要求） +### 第 47 條：Session 開始採最小必要讀取（強制要求） ``` -每次 Claude Session 開始必做： -1. 讀 CLAUDE.md 第零章（元憲法） -2. 讀 memory/MEMORY.md 索引 -3. 讀 docs/adr/README.md 索引 -4. 才開始執行任務 +每次 Codex Session 開始必做： +1. 讀 AGENTS.md +2. 讀 CONSTITUTION.md 的相關章節 +3. 讀 docs/adr/README.md，僅打開命中的 ADR +4. 讀 docs/memory/README.md，僅打開命中的 memory ``` -### 第 48 條：Session 結束沉澱 SOP（強制要求） +### 第 48 條：Session 結束沉澱採最小必要更新（強制要求） ``` 每次 Session 結束前必做 checklist： -□ 有架構決策？→ 新建 ADR-XXX.md + 更新索引 -□ 有統帥偏好？→ 更新 memory/user_profile.md -□ 有技術債？→ 更新 memory/project_tech_debt_backlog.md +□ 有新架構決策？→ 新建 ADR-XXX.md + 更新 docs/adr/README.md +□ 有長期有效的專案知識？→ 新增或更新 docs/memory/*.md + docs/memory/README.md □ 有 SOT 變更？→ 更新 AI_INTELLIGENCE_MODULE_SOT.md -□ 有憲法新條款？→ 更新 CONSTITUTION.md + CLAUDE.md -□ 更新 memory/MEMORY.md 索引 +□ 有硬性紅線變更？→ 更新 CONSTITUTION.md +□ 有入口或工作方式變更？→ 更新 AGENTS.md ``` -### 第 49 條：專案範圍邊界（絕對禁止違反） +### 第 49 條：本專案不以本地 Skills 作為正式治理層（強制要求） +- ✅ **正確**：重複流程優先寫成 `docs/guides/*.md`、腳本、測試或 ADR +- ❌ **禁止**：把 `.claude/skills`、私有 agent 腳本、外部平台工作流當成本專案正式規範來源 + +### 第 50 條：角色派工以 AGENTS 入口為準（強制要求） +- ✅ **正確**：預設派工與角色選路以 `AGENTS.md` 的一頁式 dispatch 表為準 +- ✅ **正確**：角色詳細說明以 `docs/guides/codex_agent_roles.md` 為準 +- ❌ **禁止**：把歷史上的私有 agent 腳本、舊 onboarding 或散落文件當成更高優先級的派工真相 + +### 第 51 條：專案範圍邊界（絕對禁止違反） - ✅ **本憲法範圍**：`momo-pro-system`（EwoooC）**唯一** - ❌ **禁止**：將 AWOOOI / WOOO AIOps SaaS 的決策混入本文件 - ❌ **禁止**：跨專案邊界做架構決策 diff --git a/PROJECT_CONSTITUTION.md b/PROJECT_CONSTITUTION.md new file mode 100644 index 0000000..a8df267 --- /dev/null +++ b/PROJECT_CONSTITUTION.md @@ -0,0 +1,600 @@ +# MOMO 監控系統 - 專案憲法 + +**版本：** 1.3 +**制定日期：** 2026-01-12 +**最後更新：** 2026-01-14 + +--- + +## 📜 專案基本原則 + +本憲法定義了 MOMO 監控系統的開發規範、溝通原則、安全政策及技術標準。所有參與者（開發人員、AI 助手、維護人員）必須遵守以下規範。 + +--- + +## 🗣️ 第一章：溝通規範 + +### 第 1 條：語言使用 +- **所有溝通一律使用繁體中文** +- 包含但不限於： + - 程式碼註解 + - 文檔說明 + - Commit 訊息 + - 錯誤訊息 + - 日誌輸出 + - 使用者介面文字 + - README 和文檔 + +### 第 2 條：文檔規範 +- 所有文檔檔案使用 Markdown 格式（`.md`） +- 檔案名稱使用英文大寫加底線（例：`PROJECT_CONSTITUTION.md`） +- 文檔內容必須包含版本號和最後更新日期 +- 重要變更需記錄在 CHANGELOG 中 + +### 第 3 條：註解規範 +- Python 函數必須包含繁體中文 docstring +- 複雜邏輯必須添加行內註解說明 +- 註解應說明「為什麼」而非「做什麼」 + +--- + +## 🔒 第二章：安全政策 + +### 第 4 條：敏感資訊管理 +- **禁止在程式碼中硬編碼任何敏感資訊** +- 所有憑證、API 金鑰、密碼必須使用環境變數（`.env`） +- `.env` 檔案必須列入 `.gitignore` +- 提供 `.env.example` 作為範本 + +### 第 5 條：密碼安全 +- 所有密碼必須使用 `pbkdf2:sha256` 雜湊儲存 +- 禁止使用明文密碼（僅過渡期允許，需發出警告） +- 密碼長度至少 8 個字元，包含英文字母和數字 +- 登入失敗 5 次後鎖定帳號 5 分鐘 + +### 第 6 條：輸入驗證 +- **所有使用者輸入必須經過驗證** +- SQL 查詢必須使用參數化查詢或白名單驗證 +- 檔案上傳必須驗證副檔名和檔案大小 +- 路徑操作必須使用 `safe_join()` 防止路徑遍歷 + +### 第 7 條：CSRF 防護 +- 所有 POST/PUT/DELETE/PATCH 請求必須包含 CSRF token +- HTML 表單使用 hidden input: `` +- AJAX 請求使用 header: `'X-CSRFToken': getCSRFToken()` + +### 第 8 條：Session 安全 +- Session cookie 必須設定 `HttpOnly=True` +- Session cookie 必須設定 `SameSite=Lax` +- 生產環境必須設定 `Secure=True`（HTTPS） +- Session 有效期設定為 2 小時 + +--- + +## 💻 第三章：程式碼規範 + +### 第 9 條：檔案上傳 +- 僅允許上傳：`.xlsx`, `.xls`, `.csv` +- 檔案大小限制：10 MB +- 使用 `secure_filename_unicode()` 清理檔名（支援中文） +- 檢查路徑遍歷攻擊（`..`, `/`, `\`） + +### 第 10 條：SQL 安全 +- 表名驗證：僅允許英文字母、數字、底線 +- 欄位名驗證：允許中文、英文字母、數字、底線 +- 時間戳驗證：嚴格遵守 `YYYY-MM-DD HH:MM:SS` 格式 +- 使用 `safe_read_sql()` 進行安全的 SQL 查詢 + +### 第 11 條：路徑安全 +- 所有路徑拼接使用 `safe_join(base, *paths)` +- 檢查 Windows 反斜線、連續點、雙點模式 +- 驗證最終路徑在基礎目錄內 +- 偵測到攻擊時記錄安全日誌 + +### 第 12 條：日誌規範 +- 使用結構化日誌格式：`[模組] [級別] 訊息 | 詳細資訊` +- 安全事件使用 `[Security]` 標籤 +- 記錄所有失敗的驗證嘗試 +- 日誌級別： + - `ERROR`: 系統錯誤 + - `WARNING`: 安全警告、失敗的攻擊嘗試 + - `INFO`: 重要操作成功 + - `DEBUG`: 詳細除錯資訊 + +--- + +## 🕷️ 第四章：數據爬取規範 + +### 第 13 條：爬蟲程式碼穩定性原則 +- **爬蟲程式碼屬於核心業務邏輯，修改時必須格外謹慎** +- 任何修改必須經過完整測試，確認不影響現有爬取功能 +- 修改前必須備份現有可運作的版本 +- 修改後必須驗證所有爬蟲任務正常執行 + +### 第 14 條：爬蟲選擇器維護 +- **CSS 選擇器和 XPath 是脆弱的依賴** +- 修改選擇器前必須： + 1. 記錄修改原因（網站改版、元素變更等） + 2. 測試新選擇器是否正確抓取目標資料 + 3. 保留舊選擇器作為註解備份 + 4. 記錄網站結構變更日期 +- 建議使用多層次選擇器備援（主選擇器 + 備用選擇器） + +### 第 15 條：爬蟲錯誤處理 +- **所有爬蟲函數必須包含完整的錯誤處理** +- 必須處理的情況： + 1. 網路連線失敗 + 2. 頁面載入超時 + 3. 元素找不到（選擇器失效） + 4. 資料格式異常 + 5. 反爬蟲機制觸發 +- 錯誤發生時： + - 記錄詳細錯誤日誌（包含 URL、選擇器、錯誤訊息） + - 發送通知給管理員 + - 不中斷其他爬蟲任務 + - 保存最後成功的資料作為備援 + +### 第 16 條：爬蟲測試要求 +- **修改爬蟲程式碼後必須執行完整測試** +- 測試項目： + 1. 單一商品資料爬取 + 2. 列表頁面分頁爬取 + 3. 多執行緒/並發爬取 + 4. 錯誤處理機制 + 5. 資料儲存完整性 +- 測試環境應模擬生產環境（網路延遲、並發請求） +- 使用測試資料集驗證爬取結果準確性 + +### 第 17 條：爬蟲依賴管理 +- **爬蟲依賴的套件版本必須固定** +- `requirements.txt` 中爬蟲相關套件必須指定版本號： + - `selenium==4.x.x` （具體版本） + - `requests==2.x.x` + - `beautifulsoup4==4.x.x` +- 升級套件前必須： + 1. 在測試環境驗證相容性 + 2. 檢查 changelog 確認無破壞性變更 + 3. 執行完整爬蟲測試套件 + 4. 記錄升級原因和影響 + +### 第 18 條：網站結構變更應對 +- **定期檢查目標網站結構是否變更** +- 建立網站結構監控機制： + 1. 記錄關鍵元素的 HTML 結構 + 2. 定期比對結構變化 + 3. 發現變更時立即通知 + 4. 建立選擇器失效告警 +- 保存網站結構快照（HTML samples）供除錯使用 + +### 第 19 條：爬蟲效能與禮節 +- **遵守網站的 robots.txt 規範** +- 設定合理的請求間隔（建議 1-3 秒） +- 使用 User-Agent 識別身份 +- 避免在網站高峰時段進行大量爬取 +- 實作請求失敗的退避重試機制（Exponential Backoff） + +### 第 20 條：資料驗證與清洗 +- **爬取的資料必須經過驗證** +- 驗證項目： + 1. 價格範圍合理性（不可為 0 或異常大） + 2. 日期格式正確性 + 3. 必填欄位完整性 + 4. 資料型別正確性 +- 發現異常資料時： + - 記錄到錯誤日誌 + - 標記為「需人工審核」 + - 不自動儲存到資料庫 + - 發送通知給管理員 + +### 第 21 條：爬蟲版本控制 +- **爬蟲程式碼每次修改必須建立 Git commit** +- Commit 訊息格式： + - `[Crawler] [網站名稱] 修改描述` + - 例：`[Crawler] [MOMO] 修復商品價格選擇器失效問題` +- 重大修改應建立分支，測試通過後才合併 +- 保留至少最近 3 個可運作版本的備份 + +### 第 22 條：爬蟲文檔要求 +- **每個爬蟲模組必須包含詳細文檔** +- 必須記錄： + 1. 爬取目標（網站 URL、資料類型） + 2. 執行頻率（每小時/每日） + 3. 關鍵選擇器說明 + 4. 已知問題和限制 + 5. 最後修改日期和原因 + 6. 聯絡人/負責人 +- 文檔應隨程式碼更新 + +--- + +## 🧪 第五章：測試與品質保證 + +### 第 23 條：測試覆蓋 +- 所有安全功能必須有對應的測試 +- 測試必須包含正常情況和攻擊情境 +- 使用 `test_*.py` 命名測試檔案 +- 執行 `./run_security_tests.sh` 必須全部通過 + +### 第 24 條：安全測試項目 +必須測試以下項目： +1. 環境變數與憑證管理 +2. SQL 注入防護 +3. 路徑遍歷防護 +4. 檔案上傳驗證 +5. CSRF 防護 +6. 登入驗證強化 +7. Flask 安全配置 + +### 第 25 條：爬蟲測試項目 +必須測試以下項目： +1. 選擇器有效性測試 +2. 資料完整性測試 +3. 錯誤處理測試 +4. 並發爬取測試 +5. 效能壓力測試 + +### 第 26 條：程式碼審查 +- 所有涉及安全的程式碼變更必須經過審查 +- 所有涉及爬蟲的程式碼變更必須經過審查 +- 檢查是否符合本憲法規範 +- 驗證是否通過完整測試 +- 確認日誌和錯誤處理完整 + +--- + +## 📦 第六章：部署與維運 + +### 第 27 條：環境管理規範 + +#### 27.1 環境分層 +本系統採用三層環境架構： + +1. **開發環境 (Development)** + - 位置：`/Users/ogt/momo_pro_system` (macOS Local) + - 用途：程式碼開發、快速測試、UI/UX 調整 + - 運行方式：直接執行 `python app.py` + - 特性：即時修改、快速迭代 + +2. **測試環境 (Testing)** + - 位置：同開發環境 + - 用途：功能測試、安全測試、回歸測試 + - 運行方式：執行測試腳本 + +3. **正式環境 (Production)** + - 位置：`/home/ogt/momo_pro_system` (GCP VM) + - 用途：生產服務、24/7 運行 + - 運行方式：systemd service + - 網址：`https://momo.wooo.work` + +#### 27.2 環境同步原則 + +**嚴格禁止**： +- ❌ 直接在正式環境修改程式碼 +- ❌ 跳過測試直接部署到正式環境 +- ❌ 混用不同環境的資料庫 +- ❌ 將 `.env` 檔案上傳到 Git + +**必須遵守**： +- ✅ 所有修改必須在開發環境完成 +- ✅ 完整測試通過後才能部署 +- ✅ 部署前必須備份正式環境 +- ✅ 部署後必須驗證功能正常 +- ✅ 監控 24 小時確保穩定 + +#### 27.3 標準部署流程 + +參照 `DEPLOYMENT_WORKFLOW.md` 文檔，嚴格遵守以下流程： + +``` +開發 → 測試 → 備份 → 部署 → 驗證 → 監控 +``` + +**階段性檢查**： +1. **開發階段**：程式碼符合規範、Git commit 完成 +2. **測試階段**：功能測試、安全測試、爬蟲測試通過 +3. **部署前**：備份正式環境、確認修改檔案清單 +4. **部署中**：使用標準部署腳本或手動部署 +5. **部署後**：服務狀態正常、功能驗證通過 +6. **監控期**：持續監控 24 小時 + +#### 27.4 部署方法選擇 + +**方法 A：完整部署**（推薦用於大改動） +```bash +cd /Users/ogt/momo_pro_system +./deploy_scripts/deploy_to_gcp.sh +``` +適用於： +- Python 程式碼修改 +- 依賴套件更新 +- 配置檔案變更 +- 資料庫結構變更 + +**方法 B：快速更新**（用於小改動） +```bash +gcloud compute scp --zone=asia-east1-a 修改的檔案 momo-server:~/momo_pro_system/ +``` +適用於： +- HTML/CSS/JS 檔案修改 +- 模板檔案更新 +- 靜態資源更新 + +**重要**： +- HTML/CSS/JS 修改：不需重啟服務（Flask 自動重載模板） +- Python 檔案修改：必須重啟服務 +- 配置檔案修改：必須重啟服務 + +### 第 28 條：變更前強制備份原則 ⚠️ + +**重要性：最高優先級** + +**核心原則**： +- **所有涉及嚴重影響的變更、修改操作，變更前必須先進行完整備份** +- **備份完成並確認無誤後，才可進行變更** +- 違反此原則的變更操作視為嚴重違規 + +**適用範圍**： +以下操作在執行前必須完整備份： + +1. **資料庫相關** + - 資料庫結構變更（ALTER TABLE, DROP, CREATE） + - 大量資料修改或刪除（UPDATE, DELETE 影響 >100 筆） + - 資料庫升級或遷移 + - 索引重建或優化 + +2. **系統配置** + - 系統配置檔案修改（config.py, .env） + - Nginx/Apache 配置變更 + - Systemd service 配置修改 + - 排程任務（crontab, scheduler）變更 + +3. **核心程式碼** + - 爬蟲核心邏輯修改 + - 資料庫連線和 ORM 修改 + - 認證和安全模組修改 + - API 端點的破壞性變更 + +4. **部署操作** + - 生產環境程式碼更新 + - Python 依賴套件升級 + - 系統套件升級（Python, Node.js 等） + - 伺服器遷移或重啟 + +5. **資料處理** + - Excel 匯入覆蓋現有資料 + - 批次資料清理或轉換 + - 歷史資料歸檔或刪除 + +**備份要求**： + +**必須備份的內容**： +- 完整資料庫檔案（momo.db 或 PostgreSQL dump） +- 所有程式碼檔案（Git commit + 檔案副本） +- 配置檔案（config.py, .env, nginx.conf 等） +- 重要的資料檔案（Excel, CSV 等） + +**備份驗證**： +- 檢查備份檔案完整性（檔案大小、MD5 校驗） +- 確認備份可讀取（嘗試開啟資料庫） +- 記錄備份時間和檔案位置 +- 確保備份檔案有足夠的磁碟空間 + +**備份命名規範**： +``` +資料庫：momo_backup_YYYYMMDD_HHMMSS.db +程式碼：momo_code_backup_YYYYMMDD_HHMMSS.tar.gz +配置：config_backup_YYYYMMDD_HHMMSS.tar.gz +``` + +**復原計畫**： +- 每次重大變更必須準備復原步驟文件 +- 測試復原流程的可行性 +- 記錄復原所需時間 +- 確保有回滾機制 + +**違規處理**： +- 未備份就執行重大變更：視為一級違規 +- 備份不完整或無法復原：視為二級違規 +- 必須立即停止變更，進行損害評估 +- 記錄事件並更新操作規範 + +**例外情況**： +僅以下情況可豁免備份要求： +- 純前端 HTML/CSS/JS 修改（不影響資料） +- 日誌檔案查看（唯讀操作） +- 系統監控和狀態查詢 +- 測試環境的實驗性變更 + +### 第 29 條：環境配置 +- 開發環境使用 `.env` +- 生產環境使用環境變數注入 +- 不同環境使用不同的 `SECRET_KEY` +- 定期輪換敏感憑證 + +### 第 30 條：備份策略 +- 資料庫每日自動備份 +- 備份檔案加密保存 +- 保留最近 7 天備份 +- 使用 `safe_join()` 處理備份路徑 + +### 第 31 條：更新流程 +1. **評估變更影響**（是否需要備份，參照第 28 條） +2. **完整備份**（若屬於重大變更，必須先備份） +3. 更新程式碼 +4. 執行完整測試套件（安全測試 + 爬蟲測試） +5. 檢查安全日誌 +6. 重啟服務 +7. 驗證功能正常（包含爬蟲任務） +8. 監控 24 小時確保穩定 +9. 確認備份可刪除或歸檔 + +--- + +## 🚨 第七章：事件處理 + +### 第 32 條：安全事件 +發現安全漏洞時： +1. 立即記錄詳細資訊 +2. 評估風險等級（Critical/High/Medium/Low） +3. 優先處理 Critical 和 High 級別 +4. 修復後執行完整測試 +5. 更新 `SECURITY_FIX_SUMMARY.md` + +### 第 33 條：爬蟲異常事件 +發現爬蟲異常時： +1. 記錄詳細錯誤資訊（URL、選擇器、錯誤訊息） +2. 檢查是否為網站結構變更 +3. 若為選擇器失效，立即修復並測試 +4. 發送通知給管理員 +5. 記錄在爬蟲維護日誌中 + +### 第 34 條：錯誤處理 +- 所有錯誤必須妥善處理，不得暴露敏感資訊 +- 使用者看到的錯誤訊息應簡潔明確 +- 詳細錯誤資訊記錄在日誌中 +- 開發環境可顯示詳細錯誤，生產環境僅顯示通用訊息 + +--- + +## 🔧 第八章：開發工具與依賴 + +### 第 35 條：Python 依賴 +核心依賴套件（見 `requirements.txt`）： +- Flask (Web 框架) +- Flask-WTF (CSRF 防護) +- SQLAlchemy (ORM) +- pandas (資料處理) +- selenium (網頁自動化) +- werkzeug (安全工具) + +### 第 36 條：版本控制 +- 使用 Git 進行版本控制 +- Commit 訊息使用繁體中文 +- Commit 格式：`[模組] 簡短描述` +- 例：`[Security] 修復路徑遍歷漏洞` +- 例：`[Crawler] [MOMO] 更新商品價格選擇器` + +### 第 37 條：開發環境 +- Python 3.8+ +- 使用虛擬環境 (venv) +- IDE 建議：VSCode, PyCharm +- 測試環境與生產環境分離 +- 爬蟲測試使用獨立環境 + +--- + +## 📊 第九章：監控與維護 + +### 第 38 條：系統監控 +- 定期檢查安全日誌 +- 監控登入失敗次數 +- 追蹤異常 API 請求 +- 定期執行安全測試 + +### 第 39 條：爬蟲監控 +- 監控爬蟲執行成功率 +- 追蹤選擇器失效次數 +- 檢查資料品質（異常值、缺失值） +- 監控爬取耗時變化 +- 定期檢查目標網站結構 + +### 第 40 條：效能監控 +- 資料庫查詢效能 +- API 回應時間 +- 記憶體使用量 +- 磁碟空間 +- 爬蟲執行效率 + +--- + +## 📋 第十章：憲法修訂 + +### 第 41 條：修訂流程 +- 本憲法可隨專案需求修訂 +- 修訂需說明原因和影響範圍 +- 更新版本號和修訂日期 +- 記錄在文檔歷史中 + +### 第 42 條：解釋權 +- 本憲法條款如有疑義，以最新版本為準 +- 技術決策以穩定性和安全性優先 +- 爬蟲修改以不影響現有功能為原則 +- 使用者體驗和效能次之 + +--- + +## 📚 附錄：快速檢查清單 + +### ✅ 新功能開發檢查 +- [ ] 程式碼和註解使用繁體中文 +- [ ] 無硬編碼敏感資訊 +- [ ] 所有輸入經過驗證 +- [ ] POST 請求包含 CSRF token +- [ ] 路徑操作使用 `safe_join()` +- [ ] 檔案上傳經過驗證 +- [ ] 錯誤處理完整 +- [ ] 日誌記錄完整 +- [ ] 通過安全測試 +- [ ] 更新相關文檔 + +### ⚠️ 重大變更前備份檢查 +- [ ] 評估變更影響範圍（資料庫/配置/核心程式碼/部署） +- [ ] 確認符合第 28 條適用範圍 +- [ ] 完整備份資料庫檔案 +- [ ] 備份所有程式碼（Git commit + 檔案副本） +- [ ] 備份配置檔案 +- [ ] 驗證備份檔案完整性（檔案大小、可讀取） +- [ ] 記錄備份時間和位置 +- [ ] 準備復原計畫文件 +- [ ] 測試復原流程可行性 +- [ ] 確保有回滾機制 + +### 🔒 安全審查檢查 +- [ ] SQL 查詢使用參數化或白名單 +- [ ] 無明文密碼 +- [ ] Session 配置正確 +- [ ] CSRF 防護啟用 +- [ ] 路徑遍歷防護 +- [ ] 檔案上傳限制 +- [ ] 登入失敗鎖定 +- [ ] 敏感操作有日誌 + +### 🕷️ 爬蟲修改檢查 +- [ ] 備份現有可運作版本 +- [ ] 記錄修改原因和網站變更資訊 +- [ ] 保留舊選擇器作為註解 +- [ ] 測試新選擇器正確性 +- [ ] 執行單一商品爬取測試 +- [ ] 執行列表頁面爬取測試 +- [ ] 驗證資料完整性和格式 +- [ ] 檢查錯誤處理機制 +- [ ] 更新爬蟲文檔 +- [ ] 記錄在維護日誌中 +- [ ] 建立 Git commit +- [ ] 監控 24 小時確保穩定 + +--- + +## 🎯 結語 + +本憲法旨在確保 MOMO 監控系統的安全性、穩定性、可維護性和一致性。所有參與者應： + +1. **遵守規範**：嚴格遵守本憲法所有條款 +2. **持續改進**：隨著專案發展適時修訂 +3. **穩定優先**：爬蟲修改以不影響現有功能為原則 +4. **安全第一**：任何決策以安全為最高優先 +5. **謹慎測試**：修改後必須完整測試並監控 +6. **文檔完整**：保持文檔與程式碼同步更新 + +**核心原則：** +- **安全不是功能，而是基礎** +- **爬蟲是核心業務，修改需格外謹慎** +- **測試是品質的保證，不可省略** + +--- + +**版本歷史：** +- v1.3 (2026-01-14): 新增第六章第 28 條「變更前強制備份原則」⚠️，明確規定所有涉及嚴重影響的變更操作前必須完整備份，定義適用範圍、備份要求、驗證流程、復原計畫及違規處理機制 +- v1.2 (2026-01-13): 擴充第六章第 27 條「環境管理規範」，明確定義開發/測試/正式三層環境架構、環境同步原則、標準部署流程，並新增 `DEPLOYMENT_WORKFLOW.md` 完整部署文檔 +- v1.1 (2026-01-12): 新增第四章「數據爬取規範」（第 13-22 條），定義爬蟲程式碼穩定性、選擇器維護、錯誤處理、測試要求等 10 項規範 +- v1.0 (2026-01-12): 初版發布，定義核心規範 diff --git a/docker/nginx/html/monitor-index-clean.html b/docker/nginx/html/monitor-index-clean.html index baa5fd3..0c91333 100644 --- a/docker/nginx/html/monitor-index-clean.html +++ b/docker/nginx/html/monitor-index-clean.html @@ -344,7 +344,7 @@
- 請參考 CLAUDE.md 取得登入資訊 + 請參考 docs/memory/credentials_passbook.md 取得登入資訊
diff --git a/docs/PROJECT_STRUCTURE.md b/docs/PROJECT_STRUCTURE.md index 096dbcb..ecefa57 100644 --- a/docs/PROJECT_STRUCTURE.md +++ b/docs/PROJECT_STRUCTURE.md @@ -177,7 +177,8 @@ momo-pro-system/ │ └── .env.example # 環境變數範例 │ └── 📄 文件 - ├── CLAUDE.md # AI 助手專案記憶 + ├── AGENTS.md # Codex 專案入口與工作規則 + ├── CLAUDE.md # 舊工作流相容轉址頁 ├── PROJECT_CONSTITUTION.md # 專案憲法 ├── DEPLOY_README.md # 部署說明 └── SECURITY_FIX_SUMMARY.md # 安全修復紀錄 diff --git a/docs/V10.0-OPTIMIZATION-PLAN.md b/docs/V10.0-OPTIMIZATION-PLAN.md index 7aed70f..b787d3c 100644 --- a/docs/V10.0-OPTIMIZATION-PLAN.md +++ b/docs/V10.0-OPTIMIZATION-PLAN.md @@ -464,8 +464,8 @@ docs/ ### 6.1 相關文檔 -- [CLAUDE.md](../CLAUDE.md) - 專案記憶 -- [PROJECT_CONSTITUTION.md](PROJECT_CONSTITUTION.md) - 專案憲法 +- [AGENTS.md](../AGENTS.md) - Codex 專案入口 +- [CONSTITUTION.md](../CONSTITUTION.md) - 專案憲法 - [DEPLOYMENT_WORKFLOW.md](DEPLOYMENT_WORKFLOW.md) - 部署流程 ### 6.2 變更記錄 diff --git a/docs/adr/ADR-008-actual-runtime-on-188.md b/docs/adr/ADR-008-actual-runtime-on-188.md index d2622d8..ca535cc 100644 --- a/docs/adr/ADR-008-actual-runtime-on-188.md +++ b/docs/adr/ADR-008-actual-runtime-on-188.md @@ -76,8 +76,8 @@ - `CLAUDE.md` — 所有 K3s/kubectl/PVC 指令改寫為 Docker Compose - `CLAUDE.md` — 專案路徑 `momo_pro_system` → `momo-pro`,主機 110 → 188 - `CLAUDE.md` — 承認 Harbor / Sentry / SigNoz / Gitea 在 110 仍運行 -- `memory/reference_env_map.md` — 明確劃分 110 / 188 角色 -- `memory/MEMORY.md` — 索引指向本 ADR +- `docs/memory/credentials_passbook.md` — 明確劃分 110 / 188 角色 +- `docs/memory/README.md` — 索引指向本 ADR ### 須延後處理(記入 tech debt) - 110 上 VM Nginx `mo.wooo.work → 127.0.0.1:5001` 的**實際轉發機制未證實**(110 無明顯 5001 listener,188 的 5001 是 docker-registry,兩者不相通)。需要統帥於下次進入 110 時跑 `sudo ss -tlnp | grep :5001` 或 `sudo fuser 5001/tcp` 確認。 diff --git a/docs/adr/ADR-011-cross-project-resource-isolation.md b/docs/adr/ADR-011-cross-project-resource-isolation.md index 1769f8d..ab23521 100644 --- a/docs/adr/ADR-011-cross-project-resource-isolation.md +++ b/docs/adr/ADR-011-cross-project-resource-isolation.md @@ -41,7 +41,7 @@ - **禁用** `docker compose down` / `--remove-orphans`（會殃及 orphan label 的 momo-db） - **首選** `docker compose up -d --no-deps --force-recreate ` 精準重建單一容器 - **救急** `docker network connect momo-pro_default ` 處理網路分裂 -- **容器操作前三句診斷**（見 `memory/reference_docker_topology.md`）必跑 +- **容器操作前三句診斷**（見 `AGENTS.md` 常用指令與本 ADR References）必跑 ### ③ docker-compose.yml 修正（本 ADR 同步提交） @@ -86,7 +86,7 @@ rebuild 模式在 `docker compose up -d` 之後增加健康檢查三容器全綠 - 共用 bot 的長期策略需另立專題：拆分成 `momo-pro-bot` / `awoooi-bot` / `openclaw-bot` 三個獨立 bot ## References -- `memory/reference_188_multi_project.md` — 188 上專案清單與歸屬 -- `memory/reference_docker_topology.md` — 四容器實況與診斷指令 -- `memory/feedback_shared_telegram_bot.md` — 共用 bot 踩坑 -- `memory/project_telegram_restore_20260419.md` — 本次斷訊修復記錄 +- `AGENTS.md` — Codex 入口、核心容器與診斷指令 +- `docs/memory/credentials_passbook.md` — 主機、服務與埠位對照 +- `docs/memory/history_logs.md` — 共用 bot、部署與容器事件歷史 +- `docs/memory/project_phase3f_cleanup_roadmap.md` — 3f 收尾與 ADR-011 紅線 diff --git a/docs/adr/ADR-012-agent-action-ladder.md b/docs/adr/ADR-012-agent-action-ladder.md index 3f49538..90afa9a 100644 --- a/docs/adr/ADR-012-agent-action-ladder.md +++ b/docs/adr/ADR-012-agent-action-ladder.md @@ -138,5 +138,5 @@ L1 Hermes 掛 → L0 模板直出 + 🟡 「AI 分析暫不可用」 - `services/event_router.py` — 分流入口（Phase 1） - `services/agent_actions.py` — 安全 action 白名單（Phase 1） - `services/telegram_templates.py::triaged_alert()` — L1/L2 訊息格式（Phase 1） -- `memory/feedback_agent_action_ladder.md` — 操作規範 -- `memory/reference_telegram_endpoints_map.md` — 21 個發送點盤點 +- `docs/guides/codex_agent_roles.md` — Codex 化角色矩陣與派工規則 +- `docs/memory/history_logs.md` — Agent 事件與 Telegram 相關歷史脈絡 diff --git a/docs/adr/ADR-017-modularization-cleanup-roadmap.md b/docs/adr/ADR-017-modularization-cleanup-roadmap.md index 3f469ce..035d98d 100644 --- a/docs/adr/ADR-017-modularization-cleanup-roadmap.md +++ b/docs/adr/ADR-017-modularization-cleanup-roadmap.md @@ -2,13 +2,13 @@ - **狀態**: Accepted - **日期**: 2026-04-29 -- **觸發**: 12-Agent 全景盤點（debugger / refactor-specialist / critic / db-expert / Explore） +- **觸發**: 12 Agent 全景盤點（debugger / refactor-specialist / critic / db-expert / explorer） - **相關 ADR**: ADR-008（188 拓撲）、ADR-011（資源隔離）、ADR-016（cache fingerprint） -- **相關 Memory**: feedback_flask_blueprint_shadow、project_phase3e_refactor_progress、project_phase3f_cleanup_roadmap、feedback_db_metadata_import +- **相關 Memory**: `docs/memory/project_phase3f_cleanup_roadmap.md`、`docs/memory/feedback_db_metadata_import.md`、`docs/memory/history_logs.md` ## 背景 -Phase 3e（4/28-29）完成 app.py 7,386→6,590 行（-10.8%），但**僅完成「搬檔」，未完成「拆乾淨」**。12-Agent 盤點揭露 6 個面向的殘留問題，且發現新的 critical 風險（DB metadata import 漏洞、孤兒表）。 +Phase 3e（4/28-29）完成 app.py 7,386→6,590 行（-10.8%），但**僅完成「搬檔」，未完成「拆乾淨」**。12 Agent 盤點揭露 6 個面向的殘留問題，且發現新的 critical 風險（DB metadata import 漏洞、孤兒表）。 ## 完成度真相（2026-04-29 盤點基線） diff --git a/docs/adr/README.md b/docs/adr/README.md index 066d60d..9a73f71 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -2,7 +2,7 @@ > 本目錄記錄 **EwoooC**（原 MOMO Pro System）的所有重大架構決策。 > 專案範圍：`momo-pro-system` 目錄（不含 AWOOOI / WOOO AIOps SaaS Platform） -> 遵循 Claude Code 官方規範：CLAUDE.md（憲法）+ ADR（決策）+ Memory（協作）+ Skills（流程） +> 遵循本專案的 Codex 工作規則：`AGENTS.md`（入口）+ `CONSTITUTION.md`（紅線）+ ADR（決策）+ Memory（輕量索引） ## 編號規則 @@ -44,4 +44,4 @@ 1. **任何重大架構決策**（影響三條產品線之一、改動資料結構、引入新依賴）必須建 ADR 2. **每份 ADR 包含**：Context（背景）→ Decision（決策）→ Alternatives Considered（替代方案）→ Consequences（後果） -3. **建立後同步更新**：本 README 索引、相關 SOT 文件、`MEMORY.md` +3. **建立後同步更新**：本 README 索引、相關 SOT 文件、`docs/memory/README.md`（若有新的長期記憶入口） diff --git a/docs/guides/codex_agent_roles.md b/docs/guides/codex_agent_roles.md new file mode 100644 index 0000000..533af7b --- /dev/null +++ b/docs/guides/codex_agent_roles.md @@ -0,0 +1,99 @@ +# Codex Agent Roles + +> 目的：把本專案歷史上的 12 位 Agent 工作執掌，改寫成符合 Codex 官方建議的角色矩陣。 +> 原則：角色是「思考與分工模板」，不是每次 session 都必須全文載入的正式入口。 + +## 使用原則 + +- 先由主 agent 直接處理任務。 +- 只有在任務明確分流、風險高、或需要獨立驗證時，才套用角色分工思維。 +- 角色說明用於規劃與 reviewer 心智模型，不代表一定要建立 12 個常駐子代理。 +- 若任務可以由一位 Codex 在單一上下文完成，優先不要切分。 + +## 12 角色矩陣 + +| 角色 | 核心職掌 | 適用情境 | 不該濫用 | +|---|---|---|---| +| `planner` | 先切問題、定順序、收斂風險與交付邊界 | 多階段任務、重構、跨檔案修復、部署前盤點 | 小修小補也先開長計畫 | +| `critic` | 專注找 regression、風險、遺漏測試、隱性副作用 | 大改後 review、上線前、關鍵路由與資料流改動 | 把 critic 當實作者，或在還沒成形前反覆 review | +| `debugger` | 追根因、讀 log、縮小故障範圍、建立最小重現 | 線上異常、排程失敗、Telegram 斷訊、快取錯亂 | 還沒看 log 就直接改碼 | +| `fullstack-engineer` | 在既有架構下完成端到端功能或修復 | 一般功能開發、API + template + service 串接 | 用來做純探索、純審查或超大型拆遷規劃 | +| `refactor-specialist` | 拆大檔、去重、解耦、模組化收尾 | `app.py` 拆分、Blueprint 清理、模板重整 | 在需求不明或測試不足時先大搬家 | +| `migration-engineer` | 處理 schema、資料轉換、路由遷移、兼容期策略 | migration、欄位對齊、callback prefix、資料搬遷 | 跳過回滾與相容性設計直接硬切 | +| `onboarder` | 幫新 session 或新協作者快速讀懂脈絡 | 新人接手、長期專案重啟、需要入口整理 | 把 onboarding 文件當正式治理真相來源 | +| `tool-expert` | 決定用哪個工具最穩、最省成本、最可驗證 | shell、hook、CI/CD、MCP、部署流程選型 | 用工具炫技取代簡單做法 | +| `vuln-verifier` | 站在攻擊者角度驗證防線是否真能擋住 | hook、防注入、secret 掃描、權限邊界 | 只有猜測沒有驗證就宣稱安全 | +| `web-researcher` | 補官方文件、規格、外部事實、版本現況 | API/SDK 變更、平台規則、供應商文件核對 | 拿次級來源取代官方來源，或把外部研究帶入所有 session | +| `db-expert` | 聚焦資料模型、查詢、索引、交易與 ORM 對齊 | 漏表、慢查詢、schema drift、pgvector、create_all 問題 | 把所有 bug 都歸咎資料庫 | +| `explorer` | 快速查碼、定位檔案、回答具體 codebase 問題 | 「這段在哪裡」、「誰在呼叫它」、「有哪些 duplicate route」 | 與主實作重複探索同一題，浪費 context | + +## Codex 化映射 + +| 歷史角色 | Codex 中的建議用法 | +|---|---| +| `planner` | 先做本地高階規劃；必要時只輸出簡短 plan | +| `critic` | 以 code review mindset 檢查 bug、風險、缺測 | +| `debugger` | 先看 log、traceback、runtime 訊號，再改碼 | +| `fullstack-engineer` | 預設主實作者角色 | +| `refactor-specialist` | 僅在結構性清理值得付出風險時啟用 | +| `migration-engineer` | 與 DB / API / callback 相容性變更綁定使用 | +| `onboarder` | 產出入口索引、接手說明、交接文檔 | +| `tool-expert` | 幫忙選 shell / script / CI / browser / MCP 的最小可行解 | +| `vuln-verifier` | 對安全修補做 adversarial 驗證 | +| `web-researcher` | 只在需要最新外部事實時查官方來源 | +| `db-expert` | 聚焦 schema / ORM / SQL / index / transaction | +| `explorer` | 對應 Codex 的 codebase-specific explorer 心智模型 | + +## 建議派工順序 + +### 1. 一般功能 + +1. `planner` +2. `fullstack-engineer` +3. `critic` + +### 2. 線上故障 + +1. `debugger` +2. `fullstack-engineer` +3. `critic` +4. `vuln-verifier`（若涉及安全） + +### 3. 大型重構 + +1. `planner` +2. `explorer` +3. `refactor-specialist` +4. `critic` + +### 4. DB / migration 類 + +1. `planner` +2. `db-expert` +3. `migration-engineer` +4. `critic` + +### 5. 外部規格變動 + +1. `web-researcher` +2. `tool-expert` +3. `fullstack-engineer` +4. `critic` + +## 最小入口版 + +若要把這份文件壓縮成最省 token 的心法，只要記住： + +- 先 `planner` +- 出問題先 `debugger` +- 做功能用 `fullstack-engineer` +- 拆結構找 `refactor-specialist` +- 動 DB 找 `db-expert` 或 `migration-engineer` +- 上線前一定要有 `critic` +- 涉及安全加 `vuln-verifier` +- 需要最新外部事實才叫 `web-researcher` + +## 來源註記 + +- 本文件整理自本 repo 歷史文件中可確認的角色名稱與職掌脈絡。 +- 若未來還原到更多舊 agent 定義，可再細化，但正式入口仍應維持精簡。 diff --git a/docs/guides/ty-ai-standards-onboarding.md b/docs/guides/ty-ai-standards-onboarding.md index 608824c..6bbff0b 100644 --- a/docs/guides/ty-ai-standards-onboarding.md +++ b/docs/guides/ty-ai-standards-onboarding.md @@ -1,5 +1,8 @@ # ty-ai-standards 新專案接入指令書 +> Legacy notice: 本文件屬於 Claude 時代的 onboarding 指南，保留供歷史查閱，不再是本專案正式規範。 +> 目前請以根目錄 `AGENTS.md`、`CONSTITUTION.md`、`docs/adr/README.md`、`docs/memory/README.md` 為準。 + > 本文件由統帥產生，可直接轉發給負責新專案的 Claude Code session。 > 執行前無需額外背景知識，照順序執行即可。 diff --git a/docs/memory/README.md b/docs/memory/README.md new file mode 100644 index 0000000..255b7b4 --- /dev/null +++ b/docs/memory/README.md @@ -0,0 +1,30 @@ +# Memory Index + +> 本目錄提供給 Codex 的是「按需命中索引」，不是每次 session 全讀清單。 + +## 使用規則 + +- 先讀這份索引，再打開必要的單篇 memory。 +- 只在任務與主題直接相關時才讀全文。 +- 若資訊已升格為架構決策，應以 ADR 為準，不重複維護兩份真相。 + +## 索引 + +| 檔案 | 用途 | 何時閱讀 | +|---|---|---| +| `history_logs.md` | 重大里程碑與歷史脈絡 | 要理解演進背景、排查「為何變成這樣」時 | +| `credentials_passbook.md` | 伺服器、帳密、埠位對照 | 需要維運、部署、憑證核對時 | +| `feedback_db_metadata_import.md` | SQLAlchemy metadata / `create_all()` 漏表鐵律 | 新增 model、修 schema、排查 fresh env 漏表時 | +| `project_phase3f_cleanup_roadmap.md` | ADR-017 執行矩陣與階段紅線 | 正在做 3f 模組化收尾時 | + +## 關聯 Guide + +- `docs/guides/codex_agent_roles.md` + 用途：12 位歷史 Agent 的 Codex 化角色矩陣。 + 何時閱讀：要做多角色分工、任務派工、review 流程設計時。 + +## 新增規則 + +- 單篇只處理一個主題。 +- 優先記錄高重用知識，不保存一次性對話。 +- 若內容超過一頁仍持續成長，先評估是否應改成 guide 或 ADR。