fit-ride-studio

FIT 和 KML 活动工作室

将本地骑行、跑步和徒步路线转换为基于证据的报告和本地可视化体验。按以下顺序操作：

1. 如果用户未提供文件，请索取 FIT/KML 文件；如果用户要求使用演示数据，则使用随附的合成演示数据。
2. 检查安装情况，自动安装缺失的锁定依赖项，并分析每个有效文件。
3. 展示结果，暂存私有运行时文件；如果可以访问本地浏览器，则打开随附的 Ride Relief 报告页面。

只有当用户要求生成可分享的图片、动画或视频时，才进入导出编辑器。Ride Relief 是此 Skill 内置的 Web 应用，不是需要单独安装的产品。

工作流

1. 获取路线文件

• 用户明确要求演示时，使用 <skill-root>/samples/demo.kml。说明数据为虚构数据。
• 否则，如果未提供可读取的 .fit 或 .kml 文件，请使用用户的语言索取附件或本地路径。中文示例：“请把 .fit 或 .kml 拖进对话，或告诉我文件路径（例如 ~/Downloads/ride.fit）；可以一次给多个。”
• 请求缺失的输入后立即停止。不要编造活动数据，也不要让用户配置项目。
• 只要至少有一个文件可访问，就立即继续。根据有效文件判断使用单文件模式还是汇总模式。
• 仅当用户将某个目录纳入处理范围时才接受该目录；只展开顶层的 FIT/KML 文件。
• 在本地处理路线。不要上传精确 GPS 路线，也不要在回复中暴露坐标。
• 如果某个文件损坏，只要还有其他有效路线，就继续处理该批次。报告被跳过文件的基本名称。
• 根据开始时间、距离和时长检测可能的重复项。从总计中排除重复项，并指出这些文件。

2. 检查就绪状态并分析

将 <skill-root> 解析为包含此 SKILL.md 的目录。从该目录运行：

node scripts/check-install.mjs

按以下规则确定性地处理单行状态：

• OK — 继续。
• NEED_INSTALL — 运行 npm ci，重新检查，然后继续。使用锁文件；不要改用 npm install。
• UNSUPPORTED_NODE — 说明报告中的 Node 版本要求，并在运行应用前停止。
• ERROR — 报告缺失或损坏的 Skill 文件，并在继续前重新安装或更新 Skill。

将 npm ci 视为内部准备工作，而不是用户的常规操作。如果沙盒阻止网络访问，且环境支持审批，则请求网络权限。如果无法获得权限，请告知用户从 <skill-root> 运行一次 npm ci。如果 Skill 目录为只读，请说明需要使用可写的安装目录或检出目录；不要反复尝试安装，也不要声称安装成功。

运行确定性分析器：

node scripts/analyze-fit.mjs --format json <fit-or-kml-path> [more-track-paths...]

如果现成的本地报告已足够，请使用 --format markdown。只有在用户确认匹配的活动彼此不同后，才使用 --keep-duplicates。解读字段、检查加权规则或更改报告行为时，请阅读 references/report-contract.md。

3. 展示结果

先给出结果，不要先讲依赖项或解析器的细节。

对于单次活动，展示：

1. 简洁的地形／路线判断及最重要的观察。
2. 有数据时，展示距离和爬升；只有数据支持时，才展示时长、速度／配速、卡路里和暂停。
3. 展示适合该运动类型的记录指标：骑行速度／踏频、跑步配速／步频、徒步海拔／爬升；如有记录，还要展示心率、功率、温度和坡度。
4. 数据质量覆盖情况，尤其是踏频、心率、功率和坡度。
5. 按影响大小排序的两至八条具体建议。

对于多次活动，展示：

1. 总体汇总数据和日期范围。
2. 按活动列出的表格，包含运动类型和来源格式。
3. 仅在有时间数据且活动可比的情况下，指出最长、爬升最多和最快的活动。
4. 将从最早到最晚的变化作为观察结果，而不是体能提升的证明。
5. 传感器一致性、重复项和跳过的文件。
6. 汇总建议，以及重要的单项活动例外情况。

将数据缺失与数值为零区分开来。传感器不可用时，写“未记录”／“not recorded”或“覆盖不足”／“insufficient coverage”，绝不可写成零。除非用户提供必要阈值并明确要求分析，否则不得编造 FTP、功率区间、心率区间、VO₂max、训练负荷、恢复状态或医疗结论。

遵循以下规则：

• 汇总平均速度按总距离除以总运动时间计算。
• 仅包含几何数据的 KML 不得用于推断时长、速度、配速、暂停或照片时间匹配。
• 优先使用 KML 文档元数据中声明的运动类型、距离、爬升和下降数据。使用最长的 LineString 或 gx:Track，并保留来源文件的基本名称。
• 按有效样本数加权计算踏频、心率、功率和温度。
• 将卡路里视为设备估算值，将温度视为环境温度／设备温度。
• 将踏频描述为活动模式观察，而非普适建议。解读 spm 前，先确认跑步步频的计量约定。
• 坡度覆盖率足够时，报告按距离加权的坡度区间、平滑后的代表性 P99 坡度，以及最多三段连续爬升；设备记录的最大值须标注为原始值。
• 热量／补水建议须与记录的运动时长相匹配。
• 分享高度闭合的路线前须发出警告；建议隐藏起点和终点各 300–500 m。

