Google Health API 是 Fitbit Web API 的官方后继版本。它面向 Google Health API v4，并将开发者迁移至 Google OAuth 2.0。现在有一款名为 ghealth 的开源 CLI 命令行工具，为该 API 提供了终端和 AI 智能体的封装。

该工具是一个独立的 Go 二进制文件，采用 Apache 2.0 许可证。它公开了 40 种经过验证的数据类型，以结构化 JSON 格式呈现。这种设计让你可以将睡眠、心率和步数数据直接导入到智能体的上下文（context）中。

什么是 ghealth？

ghealth 是 Google Health API v4 的一个封装器。你可以通过 `go build -o ghealth .` 从源码编译构建。它以一个自包含的二进制文件形式交付。

该工具明确以智能体（agent）优先。每条命令都返回简化且结构稳定的 JSON。此外，它还提供了确定性的退出码、`--dry-run` 标志和 `--raw` 标志。

代码仓库附带两个智能体技能（Agent Skills）文件，格式为 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，在笔记本或仪表盘中绘制图表。

ghealth 对比

下表将 ghealth 与原始 API 及另外两个 CLI 工具进行对比。另外两个 CLI 均自称是非官方工具。

对于原始控制，直接使用 REST API 是事实标准。对于终端和智能体使用，ghealth 减少了认证和格式化的样板代码。

交互式说明