In /root/projects/butler, find files related to todos, requirements, roadmaps, or feature planning. Look for files like TODO.md, ROADMAP.md, requirements.md, FEATURES.md, or any markdown files in docs/ directory. List their paths and show their contents.


I'll search for files related to todos, requirements, roadmaps, and feature planning in the butler project.


Bash

find /root/projects/butler -maxdepth 3 -type f \( -name "*.md" \) | grep -iE "(todo|roadmap|feature|requirement|plan)" | head -20

Search for markdown files with planning-related names


/root/projects/butler/tag20260215/docs/TODO.md
/root/projects/butler/tag20260302/docs/TODO.md
/root/projects/butler/docs/TODO.md


/root/projects/butler/docs/steps_fix_summary.md
/root/projects/butler/docs/MANUAL_ENTRY.md
/root/projects/butler/docs/REVIEW_AND_ROADMAP.md
/root/projects/butler/docs/context_management.md
/root/projects/butler/docs/gemini_empty_response_diagnosis.md
/root/projects/butler/docs/gemini_root_cause_analysis.md
/root/projects/butler/docs/safety_override_restored.md
/root/projects/butler/docs/proxy_issue_final_analysis.md
/root/projects/butler/docs/enhanced_logging_guide.md
/root/projects/butler/docs/log_analysis_2026-02-06.md
/root/projects/butler/docs/proxy_decision_guide.md
/root/projects/butler/docs/gmode_check_detailed.md
/root/projects/butler/docs/QUICK_START_AFTER_RETURN.md
/root/projects/butler/docs/HEALTH_SYNC_README.md
/root/projects/butler/docs/TESTING.md
/root/projects/butler/docs/TODO.md
/root/projects/butler/docs/health_query_usage.md
/root/projects/butler/docs/CRON_SETUP.md


/root/projects/butler/BOT_FEATURES_REFERENCE.md
/root/projects/butler/docs/REVIEW_AND_ROADMAP.md
/root/projects/butler/docs/TODO.md
/root/projects/butler/tag20260215/docs/REVIEW_AND_ROADMAP.md
/root/projects/butler/tag20260215/docs/TODO.md
/root/projects/butler/tag20260215/BOT_FEATURES_REFERENCE.md
/root/projects/butler/tag20260302/docs/REVIEW_AND_ROADMAP.md
/root/projects/butler/tag20260302/docs/TODO.md
/root/projects/butler/tag20260302/BOT_FEATURES_REFERENCE.md


