用途:读取用户 Android 设备同步的 Google Health Connect 数据,覆盖全天指标与生命体征(步数、距离、卡路里、心率、HRV、VO2max)、睡眠会话(阶段、质量、效率、醒来次数)以及锻炼(类型、时长、卡路里、距离、心率)。每条命令都必须带 --provider healthconnect,且它没有默认值,省略即为用法错误。
主要命令:health-cli query metrics --provider healthconnect 获取全天指标汇总(默认按天分桶,可 hourly/daily/weekly);query samples 获取原始未分桶数据点(日内心率/步数、GPS、睡眠阶段时间线);query sessions --category sleep|workout 获取睡眠或锻炼等离散会话;status 查看同步状态,加 --check-missing-entries(需配合 --start-date)可做每 30 分钟的缺口报告;auth connect 连接,auth disconnect 断开;delete 删除已存记录。
用法要点:query 命令必须传 --start-date(YYYY-MM-DD),--end-date 默认今天。发现字段用 --list-fields(sessions 需先 --category),observed: true 表示该用户数据中存在该字段。结果封装为 { coverage, records },当 coverage.complete 为 false 时应提示数据不完整并按 coverage.warning 中的 backfill_data_source 命令补拉后重查。密集读取建议用 --output <path> 写 CSV 以免占用上下文。多设备窗口会带 multi_node: true,不得跨设备求和。
限制:仅服务 Android 设备,非 Android 配对设备无数据(可用 device.list 的 platform 字段确认)。Health Connect 无法通过该 CLI 或聊天组件断开,需指引用户在设置→连接器→Health Connect→管理及 Android 系统设置中撤销权限。delete 为破坏性且不可逆操作,需一次性审批,按 provider 分别执行,不做按类别或记录 ID 删除;返回码 3 表示拒绝且未删除;删除不影响设备端记录,后续同步可能恢复。GPS 为原始经纬度,不应据此推断地点名称。该技能为设备同步、无需登录,但数据可用性取决于 Android 端权限批准与同步状态。