Guizang Sports Skill · FIT/KML 运动分析与 3D 路线故事

一个面向 Claude Code、Codex 等本地 Agent 环境的运动轨迹 Skill。把一个或多个 .fit / .kml 文件交给 Agent，它会分析骑行、跑步或徒步数据，生成有依据的结论与建议，并自动打开本地可视化报告页。需要分享时，还能继续制作带 3D 路线、数据卡片和沿途照片的 PNG / H.264 MP4。

Ride Relief 是这个 Skill 自带的本地报告网页，不需要另装软件。 它只监听本机地址，轨迹和分析通过系统临时目录交给页面，不会复制进仓库。

30 秒开始

npx skills add https://github.com/op7418/guizang-sports-skill --skill fit-ride-studio

安装后直接对 Agent 说：

帮我分析一次运动。

如果还没有收到轨迹文件，Agent 会请你把文件拖进对话，或直接告诉它本地路径（例如 ~/Downloads/ride.fit）。收到后会自动检查运行依赖、完成分析并打开报告页，不需要你手动安装网页依赖或启动服务。

没有现成文件也可以立即体验：

用示例数据演示一遍。

仓库内的 samples/demo.kml 是完全合成的闭环骑行，不包含真实运动者或住址数据；坐标仅供界面演示，不代表实际可骑行路线。

也可以把需求和文件一起发过去：

分析这份 FIT，重点看看踏频、爬坡和数据质量。
把这几次骑行做一个综合分析，找出最长、爬升最多和传感器最完整的一次。
这是两步路导出的徒步 KML，分析路线强度和主要爬坡。
把最长的那次做成一个 9:16 的 3D 路线演示视频。
用这些沿途照片做路线故事，每张停留 2.5 秒。

使用流程

1. 索要轨迹：请求里没有文件时，Agent 会请你把一个或多个 FIT / KML 拖进对话，或提供本地路径，不会让你先配置项目。
2. 自动分析：收到文件后，Agent 会用锁定版本准备缺失依赖，解析轨迹并给出单次报告或多活动综合报告。
3. 打开报告页：分析完成后，Agent 会生成临时链接并打开 Ride Relief；链接会自动加载轨迹，不依赖浏览器操作文件选择框。
4. 按需导出：只有你提出图片、动画或视频需求时，Agent 才进入导出创作器，配置比例、背景、照片、图层和水印。

本地浏览器不可用时，Agent 会降级交付文字报告和分析 JSON；云端环境里的 127.0.0.1 通常无法从你的电脑访问，因此不会假装已经打开页面。

如何取得 FIT / KML

不同 App 的菜单会随版本调整，优先选择保留原始传感器数据的 FIT；只有路线几何时再用 KML。

来源	常见取得方式
Garmin Connect	在网页版打开活动，点右上角齿轮并选择 Export Original / 导出原始文件；多数设备会得到 FIT。见 Garmin 官方说明
行者码表	用 USB 连接电脑，打开设备中的 activities 文件夹并取出 FIT。见 行者帮助中心
两步路	在轨迹详情使用“下载轨迹 / 本地下载”，选择 KML；下载自己的轨迹时注意可见范围与隐私设置
Keep	如果当前活动页没有 FIT/KML 导出入口，从记录活动的手表、码表或关联平台导出原始文件；分享图片不能代替轨迹文件

能做什么

能力	说明
单次活动分析	距离、时间、速度或配速、爬升、海拔、暂停、热量与路线特征
多活动综合分析	总量、日期范围、逐次对比、最长活动、最大爬升、同类运动趋势与异常
专业传感器分析	踏频、步频、心率、功率、温度、坡度分布和字段覆盖率；未记录的数据不会伪装成 0
爬坡识别	距离加权坡度分布、平滑 P99 代表坡度和最多三段连续爬坡
地点信息增强	先确认公开地名，再查询路线背景、补给、交通、天气与安全信息；不使用精确轨迹公开搜索
本地可视化报告	展示核心指标、坡度、主要爬坡、深度分析、行动建议和 3D 路线
图片与视频导出	1080 级 PNG；H.264 MP4、30 FPS、12 Mbps；支持多种社交媒体比例
沿途照片故事	照片可按 GPS / 拍摄时间匹配路线，也可手动定位、排序和选择封面

数据解释原则

• 缺失值和数值 0 严格分开；没有心率带时显示“未记录”，不会显示“0 bpm”。
• 综合平均速度使用总距离除以总移动时间，不直接平均每次活动的平均值。
• 不同运动类型分组比较，不用骑行速度和徒步配速得出统一“进步”结论。
• KML 没有时间戳时，不推测时长、速度、配速、停留或照片时间匹配。
• 不凭轨迹虚构 FTP、心率区间、VO₂max、训练负荷、恢复状态或医疗结论。
• 原始最大坡度保留为设备记录；路线难度优先参考平滑代表坡度和连续爬坡。

导出规格

比例	输出尺寸	推荐用途
9:16	1080 × 1920	小红书、Reels、短视频竖屏
3:4	1080 × 1440	小红书图文封面、运动卡片
1:1	1080 × 1080	社交平台方形分享
16:9	1920 × 1080	横屏视频、桌面展示

视频输出为 H.264 MP4、30 FPS、12 Mbps。单背景默认约 10 秒完成一圈地图旋转；多照片故事默认每张停留 2.5 秒，总时长按照片数量计算。

平台支持

平台	状态	说明
Claude Code	支持	可读取本地轨迹、执行分析并打开报告页
Codex	支持	适合完整分析、浏览器操作和导出流程
Cursor / 其他本地 Agent	可用	需要具备文件读写、Shell 和本地浏览器能力
普通 Chatbot	不推荐	无法稳定读取轨迹、运行解析器或打开本地报告

运行分析器需要 Node.js ^20.19.0 或 >=22.12.0。Skill 会给出明确的版本或依赖状态，不会把安装失败误报为分析成功。

隐私

• FIT、KML、照片和视频默认只在本机与本地浏览器中处理。
• 对外分享闭环路线前，建议隐藏起终点前后 300–500 米。
• 地点增强使用用户确认的公开地名，不把精确 GPS 轨迹上传到搜索服务。
• 文件名可能出现在报告和导出水印中；如包含隐私信息，导出前请修改水印。
• 报告页使用随机会话 ID 从系统临时目录读取轨迹；链接在 24 小时后失效，过期副本会在下次准备报告时清理，不随仓库更新保存。

常见问题

需要自己安装网页依赖吗？

不需要。Skill 会在首次分析时检查关键模块；缺失时由 Agent 根据 package-lock.json 自动执行 npm ci。只有 Node 版本、权限、只读目录或网络失败时才会请你介入。

一次可以分析多个文件吗？

可以。Agent 会自动进入综合分析，识别疑似重复活动，分别报告损坏或跳过的文件，并只在同类运动之间比较速度、配速和踏频。

分析后一定会导出视频吗？

不会。分析后默认只打开本地报告页；只有你明确要求图片、动画或视频时才开始导出。

本地报告会一直在后台运行吗？