withings-family：从 Withings API 获取家庭成员的多维健康数据

名称： withings-family
描述： 从 Withings API 获取多位家庭成员的健康数据，包括体重、身体成分（脂肪、肌肉、骨骼、水分）、活动和睡眠。当用户询问自己或家人的 Withings 数据、体重历史、身体指标、每日步数、睡眠质量或任何来自 Withings 设备的健康测量值时，请使用此技能。
版本： 1.1.1
主页： https://github.com/odrobnik/withings-family-skill
元数据： {"openclaw": {"emoji": "⚖️", "requires": {"bins": ["python3"], "env": ["WITHINGS_CLIENT_ID", "WITHINGS_CLIENT_SECRET"]}}}

此技能允许您与 多位家庭成员 的 Withings 账户交互，以获取来自 Withings 设备（智能秤、睡眠分析仪、活动追踪器等）的全面健康指标。

多用户支持

此技能原生支持多用户，并为每位用户提供独立的令牌文件：

tokens-alice.json
tokens-bob.json
tokens-charlie.json

每位家庭成员通过 OAuth 进行一次身份验证。他们的令牌被单独存储并自动刷新。无需复制或切换令牌——只需将用户 ID 作为第一个参数传递。

python3 scripts/withings.py alice weight
python3 scripts/withings.py bob sleep
python3 scripts/withings.py charlie activity

何时使用此技能

当用户出现以下情况时，请使用此技能：
- 询问自己的 体重 或体重历史
- 想查看自己的 身体成分（脂肪率、肌肉量、骨量、水合度）
- 请求获取 日常活动 数据（步数、距离、消耗卡路里）
- 询问自己的 睡眠数据（时长、质量、深度睡眠、快速眼动睡眠）
- 提及 "Withings" 或任何 Withings 设备（Body+, Sleep Analyzer, ScanWatch 等）
- 希望追踪自己或 家人 一段时间内的健康进展

设置：创建 Withings 开发者应用

在使用此技能之前，您需要创建一个免费的 Withings 开发者应用以获取 API 凭证。

步骤 1：创建 Withings 开发者账户

1. 访问 Withings 开发者门户
2. 点击 注册，如果已有 Withings 账户则点击 登录
3. 接受开发者服务条款

步骤 2：创建您的应用

1. 导航至 我的应用 → 创建应用
2. 填写应用详情：
   • 应用名称：选择一个名称（例如，"My Moltbot Health"）
   • 描述：简要描述您的用例
   • 联系邮箱：您的邮箱地址
   • 回调 URL：http://localhost:18081（OAuth 必需）
   • 应用类型：选择 "个人使用" 或合适的类型
3. 提交应用

步骤 3：获取您的凭证

应用创建成功后：
1. 进入 我的应用 并选择您的应用
2. 您将找到：
- 客户端 ID → 设置为 WITHINGS_CLIENT_ID 环境变量
- 客户端密钥 → 设置为 WITHINGS_CLIENT_SECRET 环境变量

步骤 4：配置环境变量

将这些添加到您的 Moltbot 环境中：

export WITHINGS_CLIENT_ID="your_client_id_here"
export WITHINGS_CLIENT_SECRET="your_client_secret_here"

或者在 ~/.openclaw/withings-family/.env（旧路径：~/.moltbot/withings-family/.env）中创建一个 .env 文件：

WITHINGS_CLIENT_ID=your_client_id_here
WITHINGS_CLIENT_SECRET=your_client_secret_here

配置

此技能提供两个脚本（位于 scripts/ 目录下）：
- scripts/withings_oauth_local.py — 使用本地回调服务器进行自动 OAuth 认证（推荐）
- scripts/withings.py — 主命令行界面 + 手动 OAuth 认证

凭证存储位置： ~/.openclaw/withings-family/（旧路径：~/.moltbot/withings-family/）
- .env — 客户端 ID/密钥（可选，也可使用环境变量）
- tokens-<userId>.json — 每位用户的 OAuth 令牌（模式 600）

在任何数据检索之前，请检查用户是否已认证。如果错误提示"未找到令牌"，请引导该特定用户完成初始身份验证流程。

身份验证方法

方法 A：自动 OAuth（推荐）

使用本地回调服务器自动捕获授权码：

python3 {baseDir}/scripts/withings_oauth_local.py <userId>

示例：

python3 {baseDir}/scripts/withings_oauth_local.py alice

该脚本将：
1. 打印授权 URL
2. 在 localhost:18081 上启动本地服务器
3. 等待重定向
4. 自动捕获授权码并交换为令牌
5. 将令牌保存到 tokens-<userId>.json

方法 B：手动 OAuth

传统的两步流程（见下文"身份验证"命令）。

可用命令

所有命令遵循以下格式：

python3 {baseDir}/scripts/withings.py <userId> <command> [options]

1. 身份验证

用户的首次设置——生成 OAuth URL：

python3 {baseDir}/scripts/withings.py alice auth

用户访问该 URL 并获得授权码后：

python3 {baseDir}/scripts/withings.py alice auth YOUR_CODE_HERE

为每位需要访问权限的家庭成员重复此步骤。

2. 获取体重

检索最新的体重测量值：

python3 {baseDir}/scripts/withings.py alice weight

以 JSON 格式返回最近的 5 个体重记录。

示例输出：

[
  { "date": "2026-01-17T08:30:00.000Z", "weight": "75.40 kg" },
  { "date": "2026-01-16T08:15:00.000Z", "weight": "75.65 kg" }
]

3. 获取身体成分

检索全面的身体指标（脂肪、肌肉、骨骼、水分、BMI）：

python3 {baseDir}/scripts/withings.py alice body

返回最近的 5 次身体成分测量结果。

示例输出：

[
  {
    "date": "2026-01-17T08:30:00.000Z",
    "weight": "75.40 kg",
    "fat_percent": "18.5%",
    "fat_mass": "13.95 kg",
    "muscle_mass": "35.20 kg",
    "bone_mass": "3.10 kg",
    "hydration": "55.2%"
  }
]

4. 获取活动数据

检索日常活动数据（步数、距离、卡路里）：

python3 {baseDir}/scripts/withings.py alice activity

可选指定天数（默认：7）：

python3 {baseDir}/scripts/withings.py alice activity 30

示例输出：

[
  {
    "date": "2026-01-17",
    "steps": 8542,
    "distance": "6.23 km",
    "calories": 2150,
    "active_calories": 450,
    "soft_activity": "45 min",
    "moderate_activity": "22 min",
    "intense_activity": "8 min"
  }
]

5. 获取睡眠数据

检索睡眠数据和质量：

python3 {baseDir}/scripts/withings.py alice sleep

可选指定天数（默认：7）：

python3 {baseDir}/scripts/withings.py alice sleep 14

示例输出：

[
  {
    "date": "2026-01-17",
    "start": "23:15",
    "end": "07:30",
    "duration": "8h 15min",
    "deep_sleep": "1h 45min",
    "light_sleep": "4h 30min",
    "rem_sleep": "1h 30min",
    "awake": "30min",
    "sleep_score": 82
  }
]

错误处理

常见错误及解决方法：

注意事项

• 多用户： 每位家庭成员都有自己的令牌文件（tokens-{userId}.json）
• 令牌刷新： 令牌过期时会自动刷新
• 权限范围： 使用的 Withings API 权限范围：user.metrics, user.activity
• 设备支持： 数据可用性取决于用户拥有的 Withings 设备类型
• 身体成分： 需要兼容的智能秤（例如，Body+, Body Comp）