# Tools Reference

**最后更新**: 2026-03-02
**参考**: `docs/ARCHITECTURE.md` | `slack_bot/tools/registry.py`

---

## 概览

Butler Bot 共提供 **21 个工具**，分 6 类。不同工具模式加载不同子集：

| 模式 | 工具数 | 包含类别 |
|------|--------|---------|
| `light` | 6 | 健康读取(2) + 写入(2) + 同步(1) + 网络(1) |
| `standard` | 10 | light + 健康读取(+2) + 写入(+2) + 分析(+1) |
| `full` | 15 | standard + 分析(+1) + 同步(+1) + 写入(+1) + 读取(+1) |
| `all` | 21 | full + Shell(+1) + 文件(+2) + 系统(+3) |

> 当前配置: `TOOL_MODE=all`（见 `.env`）

---

## 一、健康读取工具 (5个)

### 1. `get_daily_detailed_stats`

**用途**: 获取某天的完整健康摘要（指标 + 活动 + 手动日志计数）。

**适用场景**:
- "昨天睡得怎么样？"
- "2026-03-01 的健康数据"
- "今天的身体状态"

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `target_date` | string | ✅ | `YYYY-MM-DD` |

**示例调用**:
```json
{"target_date": "2026-03-01"}
```

**返回字段**: sleep_score, resting_heart_rate, hrv_value, stress_level, total_steps, body_battery, activities 列表, manual_logs 计数

---

### 2. `get_metric_history`

**用途**: 获取某指标的历史趋势，≤7天返回原始数据，>7天返回统计分析。

**适用场景**:
- "过去7天的睡眠"
- "最近2个月的静息心率"
- "上周的步数"

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `metric_type` | string | ✅ | `rhr`, `hrv`, `sleep`, `stress`, `steps`, `heart_rate`, `weight` |
| `start_date` | string | ✅ | `YYYY-MM-DD` |
| `end_date` | string | ✅ | `YYYY-MM-DD` |

**示例调用**:
```json
{
  "metric_type": "sleep",
  "start_date": "2026-02-01",
  "end_date": "2026-03-01"
}
```

---

### 3. `get_activity_history`

**用途**: 获取某时间段内的运动/锻炼记录列表。

**适用场景**:
- "过去2周我跑了几次步？"
- "上个月的运动记录"

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `start_date` | string | ✅ | `YYYY-MM-DD` |
| `end_date` | string | ✅ | `YYYY-MM-DD` |

**示例调用**:
```json
{
  "start_date": "2026-02-15",
  "end_date": "2026-03-01"
}
```

**返回字段**: 每条活动包含 activity_type, date, duration_seconds, distance_meters, calories, avg_heart_rate

---

### 4. `get_manual_history`

**用途**: 查询手动记录的日志（饮食、酒精、补剂、身体感受、断食）。

**适用场景**:
- "过去一周吃了什么？"
- "这个月喝了几次酒？"
- "最近服用了哪些补剂？"

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `start_date` | string | ✅ | `YYYY-MM-DD` |
| `end_date` | string | ✅ | `YYYY-MM-DD` |
| `category` | string | ❌ | `diet`, `alcohol`, `supplements`, `feelings`, `fasting`, `all`（默认 `all`） |

**示例调用**:
```json
{
  "start_date": "2026-02-01",
  "end_date": "2026-03-01",
  "category": "alcohol"
}
```

---

### 5. `get_aggregated_analysis`

**用途**: 长时间范围聚合分析，含趋势统计、30天滚动均值、年度对比。优于 `get_metric_history` 的长期分析场景。

**适用场景**:
- "过去2个月的 RHR 趋势"
- "今年 HRV 变化"
- "最近90天的睡眠质量"

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `start_date` | string | ❌ | `YYYY-MM-DD`（默认2年前） |
| `end_date` | string | ❌ | `YYYY-MM-DD`（默认今天） |
| `metrics` | array | ❌ | 指定指标列表，如 `["rhr", "hrv", "sleep"]`（默认全部） |

**示例调用**:
```json
{
  "start_date": "2026-01-01",
  "end_date": "2026-03-01",
  "metrics": ["rhr", "sleep"]
}
```

---

## 二、健康写入工具 (5个)

### 6. `log_diet`

**用途**: 记录饮食/餐食。

