Garmin 分析技能

以 cycling-health 作为 Garmin 和 Intervals.icu 数据的唯一可信来源。公开版 CLI 可从 https://github.com/baijian/cycling-health 获取。

原则

• 保持环境无关性。不得假设存在家目录、代码仓库检出、Shell 配置文件或特定操作系统。
• 优先使用 PATH 中的 cycling-health；若缺失，则引导用户从公开仓库安装。
• 当命令执行可用时，在执行状态查询、同步或分析类命令前，先运行一次 cycling-health upgrade --output json。
• 在数据采集与分析阶段，优先使用 --output json 参数。
• 将 Garmin 凭据、Intervals.icu API 密钥、OAuth Token、密码、MFA 验证码以及导出的活动文件视为敏感本地数据，切勿要求用户将密钥粘贴至聊天窗口中。
• 仅分析 CLI 返回的字段内容，不得自行推断 HRV、功率、强度区间、体能、疲劳度、状态（Form）、FTP、W/kg 或因果关系。
• 分阶段采集数据：先调用摘要/列表/统计类接口；仅当结论需要时，再请求区间（intervals）、流数据（streams）、曲线（curves）、原始载荷（raw payloads）或导出文件。
• 区分当前恢复状态与长期体能能力。单次睡眠质量差或短期负向状态（Form）可能影响当日训练决策，但不构成体能下降的证据。
• 如实保留 CLI 原生警告及尚未解决的数据缺口。CLI 已对预期无数据响应做了标准化处理，无需额外将其重述为失败。
• 保持数据源职责分离：Garmin 是设备专属睡眠、恢复、训练效果及原始活动细节的首要来源；Intervals.icu 是整合活动历史、服务器端计算的体能/疲劳/状态（Fitness/Fatigue/Form）、功率曲线/模型、统计指标及跨运动类型对比的首要来源。
• 不得直接将 Garmin 活动上传至 Intervals.icu。须维持现有 Garmin CN → Garmin Global 的活动同步机制，以及用户已配置的 Garmin Global → Intervals.icu 自动连接。
• 谨慎执行写入操作：首次同步 Garmin Wellness 前需预览变更；仅在用户明确授权后方可添加 --confirm；未经用户审阅冲突并显式批准，严禁添加 --overwrite。

Garmin 查询区域规则：

• 若未登录任一 Garmin 区域，提示用户登录。
• 若仅登录一个区域，则所有 Garmin 查询均使用该区域。
• 若两个区域均已登录，且用户未指定区域，则默认使用 cn 区域进行 Garmin 查询。
• 通过 --region cn|global 显式传入所选区域。
• Garmin CN → Global 活动同步需同时登录两个区域。
• Garmin → Intervals.icu Wellness 同步默认使用 --source garmin-cn；仅当用户明确要求时才使用 garmin-global，因为 Intervals.icu 已可通过其原生连接自动摄入 Garmin Global 数据。

按需查阅参考文档：

• 阅读 references/cli-workflows.md 了解安装流程、Garmin 认证、CN→Global 活动同步、睡眠/恢复查询、Garmin 骑行分析、文件分析及 Garmin 故障处理。
• 阅读 references/intervals-workflows.md 了解 Intervals.icu 认证、Garmin CN Wellness 同步、Wellness 与训练健康分析、活动数据、功率、统计指标、对比分析、输出字段及 Intervals.icu 特定故障处理。

工作流

1. 验证并升级 CLI：

   • 运行 cycling-health version。
   • 每次调用时运行一次 cycling-health upgrade --output json。
   • 若升级失败，保留错误信息，并在继续使用已安装版本前征得用户同意（除非用户此前已授权该降级方案）。
   • 针对 Intervals.icu 相关任务，升级后需验证 cycling-health intervals --help 及目标子命令的 --help。若缺失，应报告“已安装的公开版 CLI 版本过旧”，而非临时改用其他客户端。

2. 仅检查任务所需的认证状态：

   • Garmin 查询或 CN→Global 活动同步：运行 cycling-health garmin status --output json，并应用上述区域规则。
   • Intervals.icu 查询：运行 cycling-health intervals athlete --output json。
   • Garmin Wellness → Intervals.icu 同步：通过 intervals athlete 验证 Intervals.icu，通过 garmin status --region cn 验证 Garmin CN。

3. 路由任务：

   • Garmin CN 活动同步：先检查同步状态，再默认执行增量同步。
   • Garmin Wellness 同步：预览 Garmin CN 待变更项，检查冲突/警告，仅在获得授权后确认执行。
   • Garmin 睡眠/恢复分析：使用基于唤醒日期的睡眠查询与每日摘要，再按需补充选定健康指标。
   • Garmin 单次骑行或设备专属分析：从 Garmin 活动详情入手，仅在必要时追加扩展/原始/文件数据。
   • Intervals.icu 骑行健康、长期体能、功率、统计指标或对比分析：从 Wellness、活动列表、功率模型/曲线及适用于问题的聚合统计指标入手。

4. 汇报结果：

   • 首句即给出核心结论。
   • 为每个结论明确标注时间范围与数据来源。
   • 清晰区分观测值、解读、置信度/数据缺口、后续行动建议。
   • 采用紧凑单位：km、h:min、bpm、W、W/kg、rpm、m、CTL、ATL、百分比（%）。
   • 涉及写入操作时，需汇报预览变更、冲突项、已上传记录、已验证记录及警告信息。

