mcpField
P
pp-oura

pp-oura

github.com/mvanhorn其他2.1k55 次安装今天更新
代码仓库

关于 pp-oura

pp-oura 是通过 `oura-pp-cli` 访问 Oura API 数据的技能，涵盖睡眠、活动、心率等用户集合记录。它支持本地同步、离线搜索、数据分析和串联 API 操作，适用于 Oura 用户及合作应用。

主要功能

  1. 01访问 Oura 用户集合记录
  2. 02将数据同步到本地 SQLite
  3. 03使用 FTS5 搜索已同步记录
  4. 04通过分析查询汇总数据
  5. 05在工作流中串联 API 操作

适用场景

  1. 01搜索本地同步的 Oura 记录
  2. 02汇总分析健康数据
  3. 03组合执行多项 Oura API 操作

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mvanhorn/printing-press-library --skill pp-oura

安装后在 Claude Code 中输入/pp-oura确认已加载。

详细介绍

Oura — Printing Press CLI

前提条件：安装 CLI

此技能依赖 oura-pp-cli 二进制文件。调用此技能中的任何命令前，必须确认 CLI 已安装。 如果尚未安装，请先安装：

  1. 使用 Printing Press 安装程序进行安装。在 macOS/Linux 上，默认将二进制文件安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin： 
    npx -y @mvanhorn/printing-press-library install oura --cli-only
  2. 验证：oura-pp-cli --version
  3. 确保所显示的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果通过 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）。此方式会将文件安装到 $GOPATH/bin（默认为 $HOME/go/bin），因此请将该目录添加到 $PATH：

go install github.com/mvanhorn/printing-press-library/library/health/oura/cmd/oura-pp-cli@latest

如果安装后 --version 显示“command not found”，说明运行时无法在 $PATH 中找到二进制文件所在目录。验证成功之前，请勿继续执行技能命令。

概述

Oura API 可帮助 Oura 用户和合作伙伴应用利用 Oura 数据改善用户体验。 本文档介绍 Oura API Version 2（V2），这是目前访问 Oura 数据的唯一集成方式。此前的 V1 API 已停止服务。

入门

什么是 API？

API（应用程序编程接口）可让不同的软件应用相互通信。Oura API 支持以编程方式访问 Oura Ring 数据。

快速入门指南

  1. 注册 API 应用并实现 OAuth2
  2. 发起首次 API 调用： 
    curl -X GET https://api.ouraring.com/v2/usercollection/personal_info \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
  3. 探索数据类型：
    • 浏览本文档中的可用端点，了解可以访问哪些数据
    • 每个端点都包含请求和响应示例
  4. 设置 Webhook（强烈建议）：
    • Webhook 是获取 Oura 数据的首选方式
    • 如果正确实现 Webhook，我们尚未遇到客户触及速率限制的情况
    • 用户首次连接时，只需请求一次历史数据；之后使用 Webhook 获取持续更新
    • 移动应用完成数据同步后约 30 秒，会发送 Webhook 通知
    • 设置 Webhook，以便在数据发生变化时接收通知

常见问题

  • 数据延迟：不同类型的数据同步时间各不相同——睡眠数据需要用户打开 Oura 应用，而每日活动和压力数据可能会在后台同步

数据访问

要访问数据，必须注册 API 应用。 API 应用在获得 Oura 批准前最多只能有 10 位用户。应用获批后则没有数量限制。 此外，Oura 用户必须同意共享 API 应用可访问的每种数据类型。 通过 Oura API 发起的所有数据访问请求都需要进行身份验证。 此外，我们建议 Oura 用户保持移动应用为最新版本，以支持访问最新数据类型。

身份验证

Oura Cloud API 支持通过业界标准的 OAuth2 协议进行身份验证。更多信息请参阅我们的身份验证说明。 访问令牌必须按以下方式包含在请求标头中：

GET /v2/usercollection/personal_info HTTP/1.1
Host: api.ouraring.com
Authorization: Bearer <token>

请注意，个人访问令牌已于 2025 年 12 月弃用，目前已无法使用。

Oura HTTP 响应代码

响应代码说明
200 OK请求成功
400 查询参数验证错误请求包含无效或格式不正确的查询参数。
401 未授权身份验证令牌无效或已过期。
403 禁止访问请求的资源需要额外权限，或用户的 Oura 订阅已过期。
429 请求过多超出速率限制。请查看响应标头，了解重试建议。

速率限制

