Google Health API 是 Fitbit Web API 的官方继任者。它面向 Google Health API v4，并将开发者迁移至 Google OAuth 2.0。现在，一款名为 ghealth 的开源 CLI 命令行工具将该 API 封装，供终端和 AI 智能体使用。
该工具是一个采用 Apache 2.0 许可证的单一 Go 二进制文件。它以结构化 JSON 格式公开了 40 种经过验证的数据类型。这种设计让你可以将睡眠、心率和步数数据直接导入智能体的上下文。
什么是 ghealth？
ghealth 是 Google Health API v4 的一个封装工具。你可以通过 `go build -o ghealth .` 从源码构建它。它作为一个独立的二进制文件发布。
该工具明确以智能体优先。每条命令都返回形状稳定的简化 JSON。它还提供了确定的退出码、`--dry-run` 标志和 `--raw` 标志。
该仓库附带两个以 SKILL.md 文件形式提供的智能体技能。一个涵盖认证、设置和全局标志。另一个记录了所有 40 种数据类型、操作、模式和注意事项。智能体通过 `npx skills add` 安装它们。
该 CLI 位于 Google-Health-API GitHub 组织下。该组织也托管着长期存在的 Fitbit 开源仓库。
数据面：40 种经过验证的类型
这 40 种类型涵盖了大多数 Fitbit 和 Pixel Watch 信号。示例包括步数、心率、睡眠、体重、血氧饱和度和心率变异性。心电图等临床类型需要 `ecg.readonly` 作用域。
每种类型支持一部分操作。常见的操作有 list、rollup、daily-rollup 和 reconcile。可写入的类型（运动、睡眠、体重、体脂、身高）额外支持 create、update 和 delete。
reconcile 操作会合并来自多个来源的重叠数据点。这反映了 v4 API 中的 Reconciled Stream。
睡眠是模式分析的一个好例子。默认的 list 返回一个摘要。添加 `--detail` 会返回分阶段的数据（清醒、深睡、REM）。这有助于你逐周发现模式。
设置：实际流程
设置通过一条命令完成：`ghealth setup`。一个向导会引导你完成 GCP 项目和 OAuth 配置。你需要在 Google Cloud Console 中创建一个桌面类型的 OAuth 客户端。
您自行提供 OAuth 凭据。该工具不持有任何共享密钥。文件写入 `~/.config/ghealth/` 目录下，权限为 0600。模型 token 会自动刷新。
所有 Google Health API 作用域均被归类为受限范围。Google 要求生产环境访问需通过隐私与安全审查。个人使用时，您可针对自己的账号授权自己的项目。该 API 可返回来自 Fitbit、Pixel Watch 以及已连接的第三方数据源的数据。
无头流程使用 PKCE 配合 S256 挑战码。它还会在完成时验证一个随机的 state 参数。
实操：命令与输出
数据读取在不同类型间保持一致。每次读取都会返回一个对象，其数据行位于 `dataPoints` 下。
# Recent heart rate readings
ghealth data heart-rate list --from today --limit 10
# Daily step totals for a week
ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29
# Sleep stages for the last five nights
ghealth data sleep list --limit 5 --detail步数总计返回聚合后的 JSON：
{
"dataPoints": [
{"date": "2026-03-28", "countSum": "9037"},
{"date": "2026-03-27", "countSum": "2408"}
]
}默认输出为简化格式。使用 `--raw` 可获取原始 API 响应。使用 `--format csv` 或 `--format table` 可切换其他格式。`-o` 标志会将结果写入文件并打印 schema 预览。
分页是无损的。大量数据列表会返回一个 `nextPageToken`。您可以通过 `--page-token` 将其传回，以获取下一页数据。
用例示例
- 将睡眠模式输入智能体：使用 `--detail` 拉取几晚的数据。将 JSON 通过管道传给 Claude Code 或 Codex 会话。让智能体总结一周内的深度睡眠趋势。
- 将锻炼数据加载到 pandas 中：运行 `ghealth data exercise export-tcx --id <id> --output ride.csv --as csv`。每一行是一个包含心率和 GPS 的轨迹点。然后对该文件执行 `pd.read_csv`。
- 构建静息心率视图：查询 30 天内的每日静息心率。使用 `--format csv` 输出为 CSV。在 notebook 或仪表盘中绘制图表。
ghealth 对比
下表将 ghealth 与原始 API 及其他两个 CLI 工具进行了对比。另外两个 CLI 工具均自称非官方。
| 属性 | ghealth（本 CLI） | Google Health API v4（直接 REST） | rudrankriyam/Google-Health-CLI | googlehealth-cli（npm） |
|---|---|---|---|---|
| 安装 | git clone + go build | 无；自行调用 HTTP/gRPC | 从 Go 源码构建 | npm i -g googlehealth-cli |
| 语言 | Go，单一二进制文件 | 任意 | Go | Node.js |
| 认证 | 您自己的 OAuth 客户端，PKCE S256 | Google OAuth 2.0 | 您自己的 OAuth 客户端 | 您自己的 OAuth 客户端 |
| 智能体输出 | 简化 JSON、退出码、SKILL.md | 原始 JSON / gRPC | 可预测的 JSON | 稳定的 `--json` 封装 |
| 数据类型 | 40 种，经实时 API 验证 | 完整的 v4 接口 | 已记录 v4 接口文档 | 类型子集 |
| 官方状态 | 非官方；属于 Google-Health-API 组织下的社区项目 | 是；Google | 否；声明为非官方 | 否；声明为无关联 |
如需原始控制，直接使用 REST API 是最可靠的方式。对于终端和智能体使用场景，ghealth 可减少身份验证和格式化的样板代码。