ghealth

ghealth

Google Health API v4 的命令行工具。支持 40 种已验证的数据类型。

前置条件： 身份验证、设置和全局标志请参阅 ../ghealth-shared/SKILL.md。

选择正确的操作

目标	操作	示例
每日总量（步数、距离、卡路里）	daily-rollup	ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29
单次读数（心率、体重、SpO2）	list	ghealth data heart-rate list --from today --limit 20
运动和睡眠等时段	list	ghealth data exercise list --from 2026-03-01
每日摘要（静息心率、HRV、呼吸频率）	list	ghealth data daily-resting-heart-rate list --from 2026-03-01
合并多来源数据	reconcile	ghealth data weight reconcile --from 2026-01-01

为什么这很重要： steps list 返回的是分钟级区间，不含计数。使用 daily-rollup 获取实际步数总量（countSum）。distance（millimetersSum）和 floors 也同理。

数据类型一览

运行 ghealth schema types 查看当前版本。快速参考：

使用 daily-rollup 获取总量：

• steps → 每日 countSum
• distance → 每日 millimetersSum
• total-calories → 每日 kcalSum（仅 rollup）
• floors → countSum（仅 rollup）
• active-minutes →（仅 rollup）
• swim-lengths-data → 每日 strokeCountSum
• calories-in-heart-rate-zone → 每日 caloriesInHeartRateZones（仅 rollup）

使用 list 获取读数： heart-rate、weight（可写入）、body-fat（可写入）、height（可写入）、oxygen-saturation、heart-rate-variability、altitude、vo2-max、active-zone-minutes、activity-level、basal-energy-burned、active-energy-burned、blood-glucose、core-body-temperature、respiratory-rate-sleep-summary、run-vo2-max、sedentary-period、swim-lengths-data、hydration-log

使用 list 获取时段：

• exercise（可写入）——包含类型、时长、卡路里、心率摘要和备注
• sleep（可写入）——默认包含摘要。添加 --detail 可查看各睡眠阶段的细分数据。

心脏数据（专用范围，仅支持 list）：

• electrocardiogram ——波形样本和心律分类。需要 ecg.readonly。
• irregular-rhythm-notification ——警报时段。需要 irn.readonly。

营养：

• nutrition-log ——记录的食物条目及营养素/能量细分（支持 list、get、rollup、daily-rollup、reconcile）
• food、food-measurement-unit ——参考目录（仅支持 list、get）。没有时间筛选——--from/--to 会被忽略。

每日摘要（每天一个值，按日期筛选）： daily-resting-heart-rate、daily-heart-rate-variability、daily-oxygen-saturation、daily-respiratory-rate、daily-vo2-max、daily-sleep-temperature-derivations

按 ID 获取单个数据点： exercise、sleep、weight、body-fat、height、hydration-log、nutrition-log、blood-glucose、core-body-temperature、food、food-measurement-unit 支持 get --id <id>。

命令行工具无法告知的模式

这些操作需要判断，仅靠 --help 和 schema 无法得知。

查询对日期敏感的数据前，先获取用户的时区：

ghealth user settings get   # → timeZone: "Europe/London", utcOffset: "3600s"
# Then use --from/--to with the correct local dates

此命令仅用于报告账号时区信息；若要让命令行工具在该时区解析日期，请使用 ghealth config set timezone <IANA zone> 显式设置时区。

睡眠/运动的每次请求最多返回 25 条（命令行工具会自动分页）：

ghealth data sleep list --limit 5    # CLI handles pagination internally

翻阅大型 list 结果。 list 最多返回 --limit 指定的行数（默认 500）。如果还有更多结果，响应会附带 nextPageToken 和提示。将此令牌通过 --page-token 传回即可获取下一页——它会从上一页结束的位置准确继续，不会跳过或重复任何行：

ghealth data heart-rate list --from 2026-06-15 --limit 500
#   → {"dataPoints":[…500…], "nextPageToken":"ABC", "_hints":[…]}
ghealth data heart-rate list --from 2026-06-15 --limit 500 --page-token ABC
#   → next 500 rows

将心率与运动时段关联起来：

# 1. Get exercise time window
ghealth data exercise list --from today --limit 1
#    → start: "2026-03-29T14:18:32+01:00", end: "2026-03-29T14:39:14+01:00"
# 2. Query HR for that window using --filter (raw API syntax, UTC required)
ghealth data heart-rate list --filter 'heart_rate.sample_time.physical_time >= "2026-03-29T13:18:32Z" AND heart_rate.sample_time.physical_time < "2026-03-29T13:40:00Z"'

导出数据以供分析