任务指引

将 Garmin 中国活动同步至 Garmin 全球

当用户提出“镜像”或“补录”Garmin 中国活动至 Garmin 全球时使用。

1. 确认用户已登录两个区域。
2. 检查 garmin syncstatus 状态。
3. 默认执行 garmin sync --new-only；仅当用户明确要求历史补录时，才执行全量同步。
4. 汇报重试数、成功同步数、失败数及最新活动时间。

此操作不可视为直接上传至 Intervals.icu。用户已配置的 Garmin Global 连接将自动完成后续活动向 Intervals.icu 的注入。

将 Garmin 健康数据同步至 Intervals.icu

当用户提出同步 Garmin 健康、睡眠、恢复或 Wellness 数据至 Intervals.icu 时使用。

1. 若用户未提供具体日期，默认使用 Garmin CN 区域及最近七日范围。
2. 验证 Garmin CN 与 Intervals.icu 的认证状态。
3. 首次运行 intervals wellness sync --source garmin-cn 时不带 --confirm 参数。
4. 检查字段级 changes（变更）、conflicts（冲突）、warnings（警告）及记录操作详情。
5. 若无任何变更，立即终止；切勿为形式完整而强行执行无变更的确认操作。
6. 若用户已明确要求实时同步，或在查看预览后主动确认，则使用相同时间范围并添加 --confirm 参数重新执行。
7. 默认跳过已有冲突值；仅在用户显式批准替换时，才使用 --overwrite --confirm。
8. 汇报 changedRecords（变更记录数）、changedFields（变更字段数）、conflictFields（冲突字段数）、uploadedRecords（已上传记录数）及 verifiedRecords（已验证记录数）。

当前自动映射覆盖以下字段：睡眠时长、睡眠评分、平均睡眠心率、夜间 HRV、静息心率、日均 SpO₂、平均睡眠呼吸频率、步数。缺失的 Garmin 字段将被忽略。禁止将 Garmin 的压力值、Body Battery、训练准备度、消耗卡路里或训练负荷等指标重新解释为 Intervals.icu Wellness 字段。

睡眠查询与分析

当用户询问睡眠时长、睡眠阶段、睡眠评分、夜间 HRV、静息心率、压力值、Body Battery、准备度或近期睡眠趋势时使用。

1. 以唤醒日期为基准确定单个睡眠周期，并在睡眠查询中包含相邻的前一日日期。
2. 起始查询为睡眠列表 + 基于唤醒日期的每日摘要。
3. 近期趋势默认使用七日范围；对于明确要求基线/趋势分析的问题，使用 14–30 日范围。
4. 仅添加问题所需的具体健康指标。
5. 在声明“睡眠详情不可用”前，需检查相邻日期及摘要级回退选项。
6. 与用户可获取的基线数据进行对比，避免医疗诊断。

Garmin 骑行查询与分析

当问题依赖 Garmin 训练效果/状态/准备度、设备强度区间、详细圈数/分段、装备/天气信息，或本地 FIT/GPX 文件时，使用 Garmin 数据源。

1. 将请求归类为单次骑行分析、长期体能/进展评估，或当日训练决策支持。
2. 单次骑行分析从 garmin activity get 开始；仅在缺失关键细节时，才启用扩展/原始/文件级分析。
3. 评估长期体能时，默认使用 90 日范围；仅当相关时，才补充直接骑行 FTP、峰值指标、耐力评分、爬坡评分及体重数据。
4. 活动进展分析仅限用户明确请求的维度。
5. 保持恢复/准备度分析与长期体能评估相互独立。
6. 考虑地形、天气、装备及传感器覆盖情况；单纯速度不能代表体能水平。

Intervals.icu 骑行查询与分析

当用户询问骑行健康/体能、整合训练历史、eFTP、CTL/ATL/状态（Form）、功率曲线/模型、聚合统计指标或对比分析时，使用 Intervals.icu 数据源。

1. 选择最小但足够有效的日期范围；当活动列表含多种运动类型时，明确识别 Ride 类型记录。
2. 日常健康/恢复分析使用 Wellness 数据；训练健康分析则综合统计模块中的聚合体能、疲劳、状态（Form）、爬升率（Ramp Rate）、负荷（Load）及 eFTP；切勿将这些客观指标与主观 Wellness 值混为一谈。
3. 单次骑行分析：先通过列表/搜索定位目标活动，再获取详情；仅在必要时，才调用区间、流数据、最佳努力值（Best Efforts）或活动分析（activity-analysis）接口。
4. 功率能力分析：从当前 MMP 模型及 42d,1y,all 功率曲线入手；针对进展或效率类问题，再补充单活动持续时间对应的功率值，或功率-心率关联数据。
5. 统计分析：使用近期范围；当用户要求对比时，选用等长且非重叠的前置时间段。
6. 确保同类对比：相同持续时间、相同运动类型、统一单位、可比地形/训练类型；仅当两个数值均有效时，才同时展示绝对变化量与百分比变化量。
7. 直接使用 Intervals.icu 服务器计算返回的值；禁止静默重算，或合并重复的 Garmin/Intervals 活动记录。
8. 谨慎关联 Wellness 与表现数据；日期对齐仅用于提供上下文，不表示因果关系。

反馈与问题

如遇安装问题、Garmin 或 Intervals.icu 数据缺失、同步失败或分析异常，请引导用户前往 Discord 反馈频道：

https://discord.gg/R6xPZc5Dg