名称： oura-ring-data
描述： 使用 ouracli CLI 工具访问 Oura Ring 健康数据。当用户询问 "oura 数据"、"睡眠统计"、"活动数据"、"心率"、"准备度分数"、"压力水平" 或希望获取其 Oura Ring 的健康指标时使用。
允许工具： Bash

Oura Ring 数据访问

使用 ouracli 命令行接口从 Oura Ring 获取健康和健身数据。

关键：需要身份验证

运行 ouracli 命令前，务必检查身份验证。 该工具需要 PERSONAL_ACCESS_TOKEN 环境变量。

• 令牌位置：secrets/oura.env 或 ~/.secrets/oura.env
• 如果命令因身份验证错误失败，请告知用户从以下网址获取令牌：https://cloud.ouraring.com/personal-access-tokens

可用数据类型

核心健康指标

• activity - 日常活动（步数、MET 值、卡路里）
• sleep - 睡眠数据（阶段、效率、心率）
• readiness - 准备度分数及影响因素
• heartrate - 时间序列心率数据（5 分钟分辨率）
• spo2 - 血氧饱和度数据
• stress - 日常压力水平

附加数据

• workout - 锻炼记录
• session - 活动记录
• tag - 用户添加的标签
• rest-mode - 休息模式时段
• personal-info - 用户个人信息
• all - 所有可用数据类型

日期范围指定

✅ 支持的格式（使用这些！）

# 单个日期（无需引号）
ouracli activity 2025-12-25
ouracli sleep today
ouracli heartrate yesterday

# 从今天开始的相对范围（必须使用引号）
ouracli activity "7 days"      # 过去 7 天（含今天）
ouracli sleep "30 days"        # 过去 30 天
ouracli readiness "2 weeks"    # 过去 2 周
ouracli stress "1 month"       # 过去 1 个月

# 起始日期 + 时长（必须使用引号）
ouracli activity "2025-12-01 28 days"    # 从 12 月 1 日起的 28 天
ouracli sleep "2025-09-23 7 days"        # 从 9 月 23 日起的一周

⚠️ 关键：当日期范围包含空格时，必须使用引号！

❌ 不支持的格式（请勿使用）

# ❌ 错误 - 两个独立日期
ouracli activity 2025-09-23 2025-09-30

# ❌ 错误 - "to" 语法
ouracli activity "2025-09-23 to 2025-09-30"

# ❌ 错误 - 范围操作符
ouracli activity "2025-09-23..2025-09-30"

# ❌ 错误 - 相对过去表达式
ouracli activity "3 months ago"

转换日期范围

如果用户请求两个特定日期之间的数据：

步骤 1：计算天数（包含起止日期）

示例：9 月 23 日至 9 月 30 日 = 7 天
      12 月 1 日至 12 月 31 日 = 30 天

步骤 2：使用 "起始日期 + 时长" 格式

# ✅ 正确
ouracli activity "2025-09-23 7 days"
ouracli activity "2025-12-01 30 days"

输出格式

为进行程序化数据分析，请始终使用 --json。 这是最可靠的解析格式。

# ✅ 推荐用于 AI 分析
ouracli activity "7 days" --json

# 其他格式（人类可读）
ouracli activity today --tree        # 默认：树状结构
ouracli activity "7 days" --markdown # Markdown 格式（带图表）
ouracli activity "7 days" --html > activity.html  # 交互式 HTML 图表
ouracli activity "7 days" --dataframe  # Pandas DataFrame 格式

常用使用模式

快速数据检查

# 今日活动
ouracli activity today --json

# 近期睡眠数据
ouracli sleep "7 days" --json

# 当前准备度
ouracli readiness today --json

详细分析

# 每周健康摘要
ouracli all "7 days" --json

# 月度活动报告
ouracli activity "30 days" --json

# 特定日期的心率
ouracli heartrate "2025-12-15 1 days" --json

多日报告

# 按天分组的所有数据（HTML 报告）
ouracli all "7 days" --by-day --html > weekly-report.html

# 按类型分组的所有数据
ouracli all "7 days" --by-method --json

重要说明

准备度影响因素警告

⚠️ 重要：准备度数据中的 contributors.resting_heart_rate 字段是一个分数（0-100），而非实际的心率值（BPM）：
- 低分（19, 47）= 静息心率相对于基线升高（负面影响）
- 高分（95, 100）= 静息心率相对于基线处于最佳状态（正面影响）
- 实际的心率值（BPM）在 heartrate 命令的输出中

请勿将影响因素分数解释为实际的心率测量值。

Oura API 特性

• 单日查询有时会因时区问题返回空结果
• 使用日期范围（例如 "YYYY-MM-DD 2 days"）以获得更可靠的结果
• 查询特定日期时，可考虑增加一天缓冲

数据可用性

• 必须最近同步过戒指才能获取当前数据
• 历史数据的可用性取决于用户的 Oura 订阅
• 如果未返回数据，建议尝试更宽的日期范围或检查同步状态

故障排除

错误："Got unexpected extra argument"

原因：使用了两个独立的日期参数，而非一个带引号的范围

# ❌ 错误
ouracli activity 2025-09-23 2025-09-30

# ✅ 正确
ouracli activity "2025-09-23 7 days"

错误："Invalid date specification"

原因：使用了不支持的语法，如 "to"、".." 或相对表达式

# ❌ 错误
ouracli activity "2025-09-23 to 2025-09-30"

# ✅ 正确
ouracli activity "2025-09-23 7 days"

未返回数据

解决方案：
1. 尝试更宽的日期范围：ouracli activity "7 days" --json
2. 增加缓冲天数：ouracli activity "2025-12-25 2 days" --json
3. 检查戒指是否最近已同步
4. 验证日期是否在可用数据范围内

用户查询示例响应

"显示我过去一周的活动"

ouracli activity "7 days" --json

"我昨晚的睡眠怎么样？"

ouracli sleep today --json

"我十二月份的准备度如何？"

ouracli readiness "2025-12-01 30 days" --json

"获取我从 9 月 23 日到 9 月 30 日的所有数据"

# 计算：9 月 30 日 - 9 月 23 日 = 7 天
ouracli all "2025-09-23 7 days" --json

"显示我昨天的心率"

ouracli heartrate yesterday --json

快速参考

注意事项

• 为进行 AI 分析，始终首选 --json 格式
• 对所有包含空格的日期范围使用引号
• 为特定日期范围计算天数
• 如果命令失败，请检查身份验证
• 查询特定日期时，请考虑时区特性