高驰（COROS）运动健康深度分析

📖 先遇到问题？ 直接看 ❓ 常见问题解答 FAQ（Q1–Q8 覆盖登录失效 / 数据缺失 / 移动端限制 / 预测准不准 / 数据安全）；独立版见 FAQ.md，完整文档导航见 README.md。

触发条件

当用户想查看 COROS 运动手表数据并获得分析建议时触发：

"看一下我的高驰数据" / "查高驰数据" / "高驰运动数据"
"看看我的COROS数据" / "COROS数据"
"查一下运动数据" / "看看数据" / "健康数据"
"半马预测" / "全马预测" / "备赛分析" / "马拉松配速" → 使用 --race 进阶模式

触发优先级（多个说法同时命中时）：以最具体的意图为准。例如"看看数据并预测半马"会按 --race 处理（进阶模式自动包含基础数据，不会重复拉取）；"周报"+"PB"会同时叠加 --weekly --pb。基础查询与进阶参数可自由叠加，不存在冲突覆盖。

复杂组合场景示例（口语化触发词 → 实际参数，照着说即可）： | 用户说法 | 实际参数 | |---|---| | "预测我半马能跑多少，配速怎么安排" | --race | | "全马怎么分段配速，补给怎么吃" | --race | | "备赛期我的周训练量够不够" | --race --weekly | | "我这半年各距离 PB 是多少" | --pb | | "看最近一个月训练趋势和负荷" | --weekly（或 --monthly） | | "出一份能发手机看的图表报告" | --html |

技术边界与限额（并发 / 数据量 / 频次）

并发：单次报告通过线程池并行发起约 14 个 MCP 工具调用，由 COROS 官方网关统一限流调度，无需（也不建议）手动控制并发数。
数据量：--days 建议 ≤90 天；单份报告约 15 次接口调用。趋势库为本地 SQLite，仅存每日聚合指标（睡眠分 / HRV / 静息心率 / 步数 / 压力等），不保存原始明细，不上传任何隐私数据。
频次 / 缓存：本地缓存 TTL 5 分钟，重复追问命中缓存不触发新请求（数秒返回）；仅 --fresh 强制绕过缓存重新实时拉取。
超时与重试：单次工具调用超时即自动重试（退避 2s/4s，封顶 6s）；仍失败则该维度标记为 ⚠️ 并跳过，不影响其余维度与整份报告生成。

进阶功能速查（一眼看全能深挖什么）

基础报告已覆盖日常查询；想进一步分析，按需求加对应参数即可，无需通读全文：

| 想做 | 加参数 | 产出 | |---|---|---| | 预测半马/全马成绩 + 配速区间/分段/补给 | --race | Riegel 成绩预测、Daniels 五区间配速、负分割策略、补给方案 | | 看各距离历史最快（5K/10K/半马/全马） | --pb | PB 追踪与配速对比 | | 周/月训练量趋势 + 负荷过量预警 | --weekly / --monthly | 周期聚合与骤增预警 | | 生成可分享图表报告 | --html | 单文件自包含 HTML（图表 base64 内嵌） | | 强制刷新（绕过缓存） | --fresh | 重新从官方接口拉取 |

基础报告末尾会根据你的数据自动提示下一步该加哪个参数，跟着提示走即可。

前置依赖与快速开始

本 skill 依赖官方登录 skill @coros/coros（负责 OAuth 登录与 token 管理）。

首次使用只需一行引导脚本（自动安装 @coros/coros + 完成登录 + 自检）：

bash <本skill目录>/setup.sh

脚本自动探测/安装官方依赖并打印授权链接，在浏览器点击授权后即完成，全程约 30 秒，无需手动分步操作。

想手动操作：

安装依赖：skillhub install coros --namespace coros --dir <你的skills目录>
登录（设备码流程，单条命令）：
```
python3 <skills目录>/@coros/coros/scripts/coros_mcp_login.py login
```
- 自动打印授权链接并轮询等待；浏览器完成授权后输出 login ok
- 已不再需要 login-start / login-finish 分步操作

依赖与环境（使用前必读）：

图表报告（--html）依赖 matplotlib：环境缺失时脚本会明确提示并跳过图表，其余分析不受影响；先 pip3 install matplotlib 即可启用。

