wearable-sync

# MediWise · 可穿戴数据导入 Skill 把用户明确提供的可穿戴导出文件读取、标准化并写入 MediWise 健康指标。当前公开流程只面向个人本地 Agent 环境。 ## 可用性分级 | Provider | 状态 | 数据来源 | 说明 | |---|---|---|---| | Apple Health | ✅ 已验证 | `export.zip` / `export.xml` | 支持文件检查、导入、标准化与去重 | | Gadgetbridge | ✅ 已验证 | SQLite 导出数据库 | 只读导入常见活动数据表 | | Garmin Connect | 🧪 实验性 | 非官方 Garmin Connect 接口 | 没有安全的免代码凭据输入能力时不得引导绑定 | | Huawei Health Kit | ⛔ 暂不可用 | OAuth API | 授权回调尚未完成 | | Zepp / 小米云账号 | ⛔ 暂不可用 | 非官方账号接口 | 账号兼容性和凭据处理未达到稳定发布标准 | | OpenWearables | ⛔ 暂不可用 | 统一 API | 当前是 Stub | 不得因为代码中存在 Provider 类，就把实验性或未完成来源描述成“已支持”。 ## 用户交互规则 1. 用户只需要用自然语言提出导入请求并上传导出文件。 2. 不要求普通用户运行 Python、Node.js、Shell、pip 或其他命令。 3. 不在聊天中索要 API Key、账号密码、token 或其他凭据。 4. 一个本地用户可以管理多位家人：只有唯一“本人”档案时可默认本人；出现多位成员后必须按姓名确认目标，不得根据文件内容猜测。 5. 不把当前 MediWise 数据目录用于群聊机器人或多人共享服务。 6. 不修改用户提供的 Apple Health 或 Gadgetbridge 原始文件。 7. 完成后必须报告新增数量、重复跳过数量、实际指标类型和时间范围；不能只回复“同步成功”。 如果 action 返回个人模式未配置、依赖缺失或安装路径错误，应让具备本机访问权限的 AI 助手修复安装，不要把代码命令转交给普通用户。 ## Apple Health 导入流程 ### 用户侧准备 指导用户在 iPhone 中： 1. 打开“健康”App。 2. 点击右上角头像。 3. 选择“导出所有健康数据”。 4. 保存或上传系统生成的 `export.zip`。 导出包包含敏感健康数据，只能交给用户信任的个人本地 Agent。 ### Agent 执行顺序 1. 调用 `resolve-member`：唯一“本人”可默认；有多位成员时按姓名确认，并复述“姓名（身份）”。 2. 确认附件已落到当前 Agent 可读取的本地路径，扩展名为 `.zip` 或 `.xml`。 3. 调用 `device-add`，Provider 使用 `apple_health`。 4. 调用 `device-auth`，把附件本地路径作为 `export_path`。 5. 调用 `device-test` 检查标准 `export.xml`、XML 完整性和 Apple Health 根节点。 6. 调用 `sync-device` 导入。 7. 使用 `sync-device` 返回的 `provider`、`member`、`metric_types`、`metric_stats` 和 `time_range` 汇总本次结果；需要查看具体记录时再查询健康指标。 Apple Health 导出是手动快照，不是实时流。用户再次上传新导出包时可重新导入；系统会按成员、指标类型、测量时间和来源跳过重复记录。 ### Apple Health 可识别指标 - 心率、步数、血氧、睡眠 - 体重、身高、体脂 - 血糖、血压 - 活动卡路里 实际导入项以文件内容为准。不得看到 Apple Watch 型号后就声称上述指标全部存在。 ## Gadgetbridge 导入流程 ### 用户侧准备 此流程只适合已经使用 Gadgetbridge 管理设备的用户。指导用户在 Gadgetbridge App 的“设置”或“数据库管理”中导出数据库，然后上传 `Gadgetbridge` 或 `Gadgetbridge.db` 文件。 设备兼容性以 Gadgetbridge 官方支持列表为准。不要声称所有小米、Amazfit 或华为设备都适用。 ### Agent 执行顺序 1. 调用 `resolve-member`：唯一“本人”可默认；有多位成员时按姓名确认，并复述“姓名（身份）”。 2. 确认附件已落到当前 Agent 可读取的本地路径。 3. 调用 `device-add`，Provider 使用 `gadgetbridge`。 4. 调用 `device-auth`，把附件本地路径作为 `export_path`。 5. 调用 `device-test`，确认它是可读取的 SQLite 数据库且包含已知活动数据表。 6. 调用 `sync-device` 导入。 7. 查询该成员本次导入后的健康指标，汇总类型、条数和时间范围。 当前解析器可识别部分常见数据表中的心率、步数、血氧与睡眠活动。具体结果取决于设备型号、Gadgetbridge 版本及导出表结构。 ## Garmin 处理规则 Garmin Provider 已有数据获取实现，但依赖非官方 Garmin Connect Web 接口和一次账号认证，无法仅凭仓库内离线测试确认真实账号长期可用。 当前必须遵守： - 将 Garmin 表述为“实验性接入”，不表述为已验证支持。 - 绝不让用户把 Garmin 密码发到聊天中。 - 不向普通用户展示或要求执行认证命令。 - 当前客户端没有安全的本地凭据输入能力时，明确说明暂时不能绑定并停止。 - 不用环境变量、命令行参数或明文配置绕过安全限制。 ## 暂不可用来源 Huawei Health Kit、Zepp / 小米云账号和 OpenWearables 不得进入用户绑定流程： - Huawei 的 OAuth 回调尚未完成。 - Zepp 对迁移后的小米账号兼容性不足，当前凭据生命周期也不满足稳定发布要求。 - OpenWearables Provider 明确是未实现占位。 用户询问时应直接说明限制，不要让用户尝试未完成的授权流程或调试代码。 ## 可调用 Action | Action | 用途 | 关键参数 | |---|---|---| | `device-add` | 为成员登记数据来源 | `member_id`、`provider`、可选 `device_name` | | `device-list` | 查看成员已登记来源 | `member_id` | | `device-remove` | 停用已登记来源 | `device_id` | | `device-auth` | 校验并保存导出文件路径 | `device_id`、`export_path` | | `device-test` | 检查导出文件是否可读取 | `device_id` | | `sync-device` | 导入一个来源 | `device_id` | | `sync-status` | 查看最近同步状态 | `device_id` | | `sync-history` | 查看导入历史 | `device_id`、可选 `limit` | 这些 Action 由 Agent 调用，不是让用户手动执行的命令。 ## 结果与错误说明 成功回复至少包含： - 数据来源和目标成员。 - 新增条数与重复跳过条数。 - 实际出现的指标类型。 - 最早和最晚记录时间。 - 没有导入到预期指标时的明确说明。 常见失败处理： | 错误 | 处理方式 | |---|---| | 文件不存在 | 检查聊天附件是否已经下载到 Agent 可访问路径 | | ZIP/XML 不可读 | 说明文件损坏或不是 Apple Health 导出，不继续写库 | | SQLite 无已知表 | 说明当前 Gadgetbridge 设备/版本表结构尚未适配 | | 目标成员不明确 | 先列出成员并请用户选择 | | 个人模式未生效 | 由具备本机权限的 AI 修复当前 Agent 的安装配置 | | 来源暂不可用 | 如实说明状态，不尝试绕过 | ## 隐私边界 - Apple Health 和 Gadgetbridge 文件在本地读取，原文件不应被修改。 - 导入文件、数据库和同步日志不得提交到 Git、ClawHub 或测试 fixture。 - 只记录处理结果摘要，不在普通日志中输出完整健康数据。 - 云端模型不是解析这两种导出格式的必需条件。 更详细的用户操作文案见 `docs/WEARABLES.md`。