name: "withings"
description: "Use when linking Withings or reading Withings body measurements, activity, sleep, workout, heart, and intraday data."
icon: "withings"
metadata: { "includeInPrompt": false }

Withings / Withings

Query Withings body measurements, activity, sleep, and workout data via the bundled withings CLI.

通过内置的 withings 命令行工具查询 Withings 的身体测量、活动、睡眠和锻炼数据。

When to Use / 何时使用

Activate when the user asks about their Withings data:

• Body metrics (weight, BMI, body fat, blood pressure, heart rate)
  身体指标（体重、BMI、体脂、血压、心率）
• Daily activity (steps, calories, distance, active duration)
  日常活动（步数、卡路里、距离、活动时长）
• Sleep sessions (score, stages, duration, breathing rate)
  睡眠时段（评分、分期、时长、呼吸频率）
• Workout sessions (run/walk/cycle/etc.)
  锻炼时段（跑步/步行/骑行等）

Tooling / 工具

Three subcommands cover most needs:

三个子命令覆盖大多数需求：

Categories / 类别

• daily-metrics — Daily rollup of Activity (steps/calories/distance/HR) + Measures (weight/BP/body composition). Supports --interval hourly|daily|weekly (defaults to daily). Aggregation rules: sum for counters (step_count, active_energy_burned_kcal, distance_walking_running_meters), avg for hr_average_bpm, max for hr_max_bpm, last-of-bucket for body measurements (weight/BP/body fat etc.).
  daily-metrics — 活动（步数/卡路里/距离/心率）+ 测量（体重/血压/身体成分）的每日汇总。支持 --interval hourly|daily|weekly（默认 daily）。聚合规则：计数器取和（step_count、active_energy_burned_kcal、distance_walking_running_meters），hr_average_bpm 取平均，hr_max_bpm 取最大，身体测量（体重/血压/体脂等）取桶内最后一个值。
• sleep — One row per sleep session (score, stages, duration, HR, breathing).
  sleep — 每个睡眠时段一行（评分、分期、时长、心率、呼吸）。
• workout — One row per workout session (translated workout_type name, duration, distance, calories, HR).
  workout — 每个锻炼时段一行（翻译后的 workout_type 名称、时长、距离、卡路里、心率）。

Use list-fields to discover available fields per category.

用 list-fields 发现各类别可用的字段。

Output / 输出

JSON to stdout. Datetimes are local YYYY-MM-DD HH:MM:SS per record's timezone. Session rows include id (prefixed withings_<id>), start_datetime, end_datetime, timezone. daily-metrics buckets include date / hour / week_start + record_count instead of id.

JSON 输出到 stdout。日期时间按每条记录所在时区以本地 YYYY-MM-DD HH:MM:SS 表示。时段行包含 id（前缀 withings_<id>）、start_datetime、end_datetime、timezone。daily-metrics 桶包含 date / hour / week_start + record_count，而没有 id。

Examples / 示例

# Recent workouts
withings query --category workout --start-date 2026-05-01

# Weight trend (last reading per day)
withings query --category daily-metrics --start-date 2026-04-01 --fields body_mass_kg

# Weekly step totals
withings query --category daily-metrics --start-date 2026-04-01 --interval weekly --fields step_count

Auth / 认证

Before any Withings API call:

1. Run withings status.
   运行 withings status。
2. If status is not_connected, share [Connect Withings](<connect_url>) exactly — never paste the raw URL.
   如果 status 为 not_connected，原样分享 [Connect Withings](<connect_url>)——绝不要粘贴原始 URL。
3. After the user completes the callback, re-run withings status and proceed only when connected.
   用户完成回调后，重新运行 withings status，仅在 connected 时继续。

For disconnect: run withings disconnect and share [Disconnect Withings](<disconnect_url>) if present.

断开连接：运行 withings disconnect，如存在则分享 [Disconnect Withings](<disconnect_url>)。

Never print tokens or credentials.

绝不要打印令牌或凭据。

Operating Rules / 操作规则

1. Treat linking as one-time onboarding — don't re-prompt for auth unless calls keep failing.
   把关联当作一次性引导——除非调用持续失败，否则不要反复提示认证。
2. Prefer query --category <CAT> over the legacy commands. Field names are snake_case with units in the name (body_mass_kg, step_count, hr_average_bpm, sleep_total_duration_sec) — never expose Withings's numeric meas-type IDs to the user.
   优先用 query --category <CAT> 而不是旧版命令。字段名是 snake_case 且单位含在名称中（body_mass_kg、step_count、hr_average_bpm、sleep_total_duration_sec）——绝不要向用户暴露 Withings 的数字 meas-type ID。
