介绍
# Garmin Health Analysis
从 Garmin Connect 查询健康指标并生成交互式 HTML 图表。
## 两种安装路径
此技能支持 **两种不同的设置**：
1. **Clawdbot 技能**（本指南） - 配合 Clawdbot 使用，实现自动化和主动健康监控 2. **MCP 服务器**（[参见 MCP 设置指南](references/mcp_setup.md)） - 作为 MCP 服务器配合标准 Claude Desktop 使用
选择符合您用例的路径。您也可以同时使用两者！
---
## Clawdbot 技能设置（仅需首次）
### 1. 安装依赖
```bash pip3 install garminconnect ```
### 2. 配置凭据
您可以通过三种方式提供您的 Garmin Connect 凭据：
#### 选项 A：Clawdbot 配置（推荐 - UI 可配置）
将凭据添加到 `~/.clawdbot/clawdbot.json`：
```json { "skills": { "entries": { "garmin-health-analysis": { "enabled": true, "env": { "GARMIN_EMAIL": "[email protected]", "GARMIN_PASSWORD": "your-password" } } } } } ```
**提示**：您也可以通过 Clawdbot UI 的 Skills 设置面板进行设置。
#### 选项 B：本地配置文件
在技能目录中创建配置文件：
```bash cd ~/.clawdbot/skills/garmin-health-analysis # or: cd <workspace>/skills/garmin-health-analysis cp config.example.json config.json # Edit config.json and add your email and password ```
**config.json:** ```json { "email": "[email protected]", "password": "your-password" } ```
**注意**：`config.json` 已被 git 忽略，以确保您的凭据安全。
#### 选项 C：命令行
在身份验证时直接传递凭据： ```bash python3 scripts/garmin_auth.py login \ --email [email protected] \ --password YOUR_PASSWORD ```
### 3. 身份验证
登录 Garmin Connect 并保存会话令牌：
```bash python3 scripts/garmin_auth.py login ```
这将按优先级顺序使用来自以下位置的凭据： 1. 命令行参数（`--email`，`--password`） 2. 本地配置文件（`config.json`） 3. 环境变量（`GARMIN_EMAIL`，`GARMIN_PASSWORD`） 4. Clawdbot 配置（`skills.entries.garmin-health-analysis.env`）
会话令牌存储在 `~/.clawdbot/garmin-tokens.json` 中并自动刷新。
检查身份验证状态： ```bash python3 scripts/garmin_auth.py status ```
## 获取数据
使用 `scripts/garmin_data.py` 获取 JSON 数据：
```bash # Sleep (last 7 days default) python3 scripts/garmin_data.py sleep --days 14
# Body Battery (Garmin's recovery metric) python3 scripts/garmin_data.py body_battery --days 30
# HRV data python3 scripts/garmin_data.py hrv --days 30
# Heart rate (resting, max, min) python3 scripts/garmin_data.py heart_rate --days 7
# Activities/workouts python3 scripts/garmin_data.py activities --days 30
# Stress levels python3 scripts/garmin_data.py stress --days 7
# Combined summary with averages python3 scripts/garmin_data.py summary --days 7
# Custom date range python3 scripts/garmin_data.py sleep --start 2026-01-01 --end 2026-01-15
# User profile python3 scripts/garmin_data.py profile ```
输出为 JSON 格式到 stdout。解析它以回答用户问题。
## 生成图表
使用 `scripts/garmin_chart.py` 进行交互式 HTML 可视化：
```bash # Sleep analysis (hours + scores) python3 scripts/garmin_chart.py sleep --days 30
# Body Battery recovery chart (color-coded) python3 scripts/garmin_chart.py body_battery --days 30
# HRV & resting heart rate trends python3 scripts/garmin_chart.py hrv --days 90
# Activities summary (by type, calories) python3 scripts/garmin_chart.py activities --days 30
# Full dashboard (all 4 charts) python3 scripts/garmin_chart.py dashboard --days 30
# Save to specific file python3 scripts/garmin_chart.py dashboard --days 90 --output ~/Desktop/garmin-health.html ```
图表会自动在默认浏览器中打开。它们使用 Chart.js，采用现代渐变设计、统计卡片和交互式工具提示。
## 回答问题
| 用户询问 | 操作 | |-----------|--------| | "我昨晚睡得怎么样？" | `garmin_data.py summary --days 1`，报告睡眠时长 + 分数 | | "我本周恢复得如何？" | `garmin_data.py body_battery --days 7`，报告平均值 + 趋势 | | "显示我上个月的健康状况" | `garmin_chart.py dashboard --days 30` | | "我的 HRV 有改善吗？" | `garmin_data.py hrv --days 30`，分析趋势 | | "我本周做了哪些锻炼？" | `garmin_data.py activities --days 7`，列出详细活动 | | "我的静息心率怎么样？" | `garmin_data.py heart_rate --days 7`，报告平均值 + 趋势 |
## 关键指标
### 身体电量 (0-100)
Garmin 基于心率变异性 (HRV)、压力、睡眠和活动的专有恢复指标： - **高 (75-100)**：完全充电，准备好进行高强度运动 - **中 (50-74)**：能量适中，适合常规活动 - **低 (25-49)**：能量有限，需要恢复 - **极低 (0-24)**：耗尽，优先休息
### 睡眠评分 (0-100)
基于时长、阶段和干扰的整体睡眠质量： - **优秀 (90-100)**：最佳的恢复性睡眠 - **良好 (80-89)**：高质量的睡眠，存在轻微问题 - **一般 (60-79)**：尚可但有改进空间 - **较差 (0-59)**：存在显著的睡眠不足
### HRV（心率变异性）
以毫秒为单位测量，通常越高越好： - 表明神经系统平衡和恢复能力 - 随时间追踪 **趋势**（增加 = 恢复改善） - 受睡眠、压力、训练负荷和疾病影响 - 正常范围因人而异（20-200+ ms）
### 静息心率 (bpm)
通常越低表明心血管健康状况越好： - **运动员**：40-60 bpm - **健身成年人**：60-70 bpm - **普通成年人**：70-80 bpm - 突然升高可能表明压力、疾病或过度训练
### 压力水平
基于全天 HRV 分析： - **低压力**：休息和恢复期 - **中等压力**：正常日常活动 - **高压力**：身体活动或精神压力
## 健康分析
当用户询问见解或想要了解其趋势时，使用 `references/health_analysis.md` 进行： - 所有指标的科学解读 - 按年龄和健身水平划分的正常范围 - 模式检测（每周趋势、恢复周期、训练负荷平衡） - 基于数据的可行建议 - 表明需要休息或医疗咨询的警告信号
### 分析工作流程 1. 获取数据：`python3 scripts/garmin_data.py summary --days N` 2. 阅读 `references/health_analysis.md` 了解解读框架 3. 应用分析框架：状态 → 趋势 → 模式 → 见解 → 建议 4. 始终包含免责声明，说明这仅供参考，并非医疗建议
## 故障排除
### 身份验证问题 - **"Invalid credentials"（无效凭据）**：检查电子邮件/密码，尝试登录 Garmin Connect 网页版 - **"Tokens expired"（令牌过期）**：再次运行登录：`python3 scripts/garmin_auth.py login ...` - **"Too many requests"（请求过多）**：Garmin 限流；等待几分钟并重试
### 数据缺失 - 某些指标需要特定的 Garmin 设备（身体电量需要支持 HRV 的设备） - 如果设备未佩戴，历史数据可能有缺口 - 新账户的历史记录可能有限
### 库问题 - 如果 `garminconnect` 导入失败：`pip3 install --upgrade garminconnect` - Garmin 偶尔会更改其 API；如果请求失败，请更新该库
## 隐私说明
- 凭据本地存储在 `~/.clawdbot/garmin-tokens.json` 中 - 会话令牌自动刷新 - 除 Garmin 官方服务器外，数据不会发送到任何地方 - 您可以通过删除令牌文件随时撤销访问权限
## 对比：Garmin vs Whoop
| 功能 | Garmin | Whoop | |---------|--------|-------| | **恢复指标** | Body Battery (0-100) | Recovery Score (0-100%) | | **HRV 追踪** | 是（夜间平均值） | 是（详细） | | **睡眠阶段** | 浅睡、深睡、REM、清醒 | 浅睡、SWS、REM、清醒 | | **活动追踪** | 内置 GPS，多种运动模式 | 压力分数 (0-21) | | **压力** | 全天压力水平 | 未直接追踪 | | **API** | 非官方 | 官方 OAuth | | **设备类型** | 手表、健身追踪器 | 仅可穿戴手环 |
## 参考资料
- `references/api.md` — Garmin Connect API 详细信息（非官方） - `references/health_analysis.md` — 基于科学的健康数据解读 - [garminconnect library](https://github.com/cyberjunky/python-garminconnect) — Python API 封装器 - [Garmin Connect](https://connect.garmin.com) — 官方网页界面
## 版本信息
- **创建日期**：2026-01-25 - **作者**：EversonL & Claude - **版本**：1.2.0 - **依赖项**：garminconnect, fitparse, gpxpy (Python 库) - **许可证**：MIT