API 在两个层级实施速率限制，以确保所有应用都能公平访问：

  • 单个访问令牌的限制，用于限制单令牌的大量请求；以及
  • 单个应用的限制，用于限制该应用所有最终用户令牌的总流量，避免某个扇出型应用占用共享容量。

触发任一层限制的请求都会收到 429 Too Many Requests。X-RateLimit-Tier 响应标头会指出触发限制的层级。

如果你的应用经常接近速率限制，强烈建议使用 webhooks — 大多数正确实现 webhook 的应用都不会遇到速率限制问题。

速率限制响应标头

返回 429 Too Many Requests 响应时，会包含五个标头以指导重试。建议优先使用这些标头，而不是固定间隔的退避策略：

  • Retry-After — 重试前需要等待的整数秒数。符合 RFC 7231；可直接用于客户端的退避逻辑。
  • X-RateLimit-Limit — 当前窗口内的请求上限。
  • X-RateLimit-Window — 请求上限所适用的滚动窗口长度，单位为秒。
  • X-RateLimit-Reset — 窗口重置并完全恢复配额时的 Unix 纪元时间（秒）。
  • X-RateLimit-Tier — 指明超出的限制层级，便于联系支持团队。

独特功能

这些功能在此 API 的其他工具中均不可用。

  • sync — 将 Oura 用户集合数据镜像到本地 SQLite 存储，以便离线搜索和分析
  • search — 对本地同步的 Oura 记录进行 FTS5 全文搜索
  • analytics — 对本地同步的健康数据进行分组和计数聚合查询
  • workflow — 将多个 Oura API 操作串联为一条便于 Agent 使用的命令

使用示例

oura-pp-cli usercollection multiple-heartrate-documents --json

oura-pp-cli usercollection multiple-workout-documents --json

oura-pp-cli usercollection single-personal-info-document --json

命令参考

sandbox — 管理沙盒

  • oura-pp-cli sandbox multiple-daily-activity-documents — 沙盒 - 多个每日活动文档
  • oura-pp-cli sandbox multiple-daily-cardiovascular-age-documents — 沙盒 - 多个每日心血管年龄文档
  • oura-pp-cli sandbox multiple-daily-readiness-documents — 沙盒 - 多个每日准备度文档
  • oura-pp-cli sandbox multiple-daily-resilience-documents — 沙盒 - 多个每日韧性文档
  • oura-pp-cli sandbox multiple-daily-sleep-documents — 沙盒 - 多个每日睡眠文档
  • oura-pp-cli sandbox multiple-daily-spo2-documents — 沙盒 - 多个每日 Spo2 文档
  • oura-pp-cli sandbox multiple-daily-stress-documents — 沙盒 - 多个每日压力文档
  • oura-pp-cli sandbox multiple-enhanced-tag-documents — 沙盒 - 多个增强标签文档
  • oura-pp-cli sandbox multiple-heartrate-documents — 沙盒 - 多个心率文档
  • oura-pp-cli sandbox multiple-rest-mode-period-documents — 沙盒 - 多个休息模式时段文档
  • oura-pp-cli sandbox multiple-ring-battery-level-documents — 沙盒 - 多个戒指电量级别文档
  • oura-pp-cli sandbox multiple-ring-configuration-documents — 沙盒 - 多个戒指配置文档
  • oura-pp-cli sandbox multiple-session-documents — 沙盒 - 多个会话文档
  • oura-pp-cli sandbox multiple-sleep-documents — 沙盒 - 多个睡眠文档
  • oura-pp-cli sandbox multiple-sleep-time-documents — 沙盒 - 多个睡眠时间文档
  • oura-pp-cli sandbox multiple-tag-documents — 沙盒 - 多个标签文档
  • oura-pp-cli sandbox multiple-v-o2-max-documents — 沙盒 - 多个 Vo2 Max 文档
  • oura-pp-cli sandbox multiple-workout-documents — 沙盒 - 多个锻炼文档
  • oura-pp-cli sandbox single-daily-activity-document — 沙盒 - 单个每日活动文档
  • oura-pp-cli sandbox single-daily-cardiovascular-age-document — 沙盒 - 单个每日心血管年龄文档
  • oura-pp-cli sandbox single-daily-readiness-document — 沙盒 - 单个每日准备度文档
  • oura-pp-cli sandbox single-daily-resilience-document — 沙盒 - 单个每日韧性文档
  • oura-pp-cli sandbox single-daily-sleep-document — 沙盒 - 单个每日睡眠文档
  • oura-pp-cli sandbox single-daily-spo2-document — 沙盒 - 单个每日 Spo2 文档
  • oura-pp-cli sandbox single-daily-stress-document — 沙盒 - 单个每日压力文档
  • oura-pp-cli sandbox single-enhanced-tag-document — 沙盒 - 单个增强标签文档
  • oura-pp-cli sandbox single-rest-mode-period-document — 沙盒 - 单个休息模式时段文档
  • oura-pp-cli sandbox single-ring-configuration-document — 沙盒 - 单个戒指配置文档
  • oura-pp-cli sandbox single-session-document — 沙盒 - 单个会话文档
  • oura-pp-cli sandbox single-sleep-document — 沙盒 - 单个睡眠文档
  • oura-pp-cli sandbox single-sleep-time-document — 沙盒 - 单个睡眠时间文档
  • oura-pp-cli sandbox single-tag-document — 沙盒 - 单个标签文档
  • oura-pp-cli sandbox single-v-o2-max-document — 沙盒 - 单个 Vo2 Max 文档
  • oura-pp-cli sandbox single-workout-document — 沙盒 - 单个锻炼文档