使用 -o <file> 将数据写入文件。 设置 -o 后，stdout 只显示包含列架构的摘要，不显示数据本身。这意味着你可以获取数据，并立即使用 stdout 中的列名编写分析代码，无需读取文件。

ghealth data steps daily-rollup --from 2026-03-24 --to 2026-03-30 --format csv -o steps.csv

stdout 显示的内容（这是 Agent 能看到的全部内容）：

Wrote 6 rows to steps.csv

Columns: countSum, date
Preview:
countSum,date
4062,2026-03-29
9122,2026-03-28
2469,2026-03-27

文件包含的内容（完整 CSV，不会打印到 stdout）：

countSum,date
4062,2026-03-29
9122,2026-03-28
2469,2026-03-27
6541,2026-03-26
4025,2026-03-25
3995,2026-03-24

Agent 现在知道列名是 countSum 和 date，无需读取文件即可编写 pd.read_csv("steps.csv")。

不要将输出重定向到文件——请改用 -o。通过管道重定向（> file.csv）会将完整数据写入文件，但不会向 stdout 输出任何内容，因此 Agent 看不到列架构，必须读取文件才能了解其结构。

更多示例：

# Sleep — nested stageMinutes auto-flattened to stageMinutes.AWAKE, stageMinutes.DEEP, etc.
ghealth data sleep list --from 2026-03-01 --format csv -o sleep.csv

# Exercise — metricsSummary.caloriesKcal, metricsSummary.averageHeartRateBeatsPerMinute, etc.
ghealth data exercise list --from 2026-03-01 --format csv -o exercise.csv

# Heart rate — 500 readings straight to file
ghealth data heart-rate list --from today --limit 500 --format csv -o hr.csv

将运动时间序列（GPS/心率轨迹）导出为 CSV。 export-tcx --as csv 会将 TCX 轨迹展平为每个轨迹点一行——直接使用 pd.read_csv 读取，无需解析 TCX XML：

# Find the exercise id first, then export its track
ghealth data exercise list --from 2026-06-01 --limit 10
ghealth data exercise export-tcx --id <id> --output ride.csv --as csv   # or --output - for stdout

列（固定且稳定，适用于数据框）：time, activity, lap, sport, latitude_deg, longitude_deg, altitude_m, distance_m, heart_rate_bpm, cadence_rpm, speed_mps, watts。缺失的传感器数据为空单元格（在 pandas 中为 NaN），绝不会是零。distance_m 是累计值。0 行 = 室内/无传感器运动（Google 不会为此类运动生成轨迹）——训练摘要和运动笔记来自 data exercise list，而不是轨迹导出。

写入数据

可写入的类型：exercise、sleep、weight、body-fat、height。写入操作是异步的（API 会返回 Operation 对象）。

通过使用 --raw 检查实际响应，找出正确的负载格式：

ghealth data weight list --raw --limit 1
# Use the response structure as a template for your create payload

写入操作使用 create、update --id <id> [--update-mask fields]、delete --ids <ids>。

注意事项

• 缺失的日期不代表零（altitude、distance、floors、steps、total-calories）：汇总输出中没有某个日期，表示用户没有佩戴设备/数据未同步，而不是数值为零。countSum: "0" 才是真正的零（佩戴了设备，但没有活动）。绝不要将缺失的分桶填为 0，也不要将缺失日期按零计入平均值——这会在不知不觉中拉低每周/每月统计数据
• 字符串与数值遵循 protobuf JSON 编码规则：int64 字段（beatsPerMinute、countSum、minutesAsleep）是字符串；int32/double 字段（weightGrams、caloriesKcal、percentage）是数值
• --filter 原始语法：只支持 >= 和 < 比较符。民用时间字段（不带 Z）：区间类型使用 {type}.interval.civil_start_time，睡眠使用 sleep.interval.civil_end_time（只有结束时间可用于筛选），每日类型使用 {type}.date。物理时间字段（带 Z）：样本类型使用 {type}.sample_time.physical_time
• 写入操作是异步的——API 返回的是 Operation 对象，而不是创建/更新后的数据。使用 list 验证数据是否已保存
• 体脂 delete 会返回 HTTP 500——这是 API 缺陷
• 身高 update 会返回 HTTP 400（“updateMask not recognized”）——这是 API 缺陷；可使用 create + delete 作为替代方案
• daily-rollup 按民用/本地日期汇总（1 天窗口；可通过 --window-days N 更改）。rollup 按物理时间汇总（--window-size，默认 86400s）；未附带时间的 --from/--to 日期会锚定到配置时区的午夜（ghealth config set timezone <IANA zone>），如果未设置，则使用机器本地时间。要获取本地每日总量，请使用 daily-rollup。两者都会显式发送窗口大小——API 会拒绝未提供窗口大小的请求