wooo/ewoooc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(governance): 建立 Codex 專案入口與記憶索引

Browse Source
This commit is contained in:
OoO
2026-04-29 22:11:23 +08:00
parent 4cbd775c1b
commit 880511032a
15 changed files with 935 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
AGENTS.md Normal file
View File

@@ -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 <service>\""
```
## 10. 正式規範結論
- Codex 在本專案的正式工作規則來源只有四個：`AGENTS.md`、`CONSTITUTION.md`、`docs/adr/README.md`、`docs/memory/README.md`。
- 其他文件預設都視為按需查閱資料，不是 session 開場必讀。

110
CLAUDE.md
View File

@@ -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 <service>\""
# ⚠️ 禁用 --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`）。
此檔僅作為舊文件、舊連結、舊工作流的相容轉址頁。

47
CONSTITUTION.md
View File

@@ -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 的決策混入本文件
- ❌ **禁止**：跨專案邊界做架構決策

600
PROJECT_CONSTITUTION.md Normal file
View File

@@ -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: `<input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>`
- 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): 初版發布，定義核心規範

2
docker/nginx/html/monitor-index-clean.html
View File

@@ -344,7 +344,7 @@
</a>
</div>
<div class="quick-links">
<span class="quick-link"><i class="fas fa-info-circle me-1"></i>請參考 CLAUDE.md 取得登入資訊</span>
<span class="quick-link"><i class="fas fa-info-circle me-1"></i>請參考 docs/memory/credentials_passbook.md 取得登入資訊</span>
</div>
</div>
</div>

3
docs/PROJECT_STRUCTURE.md
View File

@@ -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 # 安全修復紀錄

4
docs/V10.0-OPTIMIZATION-PLAN.md
View File

@@ -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 變更記錄

4
docs/adr/ADR-008-actual-runtime-on-188.md
View File

@@ -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` 確認。

10
docs/adr/ADR-011-cross-project-resource-isolation.md
View File

@@ -41,7 +41,7 @@
- **禁用** `docker compose down` / `--remove-orphans`（會殃及 orphan label 的 momo-db）
- **首選** `docker compose up -d --no-deps --force-recreate <service>` 精準重建單一容器
- **救急** `docker network connect momo-pro_default <container>` 處理網路分裂
- **容器操作前三句診斷**（見 `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 紅線

4
docs/adr/ADR-012-agent-action-ladder.md
View File

@@ -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 相關歷史脈絡

6
docs/adr/ADR-017-modularization-cleanup-roadmap.md
View File

@@ -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 盤點基線）

4
docs/adr/README.md
View File

@@ -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`（若有新的長期記憶入口）

99
docs/guides/codex_agent_roles.md Normal file
View File

@@ -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 定義，可再細化，但正式入口仍應維持精簡。

3
docs/guides/ty-ai-standards-onboarding.md
View File

@@ -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。
> 執行前無需額外背景知識，照順序執行即可。

30
docs/memory/README.md Normal file
View File

@@ -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。