Guizang Sports Skill

这是什么？适合谁？

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

两个关键设计：

• Ride Relief 本地报告页：Skill 自带的本地网页，不需要另装软件；只监听本机地址，轨迹和分析数据通过系统临时目录交给页面，不会复制进你的仓库（隐私考量）。
• 结论要有依据：不是甩一堆图表，而是「踏频偏低（平均 72，区间集中在 65-80）」这种带数据支撑的结论与建议。

支持的运动与分析（来自 README）：骑行、跑步、徒步；踏频、爬坡、数据质量等维度检查；多文件综合分析（如「把这几次骑行做一个综合分析」）。

适合人群：

• 骑行/跑步/徒步爱好者：有 Garmin/码表/运动手表导出的 FIT 文件，想要「教练级」解读
• 运动博主：需要 3D 路线 + 数据卡片 + 沿途照片合成的高质量分享素材
• 数据爱好者：想用自然语言查询自己的运动数据（「我最近一个月的爬升趋势」）

不适合：无轨迹设备记录的运动（健身房无 GPS）；需要医疗级运动处方的人（结论是数据分析不是医学建议）。

使用前提：Claude Code / Codex 本地环境；.fit 或 .kml 轨迹文件（或先用示例数据体验）。

准备工作

1. 运行环境：Claude Code 或 Codex（本地 Agent 环境）。
2. 安装：npx skills add https://github.com/op7418/guizang-sports-skill --skill fit-ride-studio。
3. 轨迹文件：运动手表/码表导出的 .fit（Garmin/Wahoo 等）或 .kml（Google Earth 等）；没有的话用仓库自带 samples/demo.kml（完全合成的闭环骑行演示数据，不含真实运动者信息）。
4. 成本：免费；消耗 Agent tokens（含依赖检查、分析、报告生成，单次完整分析消耗中等）。
5. 时间预算：安装 2 分钟；单次分析 3-5 分钟（含报告页打开）。

3 步快速上手

第 1 步：安装

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

第 2 步：发起分析

直接对 Agent 说：

帮我分析一次运动。

Agent 会请你把文件拖进对话，或直接给本地路径（如 ~/Downloads/ride.fit）。也可以需求和文件一起发：

分析这份 FIT，重点看看踏频、爬坡和数据质量。

第 3 步：查看报告

Agent 自动检查运行依赖、完成分析并打开 Ride Relief 报告页—不需要你手动安装网页依赖或启动服务。

预期结果：浏览器自动打开本地报告页，含轨迹地图、关键数据（距离/爬升/心率区间等）与带依据的结论建议。成功判定：结论可追溯到具体数据（如「后程配速下降 15%，与坡度相关」），不是泛泛而谈。

常见踩坑

踩坑 1：FIT 文件带 GPS 误差环

• 现象：城市高楼/隧道段轨迹漂移，距离虚高。
• 原因：GPS 信号丢失后设备插值，FIT 原始数据自带误差。
• 解决：分析时让 Agent 先做数据质量检查（README 明确支持 data quality 维度），异常段剔除后再看结论。

踩坑 2：多文件分析口径不一

• 现象：几次骑行综合分析时，有的文件含心率有的没有。
• 原因：不同设备/码表记录字段不同。
• 解决：指令中说明「以共同字段（距离/爬升/时间）为口径做横向对比」；Agent 会在数据质量检查时发现字段缺失。

踩坑 3：把演示数据当真实样本

• 现象：用 samples/demo.kml 跑出的结论（如某坡度功率）引用到训练计划里。
• 原因：demo 是完全合成的闭环骑行，坐标仅供界面演示，不代表实际可骑行路线。
• 解决：演示数据只用于验证流程与 UI，真实结论必须来自自己的轨迹。

踩坑 4：担心轨迹隐私

• 现象：不想让运动轨迹（含家庭住址附近的起终点）进任何云服务。
• 原因：FIT 文件天然含高频 GPS 轨迹。
• 解决：本 Skill 全本地运行，Ride Relief 只监听本机、数据走临时目录不进仓库；分享图导出前裁掉起终点附近轨迹。

