Skip to content
Back to search

guizang-sports-skill

🚴 Claude Code / Codex skill for FIT & KML sports analysis — cycling, running, hiking, sensor and grade insights, local 3D route reports, PNG & H.264 MP4 exports. 运动轨迹分析与 3D 路线故事

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/op7418--guizang-sports-skill/badge.svg)](/listings/op7418--guizang-sports-skill)

HTML

<a href="/listings/op7418--guizang-sports-skill"><img src="/api/listings/op7418--guizang-sports-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 153 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: fit-ride-studio
  3. description: Analyze one or more cycling, running, or hiking FIT/KML activity tracks, generate evidence-based single or aggregate reports, open the bundled local Ride Relief report page when the environment supports it, enrich results with user-confirmed public location context, and create shareable PNG or H.264 MP4 route stories on request. Use whenever a user wants to analyze, compare, visualize, or export .fit or .kml activities, including requests that mention a workout but do not yet include track files.
  4. ---
  5. # FIT & KML Activity Studio
  6. Turn local cycling, running, and hiking tracks into an evidence-based report and local visual experience. Follow this sequence:
  7. 1. Ask for FIT/KML files when none were provided, or use the bundled synthetic demo when requested.
  8. 2. Check the installation, install missing locked dependencies automatically, and analyze every valid file.
  9. 3. Present the result, stage private runtime files, and open the bundled Ride Relief report page when local browser access is available.
  10. Enter the export composer only when the user asks for a shareable image, animation, or video. Ride Relief is the web app bundled inside this Skill, not a separate product to install.
  11. ## Workflow
  12. ### 1. Get the track files
  13. - When the user explicitly asks for a demo, use `<skill-root>/samples/demo.kml`. State that it is fictional data.
  14. - Otherwise, if no readable `.fit` or `.kml` was supplied, ask in the user's language for either an attachment or a local path. Example in Chinese: “请把 `.fit` 或 `.kml` 拖进对话,或告诉我文件路径(例如 `~/Downloads/ride.fit`);可以一次给多个。”
  15. - Stop after requesting missing input. Do not invent activity data and do not ask the user to configure the project.
  16. - Proceed immediately when at least one file is accessible. Infer single versus aggregate mode from valid files.
  17. - Accept a directory only when the user placed it in scope; expand only top-level FIT/KML files.
  18. - Process tracks locally. Do not upload exact GPS tracks or expose coordinates in the response.
  19. - Continue a batch when one file is corrupt, provided another track is valid. Report skipped basenames.
  20. - Detect likely duplicates by start time, distance, and duration. Exclude them from totals and identify them.
  21. ### 2. Check readiness and analyze
  22. Resolve `<skill-root>` as the directory containing this `SKILL.md`. Run from that directory:
  23. ```bash
  24. node scripts/check-install.mjs
  25. ```
  26. Handle its single-line status deterministically:
  27. - `OK` — continue.
  28. - `NEED_INSTALL` — run `npm ci`, rerun the check, then continue. Use the lock file; do not substitute `npm install`.
  29. - `UNSUPPORTED_NODE` — explain the reported Node requirement and stop before running the app.
  30. - `ERROR` — report the missing/broken Skill files and reinstall or update the Skill before continuing.
  31. Treat `npm ci` as internal preparation, not a routine user step. If a sandbox blocks network access, request network permission when the environment supports approvals. If permission is unavailable, tell the user to run `npm ci` once from `<skill-root>`. If the Skill directory is read-only, explain that a writable installation or checkout is required; do not loop on installation or claim success.
  32. Run the deterministic analyzer:
  33. ```bash
  34. node scripts/analyze-fit.mjs --format json <fit-or-kml-path> [more-track-paths...]
  35. ```
  36. Use `--format markdown` when a ready-to-read local report is sufficient. Use `--keep-duplicates` only after the user confirms matching activities are distinct. Read [references/report-contract.md](references/report-contract.md) when interpreting fields, checking weighting rules, or changing report behavior.
  37. ### 3. Present the result
  38. Start with the result, not dependency or parser details.
  39. For one activity, present:
  40. 1. A compact terrain/route verdict and the most important observation.
  41. 2. Distance and ascent when available; show duration, speed/pace, calories, and pauses only when supported.
  42. 3. Sport-appropriate recorded metrics: cycling speed/cadence, running pace/step cadence, hiking elevation/ascent, plus heart rate, power, temperature, and grade when present.
  43. 4. Data-quality coverage, especially cadence, heart rate, power, and grade.
  44. 5. Two to eight concrete suggestions ordered by impact.
  45. For multiple activities, present:
  46. 1. Overall totals and date range.
  47. 2. A per-activity table with sport and source format.
  48. 3. Longest, most climbing, and fastest only within comparable activities with time data.
  49. 4. Earliest-to-latest deltas as observations, not proof of fitness improvement.
  50. 5. Sensor consistency, duplicates, and skipped files.
  51. 6. Aggregate suggestions plus important activity-specific exceptions.
  52. Keep absent data distinct from zero. Say “未记录” / “not recorded” or “覆盖不足” / “insufficient coverage,” never zero when a sensor was unavailable. Do not invent FTP, power zones, heart-rate zones, VO₂max, training load, recovery status, or medical conclusions unless the user supplies the necessary thresholds and explicitly requests that analysis.
  53. Apply these rules:
  54. - Compute aggregate average speed as total distance divided by total moving time.
  55. - Never infer duration, speed, pace, pauses, or photo-time matching from geometry-only KML.
  56. - Prefer KML document metadata for declared sport, distance, ascent, and descent. Use the longest `LineString` or `gx:Track` and retain the source basename.
  57. - Weight cadence, heart rate, power, and temperature by valid sample counts.
  58. - Treat calories as device estimates and temperature as ambient/device temperature.
  59. - Describe cadence as an activity-pattern observation, not a universal prescription. Confirm the running-cadence convention before interpreting spm.
  60. - When grade coverage is adequate, report distance-weighted grade bands, smoothed P99 representative grade, and up to three continuous climbs; label the device maximum as raw.
  61. - Match heat/hydration suggestions to recorded moving duration.
  62. - Warn before sharing a highly closed route; recommend hiding the first and last 300–500 m.
  63. Choose two to six evidence-backed deep dives. Omit empty or speculative dimensions.
  64. When place-aware advice would materially improve the result, read [references/location-enrichment.md](references/location-enrichment.md). Confirm ambiguous public place names, search by the confirmed name rather than coordinates, and time-stamp live conditions. Do not treat an old activity as evidence that a route is currently open.
  65. ### 4. Stage and open the report page
  66. Attempt this automatically after successful analysis, but adapt to the environment.
  67. 1. Read [references/ui-report-contract.md](references/ui-report-contract.md).
  68. 2. Write the model-authored report contract to a writable temporary JSON file. Do not store per-user analysis in `public/skill-analysis.json`.
  69. 3. For a batch, select the user's requested activity; otherwise use the longest non-duplicate as the representative route while keeping the text response aggregate.
  70. 4. Stage the selected track and analysis in the private OS temporary directory:
  71. ```bash
  72. node scripts/prepare-report.mjs --track <selected-track> --analysis <temporary-report-json>
  73. ```
  74. 5. Read the returned JSON object. Keep its `url` and `session`; the URL expires after 24 hours, stale files are cleaned on the next staging run, and nothing is stored in the repository.
  75. 6. Fetch `http://127.0.0.1:5174/` and treat it as this project only when the returned HTML contains both `<title>Route Relief` and `id="fit-input"`. Otherwise start `npm run dev` from `<skill-root>`. The server uses port 5174 with `strictPort`; if another application owns the port, report the conflict instead of silently switching ports.
  76. 7. Use any available browser-opening or browser-automation capability to open the returned URL. The URL auto-loads the track and analysis; do not rely on setting a file input.
  77. 8. With screenshot/visual capability, verify the loaded source, the `Fit Ride Studio Skill` analysis badge, recommendation layout, and clipping. Without visual capability, skip visual claims and ask the user to inspect the opened page.
  78. Apply these fallbacks honestly:
  79. - If the Agent can open URLs but cannot automate page controls, open the URL; no further interaction is required for the report.
  80. - If no browser tool exists but the user shares the same machine, provide the returned URL and say to open it manually.
  81. - If running remotely or in a cloud container where the user's browser cannot reach that loopback address, deliver the text report and temporary analysis JSON instead. Do not claim the page opened.
  82. - If staging is impossible because every writable temporary location is blocked, fall back to the existing file-input workflow and give concise manual steps.
  83. Track the terminal/process handle used to start Vite. Before finishing, state whether the local server remains running and how to stop that exact process (for example, `Ctrl+C` in its terminal). Do not use a broad kill command. Clean a staged report after the user is finished when practical:
  84. ```bash
  85. node scripts/prepare-report.mjs --cleanup <session-id>
  86. ```
  87. Opening the report page does not authorize export or switching to **导出创作**.
  88. ### 5. Handle export requests
  89. Read [references/export-workflow.md](references/export-workflow.md) before operating the export UI.
  90. - Follow the user's activity selection; otherwise use a clear preference such as latest, longest, or most climbing.
  91. - Prefer user media. Disclose when a built-in abstract background will be used.
  92. - Default to 9:16, H.264 MP4 for motion, whole-activity summary card, watermark enabled, and safe placement. Use a 10-second single-background rotation or 2.5 seconds per route photo.
  93. - Before rendering, tell the user that Chromium may open a native save picker that requires their own click; otherwise the browser downloads folder is used.
  94. - Inspect the preview when visual capability exists. Without it, do not claim bounds were verified; ask the user to check the preview before the expensive render.
  95. - Choose PNG for a still and MP4 for animation/video.
  96. - Never claim success until rendering finishes and save/download is confirmed.
  97. ## Usability defaults
  98. - Use basenames in reports and watermarks; omit absolute paths.
  99. - Explain missing sensors once in the data-quality section.
  100. - Preserve the current export layout when revisiting the composer.
  101. - Avoid one “average activity” conclusion for mixed sports.
  102. - Keep user files and generated reports out of the repository. Runtime copies live in the OS temporary directory; npm packages live in the Skill directory and may be replaced by updates.
  103. ## Examples
  104. - “帮我分析一次运动。” with no file → Ask in Chinese for a dragged file or local path.
  105. - “Show me the demo.” → Use `samples/demo.kml`, state that it is synthetic, analyze it, and open the local report when reachable.
  106. - The user provides one FIT → Check/install, analyze, present, stage, and open the URL-loaded report.
  107. - “把这 8 次骑行综合分析一下。” → Analyze valid non-duplicates and open the longest ride as the representative report unless another is named.
  108. - “只看看数据,先别导出。” → Analyze and open the report page, but do not enter the export composer.
  109. - A remote Agent cannot expose loopback → Deliver the text report and JSON, explain why the local page is unavailable, and do not pretend it opened.
