Google Health API 迎来 CLI：ghealth 是 Fitbit Air 数据的开源工具
ghealth 是一个开源命令行工具，封装了 Google Health API v4，提供 40 种经过验证的数据类型，并以结构化 JSON 格式输出。它专为终端和 AI 代理设计，支持 OAuth 2.0 认证，并包含详细的设置向导。该工具属于社区项目，非 Google 官方发布。
Google Health API 是 Fitbit Web API 的官方继任者，而 ghealth 是一个新的开源命令行工具，旨在简化对该 API 的访问。它由 Go 语言编写，发布为单一二进制文件，采用 Apache 2.0 许可证。ghealth 封装了 Google Health API v4，提供 40 种经过验证的数据类型，将睡眠、心率、步数等数据以结构化 JSON 格式输出，特别适合终端环境或 AI 代理直接使用。
该工具的设计思路是“代理优先”，每个命令都返回形状稳定的简化 JSON，并支持确定性退出码、--dry-run 和 --raw 标志。仓库中还包含两个 SKILL.md 文件，分别介绍认证配置和全部 40 种数据类型的操作细节，方便 AI 代理通过 npx skills add 安装。
ghealth 支持的数据类型涵盖 Fitbit 和 Pixel Watch 的主要信号，包括步速、心率、睡眠、体重、血氧饱和度和心率变异性等。部分临床类型如心电图需要 ecg.readonly 范围。每种类型支持特定操作，如 list、rollup、daily-rollup 和 reconcile，可写类型还支持 create、update 和 delete。reconcile 操作可合并来自多个来源的重复数据点，对应 v4 API 中的 Reconciled Stream。
设置过程通过 ghealth setup 命令启动，一个向导程序会引导用户在 Google Cloud Console 中创建桌面型 OAuth 客户端。用户需自行提供 OAuth 凭据，工具不持有任何共享密钥。凭证文件存储在 ~/.config/ghealth/ 目录下，权限设置为 0600，令牌自动刷新。所有 Google Health API 范围均被归类为受限，生产环境使用需通过隐私和安全审查。个人使用则只需授权自己的项目。
实际操作中，读取数据保持一致的命令格式。例如，ghealth data heart-rate list --from today --limit 10 可获取最近心率读数，ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29 可获取每日步数总计。默认输出为简化 JSON，也可使用 --raw 获取原始响应，或通过 --format csv/table 转换格式。分页支持通过 nextPageToken 和 --page-token 实现无损遍历。
ghealth 的应用场景灵活：可将睡眠数据管道传输给 Claude Code 或 Codex 代理以分析深睡趋势；可将运动数据导出为 TCX 格式供 pandas 分析；或通过 CSV 格式查询 30 天静息心率并绘制图表。
与其他工具相比，ghealth 强调代理友好输出和简化认证。原始 REST API 提供最直接的控制，但 ghealth 降低了终端和代理使用的门槛。该工具托管在 Google-Health-API GitHub 组织下，属于社区项目，并非 Google 官方发布。