Garmin Health Analysis

核心用法

Garmin Health Analysis 是一款面向 Garmin 穿戴设备用户的健康数据分析技能，通过非官方 Garmin Connect API 获取个人健康数据，并提供交互式可视化图表。用户需配置 Garmin 账号邮箱和密码完成认证，支持三种凭证配置方式（Clawdbot UI 配置、本地配置文件、命令行参数）。认证后可通过命令行工具获取睡眠、Body Battery（身体电量）、HRV（心率变异性）、心率、活动记录、压力等多维度数据，并生成基于 Chart.js 的交互式 HTML 图表。

数据获取能力

• 睡眠分析：时长、睡眠评分（0-100）、各阶段分布
• Body Battery：Garmin 专利恢复指标（0-100），基于 HRV、压力、睡眠综合计算
• HRV 趋势：夜间平均 HRV，反映自主神经平衡与恢复能力
• 心率监测：静息心率、最大/最小心率追踪
• 活动记录：运动类型、卡路里消耗、时长统计
• 压力水平：全天候 HRV 衍生压力评估

可视化输出

支持生成单指标图表（睡眠、Body Battery、HRV、活动）及综合仪表板，图表采用渐变色现代设计，包含统计卡片与交互式悬停提示，自动在默认浏览器中打开。

显著优点

1. 数据整合度高：覆盖 Garmin 生态核心健康指标，一站式满足运动健康分析需求
2. 可视化专业：Chart.js 交互图表美观易读，支持 30/90 天等多时间维度对比
3. 分析框架科学：内置基于循证医学的指标解读指南（health_analysis.md），提供个性化建议
4. 认证机制灵活：支持 UI、文件、环境变量、命令行四种凭证配置，适应不同使用场景
5. 会话管理智能：Token 自动刷新，避免频繁重复登录

潜在缺点与局限性

• API 非官方：依赖社区维护的 garminconnect 库，Garmin 官方 API 变更可能导致功能中断
• 设备门槛：Body Battery、HRV 等高级功能需特定型号 Garmin 设备（如 Forerunner、Fenix、Venu 系列）
• 数据精度限制：睡眠分期、压力评估为算法估算，非医疗级精度
• 无实时同步：需手动触发数据获取，非自动后台同步
• 比较功能缺失：缺乏与 Apple Health、Whoop 等平台的直接数据对比工具（仅提供文字对比表）

适合人群

• 严肃跑者/铁三运动员：需要追踪训练负荷与恢复平衡
• 健身爱好者：关注睡眠、压力、心率等健康趋势
• 数据驱动型用户：希望将可穿戴设备数据转化为可行动洞察
• Garmin 手表用户（尤其是中高端型号）

常规风险

| 风险类型 | 说明 | 缓解措施 |

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

| 账号安全 | 需存储邮箱密码，存在凭证泄露风险 | 使用本地加密存储，Token 文件权限控制，定期更换密码 |

| 服务可用性 | 非官方 API 可能因 Garmin 反爬虫策略失效 | 关注库更新，避免高频请求，预留手动导出备选方案 |

| 健康误导 | 算法数据非医疗诊断，可能误判身体状况 | 明确免责声明，异常指标建议就医确认 |

| 隐私合规 | 健康数据属于敏感个人信息 | 数据仅本地处理，不向第三方传输，Token 可手动撤销 |

功能概述

Garmin Health Analysis 是一款面向 Garmin 穿戴设备用户的数据分析工具，通过非官方 Garmin Connect API 拉取睡眠、心率变异性（HRV）、Body Battery、压力水平、运动记录等健康指标，并生成基于 Chart.js 的交互式 HTML 可视化图表。

核心用法

数据获取：使用 garmin_data.py 脚本查询各类健康指标（支持 1-90 天范围），输出 JSON 格式供进一步处理。

图表生成：使用 garmin_chart.py 创建单指标或综合仪表盘（dashboard），自动在浏览器中打开。

健康分析：结合内置的 health_analysis.md 参考文档，对用户的恢复状态、训练负荷平衡、潜在过度训练信号进行解读。

显著优点

1. 数据维度全面：覆盖 Garmin 生态核心指标（Body Battery、睡眠评分、HRV 趋势、静息心率、全天压力），优于单一功能工具。
2. 可视化友好：Chart.js 驱动的渐变风格图表，支持交互式悬停提示，适合长期趋势观察。
3. 隐私优先设计：凭证本地存储（~/.clawdbot/garmin-tokens.json，700 权限），无第三方数据共享。
4. 配置灵活：支持环境变量、本地配置文件、命令行参数三种凭证输入方式，避免硬编码风险。
5. 开源透明：MIT 许可，代码结构清晰，便于审计和定制。

潜在缺点与局限性

1. 非官方 API 依赖：基于 garminconnect 库的逆向工程实现，Garmin 可能随时更改接口导致功能失效，且存在服务条款合规灰色地带。
2. 仅限 Garmin 生态：不支持 Apple Watch、Whoop、Oura 等其他品牌设备数据（虽有 Whoop 对比表，但无数据导入功能）。
3. 开发者维护风险：个人开发者项目（eversonl），GitHub 账号较新，长期维护可持续性存疑。
4. 无实时同步：依赖手动运行脚本或外部调度，非后台自动同步模式。
5. 图表 CDN 依赖：Chart.js 从 jsDelivr CDN 加载，离线环境或 CDN 故障时图表功能受限。

适合人群

• Garmin 深度用户：拥有支持 HRV/Body Battery 的中高端 Garmin 手表（如 Fenix、Forerunner、Venu 系列）。
• 数据驱动型运动爱好者：希望量化恢复状态、优化训练周期、预防过度训练。
• 隐私敏感用户：不愿将健康数据上传至第三方分析平台（如 TrainingPeaks、Strava 高级分析）。
• 技术背景用户：熟悉命令行操作，能处理 Python 环境配置和潜在的 API 故障排查。

常规风险

| 风险类别 | 说明 | 缓解建议 |

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

| API 可用性 | Garmin 可能封禁或更改非官方 API | 关注 `garminconnect` 库更新，避免高频请求 |

| 凭证安全 | 本地文件存储存在被读取风险 | 使用系统密钥库（Keychain/Secret Service）替代 |

| 数据准确性 | 设备未佩戴或佩戴不当导致数据缺失 | 结合主观感受判断，不依赖单一指标 |

| 健康建议局限 | 非医疗级分析，无专业医学背书 | 异常指标及时咨询医生，不用于疾病诊断 |

| 供应链攻击 | CDN 被篡改可能导致恶意代码执行 | 考虑离线打包 Chart.js |

安全评估

安全认证报告评分 78/100（A 级），代码无危险函数、无硬编码密钥、网络通信受限。主要风险集中于第三方 API 依赖（非官方）和个人开发者维护模式，建议用户自行审查代码并关注更新动态。