Garmin Health Analysis

核心用法

Garmin Health Analysis 是一个综合性健康数据查询与分析技能，通过非官方 Garmin Connect API 获取用户穿戴设备的生物特征数据。支持三种认证方式（环境变量、本地配置文件、命令行参数），数据获取涵盖睡眠评分、Body Battery（体能电量）、HRV（心率变异性）、静息心率、全天压力、训练准备度、血氧等20余项指标。提供时间精确查询（如"下午3点的心率"），可分析 FIT/GPX 原始运动文件，并生成基于 Chart.js 的交互式 HTML 可视化报告。

显著优点

• 指标全面：覆盖 Garmin 生态绝大多数健康数据维度，包括 proprietary 指标如 Body Battery
• 可视化能力：自动生成渐变设计风格的交互式图表，包含统计卡片与趋势分析
• 灵活查询：支持自然语言时间查询、自定义日期范围、综合摘要与专项数据模式
• 专业分析框架：内置基于循证医学的数据解读指南，提供分层的洞察与可执行建议

潜在缺点与局限性

• API 非官方：依赖社区维护的 garminconnect Python 库，Garmin 官方 API 变更可能导致功能中断
• 设备门槛：Body Battery、HRV 等核心功能需特定型号设备（如 Forerunner、Fenix、Venu 系列）
• 认证依赖：需明文存储邮箱密码或使用 OAuth tokens，存在凭证泄露理论风险
• 数据延迟：部分指标（如睡眠评分）需设备同步后延迟生成，非实时可用
• 医学免责声明：明确标注非医疗建议，重大健康决策仍需专业医师

适合人群

Garmin 智能穿戴设备深度用户、耐力运动员、量化健康爱好者、需要追踪恢复状态的 CrossFit/铁三/马拉松训练者，以及希望通过数据驱动优化训练负荷的健身教练。

常规风险

• 隐私风险：健康数据（心率、睡眠、HRV）属敏感个人信息，本地 token 文件需妥善保管
• 服务中断：非官方 API 可能因 Garmin 反爬策略或协议变更而失效
• 过度解读：用户可能误将健身追踪数据等同于医疗诊断，延误真正需要的医疗干预

核心功能

Garmin Health Analysis 是一款深度整合 Garmin Connect 的健康数据分析 Skill，提供三大核心能力：

1. 多维度健康指标获取

• 覆盖睡眠（时长、阶段、评分）、Body Battery（能量恢复指数）、HRV（心率变异性）、静息心率、血氧、压力水平等 20+ 指标
• 支持时间精确查询（如"昨天下午 3 点的心率"）
• 可解析 FIT/GPX 原始活动文件

2. 智能可视化分析

• 生成交互式 HTML 图表（Chart.js），含渐变设计、统计卡片与动态提示
• 支持睡眠、Body Battery、HRV、活动汇总等独立视图及综合仪表盘
• 图表自动在浏览器中打开，便于分享与存档

3. 科学健康洞察

• 内置 Garmin 与 Whoop 的对比参考，帮助用户理解指标含义
• 提供基于数据的恢复建议与训练调整指导
• 支持趋势分析（如 HRV 长期改善追踪）

显著优势

• 数据全面性：相比官方 Garmin Connect 移动应用，提供更灵活的时间维度查询与批量数据导出
• 隐私优先：所有数据本地处理，令牌存储于加密目录，无第三方服务器上传
• 开源透明：MIT 协议，代码可审计，依赖知名开源库（garminconnect、fitparse、gpxpy）
• 自动化友好：JSON 输出格式便于与其他工具链集成

局限性与风险

| 类型 | 说明 |

|------|------|

| **API 稳定性** | 使用非官方逆向 API，Garmin 可能随时更改接口导致功能中断 |

| **速率限制** | 约 50-100 请求/10 分钟，过度请求可能触发账户临时限制 |

| **设备兼容性** | Body Battery、HRV 等指标需特定型号（如 Fenix、Venu、Instinct 系列） |

| **数据延迟** | 部分指标需设备同步后 5-15 分钟才能在云端获取 |

| **医疗免责** | 分析结果仅供参考，非医疗诊断依据 |

适合人群

• 严肃跑者/铁三运动员：需要精细监控训练负荷与恢复平衡
• 量化健康爱好者：追求多维度生物指标追踪与长期趋势分析
• 教练与运动科研人员：需要导出结构化数据进行进一步分析
• 睡眠优化实践者：关注睡眠阶段、HRV 与恢复质量的关联

常规风险

• 凭证管理：需妥善保管 ~/.clawdbot/garmin-tokens.json，建议使用环境变量而非硬编码密码
• CDN 依赖：图表功能依赖 Chart.js CDN，离线环境需手动下载库文件
• 令牌过期：会话令牌需定期刷新，建议设置自动化登录脚本或监控