WHOOP Tracker

WHOOP API 技能综合评估

核心用法

WHOOP API 技能为用户提供与 WHOOP 专业健身追踪设备的数据对接能力，通过官方 REST API 获取全面的生理健康指标。核心功能涵盖五大模块：恢复状态（Recovery Score、HRV、静息心率、血氧、皮温）、睡眠分析（睡眠效率、各阶段时长、呼吸率、睡眠负债）、每日负荷（Strain Score、能量消耗、心率区间）、训练记录（运动类型、GPS 轨迹、心率区间分布）以及用户档案（身体测量数据）。

技能采用 OAuth 2.0 标准授权流程，支持令牌自动刷新与速率限制重试机制。提供 Python 命令行工具链，支持按日期范围筛选、运动类型过滤及 JSON 原始数据导出，便于二次分析与可视化。

显著优点

1. 数据源权威性：直接对接 WHOOP 官方 API，数据来自经临床验证的腕式光电容积脉搏波（PPG）传感器，被 NCAA、NHL、NFL 等职业体育联盟广泛采用。
2. 指标专业度高：恢复评分算法融合 HRV、睡眠质量、既往负荷等多维度变量，提供可量化的训练准备度指导。
3. 自动化运维：内置令牌过期预刷新、429 速率限制智能重试、分页数据自动遍历，降低开发维护成本。
4. 隐私合规设计：数据存储于本地 ~/.whoop/ 目录，权限设置为 600，避免凭证泄露风险。

潜在缺点与局限性

• 硬件依赖：必须拥有 WHOOP 4.0 或 3.0 设备才能产生数据，无法独立运行。
• 订阅成本：WHOOP 设备需搭配月费/年费会员（约 $18-30/月），API 访问权限绑定活跃订阅。
• 数据滞后性：部分指标（如恢复分数）需晨起后 30-60 分钟完成计算，非实时同步。
• 地理限制：API 服务受 WHOOP 运营区域限制，部分国家/地区可能无法完整使用。

适合人群

• 职业/业余运动员及体能教练，需要基于 HRV 和恢复数据的周期化训练规划
• 健身爱好者追求量化自我（Quantified Self），建立长期健康趋势追踪
• 运动科学研究者获取标准化生理数据集
• 企业 wellness 项目管理员批量导出团队健康报告

常规风险

• 授权范围过度申请：默认请求全部 6 项 OAuth scope，若仅需部分数据应精简权限，遵循最小必要原则。
• 令牌泄露：~/.whoop/credentials.json 包含 client_secret，需避免纳入版本控制或云同步目录。
• 心率数据误读：WHOOP 的光学心率在剧烈运动（如 HIIT、力量训练）中可能出现伪差，不宜作为医疗诊断依据。
• API 变更风险：WHOOP 保留 API 版本更新权利，需关注 references/api-reference.md 的变更日志。
• 数据主权疑虑：健康数据存储于 WHOOP 云端（美国服务器），跨境数据传输需符合 GDPR 等合规要求。

核心用法

WHOOP Skill 是一款面向健身追踪器用户的数据分析工具，通过官方 REST API 获取 WHOOP 可穿戴设备的完整生理数据。用户需先在 developer.whoop.com 注册应用获取 OAuth 凭证，完成授权后即可通过命令行脚本查询恢复评分、睡眠阶段、运动记录等核心指标。

主要数据维度包括：Recovery（恢复评分 0-100、心率变异性 HRV、静息心率、血氧）、Sleep（睡眠效率、REM/SWS 深度睡眠时长、呼吸频率、睡眠债）、Strain（日负荷评分 0-21、能量消耗 kJ、心率区间分布）以及 Workout（运动类型、GPS 轨迹、海拔变化）。所有数据均支持时间范围筛选和原始 JSON 导出，便于进一步分析。

显著优点

专业级生理指标覆盖：WHOOP 在运动员群体中享有盛誉，其 HRV 和恢复评分算法经过大量验证，数据维度远超普通健身手环。

安全架构设计完善：采用 OAuth 2.0 标准授权流程，Token 本地存储并设置 0600 文件权限，凭证加密传输，符合 GDPR 数据最小化原则。

开发者体验友好：提供完整的分页迭代器、自动 Token 刷新、速率限制重试机制，代码结构清晰含类型注解，降低二次开发门槛。

官方 API 背书：直接对接 WHOOP 官方端点（api.prod.whoop.com），数据来源可靠，非第三方爬虫方案，稳定性与合规性有保障。

潜在缺点与局限性

硬件门槛：必须拥有 WHOOP 4.0 或 WHOOP Strap 设备且保持有效订阅（月费 $30），无设备用户无法使用该 Skill。

数据来源单一：仅支持 WHOOP 生态，无法整合 Apple Watch、Garmin、Fitbit 等其他品牌数据，跨平台用户需手动迁移。

离线功能缺失：完全依赖网络连接，无本地缓存或离线模式，WHOOP API 服务中断时无法访问历史数据。

T3 来源等级：由个人开发者（ijaack）维护，非企业级项目，长期更新和维护承诺存在不确定性。

适合的目标群体

职业运动员与严肃训练者：需要基于 HRV 和恢复评分调整训练计划的人群，WHOOP 的生理模型对此类用户价值最高。

量化健康极客：热衷于追踪睡眠债、呼吸频率、皮肤温度变异等深度指标，希望自建数据分析管道的技术型健身爱好者。

运动科学研究人员：需要批量导出受试者生理数据进行学术研究，官方 API 的合规性优于非授权数据抓取方案。

教练与训练团队：可批量管理多名运动员的恢复状态，辅助制定周期性训练计划。

使用风险与注意事项

Token 安全风险：虽然 Skill 本身实现了安全的本地存储，但用户需确保 ~/.whoop/token.json 不被误提交至 Git 仓库或备份到不安全的云存储。建议在 .gitignore 中显式排除该目录。

API 依赖与速率限制：WHOOP API 存在请求配额（默认 25 条/页，需分页获取历史数据），大规模数据导出可能触发 429 限流。 Skill 已实现自动重试，但极端情况下仍可能中断。

隐私合规边界：健康数据属于敏感个人信息，使用该 Skill 处理他人数据（如教练管理运动员）时需确保获得明确授权，避免违反 HIPAA 或当地健康数据法规。

供应链建议：当前依赖未锁定版本，建议用户自行添加 requirements.txt 固定 requests 库版本，防范潜在的依赖投毒攻击。