ewoooc/CLAUDE.md

EwoooC (MOMO Pro System) — 核心索引

版本: V11.0 | 目標: AI 驅動 MOMO 商品監控、業績分析、策略自動化與 AIOps 自愈

治理

• 憲法: CONSTITUTION.md — 所有開發必須遵守
• 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）

核心容器（三動一 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

常用指令

# 本地開發
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
DevOps 手冊	docs/guides/devops_handbook.md
Google Drive	docs/guides/google_drive_setup.md
歷史日誌	docs/memory/history_logs.md
憑證對照表	docs/memory/credentials_passbook.md
AIOps 存檔	docs/external/aiops_saas.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 回滾防線進行安全發布） | | PPT 簡報系統 V2（ADR-014） | 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象限表+區域分佈

---

AI 開發鐵律（三條紅線）

這三條紅線適用於所有模式、所有 Agent，不可豁免。

紅線一：狙擊手模式（事實驅動）

禁止在未獲授權的情況下，使用 ls, grep, cat 等指令在專案內盲搜。所有判斷必須基於親自讀取的程式碼，附上路徑與行號。「我猜」、「應該是」、「可能」是違規。

紅線二：精準打擊（閉包紀律）

統帥給定任務時，若已明確指出目標檔案路徑，直接修改該檔案，嚴禁漫無目的掃描關聯模組。每個任務有明確的 Definition of Done，不允許「差不多完成」。

紅線三：上下文克制（徹底性）

不主動讀取超過 300 行的檔案，除非統帥明確要求。清單逐項確認，即使沒問題的項目也要標記「已查，無異狀」，不可跳過。

---

工作流程模式（P7 / P9 / P10）

根據任務範圍切換模式。這不是角色扮演，是執行紀律。

任務範圍                              模式
─────────────────────────────────────────────────────
單一功能，範圍明確                    P7 執行模式（狙擊手）
跨模組，3+ 個檔案                     P9 拆解 → P7 × N 執行
跨服務架構，5+ 個 Agent / Sprint      P10 戰略 → P9 × N 拆解

P7 執行模式（預設）

1. 讀取現實 — 先用 Read / Grep / Glob 讀相關檔案，禁止憑記憶設計
2. 設計方案 — 寫下要改什麼、為什麼、捨棄了哪些替代方案
3. 影響分析 — 列出所有 caller、test、下游模組。漏一個是缺陷
4. 實作 — 執行方案，禁止中途改設計
5. 三問自審（完成後必做）：
   • 方案正確嗎？有沒有誤解需求？
   • 影響分析完整嗎？有沒有漏掉的 caller？
   • 有沒有 regression 風險？

交付格式 [P7-COMPLETION]（每個任務完成時必用）：

[P7-COMPLETION]
任務: <原始需求>
方案: <選擇的做法 + 原因>
變更: <檔案清單 + 每個檔案的重點>
影響: <受影響的模組/呼叫者 + 為何安全>
自審:
  - 方案正確: <答案>
  - 影響完整: <答案>
  - Regression 風險: <答案>
剩餘風險: <誠實列出未覆蓋的部分，或「無」>

P9 管理模式（禁止自己寫程式碼）

觸發條件：任務涉及 3+ 個檔案或 2+ 個模組。

• 禁止自己寫程式碼，輸出是任務拆解 + Task Prompt
• 每個 Task Prompt 必含六元素：目標、範圍（精確路徑）、輸入、輸出、驗收條件、禁止碰觸的邊界
• 每個子任務完成後必過 critic 審查才能繼續

P10 戰略模式（極少用）

觸發條件：跨 3 個 Sprint 以上的重構、定義新的 Agent 協作拓撲。 輸出是戰略文件（非程式碼、非 Task Prompt），含目標、成功指標、風險、時程。

---

12 人專家團隊（Subagents）

使用 Agent 工具呼叫，subagent_type 填入下表 Agent ID。

Agent	ID	何時使用
程式碼審查官	critic	commit 前、部署前、PR 合併前、懷疑有 Bug
弱點驗證師	vuln-verifier	critic 找到弱點後，寫 PoC 確認是否可重現
除錯工程師	debugger	任何 Bug、容器掛掉、排程異常、Telegram 通知中斷
資料庫專家	db-expert	schema 設計、migration 安全審查、pgvector 索引、SQL 優化
任務拆解師	planner	任務涉及 3+ 個檔案（自動切 P9 模式）
全端工程師	fullstack-engineer	功能實作（P7 流程：設計→影響分析→實作→自審）
重構專家	refactor-specialist	10+ 個檔案的大規模重構、模組抽取、檔案搬移
遷移工程師	migration-engineer	框架/套件主版本升級、breaking change 處理
探索員	onboarder	第一次接觸某模組、快速建立程式碼心智模型
工具專家	tool-expert	MCP 工具選擇、複雜工具鏈除錯、Claude Code Hook 設計
網路研究員	web-researcher	官方文件查詢、API spec、錯誤碼、版本差異確認

Agent 定義檔位於 .claude/agents/

---

委派鐵律

必派（無條件執行）

情境	必派 Agent
完成程式碼，即將 commit / 部署	critic 審查 diff
收到 Bug 回報、容器掛掉、排程異常	debugger（第一反應，禁止猜測）
任務涉及 3+ 個檔案或 2+ 個模組	planner 先拆解（切 P9 模式）
schema 變更、migration 檔案	db-expert 審查
SSH 到 188 執行前，操作涉及 momo-db	critic 確認指令安全性
懷疑有安全漏洞	critic → vuln-verifier
大規模重構（10+ 檔案、模組重命名）	refactor-specialist
第一次接觸新模組	onboarder 建立心智模型
需要查官方文件、API 行為確認	web-researcher（禁止依賴記憶推測）

禁派（自己處理）

• 單一檔案 1-2 行修改
• 純問答、概念解釋、技術 Q&A
• 統帥明確說「你自己做」
• 只是讀單一 log 或 grep 單一關鍵字

平行派遣

獨立任務應同時派出（單一訊息多個 Agent tool call），例如：

# 前後端同時審查（不必等一個完成再派另一個）
Agent(subagent_type="critic", prompt="審查 services/ 的 diff...")   # 同一訊息
Agent(subagent_type="critic", prompt="審查 web/templates/ 的 diff...") # 並行

---

高壓模式觸發條件（PUA Mode）

切換到「徹底、不退讓」工作狀態：

觸發條件	切換行為
同一任務失敗 2 次以上	停止重試舊方案，提出 3 個全新假設並逐一驗證
即將說「我無法解決」、「可能是環境問題」	禁止說。用 WebSearch 查官方文件，讀原始碼，逐一列舉可能原因
被抓到被動等待指示	自己找下一步，你是來解決問題的
統帥說「再努力一點」、「怎麼又失敗」	進入反思模式：寫下上一步為何失敗 + 這次必須改什麼

---

Loop 模式（長時自主迭代）

統帥說「不要停」、「我去睡了」時進入 Loop 模式：

• 禁止 AskUserQuestion，自己做決定
• 用 <loop-pause>需要的資訊</loop-pause> 暫停等待人工輸入
• 用 <loop-abort>原因</loop-abort> 終止迴圈
• 每次迭代 = 一個完整 P7 週期，完成一個再開始下一個
• 統帥回來時，彙整成單一報告

---

安全架構說明（bypassPermissions）

本專案採用 bypassPermissions: true + Hook 自動政策替代人工確認對話框。 安全防線由 .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 進入 commit
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	對話快照存檔