usercollection — 管理 usercollection

  • oura-pp-cli usercollection multiple-daily-activity-documents — 多个每日活动文档
  • oura-pp-cli usercollection multiple-daily-cardiovascular-age-documents — 多个每日心血管年龄文档
  • oura-pp-cli usercollection multiple-daily-readiness-documents — 多个每日准备度文档
  • oura-pp-cli usercollection multiple-daily-resilience-documents — 多个每日韧性文档
  • oura-pp-cli usercollection multiple-daily-sleep-documents — 多个每日睡眠文档
  • oura-pp-cli usercollection multiple-daily-spo2-documents — 多个每日血氧饱和度文档
  • oura-pp-cli usercollection multiple-daily-stress-documents — 多个每日压力文档
  • oura-pp-cli usercollection multiple-enhanced-tag-documents — 多个增强标签文档
  • oura-pp-cli usercollection multiple-heartrate-documents — 多个心率文档
  • oura-pp-cli usercollection multiple-rest-mode-period-documents — 多个休息模式时段文档
  • oura-pp-cli usercollection multiple-ring-battery-level-documents — 多个戒指电量文档
  • oura-pp-cli usercollection multiple-ring-configuration-documents — 多个戒指配置文档
  • oura-pp-cli usercollection multiple-session-documents — 多个会话文档
  • oura-pp-cli usercollection multiple-sleep-documents — 多个睡眠文档
  • oura-pp-cli usercollection multiple-sleep-time-documents — 多个睡眠时间文档
  • oura-pp-cli usercollection multiple-tag-documents — 多个标签文档
  • oura-pp-cli usercollection multiple-v-o2-max-documents — 多个最大摄氧量文档
  • oura-pp-cli usercollection multiple-workout-documents — 多个锻炼文档
  • oura-pp-cli usercollection single-daily-activity-document — 单个每日活动文档
  • oura-pp-cli usercollection single-daily-cardiovascular-age-document — 单个每日心血管年龄文档
  • oura-pp-cli usercollection single-daily-readiness-document — 单个每日准备度文档
  • oura-pp-cli usercollection single-daily-resilience-document — 单个每日韧性文档
  • oura-pp-cli usercollection single-daily-sleep-document — 单个每日睡眠文档
  • oura-pp-cli usercollection single-daily-spo2-document — 单个每日血氧饱和度文档
  • oura-pp-cli usercollection single-daily-stress-document — 单个每日压力文档
  • oura-pp-cli usercollection single-enhanced-tag-document — 单个增强标签文档
  • oura-pp-cli usercollection single-personal-info-document — 单个人员信息文档
  • oura-pp-cli usercollection single-rest-mode-period-document — 单个休息模式时段文档
  • oura-pp-cli usercollection single-ring-configuration-document — 单个戒指配置文档
  • oura-pp-cli usercollection single-session-document — 单个会话文档
  • oura-pp-cli usercollection single-sleep-document — 单个睡眠文档
  • oura-pp-cli usercollection single-sleep-time-document — 单个睡眠时间文档
  • oura-pp-cli usercollection single-tag-document — 单个标签文档
  • oura-pp-cli usercollection single-v-o2-max-document — 单个最大摄氧量文档
  • oura-pp-cli usercollection single-workout-document — 单个锻炼文档

