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）中。
该工具明确以智能体（agent）优先。每条命令都返回简化且结构稳定的 JSON。此外，它还提供了确定性的退出码、
代码仓库附带两个智能体技能（Agent Skills）文件，格式为 SKILL.md。一个涵盖了认证、设置和全局标志；另一个记录了全部 40 种数据类型、操作、常见模式及注意事项。智能体通过
该 CLI 托管在 Google-Health-API GitHub 组织下。该组织还维护着一些长期存在的 Fitbit 开源仓库。
每种类型都支持一组操作子集。常见操作包括 list、rollup、daily-rollup 和 reconcile。可写入类型（运动、睡眠、体重、体脂、身高）额外支持 create、update 和 delete。
reconcile 操作会合并来自多个源的重叠数据点。这与 v4 API 中的 Reconciled Stream（已调和对齐流）功能一致。
睡眠数据是模式分析的一个很好的例子。默认 list 操作返回摘要。添加
你自行提供 OAuth 凭据。该工具不持有任何共享密钥。文件写入
所有 Google Health API 作用域均被归类为“受限”。Google 要求生产环境访问需通过隐私与安全审核。个人使用时，你需在自己的项目中授权自己的账号。该 API 可返回来自 Fitbit、Pixel Watch 及已连接的第三方来源的数据。
无浏览器交互流程使用 PKCE 加 S256 挑战。它还会在流程结束时验证一个随机 state 参数。
复制代码 已复制 请使用其他浏览器
步数汇总会返回聚合后的 JSON：
复制代码 已复制 请使用其他浏览器
默认情况下输出已简化。使用
分页不会丢失数据。大型列表会返回一个
对于原始控制，直接使用 REST API 是事实标准。对于终端和智能体使用，ghealth 减少了认证和格式化的样板代码。
该工具是一个独立的 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复制代码 已复制 请使用其他浏览器
代码:
{
"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 均自称是非官方工具。| 属性 | 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 | 否；声明为非官方 | 否；声明为无关联 |
