fitbit-analytics

核心用法

Fitbit Analytics 是一款面向个人用户的健康数据集成分析工具，通过调用 Fitbit Web API 获取用户的运动、睡眠、心率等健康指标。用户需先在 Fitbit 开发者平台创建应用并获取 OAuth 2.0 凭证（CLIENT_ID、CLIENT_SECRET、ACCESS_TOKEN、REFRESH_TOKEN），配置环境变量后即可使用。

该 Skill 提供三种主要使用方式：
1. 每日简报（fitbit_briefing.py）：生成包含昨日活动、Active Zone Minutes、今日步数/卡路里/心率/睡眠等核心指标的晨间健康报告，支持文本、精简、JSON 三种输出格式
2. CLI 数据获取（fitbit_api.py）：通过命令行获取指定时间范围的步数、卡路里、心率、睡眠等原始数据
3. Python API 调用：在代码中直接实例化 FitbitClient 或 FitbitAnalyzer 进行程序化数据获取与分析

此外，alerts.py 支持基于阈值的健康提醒功能，可设置步数、睡眠时长等指标的监控告警。

显著优点

• 零外部依赖：仅使用 Python 标准库（urllib、json、argparse 等），无 pip 包依赖，部署简单且供应链攻击风险极低
• 数据隐私优先：所有健康数据仅在本地处理，不传输至第三方服务器，Token 缓存采用 600 权限保护
• 完善的异常处理：网络请求设置 10 秒超时，API 响应有安全的数据转换函数（_safe_float、_safe_int），错误信息不泄露敏感信息
• 灵活的输出格式：支持文本简报、JSON 结构化数据、精简三行摘要等多种输出，便于集成至自动化工作流（如 Telegram 定时推送）
• Token 自动刷新：内置 OAuth Token 刷新机制，避免手动重复授权

潜在缺点与局限性

• T3 来源可信度：开发者为个人账号（kesslerio），非企业或官方组织背书，项目维护持续性存在不确定性
• 功能覆盖有限：无法获取 Fitbit Premium 专属功能（如 Cardio Load），部分高级健康指标不可用
• 配置门槛较高：需用户自行完成 Fitbit 开发者应用创建、OAuth 授权流程，对非技术用户不够友好
• 单用户设计：凭证绑定单一用户，不适合多用户共享或企业级部署场景
• 无可视化能力：仅输出原始数据或文本报告，需配合其他工具实现图表可视化

适合的目标群体

• 健康数据爱好者：希望深度分析个人运动、睡眠趋势的技术型用户
• 量化自我（Quantified Self）实践者：需要将 Fitbit 数据集成至个人自动化工作流（如 Notion、Telegram、Home Assistant）
• 开发者/工程师：具备 Python 基础，希望基于 Fitbit 数据构建自定义健康应用或智能家居联动
• 小型健康研究团队：需要批量获取脱敏健康数据进行趋势分析（需确保合规性）

使用风险

• 凭证泄露风险：FITBIT_CLIENT_SECRET 和 REFRESH_TOKEN 属于高敏感凭证，若环境变量配置不当或日志泄露可能导致账户被接管
• API 速率限制：Fitbit API 有严格的调用配额，高频自动化任务可能触发限流
• 数据准确性依赖：设备佩戴方式、同步延迟可能影响数据质量，Skill 本身不提供数据校验机制
• Token 缓存安全：虽然文件权限设置为 600，但在共享服务器或容器环境中仍存在被其他高权限用户读取的风险
• 服务可用性依赖：Fitbit API 服务中断或策略变更将直接影响 Skill 功能

核心用法

Fitbit Analytics 是一款基于 Python 标准库构建的 Fitbit 数据集成技能，用户通过配置 FITBIT_CLIENT_ID、FITBIT_CLIENT_SECRET、FITBIT_ACCESS_TOKEN、FITBIT_REFRESH_TOKEN 四类环境变量完成 OAuth 2.0 认证后，即可调用 fitbit_api.py、fitbit_briefing.py 等脚本拉取步数、卡路里消耗、心率、睡眠阶段、血氧、体重等多维健康指标。

技能提供三层使用模式：

• CLI 快捷查询：fitbit_api.py steps --days 7 等命令行方式快速获取近期数据；
• 每日简报：fitbit_briefing.py 自动生成包含 Active Zone Minutes、睡眠效率、趋势对比的晨报，支持 text/brief/json 三种输出格式；
• Python API 集成：通过 FitbitClient 与 FitbitAnalyzer 类在自定义脚本中实现批量数据获取与趋势分析。

此外，技能支持 OpenClaw 网关的定时任务（cron）配置，可将健康报告自动推送至 Telegram 等渠道，实现无人值守的每日健康监测。

显著优点

1. 零第三方依赖：仅使用 Python 标准库（urllib、json、datetime 等），彻底规避供应链攻击风险，部署体积极小。
2. 官方 API 直连：所有数据请求均通过 HTTPS 访问 api.fitbit.com，TLS 1.2+ 加密，数据来源权威可信。
3. 凭证安全机制：支持访问令牌自动刷新，缓存文件权限严格设为 600，符合 POSIX 凭证存储规范。
4. 隐私合规完备：内置 GDPR/CCPA 兼容的隐私政策，数据本地处理，明确声明不与第三方共享。
5. 自动化友好：提供标准化 JSON 输出与 cron 配置示例，易于集成至个人健康自动化工作流。

潜在缺点与局限性

• 功能边界限制：Cardio Load 等 Fitbit Premium 专属指标无法通过 API 获取；血氧（SpO2）数据需设备支持且用户开启相关权限。
• API 速率限制：Fitbit Web API 默认每小时 150 次请求，高频查询需自行实现退避重试（当前版本未内置）。
• 凭证配置门槛：需用户自行在 Fitbit 开发者后台创建应用并完成 OAuth 授权流程，对非技术用户不够友好。
• 令牌存储风险：虽文件权限已限制为 600，但仍依赖本地文件系统安全，建议配合磁盘加密使用。
• 地理与合规差异：Fitbit 数据存储受 Google 隐私政策管辖，部分国家/地区用户可能面临数据跨境传输顾虑。

适合人群

• 需要量化自我（Quantified Self）的健身爱好者与健康数据极客；
• 希望将 Fitbit 数据导出至个人数据库或 BI 工具的数据分析师；
• 追求隐私优先、不愿使用第三方云同步服务的用户；
• 具备基础 Python/Shell 能力、能独立完成 OAuth 配置的开发者。

常规风险

1. 凭证泄露风险：若环境变量或令牌缓存文件被其他进程读取，可能导致 Fitbit 账户数据被非法访问。
2. API 服务中断：Fitbit 官方 API 策略调整或 Google 服务故障可能导致数据同步失效。
3. 健康数据误读：自动生成的报告仅供参考，不能替代专业医疗诊断，用户需避免过度依赖算法趋势。
4. 自动化通知疲劳：频繁的健康告警（如步数不足、睡眠过短）可能引发焦虑，建议合理设置阈值。