webhook — 管理 webhook

  • oura-pp-cli webhook create — 创建 webhook 订阅
  • oura-pp-cli webhook delete — 删除 webhook 订阅
  • oura-pp-cli webhook get-subscription — 获取 webhook 订阅
  • oura-pp-cli webhook list-subscriptions — 列出 webhook 订阅
  • oura-pp-cli webhook renew-subscription — 续订 webhook 订阅
  • oura-pp-cli webhook update — 更新 webhook 订阅
查找合适的命令

当你知道要做什么，却不知道该用哪个命令时，可以直接询问 CLI：

oura-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有可靠的匹配项——请改用 --help，或使用更具体的查询。

身份验证设置

运行 oura-pp-cli auth setup，查看获取令牌所需的网址和步骤（添加 --launch 可打开网址）。然后保存令牌：

oura-pp-cli auth set-token YOUR_TOKEN_HERE

或者，将 OURA_OAUTH2 设置为环境变量。

运行 oura-pp-cli doctor 验证设置。

Agent 模式

为任意命令添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

  • 可通过管道传输 — JSON 输出到 stdout，错误输出到 stderr

  • 可筛选 — --select 用于保留部分字段。带点号的路径可深入嵌套结构；数组会逐个遍历元素。在冗长 API 中，这对控制上下文大小至关重要：

    oura-pp-cli sandbox multiple-daily-activity-documents --agent --select id,name,status

  • 可预览 — --dry-run 显示请求，但不会发送

  • 支持离线使用 — 有本地 SQLite 存储时，同步和搜索命令可使用该存储

  • 非交互式 — 不会提示输入，所有输入都通过标志提供

  • 明确重试条件 — 仅当已存在的创建操作应视为成功时使用 --idempotent；仅当缺失的删除目标应视为成功时使用 --ignore-missing

响应封装

从本地存储或 API 读取的命令会将输出封装在来源信息中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 以判断数据来自实时来源还是本地来源。仅当 stdout 是终端且未设置任何机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将人类可读的 N results (live) 摘要输出到 stderr——通过管道接收数据的使用者、Agent 以及显式指定格式的运行都会在 stdout 上获得纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

oura-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
oura-pp-cli feedback --stdin < notes.txt
oura-pp-cli feedback list --json --limit 10

条目会本地保存到 ~/.local/share/oura-pp-cli/feedback.jsonl。除非设置了 OURA_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 OURA_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认情况下仅保存在本地。

写下让你意外的地方，而不是提交错误报告。简短、具体，写成一行：真正能逐渐积累价值的就是这一点。

输出传送

每条命令都接受 --deliver <sink>。输出除了写入 stdout（或取代 stdout）外，还会发送到指定的接收端，让 Agent 无需手动通过管道即可路由命令结果。支持三种接收端：

接收端效果
stdout默认；仅写入 stdout
file:<path>将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>将输出正文 POST 到该 URL（使用 --compact 时，内容类型为 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回包含受支持方案列表的结构化错误。Webhook 请求失败时会返回非零状态码，并将 URL 和 HTTP 状态码记录到 stderr。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。如果定时运行的 Agent 每次都以相同配置调用同一命令，可使用配置——这就是 HeyGen 的“Beacon”模式。

oura-pp-cli profile save briefing --json
oura-pp-cli --profile briefing sandbox multiple-daily-activity-documents
oura-pp-cli profile list --json
oura-pp-cli profile show briefing
oura-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，方便进行自省的 Agent 在运行时发现这些配置。

退出代码

代码含义
0成功
2用法错误（参数错误）
3未找到资源
4需要身份验证
5API 错误（上游问题）
7触发速率限制（等待后重试）
10配置错误

参数解析

解析 $ARGUMENTS：

  1. 为空、help 或 --help → 显示 oura-pp-cli --help 输出
  2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
  3. 其他任何内容 → 直接使用（将其作为带 --agent 的 CLI 命令执行）

MCP 服务安装

  1. 安装 MCP 服务： 
    go install github.com/mvanhorn/printing-press-library/library/health/oura/cmd/oura-pp-mcp@latest
  2. 在 Claude Code 中注册： 
    claude mcp add oura-pp-mcp -- oura-pp-mcp
  3. 验证：claude mcp list

直接使用

  1. 检查是否已安装：which oura-pp-cli 如果未找到，请提供安装选项（参见本技能顶部的先决条件）。
  2. 根据用户查询，从上方的独特功能和命令参考中选择最合适的命令。
  3. 使用 --agent 标志执行： 
    oura-pp-cli <command> [subcommand] [args] --agent
  4. 如果有歧义，请深入查看子命令帮助：oura-pp-cli <command> --help。

评论

支持 Markdown