名称： garmin-health-analysis
描述： 用自然语言与你的 Garmin 数据对话——“我滑雪的最快速度是多少？”、“昨晚睡得怎么样？”、“下午3点我的心率是多少？”。访问 20+ 项指标（睡眠阶段、身体电量、HRV、最大摄氧量、训练准备度、身体成分、血氧），下载 FIT/GPX 文件进行路线分析，查询任意点的海拔/配速，并生成交互式健康仪表盘。从简单的“显示本周的锻炼”到深入的“分析我的恢复与训练负荷”。
版本： 1.2.2
作者： EversonL & Claude
主页： https://github.com/eversonl/ClawdBot-garmin-health-analysis
元数据： {"clawdbot":{"emoji":"⌚","requires":{"env":["GARMIN_EMAIL","GARMIN_PASSWORD"]},"install":[{"id":"garminconnect","kind":"python","package":"garminconnect","label":"安装 garminconnect (pip)"},{"id":"fitparse","kind":"python","package":"fitparse","label":"安装 fitparse (pip)"},{"id":"gpxpy","kind":"python","package":"gpxpy","label":"安装 gpxpy (pip)"}]}}

Garmin 健康数据分析

从 Garmin Connect 查询健康指标并生成交互式 HTML 图表。

两种安装路径

本技能支持 两种不同的设置方式：

1. ClawdBot 技能（本指南）- 与 ClawdBot 配合使用，实现自动化和主动健康监测
2. MCP 服务器（查看 MCP 设置指南）- 作为 MCP 服务器与标准 Claude Desktop 配合使用

请根据您的使用场景选择合适的路径。您也可以同时使用两者！

ClawdBot 技能设置（仅首次需要）

1. 安装依赖

pip3 install garminconnect

2. 配置凭据

您有三种方式提供 Garmin Connect 凭据：

选项 A：ClawdBot 配置（推荐 - 可通过 UI 配置）

将凭据添加到 ~/.clawdbot/clawdbot.json：

{
  "skills": {
    "entries": {
      "garmin-health-analysis": {
        "enabled": true,
        "env": {
          "GARMIN_EMAIL": "your-email@example.com",
          "GARMIN_PASSWORD": "your-password"
        }
      }
    }
  }
}

提示：您也可以通过 ClawdBot UI 的技能设置面板进行配置。

选项 B：本地配置文件

在技能目录中创建配置文件：

cd ~/.clawdbot/skills/garmin-health-analysis
# 或：cd <workspace>/skills/garmin-health-analysis
cp config.example.json config.json
# 编辑 config.json 并添加您的邮箱和密码

config.json:

{
  "email": "your-email@example.com",
  "password": "your-password"
}

注意：config.json 已加入 gitignore 以确保凭据安全。

选项 C：命令行

在认证时直接传递凭据：

python3 scripts/garmin_auth.py login \
  --email YOUR_EMAIL@example.com \
  --password YOUR_PASSWORD

3. 认证

登录 Garmin Connect 并保存会话令牌：

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 中并会自动刷新。

检查认证状态：

python3 scripts/garmin_auth.py status

获取数据

使用 scripts/garmin_data.py 获取 JSON 数据：

# 睡眠数据（默认最近 7 天）
python3 scripts/garmin_data.py sleep --days 14

# 身体电量（Garmin 的恢复指标）
python3 scripts/garmin_data.py body_battery --days 30

# HRV 数据
python3 scripts/garmin_data.py hrv --days 30

# 心率（静息、最大、最小）
python3 scripts/garmin_data.py heart_rate --days 7

# 活动/锻炼
python3 scripts/garmin_data.py activities --days 30

# 压力水平
python3 scripts/garmin_data.py stress --days 7

# 综合摘要（包含平均值）
python3 scripts/garmin_data.py summary --days 7

# 自定义日期范围
python3 scripts/garmin_data.py sleep --start 2026-01-01 --end 2026-01-15

# 用户资料
python3 scripts/garmin_data.py profile

输出为 JSON 格式到标准输出。解析它以回答用户问题。

生成图表

使用 scripts/garmin_chart.py 生成交互式 HTML 可视化图表：

# 睡眠分析（时长 + 分数）
python3 scripts/garmin_chart.py sleep --days 30

# 身体电量恢复图表（颜色编码）
python3 scripts/garmin_chart.py body_battery --days 30

# HRV 与静息心率趋势
python3 scripts/garmin_chart.py hrv --days 90

# 活动摘要（按类型、卡路里）
python3 scripts/garmin_chart.py activities --days 30

# 完整仪表盘（包含全部 4 个图表）
python3 scripts/garmin_chart.py dashboard --days 30

# 保存到指定文件
python3 scripts/garmin_chart.py dashboard --days 90 --output ~/Desktop/garmin-health.html

图表会自动在默认浏览器中打开。它们使用 Chart.js 库，具有现代渐变设计、统计卡片和交互式提示框。

回答问题

关键指标解读

身体电量 (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+ 毫秒）

静息心率 (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. 始终包含免责声明：此信息仅供参考，非医疗建议

故障排除

认证问题

• “无效凭据”：仔细检查邮箱/密码，尝试登录 Garmin Connect 网页
• “令牌过期”：重新运行登录：python3 scripts/garmin_auth.py login ...
• “请求过多”：Garmin 有速率限制；等待几分钟后重试

数据缺失

• 某些指标需要特定的 Garmin 设备（身体电量需要支持 HRV 的设备）
• 如果未佩戴设备，历史数据可能存在空白
• 新账户可能历史数据有限

库问题

• 如果 garminconnect 导入失败：pip3 install --upgrade garminconnect
• Garmin 偶尔会更改其 API；如果请求失败，请更新库

隐私说明

• 凭据本地存储在 ~/.clawdbot/garmin-tokens.json
• 会话令牌会自动刷新
• 除 Garmin 官方服务器外，数据不会发送到任何地方
• 您可以随时通过删除令牌文件来撤销访问权限

对比：Garmin vs Whoop

参考资料

• references/api.md — Garmin Connect API 详情（非官方）
• references/health_analysis.md — 基于科学的健康数据解读
• garminconnect 库 — Python API 封装
• Garmin Connect — 官方网页界面

版本信息

• 创建日期：2026-01-25
• 作者：EversonL & Claude
• 版本：1.2.0
• 依赖项：garminconnect, fitparse, gpxpy (Python 库)
• 许可证：MIT