选择两至六项有证据支持的深入分析。省略没有数据或仅属推测的内容。

如果结合地点的信息能显著改善建议，请阅读 references/location-enrichment.md。确认有歧义的公开地点名称，按确认后的名称而非坐标进行搜索，并为实时状况标注时间。不得将历史活动当作路线目前开放的证据。

4. 暂存并打开报告页面

分析成功后，尝试自动执行此操作，但要根据环境灵活处理。

1. 阅读 references/ui-report-contract.md。
2. 将模型编写的报告契约写入可写的临时 JSON 文件。不要将每位用户的分析存储在 public/skill-analysis.json 中。
3. 对于批次，选择用户指定的活动；否则，选择最长的非重复活动作为代表路线，同时保留汇总文本回复。
4. 在私有 OS 临时目录中暂存选定的轨迹和分析：

node scripts/prepare-report.mjs --track <selected-track> --analysis <temporary-report-json>

5. 读取返回的 JSON 对象。保留其中的 url 和 session；URL 将在 24 小时后过期，过期文件会在下一次暂存时清理，并且不会有任何内容存储在代码库中。
6. 获取 http://127.0.0.1:5174/，仅当返回的 HTML 同时包含 <title>Route Relief 和 id="fit-input" 时，才将其视为本项目。否则，从 <skill-root> 启动 npm run dev。服务器使用端口 5174，并启用 strictPort；如果该端口被其他应用占用，应报告冲突，而不是悄悄切换端口。
7. 使用任何可用的浏览器打开或浏览器自动化功能打开返回的 URL。该 URL 会自动加载轨迹和分析；不要依赖设置文件输入框。
8. 如果具备截图/视觉能力，请验证加载的源数据、Fit Ride Studio Skill 分析徽标、建议布局以及内容裁切情况。如果不具备视觉能力，请勿声称已进行视觉检查，并请用户检查打开的页面。

请如实采用以下回退方案：

• 如果 Agent 能打开 URL，但无法操作页面控件，则打开 URL 即可；无需对报告进行其他操作。
• 如果没有浏览器工具，但用户与 Agent 使用同一台机器，则提供返回的 URL，并说明需要手动打开。
• 如果是在远程环境或云容器中运行，而用户的浏览器无法访问该环回地址，则改为提供文本报告和临时分析 JSON。不要声称页面已打开。
• 如果所有可写临时位置都被阻止，导致无法暂存，则回退到现有的文件输入工作流，并提供简洁的手动步骤。

记录用于启动 Vite 的终端/进程句柄。结束前，说明本地服务器是否仍在运行，以及如何停止该确切进程（例如，在其终端中按 Ctrl+C）。不要使用范围过大的终止命令。实际可行时，在用户完成后清理暂存的报告：

node scripts/prepare-report.mjs --cleanup <session-id>

打开报告页面并不代表获准导出或切换到导出创作。

5. 处理导出请求

操作导出界面前，请先阅读 references/export-workflow.md。

• 遵循用户对活动的选择；否则，采用明确的偏好，例如最新、最长或爬升最多。
• 优先使用用户的媒体素材。使用内置抽象背景时，请告知用户。
• 默认使用 9:16、适用于动态内容的 H.264 MP4、整项活动摘要卡、启用水印并采用安全位置。单一背景轮换时长设为 10 秒；路线照片每张显示 2.5 秒。
• 渲染前，告知用户 Chromium 可能会打开原生保存对话框，需要用户亲自点击；否则，浏览器会使用下载文件夹。
• 如果具备视觉能力，请检查预览。如果不具备，请勿声称已确认边界；请用户在耗时较长的渲染前检查预览。
• 静态图像选择 PNG；动画/视频选择 MP4。
• 在渲染完成且已确认保存/下载之前，绝不要声称成功。

易用性默认设置

• 报告和水印中使用文件名，不包含绝对路径。
• 在数据质量部分一次性说明缺失的传感器。
• 重新打开编辑器时，保留当前导出布局。
• 对混合运动类型，不要只给出一个“平均活动”结论。
• 用户文件和生成的报告不得放入代码库。运行时副本存放在 OS 临时目录中；npm 包存放在 Skill 目录中，且可能因更新而被替换。

示例

• “帮我分析一次运动。”但未提供文件 → 用中文询问用户是否可以拖入文件或提供本地路径。
• “Show me the demo.” → 使用 samples/demo.kml，说明数据是合成的，对其进行分析，并在可访问时打开本地报告。
• 用户提供一个 FIT 文件 → 检查并安装，进行分析、展示结果、暂存文件，并打开通过 URL 加载的报告。
• “把这 8 次骑行综合分析一下。” → 分析有效且不重复的记录，并打开时长最长的骑行作为代表性报告，除非用户指定了其他记录。
• “只看看数据，先别导出。” → 分析并打开报告页面，但不要进入导出编辑器。
• 远程 Agent 无法访问回环地址 → 提供文本报告和 JSON，说明本地页面无法访问的原因，不要假装已经打开。