**适用场景**:
- "午饭吃了鸡胸肉和米饭"
- "记录早餐：燕麦+蓝莓"

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `target_date` | string | ✅ | `YYYY-MM-DD` |
| `description` | string | ✅ | 食物描述 |
| `meal_type` | string | ❌ | `breakfast`, `lunch`, `dinner`, `snack`（默认 `snack`） |
| `time` | string | ❌ | `HH:MM` |

**示例调用**:
```json
{
  "target_date": "2026-03-02",
  "description": "鸡胸肉 200g + 糙米",
  "meal_type": "lunch",
  "time": "12:30"
}
```

---

### 7. `log_alcohol`

**用途**: 记录酒精摄入。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `target_date` | string | ✅ | `YYYY-MM-DD` |
| `alcohol_type` | string | ✅ | 酒的种类（如 "红酒"、"啤酒"） |
| `amount` | string | ✅ | 摄入量（如 "200ml"、"1 pint"） |
| `time` | string | ❌ | `HH:MM` |

**示例调用**:
```json
{
  "target_date": "2026-03-01",
  "alcohol_type": "红酒",
  "amount": "200ml",
  "time": "19:30"
}
```

---

### 8. `log_supplement`

**用途**: 记录补剂/营养素摄入。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `target_date` | string | ✅ | `YYYY-MM-DD` |
| `name` | string | ✅ | 补剂名称（如 "镁"、"NAD+"、"Omega-3"） |
| `dosage` | string | ✅ | 剂量（如 "400mg"、"1粒"） |
| `time` | string | ❌ | `HH:MM` |

**示例调用**:
```json
{
  "target_date": "2026-03-02",
  "name": "镁",
  "dosage": "400mg",
  "time": "07:00"
}
```

---

### 9. `log_feeling`

**用途**: 记录身体感受或症状。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `target_date` | string | ✅ | `YYYY-MM-DD` |
| `feeling_type` | string | ✅ | 症状类型（如 "头痛"、"疲劳"、"精力充沛"） |
| `severity` | integer | ✅ | 严重程度 1-10（1=轻微，10=极重） |
| `description` | string | ✅ | 详细描述 |
| `time` | string | ❌ | `HH:MM` |

**示例调用**:
```json
{
  "target_date": "2026-03-02",
  "feeling_type": "头痛",
  "severity": 4,
  "description": "下午轻微头痛，可能是睡眠不足",
  "time": "15:00"
}
```

---

### 10. `log_fasting`

**用途**: 记录断食模式。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `target_date` | string | ✅ | `YYYY-MM-DD` |
| `mode` | string | ✅ | 断食模式，如 `OMAD`、`PSMF`、`16:8`、`24h` |

**示例调用**:
```json
{
  "target_date": "2026-03-02",
  "mode": "OMAD"
}
```

---

## 三、同步工具 (2个)

### 11. `sync_garmin`

**用途**: 从 Garmin Connect 同步最新健康数据到本地。**用户说"同步"、"更新数据"、"拉取数据"时必须调用。**

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `target_date` | string | ❌ | `YYYY-MM-DD`（默认今天） |

**示例调用**:
```json
{}
```
或指定日期:
```json
{"target_date": "2026-03-01"}
```

**同步范围**: 14 种健康指标 + 活动数据，自动增量同步（仅同步上次以后的新数据）。

---

### 12. `sync_obsidian`

**用途**: 同步 Obsidian 笔记 Vault（索引或生成每日笔记）。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `target_date` | string | ✅ | `YYYY-MM-DD` |

**示例调用**:
```json
{"target_date": "2026-03-02"}
```

---

## 四、分析工具 (2个)

### 13. `get_health_insights`

**用途**: 获取高级健康洞察和多指标关联分析。

**适用场景**:
- "最近酒精对我睡眠的影响？"
- "我的心肺健康趋势怎样？"
- "断食对身体有什么影响？"

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `analysis_type` | string | ✅ | `recovery_correlations`（酒精/活动对恢复的影响）、`fitness_trends`（RHR/体能趋势）、`lifestyle_impact`（断食/补剂影响） |
| `lookback_days` | integer | ❌ | 分析天数（默认30，建议30-90） |

**示例调用**:
```json
{
  "analysis_type": "recovery_correlations",
  "lookback_days": 60
}
```

---

### 14. `analyze_driver`

**用途**: 分析某个因素（driver）是否影响某个健康指标（target）。适用于因果关系探索。

