diff --git a/.claude/hooks/secrets.local.json b/.claude/hooks/secrets.local.json new file mode 100644 index 0000000..ecd9552 --- /dev/null +++ b/.claude/hooks/secrets.local.json @@ -0,0 +1,7 @@ +[ + {"pattern": "\\d{8,12}:[A-Za-z0-9_-]{35}", "label": "Telegram Bot Token"}, + {"pattern": "TELEGRAM[_\\s]*(?:BOT[_\\s]*)?TOKEN\\s*=\\s*[\"']?[^\\s\"']{20,}", "label": "Telegram Token 環境變數"}, + {"pattern": "GEMINI_API_KEY\\s*=\\s*[\"']?[A-Za-z0-9_-]{20,}", "label": "Gemini API Key"}, + {"pattern": "glpat-[a-zA-Z0-9_-]{20}", "label": "Gitea/GitLab PAT"}, + {"pattern": "GITEA[_\\s]*TOKEN\\s*=\\s*[\"']?[^\\s\"']{20,}", "label": "Gitea Token 環境變數"} +] diff --git a/.claude/skills/telegram-bot-menu-restoration.py b/.claude/skills/telegram-bot-menu-restoration.py new file mode 100644 index 0000000..bd18e01 --- /dev/null +++ b/.claude/skills/telegram-bot-menu-restoration.py @@ -0,0 +1,189 @@ +#!/usr/bin/env python3 +""" +Telegram Bot 菜單恢復技能記憶 + +記錄 2026-04-20 的完整 Telegram Bot 菜單系統恢復工作 +包含完整的菜單架構、實作細節和最佳實踐 +""" + +import json +from datetime import datetime + +# === 菜單恢復工作記憶 === +MENU_RESTORATION_MEMORY = { + "work_date": "2026-04-20", + "issue": "用戶回報 Telegram Bot 菜單功能缺失,原本6項簡單功能無法滿足業務需求", + "root_cause": "telegram_bot_service.py 使用簡化版菜單,openclaw_bot_routes.py 包含完整7大類別系統", + "solution": "恢復完整的三層菜單架構系統", + + # === 完整菜單架構 === + "complete_menu_structure": { + "main_menu": { + "categories": 8, # 7大類別 + 使用說明 + "items": [ + "📊 業績查詢", "🏆 商品廠商", "🎯 目標管理", + "📈 智能分析", "📄 簡報報表", "🌐 市場情報", + "🔍 競品日報", "❓ 使用說明" + ] + }, + + "submenus": { + "sales": { + "title": "業績查詢", + "features": ["今日/昨日業績", "每週/每月/每季業績", "趨勢分析", "同期比較", "分類業績", "日期區間"], + "callback_prefix": "cmd:sales, cmd:trend, cmd:history, cmd:compare, cmd:category, await:date_range_sales" + }, + + "products": { + "title": "商品廠商", + "features": ["熱銷商品/廠商", "商品健康", "補貨預測", "分類鑽取", "指定日期"], + "callback_prefix": "cmd:top, cmd:vendor, cmd:health, cmd:restock, menu:category, await:date_top" + }, + + "goals": { + "title": "目標管理", + "features": ["達成率查看", "日/月/季/半年/年目標設定"], + "callback_prefix": "cmd:goal, await:goal_daily, await:goal_monthly, await:goal_quarterly, await:goal_half, await:goal_yearly" + }, + + "analysis": { + "title": "智能分析", + "features": ["策略矩陣", "業績趨勢", "商品健康", "促銷追蹤", "趨勢圖表", "同期比較"], + "callback_prefix": "cmd:strategy, menu:trend, cmd:health, cmd:category, await:promo_range, cmd:restock, cmd:chart, cmd:compare" + }, + + "reports": { + "title": "簡報報表", + "features": ["日報/週報/月報", "策略報告", "促銷效益", "競品比較", "成長趨勢", "廠商業績"], + "callback_prefix": "cmd:ppt:daily, cmd:ppt:weekly, cmd:ppt:monthly, cmd:ppt:strategy, await:promo_range, menu:competitor, cmd:ppt:growth, cmd:ppt:vendor" + }, + + "market": { + "title": "市場情報", + "features": ["電商新聞", "天氣", "Google熱搜", "Dcard口碑", "台銀匯率", "電商節慶", "YouTube爆紅商品", "AI學習狀態", "關鍵字比價", "圖片比價說明"], + "callback_prefix": "cmd:news, cmd:weather, cmd:trends, cmd:dcard, cmd:exchange, cmd:calendar, cmd:youtube, cmd:learn, await:search_compare, cmd:photo_search_help" + }, + + "competitor": { + "title": "競品日報", + "features": ["今日/昨日簡報", "週/月/季比較", "指定日期", "長週期比較"], + "callback_prefix": "cmd:ppt:competitor, await:date_competitor, menu:competitor_ppt" + }, + + "competitor_ppt": { + "title": "競品PPT長週期", + "features": ["半年比較", "年比較"], + "callback_prefix": "cmd:ppt:competitor half, cmd:ppt:competitor yearly", + "level": 3 # 第三層菜單 + }, + + "category": { + "title": "分類業績鑽取", + "features": ["15個完整商品分類"], + "categories": [ + "美妝保養", "3C家電", "服飾配件", "居家生活", "母嬰用品", + "生鮮食品", "圖書文具", "戶外運動", "餐券票券", "醫療保健", + "美體保健", "寵物用品", "箱包精品", "車類百貨", "情趣用品" + ], + "callback_prefix": "cmd:catdetail, cmd:category" + }, + + "trend": { + "title": "業績趨勢", + "features": ["近7日/1月/3月/半年/1年", "指定月份/年份/季度"], + "callback_prefix": "cmd:trend:7, cmd:trend:month, cmd:trend:quarter, cmd:trend:half, cmd:trend:year, await:date_trend_month, await:date_trend_year, await:date_trend_quarter" + } + } + }, + + # === 關鍵發現 === + "key_discoveries": { + "market_intelligence_expansion": "市場情報從原本4項擴展為10項完整功能", + "three_layer_architecture": "建立主菜單 → 子菜單 → 特定功能的三層架構", + "category_system": "完整的15個商品分類系統", + "ppt_hierarchy": "競品PPT的第二層和第三層分離設計" + }, + + # === 實作細節 === + "implementation_details": { + "files_modified": [ + "services/telegram_bot_service.py" + ], + "methods_added": [ + "_get_market_submenu", "_get_competitor_submenu", "_get_competitor_ppt_submenu", + "_get_category_submenu", "_get_trend_submenu", "_handle_main_menu_callback" + ], + "menu_layers": 3, + "total_menu_items": 60, # 總計約60個菜單選項 + "callback_system": "menu: 前綴 + cmd: 前綴 + await: 前綴" + }, + + # === 最佳實踐 === + "best_practices": { + "menu_hierarchy": "清晰的層次結構,避免過深的嵌套", + "naming_convention": "統一的 callback_data 命名規範", + "back_navigation": "每個子菜單都包含返回主選單按鈕", + "user_experience": "直觀的圖示和清晰的中文描述", + "maintainability": "模組化的子菜單方法,便於維護" + }, + + # === 驗證結果 === + "validation_results": { + "main_menu_items": 8, # 從6項增加到8項 + "submenu_systems": 10, # 10個完整子系統 + "market_functions": 10, # 市場情報從4項擴展到10項 + "category_count": 15, # 15個商品分類 + "architecture_layers": 3, # 三層菜單架構 + "backwards_compatibility": True # 保持向下相容 + } +} + +def get_menu_restoration_memory(): + """取得菜單恢復工作記憶""" + return MENU_RESTORATION_MEMORY + +def save_menu_restoration_memory(): + """保存菜單恢復工作記憶到文件""" + timestamp = datetime.now().isoformat() + + memory_log = { + "timestamp": timestamp, + "memory": MENU_RESTORATION_MEMORY, + "action": "telegram_bot_menu_restoration_2026_04_20" + } + + # 這裡可以加入保存到文件或資料庫的邏輯 + # 目前記憶已經在代碼中完整記錄 + + return memory_log + +def get_menu_architecture_summary(): + """取得菜單架構摘要""" + memory = get_menu_restoration_memory() + + summary = f""" +=== Telegram Bot 菜單恢復工作摘要 === +日期: {memory['work_date']} +問題: {memory['issue']} +解決方案: {memory['solution']} + +菜單架構: +- 主菜單: {memory['complete_menu_structure']['main_menu']['categories']} 項功能 +- 子菜單系統: {len(memory['complete_menu_structure']['submenus'])} 個 +- 架構層次: {memory['implementation_details']['menu_layers']} 層 +- 總菜單項目: 約 {memory['implementation_details']['total_menu_items']} 項 + +關鍵成果: +✅ 市場情報功能擴展: 4 → 10 項 +✅ 建立三層菜單架構 +✅ 完整15個商品分類系統 +✅ 向下相容性保持 +✅ 模組化實作便於維護 + +記憶檔案: {__file__} +ADR記錄: ADR-015-telegram-bot-menu-restoration.md +""" + return summary + +if __name__ == "__main__": + print(get_menu_architecture_summary()) diff --git a/CLAUDE.md b/CLAUDE.md index fa95a0f..add9813 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,7 @@ # EwoooC (MOMO Pro System) — 核心索引 -> **版本**: V11.0 | **目標**: AI 驅動 MOMO 商品監控、業績分析、策略自動化與 AIOps 自愈 +> **版本**: V12.0 | **目標**: AI 驅動 MOMO 商品監控、業績分析、策略自動化與 AIOps 自愈 +> **全域工作流程**(P7/P9/P10、三紅線、委派表、PUA/Loop)見 `~/.claude/CLAUDE.md` ## 治理 - **憲法**: [CONSTITUTION.md](CONSTITUTION.md) — 所有開發必須遵守 @@ -83,166 +84,20 @@ ssh wooo@192.168.0.110 "ssh ollama@192.168.0.188 \"\ --- -## AI 開發鐵律(三條紅線) +## momo 安全架構(bypassPermissions) -這三條紅線適用於所有模式、所有 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/](.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),例如: - -```python -# 前後端同時審查(不必等一個完成再派另一個) -Agent(subagent_type="critic", prompt="審查 services/ 的 diff...") # 同一訊息 -Agent(subagent_type="critic", prompt="審查 web/templates/ 的 diff...") # 並行 -``` - ---- - -## 高壓模式觸發條件(PUA Mode) - -切換到「徹底、不退讓」工作狀態: - -| 觸發條件 | 切換行為 | -|---------|---------| -| 同一任務失敗 2 次以上 | 停止重試舊方案,提出 3 個全新假設並逐一驗證 | -| 即將說「我無法解決」、「可能是環境問題」 | 禁止說。用 WebSearch 查官方文件,讀原始碼,逐一列舉可能原因 | -| 被抓到被動等待指示 | 自己找下一步,你是來解決問題的 | -| 統帥說「再努力一點」、「怎麼又失敗」 | 進入反思模式:寫下上一步為何失敗 + 這次必須改什麼 | - ---- - -## Loop 模式(長時自主迭代) - -統帥說「不要停」、「我去睡了」時進入 Loop 模式: -- 禁止 `AskUserQuestion`,自己做決定 -- 用 `需要的資訊` 暫停等待人工輸入 -- 用 `原因` 終止迴圈 -- 每次迭代 = 一個完整 P7 週期,完成一個再開始下一個 -- 統帥回來時,彙整成單一報告 - ---- - -## 安全架構說明(bypassPermissions) - -本專案採用 `bypassPermissions: true` + Hook 自動政策替代人工確認對話框。 -安全防線由 `.claude/hooks/` 的 Hook 自動執行,覆蓋範圍: +本專案採用 `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 進入 commit | +| `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`)。