佳明健康数据分析

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

两种安装路径

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

1. Clawdbot技能（本指南）- 与Clawdbot配合使用，实现自动化主动健康监测
2. MCP服务器（参见MCP设置指南）- 作为MCP服务器与标准Claude桌面版配合使用

请根据您的使用场景选择相应路径。您也可以同时使用两种方案！

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

1. 安装依赖项

pip3 install garminconnect

2. 配置凭据

您可以通过以下三种方式提供佳明Connect登录凭据：

方案A：Clawdbot配置（推荐 - 支持界面配置）

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

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

提示：您也可以在 Clawdbot 用户界面的技能设置面板中进行这些设置。

选项 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": "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 数据：

# 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 库，具有现代渐变设计、统计卡片和交互式工具提示。

回答问题

关键指标

身体电量 (0-100)

佳明基于心率变异性、压力、睡眠和活动的专有恢复指标：

• 高（75-100分）：完全恢复，适合高强度训练
• 中（50-74分）：能量适中，适合日常活动
• 低（25-49分）：能量有限，需要恢复
• 极低（0-24分）：能量耗尽，建议优先休息

睡眠评分（0-100分）

基于时长、阶段与干扰因素的整体睡眠质量评估：

• 优秀（90-100分）：获得最佳恢复性睡眠
• 良好（80-89分）：存在细微问题的优质睡眠
• 一般（60-79分）：睡眠充足但有待改善
• 较差（0-59分）：存在显著睡眠不足问题

心率变异性

以毫秒为单位测量，数值越高通常代表状态越好：

• 表示神经系统平衡与恢复能力
• 追踪长期趋势（数值上升 = 恢复能力改善）
• 受睡眠、压力、训练负荷、疾病影响
• 正常范围因人而异（20-200+ 毫秒）

静息心率（次/分钟）

数值越低通常代表心血管健康水平越高：

• 运动员：40-60 次/分钟
• 健康成人：60-70 次/分钟
• 普通成人：70-80 次/分钟
• 心率骤升可能提示压力、疾病或训练过度

压力水平

基于全天心率变异性分析：

• 低压力：休息与恢复阶段
• 中等压力：日常正常活动
• 高压力体力活动或精神压力

健康分析

当用户请求见解或希望了解其趋势时，使用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
• 会话令牌会自动刷新
• 除发送至佳明官方服务器外，数据不会传输至任何其他地方
• 您可随时通过删除令牌文件撤销访问权限

对比：佳明 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 库)
• 许可证麻省理工学院