Now let me read the main planning documents:


     1→# 🤖 Butler Bot 功能速查手册
     2→
     3→> **快速参考**: 所有Bot功能、工具、命令的完整说明
     4→> **更新日期**: 2026-01-30
     5→
     6→---
     7→
     8→## 📑 目录
     9→
    10→1. [三Bot架构](#-三bot架构)
    11→2. [Health Bot - 14个工具](#-health-bot---14个工具)
    12→3. [Shell Bot - 系统管理](#-shell-bot---系统管理)
    13→4. [Powellllll Bot - 写作与知识](#-powellllll-bot---写作与知识)
    14→5. [特殊命令](#-特殊命令failsafe-commands)
    15→6. [对话管理](#-对话管理)
    16→7. [常见场景速查](#-常见场景速查)
    17→
    18→---
    19→
    20→## 🏗 三Bot架构
    21→
    22→Butler使用**三个独立的Slack Bot**，各司其职：
    23→
    24→| Bot | 用途 | Slack Token | 主要功能 |
    25→|-----|------|------------|---------|
    26→| **Health Bot** | 健康数据管理 | `SLACK_BOT_TOKEN` | 查询Garmin数据、记录饮食/补剂、数据分析 |
    27→| **Shell Bot** | 系统管理 | `SHELL_SLACK_BOT_TOKEN` | 执行命令、文件操作、进程管理 |
    28→| **Powellllll Bot** | 写作与知识助手 | `OBSIDIAN_SLACK_BOT_TOKEN` | 写作生成、邮件回复、决策支持、笔记搜索 |
    29→
    30→**为什么分离？**
    31→- 安全隔离：Shell Bot有系统权限，其他Bot权限受限
    32→- 上下文独立：健康数据、系统命令、写作内容互不干扰
    33→- 专业化：每个Bot使用专门的system prompt和工具集
    34→- 稳定性：一个Bot崩溃不影响其他Bot
    35→
    36→---
    37→
    38→## 🏥 Health Bot - 14个工具
    39→
    40→### 📖 数据读取工具（4个）
    41→
    42→#### 1. `get_daily_detailed_stats`
    43→**用途**: 获取某一天的完整健康摘要（睡眠+心率+步数+活动）
    44→
    45→**使用场景**:
    46→- "昨天睡得怎么样？"
    47→- "2024-01-20 的完整数据"
    48→- "今天的健康数据"
    49→
    50→**参数**:
    51→```json
    52→{
    53→  "target_date": "YYYY-MM-DD"  // 必填
    54→}
    55→```
    56→
    57→**示例**:
    58→```
    59→你: 昨天的数据
    60→Bot: [调用 get_daily_detailed_stats("2024-01-29")]
    61→     📊 2024-01-29 健康摘要:
    62→     💤 睡眠: 7h 32m, 评分 82/100
    63→     ❤ 静息心率: 53 bpm
    64→     🚶 步数: 8,234 步
    65→```
    66→
    67→---
    68→
    69→#### 2. `get_metric_history`
    70→**用途**: 查询某个指标的历史趋势
    71→
    72→**使用场景**:
    73→- "过去一周的睡眠趋势"
    74→- "最近30天的HRV变化"
    75→- "1月份的步数数据"
    76→
    77→**参数**:
    78→```json
    79→{
    80→  "metric_type": "sleep_score | rhr | hrv | steps | stress | ...",
    81→  "start_date": "YYYY-MM-DD",  // 必填
    82→  "end_date": "YYYY-MM-DD"     // 必填
    83→}
    84→```
    85→
    86→**可用指标类型**:
    87→- `sleep_score` - 睡眠评分
    88→- `total_sleep_seconds` - 总睡眠时长
    89→- `deep_sleep_seconds` - 深睡时长
    90→- `rhr` - 静息心率
    91→- `hrv` - 心率变异性
    92→- `steps` - 步数
    93→- `stress` - 压力水平
    94→- `body_battery` - Body Battery
    95→
    96→**示例**:
    97→```
    98→你: 过去7天的HRV趋势
    99→Bot: [调用 get_metric_history("hrv", "2024-01-23", "2024-01-29")]
   100→     📈 HRV 趋势 (2024-01-23 ~ 2024-01-29):
   101→     - 平均: 62 ms
   102→     - 最高: 78 ms (01-27)
   103→     - 最低: 48 ms (01-24)
   104→```
   105→
   106→---
   107→
   108→#### 3. `get_activity_history`
   109→**用途**: 查询运动活动记录
   110→
   111→**使用场景**:
   112→- "这周跑了几次步？"
   113→- "1月份的所有运动"
   114→
   115→**参数**:
   116→```json
   117→{
   118→  "start_date": "YYYY-MM-DD",  // 必填
   119→  "end_date": "YYYY-MM-DD"     // 必填
   120→}
   121→```
   122→
   123→**示例**:
   124→```
   125→你: 这周的运动记录
   126→Bot: [调用 get_activity_history("2024-01-23", "2024-01-29")]
   127→     🏃 本周运动 (7天):
   128→     - 2024-01-24: 跑步 5.2km, 用时 28分, 平均心率 152
   129→     - 2024-01-26: 力量训练 45分
   130→```
   131→
   132→---
   133→
   134→#### 4. `get_manual_history`
   135→**用途**: 查询手动记录的日志（饮食、补剂、酒精等）
   136→
   137→**使用场景**:
   138→- "上周我喝了几次酒？"
   139→- "最近记录的补剂有哪些？"
   140→
   141→**参数**:
   142→```json
   143→{
   144→  "start_date": "YYYY-MM-DD",  // 必填
   145→  "end_date": "YYYY-MM-DD",    // 必填
   146→  "category": "diet | alcohol | supplements | feelings | fasting | all"  // 可选
   147→}
   148→```
   149→
   150→**示例**:
   151→```
   152→你: 上周的酒精记录
   153→Bot: [调用 get_manual_history("2024-01-22", "2024-01-28", "alcohol")]
   154→     🍷 酒精记录 (7天):
   155→     - 2024-01-24 19:30: 红酒 150ml
   156→     - 2024-01-27 20:00: 啤酒 330ml
   157→```
   158→
   159→---
   160→
   161→### ✍ 数据记录工具（5个）
   162→
   163→#### 5. `log_diet`
   164→**用途**: 记录饮食
   165→
   166→**参数**:
   167→```json
   168→{
   169→  "target_date": "YYYY-MM-DD",           // 必填
   170→  "description": "食物描述",              // 必填
   171→  "meal_type": "breakfast | lunch | dinner | snack",  // 可选
   172→  "time": "HH:MM"                        // 可选
   173→}
   174→```
   175→
   176→**示例**:
   177→```
   178→你: 记录今天午餐吃了鸡胸肉沙拉
   179→Bot: [调用 log_diet(target_date="2024-01-29", description="鸡胸肉沙拉", meal_type="lunch")]
   180→     ✅ 已记录 2024-01-29 的午餐: 鸡胸肉沙拉
   181→```
   182→
   183→---
   184→
   185→#### 6. `log_supplement`
   186→**用途**: 记录补剂
   187→
   188→**参数**:
   189→```json
   190→{
   191→  "target_date": "YYYY-MM-DD",  // 必填
   192→  "name": "补剂名称",            // 必填
   193→  "dosage": "剂量",             // 必填
   194→  "time": "HH:MM"               // 可选
   195→}
   196→```
   197→
   198→**示例**:
   199→```
   200→你: 今天早上吃了 Vitamin D3 5000IU
   201→Bot: [调用 log_supplement(name="Vitamin D3", dosage="5000IU")]
   202→     ✅ 已记录补剂: Vitamin D3 (5000IU)
   203→```
   204→
   205→---
   206→
   207→#### 7. `log_alcohol`
   208→**用途**: 记录酒精摄入
   209→
   210→**参数**:
   211→```json
   212→{
   213→  "target_date": "YYYY-MM-DD",  // 必填
   214→  "alcohol_type": "酒精类型",    // 必填
   215→  "amount": "数量",             // 必填
   216→  "time": "HH:MM"               // 可选
   217→}
   218→```
   219→
   220→**示例**:
   221→```
   222→你: 晚上喝了一杯红酒
   223→Bot: [调用 log_alcohol(alcohol_type="红酒", amount="150ml")]
   224→     ✅ 已记录酒精: 红酒 (150ml)
   225→```
   226→
   227→---
   228→
   229→#### 8. `log_feeling`
   230→**用途**: 记录身体感受/症状
   231→
   232→**参数**:
   233→```json
   234→{
   235→  "target_date": "YYYY-MM-DD",  // 必填
   236→  "feeling_type": "感受类型",    // 必填（如"头痛"、"疲劳"）
   237→  "severity": 1-10,             // 必填（严重程度）
   238→  "description": "详细描述",     // 必填
   239→  "time": "HH:MM"               // 可选
   240→}
   241→```
   242→
   243→**示例**:
   244→```
   245→你: 今天感觉有点头痛，大概3分严重度
   246→Bot: [调用 log_feeling(feeling_type="头痛", severity=3, description="轻微头痛")]
   247→     ✅ 已记录感受: 头痛 (严重度 3/10)
   248→```
   249→
   250→---
   251→
   252→#### 9. `log_fasting`
   253→**用途**: 记录禁食模式
   254→
   255→**参数**:
   256→```json
   257→{
   258→  "target_date": "YYYY-MM-DD",  // 必填
   259→  "mode": "OMAD | PSMF | 16:8 | ..."  // 必填
   260→}
   261→```
   262→
   263→**示例**:
   264→```
   265→你: 今天采用OMAD模式
   266→Bot: [调用 log_fasting(mode="OMAD")]
   267→     ✅ 已记录禁食模式: OMAD
   268→```
   269→
   270→---
   271→
   272→### 🔄 数据同步工具（2个）
   273→
   274→#### 10. `sync_garmin`
   275→**用途**: 手动同步Garmin数据
   276→
   277→**参数**:
   278→```json
   279→{
   280→  "target_date": "YYYY-MM-DD"  // 可选，默认今天
   281→}
   282→```
   283→
   284→**示例**:
   285→```
   286→你: 同步今天的Garmin数据
   287→Bot: [调用 sync_garmin()]
   288→     ⏳ 正在同步 2024-01-29 的数据...
   289→     ✅ 已同步: 睡眠、心率、步数、HRV
   290→```
   291→
   292→---
   293→
   294→#### 11. `sync_obsidian`
   295→**用途**: 同步健康数据到Obsidian笔记
   296→
   297→**参数**:
   298→```json
   299→{
   300→  "target_date": "YYYY-MM-DD"  // 必填
   301→}
   302→```
   303→
   304→---
   305→
   306→### 📊 高级分析工具（2个）
   307→
   308→#### 12. `get_health_insights`
   309→**用途**: 获取高级健康洞察（相关性、趋势分析）
   310→
   311→**参数**:
   312→```json
   313→{
   314→  "analysis_type": "recovery_correlations | fitness_trends | lifestyle_impact",
   315→  "lookback_days": 30-90  // 建议30-90天
   316→}
   317→```
   318→
   319→**分析类型**:
   320→- `recovery_correlations`: 酒精/运动对恢复的影响
   321→- `fitness_trends`: RHR/HRV趋势分析
   322→- `lifestyle_impact`: 禁食/补剂对健康的影响
   323→
   324→**示例**:
   325→```
   326→你: 分析过去60天的健身趋势
   327→Bot: [调用 get_health_insights(analysis_type="fitness_trends", lookback_days=60)]
   328→     📈 60天健身趋势:
   329→     - RHR下降 5%，有氧适能提升
   330→     - HRV上升 12%，恢复能力增强
   331→```
   332→
   333→---
   334→
   335→#### 13. `analyze_driver`
   336→**用途**: 分析某个因素（Driver）对健康指标的影响
   337→
   338→**参数**:
   339→```json
   340→{
   341→  "driver_metric": "alcohol_units | stress | steps | has_magnesium | ...",
   342→  "target_metric": "sleep_score | rhr | hrv | body_battery",
   343→  "method": "correlation | group_compare",
   344→  "lookback_days": 30  // 可选，默认30天
   345→}
   346→```
   347→
   348→**方法选择**:
   349→- `correlation`: 用于连续变量（如酒精量 vs 睡眠评分）
   350→- `group_compare`: 用于事件对比（如有镁 vs 无镁）
   351→
   352→**示例**:
   353→```
   354→你: 分析镁对睡眠的影响
   355→Bot: [调用 analyze_driver(driver_metric="has_magnesium", target_metric="sleep_score", method="group_compare")]
   356→     🔬 分组对比分析:
   357→     - 有镁组: 平均睡眠评分 84.2
   358→     - 无镁组: 平均睡眠评分 76.5
   359→     - 差异: +7.7 分 (统计显著, p=0.03)
   360→```
   361→
   362→---
   363→
   364→### 🌐 网络搜索工具（1个）
   365→
   366→#### 14. `search_web`
   367→**用途**: 实时网络搜索（DuckDuckGo）
   368→
   369→**使用场景**:
   370→- "最新的NMN研究"
   371→- "berberine副作用"
   372→- "查询长寿相关新闻"
   373→
   374→**参数**:
   375→```json
   376→{
   377→  "query": "搜索关键词"  // 必填
   378→}
   379→```
   380→
   381→**隐私说明**: 只搜索关键词，**不会**上传你的个人健康数据。
   382→
   383→---
   384→
   385→## 💻 Shell Bot - 系统管理
   386→
   387→### 核心工具
   388→
   389→#### `execute_shell`
   390→**用途**: 执行zsh命令（持久化会话）
   391→
   392→**参数**:
   393→```json
   394→{
   395→  "command": "命令字符串",
   396→  "timeout": 2.0  // 可选，默认2秒
   397→}
   398→```
   399→
   400→**特性**:
   401→- 每个Slack频道有独立的shell会话
   402→- 工作目录会保持（cd有效）
   403→- 环境变量持久化
   404→
   405→**示例**:
   406→```
   407→你: 检查当前目录
   408→Bot: [调用 execute_shell("pwd")]
   409→     📟 /root/projects/butler
   410→
   411→你: 列出文件
   412→Bot: [调用 execute_shell("ls -lh")]
   413→     📟 total 48
   414→     drwxr-xr-x  12 lili  staff   384B Jan 23 15:20 health
   415→     drwxr-xr-x   8 lili  staff   256B Jan 23 15:20 slack_bot
   416→```
   417→
   418→---
   419→
   420→#### `download_file`
   421→**用途**: 从服务器下载文件到Slack
   422→
   423→**参数**:
   424→```json
   425→{
   426→  "file_path": "/absolute/path/to/file"
   427→}
   428→```
   429→
   430→---
   431→
   432→#### `save_file`
   433→**用途**: 保存内容到服务器文件
   434→
   435→**参数**:
   436→```json
   437→{
   438→  "file_path": "/absolute/path",
   439→  "content": "文件内容",
   440→  "overwrite": true  // 可选
   441→}
   442→```
   443→
   444→---
   445→
   446→#### `get_system_status`
   447→**用途**: 获取系统健康仪表板（CPU、内存、磁盘、进程）
   448→
   449→---
   450→
   451→#### `get_process_list`
   452→**用途**: 列出运行中的进程
   453→
   454→**参数**:
   455→```json
   456→{
   457→  "filter_name": "进程名关键词",  // 可选
   458→  "limit": 15                  // 可选
   459→}
   460→```
   461→
   462→---
   463→
   464→#### `kill_process`
   465→**用途**: 终止进程
   466→
   467→**参数**:
   468→```json
   469→{
   470→  "pid": 12345,
   471→  "signal_type": "SIGTERM | SIGKILL"  // 可选，默认SIGTERM
   472→}
   473→```
   474→
   475→---
   476→
   477→## ✍ Powellllll Bot - 写作与知识
   478→
   479→### 概述
   480→
   481→**Powellllll Bot** 是一个连接你Obsidian笔记库的**智能写作助手**，它能：
   482→- 学习你的写作风格，模仿你的语气生成文章
   483→- 根据你的沟通风格起草专业邮件回复
   484→- 作为"魔鬼代言人"帮你做决策分析
   485→- 搜索你的Obsidian笔记库提供上下文
   486→
   487→**核心特点**：
   488→- 📚 **RAG增强**: 自动检索Obsidian vault中的相关笔记
   489→- 🎨 **风格学习**: 从`#writing_sample`和`#reply_sample`标签的笔记中学习你的表达方式
   490→- 🧠 **知识库集成**: 基于`writing_style.md`、`methodology.md`等你的个人知识体系
   491→- 🔄 **持续对话**: 支持多轮修改和迭代
   492→
   493→---
   494→
   495→### 4种工作模式
   496→
   497→Powellllll Bot有4种模式，使用前需要先切换模式：
   498→
   499→#### 模式切换命令
   500→
   501→```
   502→mode write      # 写作模式
   503→mode reply      # 邮件回复模式
   504→mode decide     # 决策支持模式
   505→mode search     # 笔记搜索模式
   506→```
   507→
   508→---
   509→
   510→### 模式1: Write（写作助手）
   511→
   512→**用途**: 根据主题生成文章，模仿你的写作风格
   513→
   514→**工作流程**:
   515→1. 切换模式: `mode write`
   516→2. 第一轮输入: `<主题> | <额外上下文>`（可选用`|`分隔）
   517→3. Bot会：
   518→   - 从Obsidian中检索相关笔记（RAG）
   519→   - 加载3个`#writing_sample`样本学习你的风格
   520→   - 读取`writing_style.md`和`methodology.md`
   521→   - 生成初稿
   522→4. 后续轮次: 直接提修改要求（如"加个比喻"、"改得更口语化"）
   523→
   524→**示例**:
   525→```
   526→你: mode write
   527→Bot: ✅ Switched to mode: write
   528→
   529→你: 云计算的本质 | 我想从Lighthouse产品的角度来讲
   530→Bot: [读取笔记 + 风格样本]
   531→     云计算到底在干什么？说白了就是想建一个IT的巴别塔...
   532→     [生成800字初稿]
   533→
   534→你: 加一个关于"毛坯房vs简装房"的比喻
   535→Bot: [修改后的版本，新增比喻]
   536→
   537→你: 结尾改得不要那么"展望未来"，说点实在的
   538→Bot: [修改结尾，去除AI味]
   539→```
   540→
   541→**相关文件**:
   542→- `writing_style.md` - 你的写作风格指南
   543→- `methodology.md` - 你的思维方法论
   544→- `POWELL_REVISE.md` - AI味去除修订规范（可手动参考）
   545→
   546→---
   547→
   548→### 模式2: Reply（邮件回复生成器）
   549→
   550→**用途**: 起草高情商、逻辑严谨的专业邮件回复
   551→
   552→**工作流程**:
   553→1. 切换模式: `mode reply`
   554→2. 第一轮输入: 粘贴需要回复的邮件原文
   555→3. Bot会：
   556→   - 分析邮件的关键信息和隐含诉求
   557→   - 加载`#reply_sample`样本学习你的沟通风格
   558→   - 生成回复草稿
   559→4. 后续轮次: 修改要求（如"语气再委婉点"、"加上时间线"）
   560→
   561→**示例**:
   562→```
   563→你: mode reply
   564→Bot: ✅ Switched to mode: reply
   565→
   566→你: [粘贴邮件]
   567→    "Hi Powell, 我们团队想在下周上线新功能，需要你们配合升级底层服务..."
   568→
   569→Bot: [分析邮件诉求]
   570→     Subject: Re: 新功能上线协调
   571→
   572→     Hi XXX，
   573→
   574→     收到，下周上线这个时间点我们这边可以配合。有几个技术细节想先确认...
   575→     [生成完整回复]
   576→
   577→你: 语气再客气一点，别显得太生硬
   578→Bot: [调整后的版本]
   579→```
   580→
   581→**相关文件**:
   582→- `REPLY-SAMPLE.md` - 你的回复样本集
   583→
   584→---
   585→
   586→### 模式3: Decide（决策支持）
   587→
   588→**用途**: 扮演"魔鬼代言人"，帮你做决策分析
   589→
   590→**工作流程**:
   591→1. 切换模式: `mode decide`
   592→2. 第一轮输入: 描述决策问题和你的初步想法
   593→3. Bot会：
   594→   - 使用你的决策框架（如GPA、IPO）分析
   595→   - 从多个角度质疑你的假设
   596→   - 列出潜在风险和机会
   597→4. 后续轮次: 继续深入讨论
   598→
   599→**示例**:
   600→```
   601→你: mode decide
   602→Bot: ✅ Switched to mode: decide
   603→
   604→你: 我在考虑要不要接受新的Tech Lead职位，担心会牺牲技术深度
   605→Bot: 让我从几个角度帮你分析这个决策：
   606→
   607→     【假设检验】
   608→     - 你假设"管理=牺牲技术深度"，但这个前提成立吗？
   609→     - 是否存在"管理型技术专家"的路径？
   610→
   611→     【机会成本】
   612→     - 如果不接受，3年后的你会在哪里？
   613→     - 接受后，最坏的情况是什么？可逆吗？
   614→
   615→     【风险点】
   616→     ...
   617→
   618→你: 你说的"可逆性"很关键，如果试一年发现不合适，我还能回到IC路线吗？
   619→Bot: [继续分析可逆性和退出策略]
   620→```
   621→
   622→**相关框架**:
   623→- GPA框架（Goal-Plan-Action）
   624→- IPO框架（Input-Process-Output）
   625→- 你在`methodology.md`中定义的其他决策工具
   626→
   627→---
   628→
   629→### 模式4: Search（笔记搜索与分析）
   630→
   631→**用途**: 搜索Obsidian笔记库，提供智能摘要
   632→
   633→**工作流程**:
   634→1. 切换模式: `mode search`
   635→2. 输入查询关键词
   636→3. Bot会：
   637→   - 在Obsidian vault中搜索相关笔记
   638→   - 提取关键片段
   639→   - 进行智能摘要和关联分析
   640→   - （可选）触发Web搜索补充最新信息
   641→
   642→**示例**:
   643→```
   644→你: mode search
   645→Bot: ✅ Switched to mode: search
   646→
   647→你: 我之前写过关于"技术债务"的笔记吗？
   648→Bot: [搜索vault]
   649→     找到3条相关笔记：
   650→
   651→     1. 《重构vs技术债务.md》（2024-01-15）
   652→        - 核心观点：技术债务不是技术问题，是优先级问题
   653→        - 引用了Martin Fowler的Technical Debt Quadrant
   654→
   655→     2. 《项目复盘-XX重构.md》（2023-12-03）
   656→        - 实战案例：重构导致延期2周的教训
   657→        ...
   658→
   659→     【关联分析】
   660→     这些笔记都提到了"可逆性"这个关键词，与你的决策方法论一致。
   661→
   662→你: 帮我总结一下我对技术债务的核心观点
   663→Bot: [基于笔记生成摘要]
   664→```
   665→
   666→---
   667→
   668→### 通用命令
   669→
   670→这些命令在所有模式下都可用：
   671→
   672→#### `clear`
   673→清空当前对话历史
   674→
   675→```
   676→你: clear
   677→Bot: 🧹 Context cleared.
   678→```
   679→
   680→#### `reload`
   681→重新扫描Obsidian vault（当你新增笔记后使用）
   682→
   683→```
   684→你: reload
   685→Bot: 🔄 Vault reloaded.
   686→```
   687→
   688→---
   689→
   690→### 配置要求
   691→
   692→**环境变量**（在`.env`中配置）:
   693→```bash
   694→# Obsidian Bot Tokens
   695→OBSIDIAN_SLACK_BOT_TOKEN=xoxb-your-token
   696→OBSIDIAN_SLACK_APP_TOKEN=xapp-your-token
   697→
   698→# Obsidian Vault路径
   699→OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault
   700→```
   701→
   702→**Obsidian笔记库结构**:
   703→```
   704→your-vault/
   705→├── writing_style.md        # 必需：你的写作风格指南
   706→├── methodology.md          # 必需：你的方法论
   707→├── REPLY-SAMPLE.md         # Reply模式需要
   708→├── notes/
   709→│   ├── article1.md         # 带 #writing_sample 标签
   710→│   ├── email_reply1.md     # 带 #reply_sample 标签
   711→│   └── ...
   712→```
   713→
   714→**标签规范**:
   715→- `#writing_sample` - 标记你的优质文章，供Write模式学习
   716→- `#reply_sample` - 标记你的优质邮件回复，供Reply模式学习
   717→
   718→---
   719→
   720→### AI味去除工具
   721→
   722→**POWELL_REVISE.md** 是一个手动修订规范，用于AI生成内容后的"去AI味"处理。
   723→
   724→**典型AI痕迹**:
   725→- ❌ "首先...其次...最后..."
   726→- ❌ "总而言之" "综上所述"
   727→- ❌ 过度工整的排比句
   728→- ❌ "让我们携手共进，共创美好未来"
   729→
   730→**修订策略**:
   731→- ✅ 删除过渡词堆积
   732→- ✅ 打破排比对仗
   733→- ✅ 增加口语化（"说实话" "其实" "btw"）
   734→- ✅ 保留技术准确性
   735→- ✅ 加入你的典型比喻（巴别塔、毛坯房、魔法）
   736→
   737→**快速修订流程**（5分钟）:
   738→1. 批量替换："首先"→删除，"总而言之"→删除
   739→2. 挑3个最AI的句子重写
   740→3. 加1个比喻
   741→4. 改结尾：从"展望未来"改成"下一步要做X"
   742→
   743→详见完整的`POWELL_REVISE.md`文档。
   744→
   745→---
   746→
   747→### 使用技巧
   748→
   749→#### ✅ 最佳实践
   750→
   751→1. **标签管理**: 定期给优质笔记打上`#writing_sample`或`#reply_sample`标签
   752→2. **风格文件维护**: 随时更新`writing_style.md`，记录你的新表达习惯
   753→3. **分阶段修改**: 先生成初稿，再分多轮微调（比一次性要求更准确）
   754→4. **上下文提供**: Write模式第一轮尽量提供充足的背景信息
   755→5. **Reload及时**: 新增重要笔记后记得`reload`
   756→
   757→#### ⚠ 注意事项
   758→
   759→1. **隐私安全**: Bot读取本地Obsidian文件，但不会上传到云端（仅发送给Gemini LLM处理）
   760→2. **首轮质量**: 第一轮生成的质量取决于`#writing_sample`的数量和质量（建议至少5篇）
   761→3. **长文章限制**: Slack消息有长度限制（~12000字符），超长文章会被截断
   762→4. **模式切换**: 切换模式会自动`clear`历史，避免上下文混乱
   763→
   764→---
   765→
   766→### 典型工作流
   767→
   768→#### 场景1: 写一篇技术博客
   769→```
   770→1. mode write
   771→2. 云原生架构的演进 | 我想从Kubernetes到Serverless的路径来讲
   772→3. [Bot生成初稿]
   773→4. 加一个关于"巴别塔"的比喻
   774→5. 第二段太长了，拆成两段
   775→6. 结尾改得实际点，不要"展望未来"
   776→7. [定稿，复制到编辑器]
   777→8. [手动参考POWELL_REVISE.md进行最后润色]
   778→```
   779→
   780→#### 场景2: 回复合作伙伴邮件
   781→```
   782→1. mode reply
   783→2. [粘贴合作伙伴的需求邮件]
   784→3. [Bot生成回复草稿]
   785→4. 语气再委婉点，别显得太直接
   786→5. 加上我们这边的时间安排
   787→6. [定稿，发送]
   788→```
   789→
   790→#### 场景3: 重大决策分析
   791→```
   792→1. mode decide
   793→2. 我在考虑要不要all-in做AI方向，担心风险太大
   794→3. [Bot从多角度分析]
   795→4. 你说的"机会成本"很关键，能展开讲讲吗？
   796→5. 如果我要测试这个方向，最小可行方案是什么？
   797→6. [继续讨论，最终形成决策框架]
   798→```
   799→
   800→---
   801→
   802→## 🚨 特殊命令（Failsafe Commands）
   803→
   804→这些是**硬编码**的系统级命令，直接触发脚本执行，**不经过LLM**。
   805→
   806→### 1. Gemini配置切换 (`gmode`)
   807→
   808→**格式**: `### gmode <config_name> ###`
   809→
   810→**可用配置**:
   811→- `local` - 本地代理（127.0.0.1:8045）
   812→- `openrouter` - OpenRouter（需要API key）
   813→- `check` - 快速检查所有配置的基本连接状态
   814→- `check-detailed` - 全面检查所有配置（包括function calling测试）
   815→
   816→**示例**:
   817→```
   818→你: ### gmode local ###
   819→Bot: ♻ System Reset: Switched to `local`. Restarting process...
   820→     [Bot自动重启，加载新配置]
   821→
   822→你: ### gmode check ###
   823→Bot: 🔍 Health Check Results:
   824→     CONFIG                    | MODEL                          | STATUS     | MESSAGE
   825→     ------------------------------------------------------------------------------------------
   826→     .gemini.local.env (current) | gemini-3-pro-high              | ✅ PASS   | OK (1234ms)
   827→     .gemini.openrouter.env      | google/gemini-3-flash-preview  | ✅ PASS   | OK (567ms)
   828→
   829→你: ### gmode check-detailed ###
   830→Bot: 🔍 Comprehensive Health Check Results:
   831→     ================================================================================
   832→     📋 Testing: .gemini.local.env ⭐ CURRENT
   833→     ================================================================================
   834→     Model: gemini-3-pro-high
   835→     Base URL: http://127.0.0.1:8045
   836→
   837→       Running: 简单对话（无工具）... ✅ (285 chars) [7.40s]
   838→       Running: 健康查询（无工具）... ❌ (empty) [8.61s]
   839→       Running: Function Calling (6工具)... ❌ (no tool calls) [5.59s]
   840→
   841→     Overall Grade: 🟡 C (33% success, avg 7.20s)
   842→
   843→     ================================================================================
   844→     📋 Testing: .gemini.openrouter.env
   845→     ================================================================================
   846→     Model: google/gemini-3-flash-preview
   847→     Base URL: https://openrouter.ai/api
   848→
   849→       Running: 简单对话（无工具）... ✅ (32 chars) [2.73s]
   850→       Running: 健康查询（无工具）... ❌ (empty) [1.75s]
   851→       Running: Function Calling (6工具)... ✅ (1 tools) [1.43s]
   852→
   853→     Overall Grade: 🟢 A (67% success, avg 1.97s)
   854→```
   855→
   856→**实现位置**: `slack_bot/shell_main.py:131`, `scripts/select_gemini.py`
   857→
   858→---
   859→
   860→### 2. Bot进程管理 (`bot`)
   861→
   862→**格式**: `### bot <command> [args] ###`
   863→
   864→**可用命令**:
   865→```bash
   866→### bot status ###           # 查看所有bot状态
   867→### bot start health ###      # 启动Health Bot
   868→### bot start shell ###       # 启动Shell Bot
   869→### bot stop health ###       # 停止Health Bot
   870→### bot restart health ###    # 重启Health Bot
   871→### bot logs health ###       # 查看Health Bot日志
   872→```
   873→
   874→**实现位置**: `slack_bot/shell_main.py:166`
   875→
   876→**示例**:
   877→```
   878→你: ### bot status ###
   879→Bot: 🤖 Bot Manager Output:
   880→     Health Bot: Running (PID 12345)
   881→     Shell Bot: Running (PID 12346)
   882→
   883→你: ### bot restart health ###
   884→Bot: 🤖 Restarting Health Bot...
   885→     ✅ Done. PID: 12347
   886→```
   887→
   888→---
   889→
   890→## 💬 对话管理
   891→
   892→### 清除上下文
   893→
   894→**命令**: `clear` / `reset` / `清除`
   895→
   896→**作用**: 清空当前频道的对话历史（上下文窗口）
   897→
   898→**示例**:
   899→```
   900→你: clear
   901→Bot: 🧹 Context cleared. (对话历史已清除)
   902→```
   903→
   904→### Help菜单
   905→
   906→**命令**: `help` / `help?` / `帮助` / `menu`
   907→
   908→**作用**: 显示Shell Bot的帮助文档
   909→
   910→---
   911→
   912→## 🎯 常见场景速查
   913→
   914→### 场景1: 每日健康检查
   915→```
   916→你: 昨天睡得怎么样？
   917→Bot: [get_daily_detailed_stats("2024-01-28")]
   918→```
   919→
   920→### 场景2: 记录早餐
   921→```
   922→你: 记录今天早上吃了燕麦和蓝莓
   923→Bot: [log_diet(description="燕麦和蓝莓", meal_type="breakfast")]
   924→```
   925→
   926→### 场景3: 分析补剂效果
   927→```
   928→你: 分析过去30天镁对我睡眠的影响
   929→Bot: [analyze_driver(driver_metric="has_magnesium", target_metric="sleep_score", method="group_compare", lookback_days=30)]
   930→```
   931→
   932→### 场景4: 系统状态检查
   933→```
   934→你: 系统负载怎么样？
   935→Bot: [execute_shell("uptime")]
   936→```
   937→
   938→### 场景5: 查询科学文献
   939→```
   940→你: 搜索最新的NAD+补充剂研究
   941→Bot: [search_web(query="NAD+ supplement 2024 research")]
   942→```
   943→
   944→### 场景6: 切换Gemini配置
   945→```
   946→你: ### gmode local ###
   947→Bot: [切换到本地代理并重启]
   948→```
   949→
   950→### 场景7: 写作助手生成文章
   951→```
   952→你: mode write
   953→Bot: ✅ Switched to mode: write
   954→
   955→你: 云计算的本质 | 想从Lighthouse角度讲
   956→Bot: [生成基于你风格的文章初稿]
   957→
   958→你: 加个"毛坯房vs简装房"的比喻
   959→Bot: [修改后的版本]
   960→```
   961→
   962→### 场景8: 决策分析
   963→```
   964→你: mode decide
   965→Bot: ✅ Switched to mode: decide
   966→
   967→你: 我在考虑要不要接受Tech Lead职位
   968→Bot: [从多角度分析，质疑假设，列出风险]
   969→```
   970→
   971→---
   972→
   973→## 📝 使用技巧
   974→
   975→### ✅ 最佳实践
   976→
   977→1. **日期格式统一**: 使用 `YYYY-MM-DD`（如 `2024-01-29`）
   978→2. **时间格式统一**: 使用 `HH:MM`（如 `18:30`）
   979→3. **自然语言优先**: Bot会自动解析你的意图，无需记忆命令
   980→4. **批量查询**: "过去7天的睡眠和HRV" - Bot会自动调用多个工具
   981→5. **分析周期**: 建议30-90天，太短无统计意义，太长数据可能不完整
   982→
   983→### ⚠ 注意事项
   984→
   985→1. **图片限制**: 图片会自动压缩到1024x1024，确保清晰度
   986→2. **Shell会话超时**: 30分钟无活动会自动重启会话
   987→3. **数据同步**: Garmin数据不会自动同步，需手动调用 `sync_garmin`
   988→4. **隐私保护**: Web搜索只发送关键词，不发送个人数据
   989→
   990→---
   991→
   992→## 🔗 相关文档
   993→
   994→- [完整使用指南](Butler-Bot使用指南.md)
   995→- [开发者文档](README.md)
   996→- [代码规范](CLAUDE.md)
   997→
   998→---
   999→
  1000→**最后更新**: 2026-01-30
  1001→**版本**: v1.0
  1002→**维护者**: Lili
  1003→

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>


     1→# 📋 Butler 项目待办事项清单
     2→
     3→**最后更新**: 2026-03-02
     4→**参考文档**: `docs/REVIEW_AND_ROADMAP.md` (完整审查报告)
     5→
     6→---
     7→
     8→## 🎯 快速开始指南
     9→
    10→回来后执行以下命令:
    11→
    12→```bash
    13→# 1. 进入项目目录
    14→cd /root/projects/butler
    15→git status
    16→
    17→# 2. 激活虚拟环境
    18→source venv/bin/activate
    19→
    20→# 3. 开始第一周的任务
    21→# 参考下方 "Week 1" 部分
    22→```
    23→
    24→---
    25→
    26→## ⚡ 优先级说明
    27→
    28→- **P0** - 🔴 紧急且重要 (安全、可靠性)
    29→- **P1** - 🟡 重要但不紧急 (架构改进、文档)
    30→- **P2** - 🟢 重要性较低 (性能优化、新功能)
    31→
    32→---
    33→
    34→## 📅 Week 1: 安全和稳定性 (6小时)
    35→
    36→### Day 1-2: 安全修复 (3小时)
    37→
    38→#### [x] Task 1.1: 修复敏感信息日志泄露 (1h) - P0 🔴 ✅
    39→**文件**: `slack_bot/dispatcher.py:342`
    40→
    41→**问题**:
    42→```python
    43→# 当前代码 (Line 342)
    44→token_masked = f"{token[:5]}...{token[-5:]}" if token else "None"
    45→logger.info(f"{prefix} Attempting download from {url} with token {token_masked}")
    46→```
    47→
    48→**修复方案**:
    49→```python
    50→# 选项 A: 完全移除 token 日志
    51→logger.info(f"{prefix} Attempting download from {url}")
    52→
    53→# 选项 B: 仅在 DEBUG 模式下输出
    54→if os.getenv("DEBUG") == "true":
    55→    token_masked = f"{token[:5]}...{token[-5:]}"
    56→    logger.debug(f"Using token {token_masked}")
    57→```
    58→
    59→**验证**:
    60→```bash
    61→# 测试 Slack 图片下载功能
    62→# 检查日志文件确认无 token 泄露
    63→grep -i "token" logs/*.log
    64→```
    65→
    66→---
    67→
    68→#### [x] Task 1.2: 添加环境变量验证 (1h) - P0 🔴 ✅
    69→**新建文件**: `config/settings.py`
    70→
    71→**实现**:
    72→```python
    73→from pydantic_settings import BaseSettings
    74→from typing import Optional
    75→
    76→class GarminSettings(BaseSettings):
    77→    email: str
    78→    password: str
    79→
    80→    class Config:
    81→        env_prefix = "GARMIN_"
    82→
    83→class SlackSettings(BaseSettings):
    84→    bot_token: str
    85→    app_token: str
    86→
    87→    class Config:
    88→        env_prefix = "SLACK_"
    89→
    90→class LLMSettings(BaseSettings):
    91→    api_key: str
    92→    base_url: str = "http://127.0.0.1:8045"
    93→    model: str = "gemini-2.0-flash-exp"
    94→
    95→    class Config:
    96→        env_prefix = "GEMINI_"
    97→
    98→class AppSettings(BaseSettings):
    99→    garmin: GarminSettings
   100→    slack: SlackSettings
   101→    llm: LLMSettings
   102→
   103→    class Config:
   104→        env_file = ".env"
   105→
   106→# 全局实例
   107→settings = AppSettings()
   108→```
   109→
   110→**迁移步骤**:
   111→1. 创建 `config/settings.py`
   112→2. 安装依赖: `pip install pydantic-settings`
   113→3. 更新 `requirements.txt`
   114→4. 逐步替换所有 `os.getenv()` 调用
   115→5. 测试启动时的验证
   116→
   117→**验证**:
   118→```bash
   119→# 测试缺失变量时的错误提示
   120→mv .env .env.backup
   121→python -c "from config.settings import settings"
   122→# 应该看到清晰的错误信息
   123→mv .env.backup .env
   124→```
   125→
   126→---
   127→
   128→#### [x] Task 1.3: Shell 命令黑名单 (1h) - P0 🔴 ✅
   129→**文件**: `slack_bot/tools/shell_tool.py`
   130→
   131→**实现**:
   132→```python
   133→# 在文件开头添加
   134→DANGEROUS_COMMANDS = [
   135→    "rm -rf /",
   136→    "rm -rf /*",
   137→    "mkfs",
   138→    "dd if=/dev/zero",
   139→    "> /dev/sda",
   140→    "fork bomb",
   141→    ":(){ :|:& };:",
   142→]
   143→
   144→DANGEROUS_PATTERNS = [
   145→    r"rm\s+-rf\s+/",
   146→    r"sudo\s+rm",
   147→    r"chmod\s+-R\s+777",
   148→    r"chown\s+-R",
   149→]
   150→
   151→def is_safe_command(command: str) -> tuple[bool, str]:
   152→    """Check if command is safe to execute.
   153→
   154→    Returns:
   155→        (is_safe, reason)
   156→    """
   157→    import re
   158→
   159→    # Check exact matches
   160→    for dangerous in DANGEROUS_COMMANDS:
   161→        if dangerous in command.lower():
   162→            return False, f"Blocked dangerous command pattern: {dangerous}"
   163→
   164→    # Check regex patterns
   165→    for pattern in DANGEROUS_PATTERNS:
   166→        if re.search(pattern, command):
   167→            return False, f"Blocked dangerous pattern: {pattern}"
   168→
   169→    return True, ""
   170→
   171→def execute_shell(command: str, channel_id: str, timeout: float = 2.0) -> str:
   172→    """Execute shell command with safety checks."""
   173→
   174→    # Safety check
   175→    is_safe, reason = is_safe_command(command)
   176→    if not is_safe:
   177→        return f"❌ BLOCKED: {reason}"
   178→
   179→    # ... 原有逻辑
   180→```
   181→
   182→**验证**:
   183→```bash
   184→# 测试危险命令拦截
   185→python -c "
   186→from slack_bot.tools.shell_tool import execute_shell
   187→print(execute_shell('rm -rf /', 'test'))
   188→print(execute_shell('ls -la', 'test'))
   189→"
   190→```
   191→
   192→---
   193→
   194→### Day 3-4: 可靠性增强 (3小时)
   195→
   196→#### [x] Task 1.4: 添加 Garmin API 重试机制 (2h) - P0 🔴 ✅
   197→**文件**: `health/services/data_sync.py`
   198→
   199→**安装依赖**:
   200→```bash
   201→pip install tenacity
   202→echo "tenacity>=8.0.0" >> requirements.txt
   203→```
   204→
   205→**实现**:
   206→```python
   207→from tenacity import (
   208→    retry,
   209→    stop_after_attempt,
   210→    wait_exponential,
   211→    retry_if_exception_type
   212→)
   213→from health.utils.exceptions import GarminAPIError
   214→
   215→# 在 HealthDataSync 类中修改
   216→@retry(
   217→    stop=stop_after_attempt(3),
   218→    wait=wait_exponential(multiplier=1, min=4, max=10),
   219→    retry=retry_if_exception_type(GarminAPIError),
   220→    reraise=True
   221→)
   222→def sync_daily_metric(
   223→    self, metric_type: str, target_date: date, force: bool = False
   224→) -> bool:
   225→    """Sync a single daily metric with retry logic."""
   226→    # 原有逻辑保持不变
   227→    ...
   228→```
   229→
   230→**验证**:
   231→```bash
   232→# 临时断网测试重试
   233→# 或者修改 garmin_client.py 模拟失败
   234→python -m health.cli.sync sync --days 1
   235→# 观察日志中的重试行为
   236→```
   237→
   238→---
   239→
   240→#### [x] Task 1.5: SQLite WAL 模式优化 (1h) - P0 🔴 ✅
   241→**文件**: `health/db/schema.py`
   242→
   243→**实现**:
   244→```python
   245→def init_database(db_path: Optional[Path] = None) -> None:
   246→    """Initialize database with performance optimizations."""
   247→    path = db_path or DB_PATH
   248→    logger.info(f"Initializing database at {path}")
   249→
   250→    with get_connection(path) as conn:
   251→        cursor = conn.cursor()
   252→
   253→        # Performance optimizations
   254→        cursor.execute("PRAGMA journal_mode=WAL;")
   255→        cursor.execute("PRAGMA synchronous=NORMAL;")
   256→        cursor.execute("PRAGMA cache_size=10000;")
   257→        cursor.execute("PRAGMA temp_store=MEMORY;")
   258→
   259→        # Create tables
   260→        cursor.execute(CREATE_SYNC_RECORDS_TABLE)
   261→        # ... 其余保持不变
   262→```
   263→
   264→**验证**:
   265→```bash
   266→# 检查 WAL 模式是否启用
   267→sqlite3 data/health/health.db "PRAGMA journal_mode;"
   268→# 应该输出: wal
   269→
   270→# 性能测试 (可选)
   271→python -c "
   272→from health.db.repository import HealthRepository
   273→import time
   274→repo = HealthRepository()
   275→start = time.time()
   276→for i in range(1000):
   277→    repo.get_last_sync_date('sleep')
   278→print(f'1000 queries: {time.time()-start:.2f}s')
   279→"
   280→```
   281→
   282→---
   283→
   284→## 📅 Week 2: 文档和测试 (8小时)
   285→
   286→### Day 1-2: 核心文档 (4小时)
   287→
   288→#### [ ] Task 2.1: 编写 ARCHITECTURE.md (2h) - P0 🔴
   289→**新建文件**: `docs/ARCHITECTURE.md`
   290→
   291→**内容大纲**:
   292→```markdown
   293→# Butler 架构文档
   294→
   295→## 1. 系统概览
   296→- 架构图
   297→- 核心模块
   298→- 技术栈
   299→
   300→## 2. 模块详解
   301→### 2.1 Health Module
   302→- 数据流
   303→- 同步逻辑
   304→- 存储策略
   305→
   306→### 2.2 Slack Bot
   307→- 消息处理流程
   308→- 工具系统
   309→- 上下文管理
   310→
   311→### 2.3 Obsidian Integration
   312→- 索引机制
   313→- 生成器
   314→
   315→## 3. 设计决策
   316→- 为什么选择 SQLite + JSON?
   317→- 为什么使用双 Bot 架构?
   318→- 为什么本地优先?
   319→
   320→## 4. 扩展指南
   321→- 如何添加新的健康指标
   322→- 如何添加新工具
   323→- 如何集成新数据源
   324→```
   325→
   326→**参考**:
   327→- 查看 `REVIEW_AND_ROADMAP.md` 的架构章节
   328→- 使用 Mermaid 绘制流程图
   329→
   330→---
   331→
   332→#### [ ] Task 2.2: 编写 TOOLS_REFERENCE.md (2h) - P0 🔴
   333→**新建文件**: `docs/TOOLS_REFERENCE.md`
   334→
   335→**内容大纲**:
   336→```markdown
   337→# Tools Reference
   338→
   339→## 概览
   340→Butler Bot 提供 14 个工具，分为 5 类:
   341→- 读取工具 (4个)
   342→- 写入工具 (5个)
   343→- 同步工具 (2个)
   344→- 分析工具 (2个)
   345→- 系统工具 (2个)
   346→
   347→## 详细文档
   348→
   349→### 1. get_daily_detailed_stats
   350→**用途**: 获取某一天的完整健康摘要
   351→
   352→**参数**:
   353→- `target_date` (必填): YYYY-MM-DD
   354→
   355→**使用场景**:
   356→- "昨天我睡得怎么样?"
   357→- "2024-01-15 的数据"
   358→
   359→**示例**:
   360→```json
   361→{
   362→  "target_date": "2024-01-22"
   363→}
   364→```
   365→
   366→**返回示例**:
   367→```json
   368→{
   369→  "date": "2024-01-22",
   370→  "sleep": {...},
   371→  "steps": 8234,
   372→  "activities": [...],
   373→  "manual_logs": {
   374→    "diet": 3,
   375→    "supplements": 2
   376→  }
   377→}
   378→```
   379→
   380→... (为每个工具重复)
   381→```
   382→
   383→---
   384→
   385→### Day 3-5: 测试覆盖 (4小时)
   386→
   387→#### [ ] Task 2.3: 配置测试覆盖率工具 (2h) - P1 🟡
   388→
   389→**安装依赖**:
   390→```bash
   391→pip install pytest-cov pytest-mock
   392→echo "pytest-cov>=4.0.0" >> requirements.txt
   393→echo "pytest-mock>=3.10.0" >> requirements.txt
   394→```
   395→
   396→**配置文件**: `pytest.ini` (新建)
   397→```ini
   398→[pytest]
   399→testpaths = tests
   400→python_files = test_*.py
   401→python_classes = Test*
   402→python_functions = test_*
   403→
   404→# Coverage settings
   405→addopts =
   406→    --cov=health
   407→    --cov=slack_bot
   408→    --cov-report=html
   409→    --cov-report=term-missing
   410→    --cov-fail-under=60
   411→
   412→# Ignore warnings
   413→filterwarnings =
   414→    ignore::DeprecationWarning
   415→```
   416→
   417→**运行测试**:
   418→```bash
   419→pytest
   420→# 查看覆盖率报告
   421→open htmlcov/index.html
   422→```
   423→
   424→**分析覆盖率**:
   425→1. 找出覆盖率 <50% 的模块
   426→2. 优先补充核心路径测试
   427→3. 目标: 整体覆盖率 ≥60%
   428→
   429→---
   430→
   431→#### [ ] Task 2.4: 添加关键路径集成测试 (2h) - P1 🟡
   432→
   433→**新建文件**: `tests/integration/test_sync_flow.py`
   434→
   435→```python
   436→import pytest
   437→from datetime import date, timedelta
   438→from health.services.data_sync import HealthDataSync
   439→
   440→@pytest.fixture
   441→def sync_service():
   442→    """Create sync service for testing."""
   443→    return HealthDataSync()
   444→
   445→def test_incremental_sync_flow(sync_service):
   446→    """Test complete incremental sync flow."""
   447→    # 1. Authenticate
   448→    sync_service.authenticate()
   449→
   450→    # 2. Get current status
   451→    status = sync_service.get_sync_status()
   452→    assert isinstance(status, dict)
   453→
   454→    # 3. Perform incremental sync
   455→    yesterday = date.today() - timedelta(days=1)
   456→    results = sync_service.sync_incremental(
   457→        until_date=yesterday
   458→    )
   459→
   460→    # 4. Verify results
   461→    assert "sleep" in results
   462→    assert results["sleep"]["synced"] >= 0
   463→    assert results["sleep"]["errors"] == 0
   464→
   465→def test_manual_log_flow():
   466→    """Test manual logging flow."""
   467→    from health.services.manual_log_storage import ManualLogStorage
   468→
   469→    storage = ManualLogStorage()
   470→
   471→    # Log diet
   472→    storage.log_diet(
   473→        target_date=date.today(),
   474→        description="Test meal",
   475→        meal_type="lunch"
   476→    )
   477→
   478→    # Query back
   479→    logs = storage.get_logs(
   480→        start_date=date.today(),
   481→        end_date=date.today(),
   482→        category="diet"
   483→    )
   484→
   485→    assert len(logs) > 0
   486→    assert logs[-1]["description"] == "Test meal"
   487→```
   488→
   489→**新建文件**: `tests/integration/test_slack_bot.py`
   490→
   491→```python
   492→import pytest
   493→from slack_bot.dispatcher import MessageDispatcher
   494→
   495→@pytest.fixture
   496→def dispatcher():
   497→    """Create dispatcher with test config."""
   498→    return MessageDispatcher()
   499→
   500→def test_message_dispatch_simple(dispatcher, mocker):
   501→    """Test simple message dispatch."""
   502→    # Mock Slack client
   503→    mock_client = mocker.patch.object(dispatcher, 'client')
   504→
   505→    # Mock LLM response
   506→    mocker.patch.object(
   507→        dispatcher.llm,
   508→        'generate_response',
   509→        return_value=("Hello! I'm Butler.", [])
   510→    )
   511→
   512→    # Dispatch message
   513→    dispatcher.dispatch(
   514→        message_text="你好",
   515→        channel_id="C12345",
   516→        user_id="U12345"
   517→    )
   518→
   519→    # Verify Slack was called
   520→    assert mock_client.chat_postMessage.called
   521→```
   522→
   523→---
   524→
   525→## 📅 Week 3+: 功能增强 (按需选择)
   526→
   527→### 高价值功能推荐
   528→
   529→#### [ ] Feature 3.1: 健康洞察自动化报告 (1天) - P0 🔴
   530→**新建文件**: `health/analytics/weekly_report.py`
   531→
   532→**功能**:
   533→- 每周日晚生成健康周报
   534→- 自动分析本周数据
   535→- 发送到 Slack
   536→
   537→**Cron 配置**:
   538→```bash
   539→# 每周日 20:00 运行
   540→0 20 * * 0 cd /root/projects/butler && source venv/bin/activate && python -m health.analytics.weekly_report
   541→```
   542→
   543→---
   544→
   545→#### [ ] Feature 3.2: Streamlit 仪表板 (3天) - P1 🟡
   546→**新建目录**: `apps/dashboard/`
   547→
   548→**安装**:
   549→```bash
   550→pip install streamlit plotly
   551→```
   552→
   553→**实现**:
   554→```python
   555→# apps/dashboard/app.py
   556→import streamlit as st
   557→import plotly.express as px
   558→from health.services.query import HealthDataQuery
   559→
   560→st.title("🏥 Butler Health Dashboard")
   561→
   562→# 日期选择
   563→date_range = st.date_input("选择日期范围", ...)
   564→
   565→# 睡眠趋势图
   566→sleep_data = query.get_metric_history("sleep", ...)
   567→fig = px.line(sleep_data, x="date", y="sleep_score")
   568→st.plotly_chart(fig)
   569→```
   570→
   571→**运行**:
   572→```bash
   573→streamlit run apps/dashboard/app.py
   574→```
   575→
   576→---
   577→
   578→#### [ ] Feature 3.3: 数据导出功能 (2天) - P1 🟡
   579→**新建文件**: `health/services/export.py`
   580→
   581→**功能**:
   582→- 导出为 CSV
   583→- 导出为 PDF 报告
   584→- 支持日期范围过滤
   585→
   586→**CLI**:
   587→```bash
   588→python -m health.cli.export csv --start 2024-01-01 --end 2024-01-31
   589→python -m health.cli.export pdf --start 2024-01-01 --end 2024-01-31
   590→```
   591→
   592→---
   593→
   594→## 🔧 配置和依赖更新
   595→
   596→### 需要添加的依赖
   597→
   598→```txt
   599→# 安全和稳定性
   600→tenacity>=8.0.0
   601→
   602→# 配置管理
   603→pydantic-settings>=2.0.0
   604→
   605→# 测试
   606→pytest-cov>=4.0.0
   607→pytest-mock>=3.10.0
   608→
   609→# 数据可视化 (可选)
   610→streamlit>=1.20.0
   611→plotly>=5.14.0
   612→
   613→# 数据导出 (可选)
   614→reportlab>=4.0.0  # PDF 生成
   615→```
   616→
   617→### 安装命令
   618→
   619→```bash
   620→# 安装核心优化依赖
   621→pip install tenacity pydantic-settings pytest-cov pytest-mock
   622→
   623→# 更新 requirements.txt
   624→pip freeze > requirements_new.txt
   625→# 手动合并到 requirements.txt
   626→```
   627→
   628→---
   629→
   630→## 📊 进度跟踪
   631→
   632→### Week 1 进度 (0/5)
   633→- [ ] 1.1 修复敏感信息日志泄露
   634→- [ ] 1.2 添加环境变量验证
   635→- [ ] 1.3 Shell 命令黑名单
   636→- [ ] 1.4 Garmin API 重试机制
   637→- [ ] 1.5 SQLite WAL 模式优化
   638→
   639→### Week 2 进度 (0/4)
   640→- [ ] 2.1 编写 ARCHITECTURE.md
   641→- [ ] 2.2 编写 TOOLS_REFERENCE.md
   642→- [ ] 2.3 配置测试覆盖率工具
   643→- [ ] 2.4 添加集成测试
   644→
   645→### Week 3+ (可选)
   646→- [ ] 3.1 健康洞察自动化报告
   647→- [ ] 3.2 Streamlit 仪表板
   648→- [ ] 3.3 数据导出功能
   649→
   650→---
   651→
   652→## 🎯 回来后的第一条命令
   653→
   654→```bash
   655→# 提醒 Claude 继续工作
   656→我回来了，请阅读 docs/REVIEW_AND_ROADMAP.md 和 docs/TODO.md，
   657→让我们开始执行 Week 1 的任务，从 Task 1.1 开始。
   658→```
   659→
   660→---
   661→
   662→## 📝 备注
   663→
   664→- 所有任务都是**非破坏性**的，不会影响现有功能
   665→- 优先级 P0 的任务建议优先完成
   666→- 每个任务完成后建议 git commit
   667→- 测试通过后再 push
   668→
   669→**Good luck! 🚀**
   670→

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>


     1→# 🔍 Butler 项目全面审查报告与规划
     2→
     3→**审查日期**: 2026-01-23
     4→**项目版本**: 当前主要模块完成 (Health, Obsidian, Shell)
     5→**总体评分**: ⭐⭐⭐⭐☆ (4.1/5)
     6→
     7→---
     8→
     9→## 一、总体评价
    10→
    11→你的项目整体架构非常清晰，代码质量很高，完全符合 `CLAUDE.md` 中定义的开发标准。三个主要模块(Health、Obsidian、Shell)职责明确，相互协作良好。这是一个**企业级质量**的个人项目。
    12→
    13→**代码统计**:
    14→- Python 文件: 6297 个 (含 venv)
    15→- 核心代码: ~100 个文件, ~10,601 行
    16→- Health 模块: ~5000 行
    17→- Slack Bot 模块: ~3100 行
    18→- 数据存储: 104MB
    19→
    20→---
    21→
    22→## 二、架构与结构审查
    23→
    24→### ✅ 优势亮点
    25→
    26→#### 1. 清晰的分层架构 (满分)
    27→- **三层分离**: 数据获取层(GarminClient) → 业务逻辑层(Services) → 数据访问层(Repository + Storage)
    28→- **职责单一**: 每个模块都有明确的职责边界
    29→- **依赖注入**: 构造函数支持依赖注入，便于测试
    30→
    31→#### 2. 优秀的设计模式应用
    32→- **Repository Pattern**: `HealthRepository` 封装数据库访问
    33→- **Service Layer Pattern**: `HealthDataSync` 编排业务逻辑
    34→- **Registry Pattern**: `TOOLS_SCHEMA` + `TOOL_FUNCTIONS` 的工具注册表设计非常优雅
    35→- **Strategy Pattern**: LLM 抽象基类 + Gemini 实现
    36→
    37→#### 3. 数据存储策略
    38→- **混合存储**: SQLite 索引 + JSON 文件存储，兼顾查询性能和数据完整性
    39→- **按日期分层**: `2024/01/2024-01-15.json`，易于管理和扩展
    40→- **本地优先**: 隐私安全，无云依赖
    41→
    42→#### 4. 代码质量
    43→- **类型安全**: 全面使用 Pydantic 和类型提示(100% 覆盖率)
    44→- **防御性编程**: 工具执行失败时优雅降级、防幻觉机制、输出截断
    45→- **错误处理**: 自定义异常类，分层错误捕获
    46→
    47→#### 5. 可扩展性
    48→- **模块化工具系统**: 添加新工具只需在 `registry.py` 中注册
    49→- **插件化架构**: Health、Obsidian、Shell 可独立运行
    50→- **双 Bot 架构**: Health Bot 和 Shell Bot 互不干扰
    51→
    52→---
    53→
    54→### ⚠ 需要改进的地方
    55→
    56→#### 1. 代码组织和一致性问题
    57→
    58→**问题 A: 模块边界模糊**
    59→- `slack_bot/obsidian/` 和 `health/services/obsidian.py` 职责重叠
    60→- `health/cli/obsidian.py` 和 `slack_bot/obsidian/cli.py` 功能重复
    61→- **建议**: 将所有 Obsidian 相关代码统一到 `obsidian/` 顶层模块
    62→
    63→**问题 B: Shell 模块归属不清**
    64→- Shell 功能现在在 `slack_bot/shell/`，但它是通用工具，不应只属于 Slack Bot
    65→- **建议**: 提取为独立的 `shell/` 顶层模块
    66→
    67→**问题 C: 配置管理分散**
    68→- `health/config.py`、`health/utils/env_loader.py`、`.env` 三处配置
    69→- **建议**: 统一到 `config/` 模块，使用 Pydantic Settings
    70→
    71→#### 2. 测试覆盖不足
    72→
    73→**当前状态**:
    74→- 有测试框架，但覆盖率不明确
    75→- 缺少集成测试的完整场景覆盖
    76→
    77→**建议**:
    78→```bash
    79→# 添加测试覆盖率工具
    80→pip install pytest-cov
    81→
    82→# 目标: 核心模块 ≥80% 覆盖率
    83→pytest --cov=health --cov=slack_bot --cov-report=html
    84→```
    85→
    86→#### 3. 性能和监控问题
    87→
    88→**问题 A: 缺少性能监控**
    89→- Garmin API 调用无重试计数和超时统计
    90→- LLM 调用无 token 使用量统计
    91→- **建议**: 添加 metrics 收集(可用 Prometheus 或简单的 JSON 日志)
    92→
    93→**问题 B: 上下文管理可能导致性能问题**
    94→- `ContextStorage` 滑动窗口是 40 条消息，但单条消息可能很大
    95→- **建议**: 按 token 数量而非消息数量限制(使用 `tiktoken` 计算)
    96→
    97→**问题 C: 图片下载和处理缺少缓存**
    98→- 每次都重新下载和压缩图片
    99→- **建议**: 添加基于文件 ID 的本地缓存
   100→
   101→#### 4. 错误恢复和可靠性
   102→
   103→**问题 A: Garmin API 失败时缺少重试机制**
   104→- `sync_daily_metric` 遇到 API 错误就跳过，没有指数退避重试
   105→- **建议**: 使用 `tenacity` 库实现智能重试
   106→
   107→**问题 B: Bot 崩溃时无自动重启**
   108→- `scripts/bot_manager.py` 只能手动启动/停止
   109→- **建议**: 集成 `supervisor` 或 `systemd`，实现自动重启
   110→
   111→**问题 C: 数据库锁问题潜在风险**
   112→- SQLite 在高并发写入时可能遇到 `database is locked`
   113→- **建议**: 增加 WAL 模式和超时配置
   114→
   115→#### 5. 文档和注释
   116→
   117→**问题 A: 缺少架构文档**
   118→- README 很好，但缺少 **数据流图** 和 **架构决策记录(ADR)**
   119→- **建议**: 添加 `docs/ARCHITECTURE.md` 和 `docs/DATA_FLOW.md`
   120→
   121→**问题 B: 工具使用文档不够详细**
   122→- 14 个工具的使用场景和示例不够清晰
   123→- **建议**: 添加 `docs/TOOLS_REFERENCE.md`，包含每个工具的使用案例
   124→
   125→#### 6. 安全性
   126→
   127→**问题 A: 敏感信息日志泄露风险**
   128→- `dispatcher.py:342` 中的 `token_masked` 仍可能泄露部分 token
   129→- **建议**: 完全移除 token 日志，或仅在 DEBUG 模式下输出
   130→
   131→**问题 B: Shell 执行风险**
   132→- `execute_shell` 工具没有命令白名单或沙箱
   133→- **建议**: 添加危险命令黑名单(`rm -rf /`, `sudo`, 等)
   134→
   135→**问题 C: 环境变量验证不足**
   136→- `.env` 文件加载后没有验证必需变量是否存在
   137→- **建议**: 使用 Pydantic `BaseSettings` 强制验证
   138→
   139→---
   140→
   141→## 三、逻辑清晰程度评估
   142→
   143→### ✅ 清晰的部分
   144→
   145→1. **Health 数据同步流程** (9/10)
   146→   - 增量同步逻辑清晰: `get_last_sync_date()` → 计算增量 → 同步 → 更新状态
   147→   - 批处理逻辑合理: `split_date_range()` 避免 API 限流
   148→
   149→2. **Slack Bot 消息分发** (8.5/10)
   150→   - 流程清晰: 消息 → 上下文加载 → LLM → 工具执行 → 结果分析 → 响应
   151→   - 防幻觉机制设计良好: 图片下载失败时禁用工具
   152→
   153→3. **工具注册系统** (10/10)
   154→   - `TOOLS_SCHEMA` 和 `TOOL_FUNCTIONS` 的映射关系一目了然
   155→   - 易于扩展: 添加新工具只需三步(定义 schema、实现函数、注册)
   156→
   157→### ⚠ 可以更清晰的部分
   158→
   159→1. **Obsidian 集成逻辑** (6/10)
   160→   - `ObsidianTool.sync_obsidian()` 的具体行为不够明确
   161→   - **建议**: 添加流程图和详细注释
   162→
   163→2. **Analytics 引擎** (7/10)
   164→   - 相关性分析和趋势分析的算法需要更详细的文档
   165→   - **建议**: 添加公式说明和统计学假设
   166→
   167→3. **Shell 会话管理** (6.5/10)
   168→   - PTY 会话的超时和重启逻辑比较复杂
   169→   - **建议**: 添加状态机图
   170→
   171→---
   172→
   173→## 四、优化空间
   174→
   175→### 🚀 短期优化 (1-2周)
   176→
   177→#### 1. 性能优化
   178→
   179→```python
   180→# A. 添加 Garmin API 调用缓存
   181→from functools import lru_cache
   182→from datetime import timedelta
   183→
   184→@lru_cache(maxsize=128)
   185→def fetch_sleep_cached(self, target_date: date) -> Optional[SleepData]:
   186→    # 缓存 1 小时
   187→    ...
   188→
   189→# B. 优化 SQLite 性能
   190→# 在 schema.py 中添加:
   191→PRAGMA journal_mode=WAL;
   192→PRAGMA synchronous=NORMAL;
   193→PRAGMA cache_size=10000;
   194→
   195→# C. 批量插入优化
   196→# repository.py 中使用 executemany
   197→```
   198→
   199→#### 2. 可观测性增强
   200→
   201→```python
   202→# A. 添加结构化日志
   203→import structlog
   204→
   205→logger = structlog.get_logger()
   206→logger.info("sync_completed", metric_type="sleep", records=10, duration_ms=234)
   207→
   208→# B. 添加 Metrics 收集
   209→from dataclasses import dataclass
   210→from datetime import datetime
   211→
   212→@dataclass
   213→class SyncMetrics:
   214→    timestamp: datetime
   215→    metric_type: str
   216→    records_synced: int
   217→    duration_seconds: float
   218→    api_calls: int
   219→    errors: int
   220→```
   221→
   222→#### 3. 配置管理重构
   223→
   224→```python
   225→# config/settings.py (新建)
   226→from pydantic_settings import BaseSettings
   227→
   228→class GarminSettings(BaseSettings):
   229→    email: str
   230→    password: str
   231→
   232→    class Config:
   233→        env_prefix = "GARMIN_"
   234→
   235→class SlackSettings(BaseSettings):
   236→    bot_token: str
   237→    app_token: str
   238→
   239→    class Config:
   240→        env_prefix = "SLACK_"
   241→
   242→class AppSettings(BaseSettings):
   243→    garmin: GarminSettings
   244→    slack: SlackSettings
   245→
   246→# 统一加载
   247→settings = AppSettings()
   248→```
   249→
   250→#### 4. 错误处理增强
   251→
   252→```python
   253→# 使用 tenacity 实现智能重试
   254→from tenacity import retry, stop_after_attempt, wait_exponential
   255→
   256→@retry(
   257→    stop=stop_after_attempt(3),
   258→    wait=wait_exponential(multiplier=1, min=4, max=10),
   259→    reraise=True
   260→)
   261→def fetch_with_retry(self, target_date: date):
   262→    return self.client.get_data(target_date)
   263→```
   264→
   265→---
   266→
   267→### 📈 中期优化 (1-2月)
   268→
   269→#### 1. 数据分析增强
   270→- 添加机器学习预测模型(睡眠质量预测)
   271→- 实现多变量相关性分析
   272→- 添加可视化仪表板(Streamlit 或 Plotly Dash)
   273→
   274→#### 2. 跨平台集成
   275→- 支持 Apple Health 数据导入
   276→- 支持 Google Fit 集成
   277→- 实现数据导出(CSV、PDF 报告)
   278→
   279→#### 3. LLM 能力扩展
   280→- 添加图表生成工具(使用 `matplotlib` 或 `plotly`)
   281→- 实现对话式报告生成
   282→- 添加个性化健康建议引擎
   283→
   284→#### 4. 测试和 CI/CD
   285→
   286→```yaml
   287→# .github/workflows/test.yml
   288→name: Tests
   289→on: [push, pull_request]
   290→jobs:
   291→  test:
   292→    runs-on: ubuntu-latest
   293→    steps:
   294→      - uses: actions/checkout@v2
   295→      - name: Set up Python
   296→        uses: actions/setup-python@v2
   297→        with:
   298→          python-version: '3.12'
   299→      - name: Install dependencies
   300→        run: |
   301→          pip install -r requirements.txt
   302→          pip install pytest pytest-cov
   303→      - name: Run tests
   304→        run: pytest --cov --cov-report=xml
   305→      - name: Upload coverage
   306→        uses: codecov/codecov-action@v2
   307→```
   308→
   309→---
   310→
   311→### 🎯 长期规划 (3-6月)
   312→
   313→#### 1. 架构演进
   314→
   315→**当前架构**: Monolith (单体应用)
   316→**目标架构**: Modular Monolith (模块化单体)
   317→
   318→```
   319→butler/
   320→├── packages/
   321→│   ├── health/           # 独立包
   322→│   ├── obsidian/         # 独立包
   323→│   ├── shell/            # 独立包
   324→│   ├── llm/              # 独立包
   325→│   └── analytics/        # 独立包
   326→├── apps/
   327→│   ├── slack_bot/        # 应用层
   328→│   ├── cli/              # CLI 应用
   329→│   └── web/              # Web Dashboard (新)
   330→└── shared/
   331→    ├── config/
   332→    ├── db/
   333→    └── utils/
   334→```
   335→
   336→#### 2. Web Dashboard
   337→- **技术栈**: Next.js + Tailwind CSS
   338→- **功能**:
   339→  - 健康数据可视化
   340→  - 手动记录界面
   341→  - 分析报告查看
   342→  - LLM 聊天界面
   343→
   344→#### 3. 知识图谱构建
   345→- 使用 Neo4j 构建健康数据知识图谱
   346→- 关系: 补剂 → 影响 → 睡眠质量
   347→- 支持复杂查询: "哪些因素组合对 HRV 有正面影响?"
   348→
   349→#### 4. 多用户支持
   350→- 用户认证和授权
   351→- 数据隔离
   352→- 共享分析模板
   353→
   354→---
   355→
   356→## 五、详细任务清单
   357→
   358→### 🔧 技术债务清理
   359→
   360→| 优先级 | 任务 | 估时 | 类别 | 文件位置 |
   361→|-------|------|------|------|---------|
   362→| P0 | 添加 Garmin API 重试机制 | 2h | 可靠性 | `health/services/data_sync.py` |
   363→| P0 | 修复敏感信息日志泄露 | 1h | 安全 | `slack_bot/dispatcher.py:342` |
   364→| P0 | 添加环境变量验证 | 1h | 安全 | `health/utils/env_loader.py` |
   365→| P0 | Shell 命令黑名单 | 1h | 安全 | `slack_bot/tools/shell_tool.py` |
   366→| P1 | 重构配置管理(Pydantic Settings) | 4h | 架构 | 新建 `config/settings.py` |
   367→| P1 | 统一 Obsidian 模块位置 | 3h | 架构 | 重组文件结构 |
   368→| P1 | 提取 Shell 为独立模块 | 3h | 架构 | 移动 `slack_bot/shell/` |
   369→| P1 | 添加测试覆盖率报告 | 2h | 质量 | 配置 pytest-cov |
   370→| P2 | SQLite 性能优化(WAL 模式) | 1h | 性能 | `health/db/schema.py` |
   371→| P2 | 上下文按 token 数量限制 | 2h | 性能 | `slack_bot/context/storage.py` |
   372→| P2 | 图片下载缓存 | 2h | 性能 | `slack_bot/dispatcher.py` |
   373→
   374→### 🆕 新功能开发
   375→
   376→| 优先级 | 功能 | 估时 | 价值 | 描述 |
   377→|-------|------|------|------|------|
   378→| P0 | 健康洞察自动化报告(每周) | 1天 | 高 | 自动生成周报并发送到 Slack |
   379→| P0 | 添加血压、血糖指标支持 | 0.5天 | 高 | 扩展健康指标类型 |
   380→| P1 | Streamlit 数据可视化仪表板 | 3天 | 高 | 交互式数据探索界面 |
   381→| P1 | CSV/PDF 数据导出 | 2天 | 中 | 支持数据导出和分享 |
   382→| P1 | 睡眠质量预测模型(ML) | 5天 | 高 | 使用 scikit-learn 预测 |
   383→| P2 | Apple Health 集成 | 4天 | 中 | 导入 Apple Health 数据 |
   384→| P2 | 语音记录功能(Whisper) | 3天 | 中 | 语音输入饮食记录 |
   385→| P2 | 移动端 PWA | 10天 | 低 | 渐进式 Web 应用 |
   386→
   387→### 📚 文档和流程
   388→
   389→| 优先级 | 任务 | 估时 | 输出文件 |
   390→|-------|------|------|----------|
   391→| P0 | 编写架构文档 | 2h | `docs/ARCHITECTURE.md` |
   392→| P0 | 编写工具参考文档 | 2h | `docs/TOOLS_REFERENCE.md` |
   393→| P1 | 添加数据流图 | 1h | `docs/DATA_FLOW.md` |
   394→| P1 | 添加贡献指南 | 1h | `CONTRIBUTING.md` |
   395→| P1 | 录制使用演示视频 | 2h | YouTube/私有链接 |
   396→| P2 | 设置 CI/CD 流程 | 3h | `.github/workflows/` |
   397→
   398→---
   399→
   400→## 六、立即行动建议(回来后优先执行)
   401→
   402→### 第一周: 安全和稳定性 (6小时)
   403→
   404→**Day 1-2: 安全修复 (3小时)**
   405→1. ✅ 修复敏感信息日志泄露 (1h)
   406→   - 文件: `slack_bot/dispatcher.py`
   407→   - 移除或条件化 token 日志
   408→
   409→2. ✅ 添加环境变量验证 (1h)
   410→   - 文件: 新建 `config/settings.py`
   411→   - 使用 Pydantic BaseSettings
   412→
   413→3. ✅ Shell 命令黑名单 (1h)
   414→   - 文件: `slack_bot/tools/shell_tool.py`
   415→   - 拒绝危险命令执行
   416→
   417→**Day 3-4: 可靠性增强 (3小时)**
   418→4. ✅ 添加 Garmin API 重试机制 (2h)
   419→   - 文件: `health/services/data_sync.py`
   420→   - 安装 tenacity: `pip install tenacity`
   421→   - 实现智能重试
   422→
   423→5. ✅ SQLite WAL 模式优化 (1h)
   424→   - 文件: `health/db/schema.py`
   425→   - 添加性能 PRAGMA
   426→
   427→### 第二周: 文档和测试 (8小时)
   428→
   429→**Day 1-2: 核心文档 (4小时)**
   430→6. ✅ 编写 `ARCHITECTURE.md` (2h)
   431→7. ✅ 编写 `TOOLS_REFERENCE.md` (2h)
   432→
   433→**Day 3-5: 测试覆盖 (4小时)**
   434→8. ✅ 配置测试覆盖率工具 (2h)
   435→   - 安装: `pip install pytest-cov`
   436→   - 运行: `pytest --cov=health --cov=slack_bot --cov-report=html`
   437→   - 分析并提升覆盖率到 60%+
   438→
   439→9. ✅ 添加关键路径集成测试 (2h)
   440→   - 测试: Garmin 同步流程
   441→   - 测试: Slack Bot 消息处理
   442→
   443→### 第三周+: 功能增强 (按需选择)
   444→
   445→根据实际需求从"新功能开发"清单中选择优先级最高的功能开发。
   446→
   447→---
   448→
   449→## 七、评分卡
   450→
   451→```
   452→架构设计:   ⭐⭐⭐⭐⭐ 5/5
   453→代码质量:   ⭐⭐⭐⭐⭐ 5/5
   454→功能完整性: ⭐⭐⭐⭐☆ 4/5
   455→可维护性:   ⭐⭐⭐⭐☆ 4/5
   456→性能优化:   ⭐⭐⭐☆☆ 3/5
   457→测试覆盖:   ⭐⭐⭐☆☆ 3/5
   458→文档质量:   ⭐⭐⭐☆☆ 3/5
   459→安全性:     ⭐⭐⭐⭐☆ 4/5
   460→
   461→总体评分:   ⭐⭐⭐⭐☆ 4.1/5
   462→```
   463→
   464→---
   465→
   466→## 八、结论
   467→
   468→这是一个**非常优秀**的个人项目，已经达到了**企业级代码质量标准**。主要优势在于清晰的架构设计、完善的类型系统和良好的可扩展性。
   469→
   470→**继续优化方向**:
   471→1. 提升可靠性(重试、监控)
   472→2. 增强安全性(验证、日志清理)
   473→3. 补充文档(架构图、工具手册)
   474→4. 提高测试覆盖率
   475→5. 添加性能监控
   476→
   477→按照上述规划逐步优化，可以成为一个**开源示范项目**。
   478→
   479→---
   480→
   481→**下次会话开始命令**:
   482→```
   483→我回来了，请阅读 docs/REVIEW_AND_ROADMAP.md 和 docs/TODO.md，
   484→让我们开始执行第一周的安全和稳定性改进任务。
   485→```
   486→

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>


Perfect! I've found all the planning-related documentation. Let me provide you with a comprehensive summary:

## Summary of Planning Documents in Butler Project

I found **three main planning/documentation files** in `/root/projects/butler`:

### 1. **`/root/projects/butler/docs/TODO.md`** (Last updated: 2026-03-02)
This is the **primary task list** organized by week and priority:

**Structure**:
- **Week 1 (6 hours)**: Security & Stability
  - ✅ Task 1.1: Fix sensitive info logging leak (1h) - P0
  - ✅ Task 1.2: Add environment variable validation (1h) - P0
  - ✅ Task 1.3: Shell command blacklist (1h) - P0
  - ✅ Task 1.4: Add Garmin API retry mechanism (2h) - P0
  - ✅ Task 1.5: SQLite WAL mode optimization (1h) - P0

- **Week 2 (8 hours)**: Documentation & Testing
  - [ ] Task 2.1: Write ARCHITECTURE.md (2h) - P0
  - [ ] Task 2.2: Write TOOLS_REFERENCE.md (2h) - P0
  - [ ] Task 2.3: Configure test coverage tool (2h) - P1
  - [ ] Task 2.4: Add integration tests (2h) - P1

- **Week 3+ (Optional)**: Feature Enhancements
  - [ ] Feature 3.1: Health insights automated reports (1 day) - P0
  - [ ] Feature 3.2: Streamlit dashboard (3 days) - P1
  - [ ] Feature 3.3: Data export functionality (2 days) - P1

**Progress**: Week 1 tasks are marked as **complete** (✅), Week 2+ still pending.

---

### 2. **`/root/projects/butler/docs/REVIEW_AND_ROADMAP.md`** (Review date: 2026-01-23)
This is a **comprehensive architecture review and planning document** (~486 lines):

**Key Sections**:

| Section | Content |
|---------|---------|
| **Overall Assessment** | 4.1/5 stars - Enterprise-grade code quality |
| **Architecture Strengths** | Clear 3-layer separation, excellent design patterns, hybrid storage (SQLite + JSON), 100% type safety |
| **Areas for Improvement** | Module boundary clarity, test coverage insufficiency, performance monitoring gaps, error recovery limitations |
| **Optimization Timeline** | Short-term (1-2 weeks), Medium-term (1-2 months), Long-term (3-6 months) |
| **Detailed Task List** | Tech debt cleanup + New features with time estimates |
| **Scorecard** | 8 categories rated (Architecture 5/5, Code Quality 5/5, Testing 3/5, Documentation 3/5, etc.) |

---

### 3. **`/root/projects/butler/BOT_FEATURES_REFERENCE.md`** (Updated: 2026-01-30)
This is a **quick reference manual** for all bot functionality:

**Bot Architecture**:
- **Health Bot**: 14 tools for health data (4 read, 5 write, 2 sync, 2 analysis, 1 search)
- **Shell Bot**: System management (execute shell, file ops, process management)
- **Powellllll Bot**: Writing assistant + knowledge (4 modes: write, reply, decide, search)

**Key Features Documented**:
- Detailed tool specifications with examples
- Usage scenarios for each tool
- Mode switching commands for Powellllll Bot
- Failsafe commands (gmode, bot management)
- Best practices and common use cases

---

### Additional Archive Files:
- `/root/projects/butler/tag20260215/docs/TODO.md` - Old backup from 2026-02-15
- `/root/projects/butler/tag20260215/docs/REVIEW_AND_ROADMAP.md` - Old backup
- `/root/projects/butler/tag20260302/docs/TODO.md` - Snapshot after migration
- `/root/projects/butler/tag20260302/docs/REVIEW_AND_ROADMAP.md` - Snapshot

---

## Current Status Summary

Based on the MEMORY context:
- **Week 1 P0 tasks**: ALL COMPLETED ✅ (security & reliability improvements)
- **Week 2 tasks**: Pending (architecture & test documentation)
- **Feature 3.1**: COMPLETED ✅ (weekly health report automation)
- **Next Priority**: Week 2 documentation tasks (ARCHITECTURE.md, TOOLS_REFERENCE.md)

The project has a clear, well-structured roadmap with all files using consistent formatting and tracking progress transparently.