52run 跑步截图出图器
用户说人话，你出图。不要问字段、不要让他打开浏览器填、不要让他画轨迹。
铁律
- 只出户外跑步。 运动类型固定
run，不做室内跑步、不做行走、不做骑行。
用户要是问室内跑或骑行，直接说这版只做户外跑步。 - 有 TCX 就以 TCX 为准，没有才问。 用户给了
--tcx，距离、配速、日期、开跑时间、心率、步频、爬升
全部从文件里读，一个字都不用他填；他额外说了某个数（比如"就当 10 公里"），用他说的覆盖文件里的。
没给 TCX 时：距离和配速必须说，日期没说就今天，时间没说就 06:00，
卡路里/心率/步频/爬升没说就不传（页面自己按配速推算，心率页内有默认值）。
只有一件事值得追问：既没 TCX、又缺距离或配速——这情况出不了图。 - 不要点按钮、不要模拟填表。 页面有预填协议，直接写数据。
- 出图必须核对。 生成后打开 PNG 看一眼：公里数、配速、日期对不对。数字错了就是参数传错了，重出，别糊弄过去。
机制（为什么不用手动填）
https://www.52run.cn/shot.html 支持两条 localStorage 协议，这是唯一的正道：
| 键 | 内容 | 作用 |
|---|---|---|
shot_prefill_v1 |
{v:1, t:Date.now(), sport, distKm, paceSec, dateStr, startLocalMs, hrAvg, cad, calories, ascent, nick} |
页面加载时自动把参数填进表单并出图。30 分钟内有效，读完即删 |
shot_track |
{track:[{lat,lon},...]} |
替换默认路线；不写就用页面内置环湖路线 |
流程：打开页面 → 写 localStorage → 刷新 → 等画布稳定 → 取 #cvShort / #cvLong 的 toDataURL('image/png') → 存盘。
shoot.py 已经把这套封装好了，你只管传参数。
配速 min/max 两个框：页面收到一个 paceSec 会同时写进 inPaceMin 和 inPaceMax，两个值一模一样，符合预期，不用管。
轨迹从哪来（两档）
| 档 | 来源 | 覆盖范围 | 说明 |
|---|---|---|---|
| 1 | --place 地名 |
全国任意地名 | 调 52run 轨迹接口 /api/track，服务端沿真实道路生成环线；技能不含 key |
| 2 | 用户自己的 TCX / GPX | 任意地点，无死角 | 用户本来就在那儿跑过，文件里自带轨迹，不用生成 |
没有内置轨迹库了（早期版本带的 8 条已删除）——能按地名生成任意位置，就没必要预存固定路线。
自然语言 → 参数（照这个映射，别自己发挥）
| 用户说 | 传什么 |
|---|---|
| 十公里 / 10 公里 / 10k | --km 10 |
| 半马 | --km 21.0975 |
| 全马 | --km 42.195 |
| 五分半 / 5'30" / 5:30 | --pace 5:30 |
| 六分整 | --pace 6:00 |
| 昨天 / 前天 / 今天 | --date 昨天 |
| 11月3号 | --date 11-03 |
| 早上六点 / 6:30 | --time 06:00 / --time 6:30 |
| 晚上六点 | --time 18:00 |
| 下午三点半 | --time 15:30 |
| 我这有一条轨迹（给了文件） | --gpx "路径.gpx" |
| 昵称叫老王 / 名字写 XX | --nick 老王 |
运动日期就是开跑日期，两者同一个 dateStr，不要拆成两个参数。
怎么调
# 主用法：用户自己的 TCX，啥都不用填
python scripts/shoot.py --tcx "D:/导出/today.tcx"
# TCX + 改数字（轨迹照用文件里的，距离说成 10）
python scripts/shoot.py --tcx "D:/today.tcx" --km 10
# 最简：没文件，只要距离和配速
python scripts/shoot.py --km 10 --pace 5:30
# 说全了
python scripts/shoot.py --place "重庆北碚龙凤桥" --km 10 --pace 6:00 --date 前天 --time 晚上8点 --nick 老王
# 要长图加 --long
python scripts/shoot.py --km 5 --pace 4:45 --long
# 自己的轨迹 + 昵称
python scripts/shoot.py --km 42.195 --pace 5:50 --gpx "D:/轨迹.gpx" --nick 老王
| 参数 | 说明 |
|---|---|
--tcx |
给一份 TCX，全指标自动读，可覆盖。这是主用法 |
--km |
公里数（有 TCX 可不给；给了就覆盖文件里的距离） |
--pace |
必填，5:30 / 5'30" / 330 都认 |
--date |
今天 昨天 前天 2026-11-03 11-03，不给=今天 |
--time |
06:30 晚上6点 下午3点半，不给=06:00 |
--cal --hr --cad --ascent |
卡路里/平均心率/步频/爬升，不给就由页面按配速推算 |
--nick |
昵称。注意：预填协议里没有昵称字段，它存在 shot_cfg_v1 的 inNick 键里，脚本已自动处理 |
--avatar |
头像图片路径 |
--place |
地名，如 贵州大学 —— 自动搜索→取第一个结果→框选→沿真实道路生成轨迹 |
--gpx |
自带 GPX 道路径 |
--out |
输出目录，默认 桌面/跑步截图 |
--long |
只出长图（默认只出短图） |
--short |
单独用无效果；和 --long 一起给才出两张 |
--place 怎么工作（只调一个自有接口）
技能不含任何地图密钥，也不直接调任何地图厂商。它只发一个请求：
GET https://www.52run.cn/api/track?place=贵州大学&km=5&rounds=2
-> {"ok":true,"place":"贵州大学(花溪西校区)","km":5.19,"points":[[lat,lng],...],
"cached":false,"calls":5}
服务端负责搜索地点、沿道路生成环线、按目标里程校准，地图供应商藏在服务端。
这样设计的好处：
- 换地图供应商（腾讯额度不够换高德/百度）只改服务器，技能不用动、不用重新发版
- 服务端有缓存：同地点同距离第二次直接返回，0 次外部调用
- 服务端有每 IP 每日限额，别人用技能烧不到主账号额度
- 技能里没有 key，审核和分发都不涉及密钥
请求失败时按返回的 err 字段如实告诉用户，不要自己编一条轨迹糊弄。
出图之后
- 用
present_files把 PNG 递给用户（短图在前）。 - 文字里报一句：距离、配速、日期、用时（= 距离 × 配速，自己算好说出来）。
- 默认只出短图，别自作主张附一张长图。用户明确要长图才加
--long。
排错
| 现象 | 原因 / 处理 |
|---|---|
页面没出图（画布为空） |
没网、或页面改版。先确认 https://www.52run.cn/shot.html 能打开 |
| 图上数字不对 | 参数传错，看 --km --pace 有没有被中文覆盖 |
| 地图空白/灰块 | 瓦片没加载完，加大等待（脚本已等 40 秒）；重跑一次 |
| 地名生成失败 | 换个更具体的地名（加区/市前缀），或改用 --gpx 给轨迹 |