**适用场景**:
- "镁补剂是否改善了睡眠？"
- "步数多的天 HRV 更高吗？"
- "酒精单位数和睡眠分数的相关性"

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `driver_metric` | string | ✅ | 原因指标。连续值: `alcohol_units`, `stress`, `steps`；事件: `fasting_mode`, `has_magnesium`, `has_alcohol` |
| `target_metric` | string | ✅ | 结果指标: `sleep`, `rhr`, `hrv`, `body_battery` |
| `method` | string | ✅ | `correlation`（连续值相关性）或 `group_compare`（有/无对比） |
| `lookback_days` | integer | ❌ | 分析天数（默认30） |

**示例调用**（镁 vs 睡眠）:
```json
{
  "driver_metric": "has_magnesium",
  "target_metric": "sleep",
  "method": "group_compare",
  "lookback_days": 60
}
```

**示例调用**（酒精 vs 睡眠相关性）:
```json
{
  "driver_metric": "alcohol_units",
  "target_metric": "sleep",
  "method": "correlation",
  "lookback_days": 30
}
```

---

## 五、网络工具 (1个)

### 15. `search_web`

**用途**: 搜索网络获取实时信息、最新研究或生物黑客经验。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | ✅ | 搜索关键词 |

**示例调用**:
```json
{"query": "NAD+ supplement sleep quality research 2025"}
```

---

## 六、系统工具 (6个，仅 `all` 模式)

### 16. `execute_shell`

**用途**: 在持久 shell session 中执行系统命令。

> ⚠️ 此工具已启用命令黑名单，危险命令（rm -rf /、mkfs 等）会被拦截。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `command` | string | ✅ | 要执行的命令 |
| `timeout` | number | ❌ | 超时秒数（默认2.0，长命令可增大） |

**示例调用**:
```json
{"command": "df -h", "timeout": 5.0}
```

---

### 17. `download_file`

**用途**: 将服务器上的文件上传到 Slack（供用户查看日志、配置等）。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_path` | string | ✅ | 服务器上的绝对路径 |

**示例调用**:
```json
{"file_path": "/root/projects/butler/logs/slack_bot.log"}
```

---

### 18. `save_file`

**用途**: 在服务器上创建或编辑文本文件。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_path` | string | ✅ | 目标绝对路径 |
| `content` | string | ✅ | 文件内容 |
| `overwrite` | boolean | ❌ | 是否覆盖已有文件（默认 false） |

---

### 19. `get_system_status`

**用途**: 获取系统健康仪表盘（CPU、内存、磁盘、Top 进程）。

**参数**: 无

**示例调用**:
```json
{}
```

---

### 20. `kill_process`

**用途**: 通过 PID 终止进程。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `pid` | integer | ✅ | 进程 ID |
| `signal_type` | string | ❌ | `SIGTERM`（默认，优雅停止）或 `SIGKILL`（强制） |

---

### 21. `get_process_list`

**用途**: 列出运行中的进程，支持名称过滤。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `filter_name` | string | ❌ | 按进程名过滤（不区分大小写） |
| `limit` | integer | ❌ | 返回条数上限（默认15） |

**示例调用**:
```json
{"filter_name": "python", "limit": 10}
```

---

## 附录：工具分组对照

| 工具名 | light | standard | full | all |
|--------|-------|----------|------|-----|
| get_daily_detailed_stats | ✅ | ✅ | ✅ | ✅ |
| get_metric_history | ✅ | ✅ | ✅ | ✅ |
| get_activity_history | | ✅ | ✅ | ✅ |
| get_manual_history | | ✅ | ✅ | ✅ |
| get_aggregated_analysis | | | ✅ | ✅ |
| log_diet | ✅ | ✅ | ✅ | ✅ |
| log_supplement | ✅ | ✅ | ✅ | ✅ |
| log_alcohol | | ✅ | ✅ | ✅ |
| log_feeling | | ✅ | ✅ | ✅ |
| log_fasting | | | ✅ | ✅ |
| sync_garmin | ✅ | ✅ | ✅ | ✅ |
| sync_obsidian | | | ✅ | ✅ |
| get_health_insights | | ✅ | ✅ | ✅ |
| analyze_driver | | | ✅ | ✅ |
| search_web | ✅ | ✅ | ✅ | ✅ |
| execute_shell | | | | ✅ |
| download_file | | | | ✅ |
| save_file | | | | ✅ |
| get_system_status | | | | ✅ |
| kill_process | | | | ✅ |
| get_process_list | | | | ✅ |