--days N 默认 7 天，常用 7–90 天（趋势库按天积累，≥4 天自动出趋势图）；无硬性上限，但建议 ≤90 天以保证接口响应。

必须在已登录 @coros/coros 且有 shell 环境（桌面端 / 云端 Agent）下运行；移动端无 shell，只能查看已生成的 HTML 报告。

⚠️ 不要这样做（常见反模式）

为避免误用导致数据缺失或受伤，请注意以下错误用法：

| 反模式 | 为什么不行 | 正确做法 | |---|---|---| | token 失效后反复直接跑分析脚本 | 旧 token 会让各维度静默拉取失败，报告出现大片空值（脚本会明确标出失败维度，但仍应先修好登录） | 先 python3 <官方skill>/coros_mcp_login.py login 重新授权，或加 --fresh 重试 | | 未登录 @coros/coros 就运行脚本 | 官方 skill 无 token，全部维度报错 | 先 bash setup.sh 完成一键登录 | | 用移动端 App 直接跑脚本 | 移动端无 shell 环境，无法执行 Python | 让桌面 / 云端 Agent 运行，再把 HTML 报告分享到手机查看 | | 训练中断 >30 天还照搬旧配速计划 | 体能已下降，硬上强度易受伤 | 按报告给的「分阶段恢复计划」循序渐进 | | 停训后直接套用 Riegel 全马预测 | 停训期预测偏乐观，不反映真实状态 | 恢复规律训练 2–4 周后再预测 | | 忽略报告里的 ⚠️ 提醒 | 这些是基于真实数据的异常信号 | 优先处理高优先级（🔴）提醒 | | 看到「数据维度获取失败」就以为 skill 坏了 | 多为网络波动 / token 临时失效，其余分析正常 | 重试一次或加 --fresh；持续失败再查登录态 |

故障排查

| 现象 | 处理 | |---|---| | 未找到 @coros/coros 官方 skill | 先安装官方 skill（见前置依赖） | | no local token cache found | 引导用户重新登录：python3 <官方skill>/coros_mcp_login.py login，浏览器点一次授权即完成 | | 某维度数据为空 | 正常现象（如近30天无运动记录），报告会标注"无数据" | | token 过期 | 脚本自动刷新；若失效则重新登录 |

常见问题解答 FAQ（集中问答区）

遇到问题先来这里查；下文「使用边界速览」一眼看清限制，详细 Q&A 在后面。

📌 使用边界速览（一眼看清，避免踩坑）

移动端不能直接跑脚本：skill 依赖 shell 环境（桌面端 / 云端 Agent）执行 Python；手机可看 Agent 生成后分享的 HTML 报告。
趋势图 / 趋势对比需 ≥4 天数据：趋势库按天本地积累，跑够天数才自动出图。
PB（--pb）/ 周期训练（--weekly/--monthly）需有运动记录：无近 90 天记录则无数据，非故障。
数据缓存 5 分钟：5 分钟内重复问数秒回；要强制刷新加 --fresh。
「无数据」≠ 故障：常为当日无对应记录（休息日无运动、当晚睡眠未同步等）。

Q&A

Q1：报告里某维度显示「无数据」/「数据维度获取失败」，是 skill 坏了吗？ A：多为正常现象或瞬时问题。「无数据」常为当日无对应记录（休息日无运动、当晚睡眠未同步）；「获取失败」多为网络波动或 token 临时失效，脚本已自动重试最多 3 次并明确标出失败维度，其余分析不受影响。重试一次或加 --fresh；持续失败再查登录态。

Q2：为什么图表 / 趋势对比要等几天才出现？ A：趋势库按天本地积累，需 ≥4 天数据才会自动追加「📈 趋势对比」小节；HRV / 静息心率趋势图同理。PB（--pb）需近 90 天有运动记录、周期训练分析（--weekly/--monthly）需 ≥2 个周期才有意义。这些是数据积累型功能，并非故障。

