跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.mirobody.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
什么是 Provider

Provider 是一种可插拔的适配器，负责从外部数据源（可穿戴 API、移动健康平台、数据库等）拉取原始数据，并将其归一化为 Mirobody 的 StandardPulseData 标准结构。每个 Provider 位于 mirobody/pulse/ 下的独立目录中（自定义 Provider 则放在 providers/），启动时自动加载。 健康垂直下的 Provider 大致分为三类：
  • Theta 平台（mirobody/pulse/theta/）—— 由 Mirobody 自行维护的直连 OAuth/凭据集成：Garmin、Whoop、Oura、Renpho、Vital、PostgreSQL。
  • Apple（mirobody/pulse/apple/）—— iOS Health 导出以及 CDA（Clinical Document Architecture）医疗记录。
  • Vital（位于 Theta 平台之下）—— 一个聚合层，通过单一 OAuth 流程对接 300+ 可穿戴和 EHR 端点，覆盖约 90% 的美国医疗记录。
所有 Provider 最终都写入相同的归一化表（th_series_data、th_event_data），因此下游工具、Agent 和 MCP 客户端无论数据来源如何，看到的都是统一的数据模型。

​
Provider 矩阵

Provider模块数据认证方式配置键凭据获取
Garminmirobody/pulse/theta/mirobody_garmin_connect/活动、睡眠、心率、HRV、压力、身体成分、训练OAuth 1.0aGARMIN_CLIENT_ID、GARMIN_CLIENT_SECRET、GARMIN_REDIRECT_URLGarmin 开发者门户
Whoopmirobody/pulse/theta/mirobody_whoop/恢复、睡眠、负荷、训练、周期OAuth 2.0WHOOP_CLIENT_ID、WHOOP_CLIENT_SECRET、WHOOP_REDIRECT_URLWhoop 开发者门户
Ouramirobody/pulse/theta/mirobody_oura/睡眠、准备度、活动、HRVOAuth 2.0OURA_CLIENT_ID、OURA_CLIENT_SECRET、OURA_REDIRECT_URLcloud.ouraring.com
Renphomirobody/pulse/theta/mirobody_renpho/体重、体脂、BMI、肌肉量、水分邮箱 + 密码RENPHO_*（绑定时由用户提供）Renpho 移动应用账号
Vitalmirobody/pulse/theta/mirobody_vital/300+ 可穿戴及 EHR 端点（Fitbit、Polar、Withings、Dexcom、Epic、Cerner 等）通过 Vital 的 OAuthVITAL_API_KEY、VITAL_ENVIRONMENT、VITAL_REDIRECT_URLtryvital.io
PostgreSQLmirobody/pulse/theta/mirobody_pgsql/用户自有 Postgres 数据库中的任意表连接串绑定时的 host、port、database、user、password您自己的数据库
Apple Healthmirobody/pulse/apple/iOS Health 导出、CDA 医疗记录iOS App + Apple OAuthAPPLE_CLIENT_ID、APPLE_TEAM_ID、APPLE_KEY_ID、APPLE_PRIVATE_KEYApple 开发者门户
Google Health通过 VitalAndroid Health Connect、Google Fit通过 Vital 的 OAuth（在 Vital 下配置）Google Cloud Console
各配置键的写入位置和首次加载时的 Fernet 加密机制，参见 配置。

​
如何连接一个 Provider

1

在配置文件中填入 OAuth 凭据

先到对应厂商的开发者门户（见上方矩阵中的链接）注册应用，然后将凭据写入 config.{env}.yaml。以 Garmin 为例：
config.localdb.yaml
GARMIN_CLIENT_ID: 'your_consumer_key'
GARMIN_CLIENT_SECRET: 'your_consumer_secret'
GARMIN_REDIRECT_URL: 'http://localhost:18080/api/v1/pulse/theta/theta_garmin/callback'
重启 Mirobody，让加密后的值重新加载。完整的配置键列表见 配置。
2

打开 Web 界面

访问 localhost:18080 登录，进入 Drive → Providers。所有在配置中找到凭据的 Provider 都会出现在列表里，其余则灰显并附带提示，指引你回到这里。
3

点击 Connect

按钮会在新标签页中打开厂商的 OAuth 同意页。授权后，厂商会重定向回上一步配置的回调地址，Mirobody 会把（加密的）刷新令牌写入该用户记录。对于密码型 Provider（Renpho）和 DSN 型 Provider（PostgreSQL），看到的是一个小表单而不是 OAuth 跳转。
4

验证

Provider 卡片切换为 Connected 并显示最近同步时间。也可以通过 API 验证：
curl "http://localhost:18080/api/v1/pulse/providers?user_id=YOUR_USER_ID"
该 Provider 的 "status" 应为 "connected"，last_sync 不为空。

​
拉取节奏与同步

Provider 绑定后，mirobody/pulse/theta/platform/pull_task.py 会为该用户调度一个 pull 任务：
  • 初次回填 立即执行。窗口长度由厂商决定 —— Garmin 与 Whoop 默认 30 天，Oura 默认 90 天，Vital 按上游 API 允许的范围拉取。
  • 增量拉取 按固定节奏运行（多数 Provider 每小时一次；仅体成分类的 Provider 改为每日一次）。每次拉取以 last_sync 为窗口起点，并按 msg_id 去重。
  • Token 刷新 对 OAuth 2.0 Provider 自动完成；OAuth 1.0a Token（Garmin）不过期。
  • 失败 会按 用户/Provider 组合记录日志，并在下一次轮询时重试 —— 不会阻塞其他 Provider。
手动触发同步： 
curl -X POST "http://localhost:18080/api/v1/pulse/theta/theta_garmin/pull" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "YOUR_USER_ID"}'
解除绑定： 
curl -X POST "http://localhost:18080/api/v1/pulse/theta/theta_garmin/unlink" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "YOUR_USER_ID"}'

​
自定义 Provider

如果上面的矩阵里没有你需要的设备或数据源，自己写一个即可。在项目根目录的 providers/ 下新建一个 mirobody_<slug>/ 目录，继承 BaseThetaProvider，实现 info、凭据校验方法以及（可选的）pull_from_vendor_api。Mirobody 下次启动时会自动发现并加载。

Provider 集成指南

完整流程：目录结构、基类、OAuth 模式、数据映射、测试。

​
下一步

配置

所有 Provider 的配置键及其写入位置

OAuth 实现

Theta Provider 使用的 OAuth 1.0a 与 2.0 模式

数据映射

厂商原始数据到 StandardPulseData

Provider 测试

端到端测试 link、callback、pull 与 unlink