garmin-health-analysis

Garmin 健康分析

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

两种安装方式

此技能支持两种不同的配置方式：

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

请选择符合你使用场景的方式。你也可以同时使用这两种方式！

---

配置 Clawdbot 技能（仅首次配置）

1. 安装依赖项

pip3 install garminconnect

2. 配置凭据

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

选项 A：Clawdbot 配置（推荐，可通过 UI 配置）

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

{
  "skills": {
    "entries": {
      "garmin-health-analysis": {
        "enabled": true,
        "env": {
          "GARMIN_EMAIL": "[email protected]",
          "GARMIN_PASSWORD": "your-password"
        }
      }
    }
  }
}

提示：你也可以在 Clawdbot UI 的 Skills 设置面板中设置这些内容。

选项 B：本地配置文件

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

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：

{
  "email": "[email protected]",
  "password": "your-password"
}

注意：config.json 已加入 gitignore，以保护你的凭据。

选项 C：命令行

进行身份验证时直接传入凭据：

python3 scripts/garmin_auth.py login \
  --email [email protected] \
  --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 数据：

# 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，并写入标准输出。解析数据以回答用户的问题。

生成图表

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

# 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，报告平均值和趋势

关键指标

Body Battery（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. 务必注明免责声明：这些信息仅供参考，不构成医疗建议

故障排除

身份验证问题

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

数据缺失

• 某些指标需要特定的 Garmin 设备（Body Battery 需要支持 HRV 的设备）
• 如果未佩戴设备，历史数据可能会有缺失
• 新账户可能只有有限的历史数据

库问题

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

隐私说明

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

对比：Garmin 与 Whoop

特性	Garmin	Whoop
恢复指标	Body Battery（0-100）	Recovery Score（0-100%）
HRV 跟踪	是（夜间平均值）	是（详细数据）
睡眠阶段	浅睡、深睡、REM、清醒	浅睡、SWS、REM、清醒
活动跟踪	内置 GPS、多种运动模式	Strain 分数（0-21）
压力	全天压力等级	不直接跟踪
API	非官方（garminconnect）	官方 OAuth
设备类型	手表、健身追踪器	仅可穿戴腕带

参考资料

• 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