核心用法
withings-family 是一款面向家庭场景的健康数据聚合技能，通过 Withings API 获取智能体重秤、睡眠监测仪、运动手环等设备的多维健康指标。支持多用户 OAuth 认证体系，每个家庭成员独立存储 Token，互不干扰。
主要功能模块
- 体重管理：获取最新体重记录及历史趋势
- 身体成分分析：体脂率、肌肉量、骨量、水分含量、BMI
- 活动追踪：步数、距离、卡路里消耗、活动强度分级
- 睡眠质量：睡眠时长、深睡/浅睡/REM 比例、睡眠评分
认证流程
首次使用需完成 Withings 开发者应用注册（免费），配置 WITHINGS_CLIENT_ID 和 WITHINGS_CLIENT_SECRET 环境变量。支持两种 OAuth 模式：自动本地回调服务器（推荐）或传统手动授权码交换。Token 过期自动刷新，无需重复认证。
多用户设计亮点
采用 tokens-<userId>.json 文件隔离机制，命令行首个参数指定用户身份，天然支持家庭多成员场景：
python3 scripts/withings.py alice weight # 获取 Alice 体重 python3 scripts/withings.py bob sleep # 获取 Bob 睡眠数据
显著优点
1. 多用户架构原生支持：无需复杂配置即可管理全家健康数据
2. Token 生命周期全自动：刷新、存储、隔离完全透明
3. 设备生态完整：覆盖 Withings 全系产品（Body+、ScanWatch、Sleep Analyzer 等）
4. 数据维度丰富：从基础体重到睡眠分期、活动强度分级
5. 隐私隔离到位：每个用户独立 Token 文件，权限边界清晰
潜在局限
- 前置依赖较重：需自行注册 Withings 开发者账号，流程对非技术用户不够友好
- 设备门槛：身体成分数据需兼容型号（如 Body+），基础款体重秤无法提供
- 本地化限制：回调 URL 固定
localhost:18081，远程部署需额外隧道方案 - API 稳定性：依赖 Withings 官方 API，偶发 503 服务不可用
- 无内置可视化：纯 JSON 输出，需配合外部工具做图表展示
适合人群
- 已有 Withings 智能设备的家庭用户
- 需要集中管理多位家庭成员健康数据的场景
- 具备基础技术能力、能独立完成 OAuth 配置的 DIY 用户
- 希望将健康数据导入自定义系统（Notion、Home Assistant、自建数据库）的进阶玩家
常规风险
- Token 文件安全：
tokens-*.json包含敏感凭证，需确保600权限及存储路径安全 - 环境变量泄露：CLIENT_SECRET 若写入 shell history 或日志存在暴露风险
- 数据隐私合规：家庭健康数据属于敏感个人信息，跨账户聚合需获得成员明确授权
- API 速率限制：高频调用可能触发 Withings 限流策略
- Token 失效场景：用户修改 Withings 密码或撤销授权后需重新走完整认证流程