README.md · README · 158 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Guizang Sports Skill · FIT/KML 运动分析与 3D 路线故事
  2. ![GitHub stars](https://img.shields.io/github/stars/op7418/guizang-sports-skill?style=flat-square)
  3. ![License](https://img.shields.io/github/license/op7418/guizang-sports-skill?style=flat-square)
  4. ![Skill](https://img.shields.io/badge/Skill-Agent-111111?style=flat-square)
  5. ![Tracks](https://img.shields.io/badge/Tracks-FIT%20%2F%20KML-D6FF64?style=flat-square&labelColor=202020)
  6. ![Claude Code](https://img.shields.io/badge/Claude%20Code-Supported-6B5B95?style=flat-square)
  7. ![Codex](https://img.shields.io/badge/Codex-Supported-222222?style=flat-square)
  8. 一个面向 Claude Code、Codex 等本地 Agent 环境的运动轨迹 Skill。把一个或多个 `.fit` / `.kml` 文件交给 Agent,它会分析骑行、跑步或徒步数据,生成有依据的结论与建议,并自动打开本地可视化报告页。需要分享时,还能继续制作带 3D 路线、数据卡片和沿途照片的 PNG / H.264 MP4。
  9. **Ride Relief 是这个 Skill 自带的本地报告网页,不需要另装软件。** 它只监听本机地址,轨迹和分析通过系统临时目录交给页面,不会复制进仓库。
  10. ![Ride Relief 运动分析与 3D 路线演示](https://github.com/user-attachments/assets/05c81338-b6a0-486a-90f9-046be56c20f7)
  11. ## 30 秒开始
  12. ```bash
  13. npx skills add https://github.com/op7418/guizang-sports-skill --skill fit-ride-studio
  14. ```
  15. 安装后直接对 Agent 说:
  16. ```text
  17. 帮我分析一次运动。
  18. ```
  19. 如果还没有收到轨迹文件,Agent 会请你把文件拖进对话,或直接告诉它本地路径(例如 `~/Downloads/ride.fit`)。收到后会自动检查运行依赖、完成分析并打开报告页,不需要你手动安装网页依赖或启动服务。
  20. 没有现成文件也可以立即体验:
  21. ```text
  22. 用示例数据演示一遍。
  23. ```
  24. 仓库内的 [`samples/demo.kml`](./samples/demo.kml) 是完全合成的闭环骑行,不包含真实运动者或住址数据;坐标仅供界面演示,不代表实际可骑行路线。
  25. 也可以把需求和文件一起发过去:
  26. ```text
  27. 分析这份 FIT,重点看看踏频、爬坡和数据质量。
  28. 把这几次骑行做一个综合分析,找出最长、爬升最多和传感器最完整的一次。
  29. 这是两步路导出的徒步 KML,分析路线强度和主要爬坡。
  30. 把最长的那次做成一个 9:16 的 3D 路线演示视频。
  31. 用这些沿途照片做路线故事,每张停留 2.5 秒。
  32. ```
  33. ## 使用流程
  34. 1. **索要轨迹**:请求里没有文件时,Agent 会请你把一个或多个 FIT / KML 拖进对话,或提供本地路径,不会让你先配置项目。
  35. 2. **自动分析**:收到文件后,Agent 会用锁定版本准备缺失依赖,解析轨迹并给出单次报告或多活动综合报告。
  36. 3. **打开报告页**:分析完成后,Agent 会生成临时链接并打开 Ride Relief;链接会自动加载轨迹,不依赖浏览器操作文件选择框。
  37. 4. **按需导出**:只有你提出图片、动画或视频需求时,Agent 才进入导出创作器,配置比例、背景、照片、图层和水印。
  38. 本地浏览器不可用时,Agent 会降级交付文字报告和分析 JSON;云端环境里的 `127.0.0.1` 通常无法从你的电脑访问,因此不会假装已经打开页面。
  39. ## 如何取得 FIT / KML
  40. 不同 App 的菜单会随版本调整,优先选择保留原始传感器数据的 FIT;只有路线几何时再用 KML。
  41. | 来源 | 常见取得方式 |
  42. | --- | --- |
  43. | Garmin Connect | 在网页版打开活动,点右上角齿轮并选择 **Export Original / 导出原始文件**;多数设备会得到 FIT。见 [Garmin 官方说明](https://support.garmin.com/en-IN/?=&faq=W1TvTPW8JZ6LfJSfK512Q8) |
  44. | 行者码表 | 用 USB 连接电脑,打开设备中的 `activities` 文件夹并取出 FIT。见 [行者帮助中心](https://hc.imxingzhe.com/hc/xing/articles/1708510246-fit) |
  45. | 两步路 | 在轨迹详情使用“下载轨迹 / 本地下载”,选择 KML;下载自己的轨迹时注意可见范围与隐私设置 |
  46. | Keep | 如果当前活动页没有 FIT/KML 导出入口,从记录活动的手表、码表或关联平台导出原始文件;分享图片不能代替轨迹文件 |
  47. ## 能做什么
  48. | 能力 | 说明 |
  49. | --- | --- |
  50. | 单次活动分析 | 距离、时间、速度或配速、爬升、海拔、暂停、热量与路线特征 |
  51. | 多活动综合分析 | 总量、日期范围、逐次对比、最长活动、最大爬升、同类运动趋势与异常 |
  52. | 专业传感器分析 | 踏频、步频、心率、功率、温度、坡度分布和字段覆盖率;未记录的数据不会伪装成 0 |
  53. | 爬坡识别 | 距离加权坡度分布、平滑 P99 代表坡度和最多三段连续爬坡 |
  54. | 地点信息增强 | 先确认公开地名,再查询路线背景、补给、交通、天气与安全信息;不使用精确轨迹公开搜索 |
  55. | 本地可视化报告 | 展示核心指标、坡度、主要爬坡、深度分析、行动建议和 3D 路线 |
  56. | 图片与视频导出 | 1080 级 PNG;H.264 MP4、30 FPS、12 Mbps;支持多种社交媒体比例 |
  57. | 沿途照片故事 | 照片可按 GPS / 拍摄时间匹配路线,也可手动定位、排序和选择封面 |
  58. ## 数据解释原则
  59. - 缺失值和数值 0 严格分开;没有心率带时显示“未记录”,不会显示“0 bpm”。
  60. - 综合平均速度使用总距离除以总移动时间,不直接平均每次活动的平均值。
  61. - 不同运动类型分组比较,不用骑行速度和徒步配速得出统一“进步”结论。
  62. - KML 没有时间戳时,不推测时长、速度、配速、停留或照片时间匹配。
  63. - 不凭轨迹虚构 FTP、心率区间、VO₂max、训练负荷、恢复状态或医疗结论。
  64. - 原始最大坡度保留为设备记录;路线难度优先参考平滑代表坡度和连续爬坡。
  65. ## 导出规格
  66. | 比例 | 输出尺寸 | 推荐用途 |
  67. | --- | ---: | --- |
  68. | 9:16 | 1080 × 1920 | 小红书、Reels、短视频竖屏 |
  69. | 3:4 | 1080 × 1440 | 小红书图文封面、运动卡片 |
  70. | 1:1 | 1080 × 1080 | 社交平台方形分享 |
  71. | 16:9 | 1920 × 1080 | 横屏视频、桌面展示 |
  72. 视频输出为 H.264 MP4、30 FPS、12 Mbps。单背景默认约 10 秒完成一圈地图旋转;多照片故事默认每张停留 2.5 秒,总时长按照片数量计算。
  73. ## 平台支持
  74. | 平台 | 状态 | 说明 |
  75. | --- | --- | --- |
  76. | Claude Code | 支持 | 可读取本地轨迹、执行分析并打开报告页 |
  77. | Codex | 支持 | 适合完整分析、浏览器操作和导出流程 |
  78. | Cursor / 其他本地 Agent | 可用 | 需要具备文件读写、Shell 和本地浏览器能力 |
  79. | 普通 Chatbot | 不推荐 | 无法稳定读取轨迹、运行解析器或打开本地报告 |
  80. 运行分析器需要 Node.js `^20.19.0` 或 `>=22.12.0`。Skill 会给出明确的版本或依赖状态,不会把安装失败误报为分析成功。
  81. ## 隐私
  82. - FIT、KML、照片和视频默认只在本机与本地浏览器中处理。
  83. - 对外分享闭环路线前,建议隐藏起终点前后 300–500 米。
  84. - 地点增强使用用户确认的公开地名,不把精确 GPS 轨迹上传到搜索服务。
  85. - 文件名可能出现在报告和导出水印中;如包含隐私信息,导出前请修改水印。
  86. - 报告页使用随机会话 ID 从系统临时目录读取轨迹;链接在 24 小时后失效,过期副本会在下次准备报告时清理,不随仓库更新保存。
  87. ## 常见问题
  88. **需要自己安装网页依赖吗?**
  89. 不需要。Skill 会在首次分析时检查关键模块;缺失时由 Agent 根据 `package-lock.json` 自动执行 `npm ci`。只有 Node 版本、权限、只读目录或网络失败时才会请你介入。
  90. **一次可以分析多个文件吗?**
  91. 可以。Agent 会自动进入综合分析,识别疑似重复活动,分别报告损坏或跳过的文件,并只在同类运动之间比较速度、配速和踏频。
  92. **分析后一定会导出视频吗?**
  93. 不会。分析后默认只打开本地报告页;只有你明确要求图片、动画或视频时才开始导出。
  94. **本地报告会一直在后台运行吗?**
  95. Agent 启动报告服务后会说明它是否仍在运行,以及如何停止对应进程。临时轨迹与分析不会写入仓库,并会自动过期。
  96. **导出时为什么还需要我点击?**
  97. Chromium 的原生保存窗口通常不能由 Agent 代点。开始渲染前 Agent 会提醒你;不支持保存窗口时,文件会进入浏览器下载目录。
  98. **如何更新?**
  99. 重新运行安装命令即可获取最新版。
  100. ## 贡献
  101. 欢迎通过 [Issues](https://github.com/op7418/guizang-sports-skill/issues) 报告解析、数据解释、页面显示或导出问题,也欢迎提交 Pull Request。修改指标定义、报告字段或导出参数时,请同步更新对应的 `references/` 约定并运行项目测试。
  102. ## 技术参考
  103. 网页端使用 Three.js 实现 3D 路线表达,概念参考 [Any Distance iOS 的 RouteScene.swift](https://github.com/Any-Distance/any-distance-ios/blob/main/ADAC/ADAC/Route%20Rendering/RouteScene.swift)。本项目不是对 Swift 源码的逐行翻译,也未使用 Any Distance 的品牌素材。
  104. ## License
  105. AGPL-3.0 © 2026 [op7418](https://github.com/op7418)
  106. 本项目采用 **GNU AGPL-3.0** 协议。修改、分发或通过网络服务提供修改版本时,需要按协议保留署名并公开相应源代码。完整条款见 [`LICENSE`](./LICENSE)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.