Q3：移动端（手机 App）能直接查数据吗？ A：不能直接运行脚本——skill 依赖 shell 环境（桌面端 / 云端 Agent）执行 Python。但移动端可查看 Agent 生成后分享的 HTML 报告（单文件自带图表，手机浏览器直接渲染）。用法：让桌面 / 云端会话跑 --html，再把 reports/*.html 分享 / 预览打开即可。

Q4：登录失效了怎么办？ A：看到「登录失效」提示时，重新授权一次即可，无需重装： python3 <官方skill>/coros_mcp_login.py login 浏览器点一次授权即完成，token 自动刷新。

Q5：数据多久更新一次？会不会重复拉取很慢？ A：本地缓存 TTL 5 分钟，同会话或 5 分钟内重复问数秒回（约 0.1s）。需要强制刷新用 --fresh；TTL 到期或参数变化会自动重新拉取。

Q6：半马 / 全马预测准吗？ A：基于 Riegel 公式（指数 1.06，全马上限 1.08）+ COROS 乳酸阈配速推算，属科学估算。停训 / 数据不足时偏乐观，恢复规律训练 4–6 周后更可信；预测附带保守~乐观区间与分段策略，供备赛参考而非绝对成绩。

Q7：报告里的 ⚠️ 提醒要管吗？ A：要。这些是真实数据触发的异常信号，按优先级处理：🔴 高 > 🟡 中 > 🟢 低。忽略高优先级提醒可能延误恢复或增加受伤风险。

Q8：我的数据安全吗？ A：只读访问 COROS 官方 MCP 网关，OAuth 授权；token 由官方 skill 加密缓存，本脚本不经手、不打印；不修改任何账号数据。

数据安全

通过 COROS 官方 MCP 网关（mcp.coros.com）访问，OAuth 授权
token 由官方 skill 加密缓存，本脚本不经手、不打印 token
所有查询均为只读操作，不修改任何 COROS 账号数据

执行流程

运行本 skill 自带的分析脚本（脚本会自动探测 @coros/coros 安装位置）：

python3 <本skill目录>/scripts/coros_analysis.py

脚本自动拉取 15 个维度数据并生成结构化报告：

| 类别 | 维度 | |---|---| | 画像 | 用户信息（身高/体重/BMI）、绑定设备 | | 健康 | 日常健康汇总、睡眠详情、静息心率、平均心率、睡眠 HRV、压力水平、健康检查时间序列 | | 训练 | 训练负荷、恢复状态、体能评估（VO2max/阈值配速）、运动记录（近30天）、训练日历 |

报告包含：

各维度数据表格（含参考值与评价）
异常提醒列表（⚠️ 标注）
趋势对比小节（近7天 vs 前7天均值，📈改善/📉需关注）
专业运动建议引擎输出：
- 训练连续性评估 → 分阶段恢复计划（3 周递进）
- 睡眠质量评估 → 行动项清单
- HRV/基线比值 → 自主神经恢复建议
- 静息心率/压力/步数 → 对应干预建议
- 阈值配速 → 训练配速区间表（Z1-Z4）

将脚本输出的完整报告直接呈现给用户，无需额外加工。

可选参数

| 用户表达 | 命令 | |---|---| | "全量数据" / "详细分析" | python3 scripts/coros_analysis.py --full（含近90天运动记录+压力时间序列） | | "半马预测" / "全马预测" / "备赛分析" | python3 scripts/coros_analysis.py --race（进阶分析模式） | | "生成图表" / "图表报告" / "可视化报告" | python3 scripts/coros_analysis.py --html（图表 HTML 报告，可组合 --race 出 5 张图） | | "最近 N 天" | python3 scripts/coros_analysis.py --days N（默认 7，常用 7–90） | | 程序化调用 | python3 scripts/coros_analysis.py --json（结构化 JSON 输出） | | 强制刷新 | python3 scripts/coros_analysis.py --fresh（跳过本地缓存重新拉取） | | "我的 PB" / "历史最佳" / "最快配速" | python3 scripts/coros_analysis.py --pb（近 90 天各距离最快配速/最短用时，标准桶 5K/10K/半马/全马） | | "周报" / "月报" / "周期总结" | python3 scripts/coros_analysis.py --weekly（或 --monthly，周期训练量聚合 + 负荷过量预警） |

性能优化（v1.3.5 新增）

为降低"看数据"的等待时间，脚本做了两层加速：

并行拉取：fetch_all 用线程池并发调用官方 14 个工具（运动峰值额外并发），原本串行约 14s 降至约 3.5s。
本地缓存：按 (天数, 是否全量) 缓存原始数据到 ~/.cache/coros_analysis/，默认 TTL 5 分钟。同会话或 5 分钟内重复问数秒回（约 0.1s），无需重新打官方 API。
数据需强制更新时用 --fresh；TTL 到期或参数（天数/全量）变化会自动重新拉取。

图表报告模式（v1.3.0 新增，--html 触发）

生成自包含单文件 HTML 报告（图表 base64 内嵌，无外部依赖，可直接分享/浏览器打开）：

输出位置：<本skill目录>/reports/coros_report_YYYYMMDD_HHMM.html
图表清单（matplotlib 绘制）：
1. HRV 趋势折线（含基线参考线）
2. 睡眠结构堆叠柱状图（深睡/浅睡/REM/清醒）
3. 静息心率与压力双轴折线
4. 步数柱状图（8000 步目标线，红黄绿着色）
5. Daniels 训练配速区间条形图（需叠加 --race）
参数可组合：--html --race --days 14、--html --full 等

跨端使用说明：

| 环境 | 支持情况 | |---|---| | 桌面端 / 云端 Agent（有 shell） | ✅ 完整支持：查询、分析、图表、趋势库全部功能 | | 移动端 App（无 shell） | ⚠️ 不能直接运行脚本；但可查看 Agent 生成后分享的 HTML 报告（单文件自带图表，手机浏览器直接渲染） |

提示：移动端用户让 Agent（桌面/云端会话）运行 --html 后，通过文件分享/预览打开报告即可。

进阶分析模式（v1.2.0 新增，--race 触发）

面向半马/全马备赛与高阶跑者，基于 COROS 乳酸阈配速自动推算：

比赛成绩预测（Riegel 公式）：5K/10K/半马/全马，全马给保守~乐观区间
Daniels 五区间训练配速：E 轻松跑 / M 马拉松 / T 乳酸阈 / I 间歇 / R 重复跑
推导逻辑（与脚本算法一致）：以 COROS 乳酸阈配速 tp（如 4:45/km，来自体能评估）为唯一锚点，各区间 = tp ± 秒数偏移，无需任何比赛记录即可推算：
- E 轻松跑 = tp + 75~105s/km（有氧基础，占周跑量 70-80%）
- M 马拉松 = tp + 12~22s/km（比赛专项 / 长距离）
- T 乳酸阈 = tp ± 3s/km（节奏跑，20-40min 持续）
- I 间歇 = tp - 18~8s/km（VO2max，3-5min 重复）
- R 重复跑 = tp - 38~28s/km（速度 / 经济性，200-400m）阈值配速越快的跑者，五个区间的绝对配速同步前移；区间宽度固定为相对偏移，确保强度分层稳定。
分段配速策略：半马 4 段 / 全马 4 段负分割策略（逐段配速 + 执行要点）
补给策略：半马/全马赛前饮食、能量胶节点、补水/电解质节奏
备赛就绪度：周跑量对照备赛标准（半马峰值 35-40km/周，全马 55-65km/周 + LSD 里程碑）
高阶要点：80/20 极化训练、ACWR 负荷比安全区间、赛前 Taper 原则

输出示例（节选）

## 🎯 专业运动建议
### 🔴 建议 1：训练中断超过30天
- 分阶段恢复计划：
  - 第1周：快走 30min × 3次，心率 <130 bpm
  - 第2周：慢跑 20min + 快走 10min × 3次
  - 第3周：连续慢跑 30min × 3次

### ℹ️ 建议 5：阈值配速 4:45/km
- 训练配速区间：
  | 恢复跑 Z1 | 4:45 +90~120s/km |
  | 有氧跑 Z2 | 4:45 +45~75s/km |
  | 节奏跑 Z3 | 4:45 +15~30s/km |
  | 阈值跑 Z4 | 4:45 ~ +10s/km |

本地趋势库（v1.1.0 新增）

每次运行自动将当日及近期指标 upsert 到本地 SQLite（scripts/data/trend.db）：

采集字段：睡眠评分、深/浅/REM 占比、清醒占比、静息心率、HRV、压力、步数、热量、阈值配速
积累 ≥4 天后，报告自动追加「📈 趋势对比」小节（近7天 vs 前7天均值 + 方向箭头）
数据随 skill 目录存储，不联网上传；删除 data/trend.db 即清空历史