3. If unsure of a field name, run withings list-fields --category <CAT> BEFORE composing query --fields. Withings-native names (calories, distance, hr_average, weight) are NOT valid — they're translated to snake_case with units (energy_burned_kcal, distance_meters, hr_average_bpm, body_mass_kg). An empty filter result usually means the field name was wrong, not that the data is missing.
   如果不确定字段名，先运行 withings list-fields --category <CAT>，再组装 query --fields。 Withings 原生名称（calories、distance、hr_average、weight）是无效的——它们会被翻译为带单位的 snake_case（energy_burned_kcal、distance_meters、hr_average_bpm、body_mass_kg）。过滤结果为空通常意味着字段名写错了，而不是数据缺失。
4. Default to the last 7 days when the user asks for recent trends without specifying dates.
   当用户询问近期趋势而未指定日期时，默认取最近 7 天。
5. For broad trends, use --category daily-metrics --interval weekly instead of pulling every reading. The --interval flag already aggregates per the rules above — do NOT apply additional aggregation (sum/avg) to the bucketed output client-side.
   对于大范围趋势，用 --category daily-metrics --interval weekly，而不是拉取每一条读数。--interval 标志已按上述规则聚合——不要在客户端对分桶输出再做额外聚合（求和/平均）。
6. If query returns [], say so clearly — never invent values. If the user is asking for a metric not surfaced by list-fields, drop to the legacy escape hatch (measures --meas-types <ID> or a more specific subcommand like heart-list; see references/commands.md for the meas-type ID table).
   如果 query 返回 []，明确说出来——绝不要编造数值。如果用户要的指标未出现在 list-fields 中，退回到旧版逃生通道（measures --meas-types <ID> 或更具体的子命令如 heart-list；meas-type ID 对照表见 references/commands.md）。

Legacy / Advanced Commands / 旧版/高级命令

Pre-query per-endpoint passthroughs that return raw {ok, status, body: <Withings native>} envelopes. Use only as an escape hatch for data not exposed by query — e.g. a meas-type missing from the translation table (withings measures --meas-types 130 for AFib ECG result), high-frequency sleep sensor data (withings sleep), or ECG signals (withings heart-list / heart-get).

早于 query 的逐端点透传命令，返回原始的 {ok, status, body: <Withings native>} 信封。只作为 query 未暴露数据的逃生通道使用——例如翻译表中缺失的 meas-type（withings measures --meas-types 130 获取房颤 ECG 结果）、高频睡眠传感器数据（withings sleep），或 ECG 信号（withings heart-list / heart-get）。

Quick reference for the other passthroughs:

• withings activity — raw daily Activity rows.
  withings activity — 原始的每日活动行。
• withings sleep-summary — raw nightly sleep summaries with Withings-native field names.
  withings sleep-summary — 使用 Withings 原生字段名的原始夜间睡眠摘要。
• withings intraday — minute-resolution activity sensor data.
  withings intraday — 分钟级分辨率的活动传感器数据。
• withings devices — list paired Withings devices.
  withings devices — 列出已配对的 Withings 设备。

Full command matrix, meas-type IDs, and Withings → Muse field mapping: references/commands.md.

完整命令矩阵、meas-type ID 以及 Withings → Muse 字段映射：references/commands.md。

• Permission-withheld data: while the user's "Read measurements and heart
  data" permission is deny or ask, query --category daily-metrics wraps its
  rows in {"withheld": {...}, "records": [...]} with body metrics (weight,
  blood pressure, SpO2, heart measurements) removed, and a request for only
  those fields fails with data_class_excluded. Key off the withheld
  marker: when present, the permission is restricting those fields — say so
  instead of "no readings". When the user actually needs a withheld metric
  and the permission requires approval (withheld.reason is
  requires_approval, or a body-metrics-only query failed with
  data_class_excluded saying it requires approval), run
  withings measures --category 1 --start-date <d> --end-date <d>, which is
  governed by that permission and shows the user the approval prompt. Sleep
  and workout results are never wrapped; a response without the marker is an
  ordinary result.
  权限被扣留的数据：当用户的"读取测量和心脏数据"权限为 deny 或 ask 时，query --category daily-metrics 会把其行包装在 {"withheld": {...}, "records": [...]} 中，并移除身体指标（体重、血压、SpO2、心脏测量），而只请求这些字段的查询会以 data_class_excluded 失败。以 withheld 标记为准：当它出现时，说明权限正在限制这些字段——要如实说明，而不是说"没有读数"。当用户确实需要某个被扣留的指标且该权限需要审批（withheld.reason 为 requires_approval，或仅身体指标的查询以 data_class_excluded 失败并说明需要审批）时，运行 withings measures --category 1 --start-date <d> --end-date <d>，它受该权限管辖并会向用户展示审批提示。睡眠和锻炼结果从不被包装；没有该标记的响应就是普通结果。
  【评论】数据按权限类别在服务端过滤，代理通过 withheld 标记区分"无数据"与"被权限扣留"，避免把隐私限制误报为设备没有数据。