踩坑 5：3D 分享图视频渲染失败

• 现象：MP4 导出环节报编码错误。
• 原因：H.264 编码依赖系统 ffmpeg，环境缺失或版本过旧。
• 解决：让 Agent 先检查依赖（Skill 本身会做依赖检查）；Windows 用户注意 PATH 里的 ffmpeg。

踩坑 6：照片时区错位

• 现象：沿途照片合成到 3D 路线时位置飘。
• 原因：照片 EXIF 时间与轨迹记录时区不一致（出国骑行常见）。
• 解决：制作分享图前统一时区（告诉 Agent 照片拍摄时区），或手动核对首张照片的对应位置。

初级用法

1. 单次骑行复盘：一次 ride 的完整分析报告，重点看爬坡分段与踏频分布。
2. 数据质量体检：新设备上手先跑一次「只做数据质量检查」，确认记录无异常。
3. 示例数据演示：用示例数据演示一遍—零门槛看报告页长什么样。

高级玩法

1. 多骑行横向对比：几次同类骑行的综合分析（配速策略/爬坡能力演变），形成训练周期复盘。
2. 3D 路线分享图：3D 路线 + 数据卡片 + 沿途照片合成 PNG/MP4，直接发社交媒体（运动博主刚需）。
3. 自然语言数据查询：把历次 FIT 存一个目录，问「我最近三个月的 FTP 变化趋势」「哪次骑行的 TSS 最高」。
4. 训练计划建议链：分析结论 -> 让 Agent 按结论给下周期训练建议 -> 下一周期数据回来再验证建议有效性，闭环迭代。

小技巧

1. 「重点看 X」引导分析深度：明说关注维度（踏频/爬坡/心率），比「帮我分析」产出更聚焦。
2. 依赖让 Agent 自己查：Skill 设计为自动检查运行依赖，报错时把错误原样贴回给 Agent 即可自修。
3. 临时目录机制别改：Ride Relief 通过系统临时目录传数据的设计是隐私保障，别为了方便把轨迹复制进项目。
4. 分享图先出 PNG 再视频：PNG 快且够用，MP4 留给重点骑行。
5. KML 适合路线规划：没有 FIT 设备时，用 Google Earth 画条路线存 KML 也能预览 3D 路线效果。

常见问题 FAQ

Q1: 和 Strava/Garmin Connect 的分析有什么区别？

A: 平台分析是固定模板（标准图表+固定指标）；本 Skill 是自然语言驱动的定制分析—你可以问任何问题（「我哪段爬坡掉速最狠，为什么」），结论带数据依据，且 3D 路线+照片合成分享图是平台没有的产出形态。全部本地运行也是差异点。

Q2: 哪些设备的文件能用？

A: 任何导出 .fit（Garmin/Wahoo/Zwift 等）或 .kml 的设备/平台。FIT 是运动记录标准格式，覆盖绝大多数码表与手表。

Q3: 会上传我的轨迹吗？

A: 不会。Skill 在本地 Agent 环境运行，Ride Relief 报告页只监听本机地址，轨迹和分析数据经系统临时目录传递、不复制进仓库。分享图导出后自行决定发布范围。

Q4: AGPL-3.0 协议对我有什么影响？

A: 个人分析使用无任何影响。若把 Skill（或基于它的修改）作为网络服务提供给他人，AGPL 要求开源你的修改—自用场景不触发。

Q5: 分析结论可信吗，能当训练指导吗？

A: 结论有数据依据（每个结论可追溯到具体指标），作为训练参考可信度高；但它不做医疗级判断—心率异常、伤痛相关信号请咨询专业人士。

参考链接

• GitHub 仓库
• 示例数据 samples/demo.kml

本文基于公开资料整理（GitHub 仓库 README，数据核验日期 2026-08-25），AI 辅助生成。