MapLibre · Agent Skill · 开源

让地图成为
历史视频的舞台

古卷底图、路线行进、自动取景、合规规则——写一份 JSON，或者对 agent 说一句话，就能逐帧渲染出可上线的地图镜头。

Narrative maps for history videos. One JSON, frame-exact.

npx skills add hopechen067/MapStage --skill mapstage -g

安全区 0.06 / 0.22 / 0.94 / 0.78

示例 · story.json河西走廊 · 武威 → 敦煌

seek(0.00) 安全区

14期长征系列 1部四渡赤水 3次平台审核整改 1份 JSON 驱动整段镜头

三层结构

底图、叙事、舞台，各管一件事

底图只管「长什么样」，叙事只管「讲什么」，舞台只管「第几秒画什么」。三层各自一份规范，可以单独调，也可以单独换。

01 · Look

底图 Preset

五套古卷皮肤、真实地形、可选卫星与水系、区域拆出。调参台里调好，导出 v3 preset JSON。

{
  "version": 3,
  "skin": "parchment",
  "terrain": { "exaggeration": 1.0 },
  "camera": { "center": [104, 35.5], "zoom": 4.2 }
}

02 · Story

叙事 Story

地点、路线、阵营、地名状态、镜头、字卡。长征十四期里反复手写的东西，收成一份声明式规范。

{
  "routes": [{ "id": "march", "side": "red",
    "via": ["武威", "张掖", "酒泉", "敦煌"],
    "draw": [2, 14] }],
  "shots": [{ "t": 0, "fit": ["武威", "敦煌"] }]
}

03 · Stage

舞台 Stage

给宿主一个 seek(t)：HyperFrames、Remotion、Playwright 截帧都按同一个时间契约逐帧取画面。

const stage = await MapStage.mount(el, { preset, story });
await stage.seek(12.5); // 地图 idle 后才 resolve

一句话出片

对 agent 说一句话，剩下的交给 skill

安装后用 /mapstage 调起。skill 会按规范生成数据、起本地预览、出低清样片，等你确认再出终版。

描述镜头
「做一个河西走廊从武威到敦煌的路线移动」
生成 story
查坐标、定阵营色、按口播反算机位，写出 story.json。
低清预览
960×540@10 先看节奏与构图，合规检查自动跑。
逐帧终版
确认后 1080p 逐帧截取，断点续拍，局部重拍。

安装 MapStage skill：https://github.com/hopechen067/MapStage
然后用 /mapstage 做一段河西走廊从武威到敦煌的路线移动，完成后启动本地预览。

内置规则

踩过的坑，写成默认值

这些规则来自长征系列与四渡赤水的制作记录和审核整改。默认开启，想关要显式声明。

合规底图

不画省界和国界，不加雾化和暗角；出全图时台湾、海南、海岸线完整显示。

来源：长征 ep03 / ep14 审核整改

一句一动

一句口播最多一次有目的的镜头移动，到位后停稳，只做 6–7% 缓推和 3° 俯仰。

来源：长征 ep02 r8（机位 59 → 38）

自动取景

给一组地点，按安全区反算最小视距；全线总览单独放宽上限，路线不再出画。

来源：cz_render camfit · ep12

地名不消失

地名与城池一旦出现就留在画面上，只在普通、激活、变暗三态之间切换。

来源：四渡赤水 AGENTS

阵营与主次

红军红、敌方灰蓝，箭头与牌子同色；同屏最多 1 条主线、2 个部队名牌。

来源：长征 ep06 · 四渡赤水分级表

逐帧确定

录制路径只用 jumpTo + 等 idle，不用 easeTo / flyTo；同一时间点永远同一画面。

来源：tuner hard rules · shoot_v4

读完整的长征系列地图经验 →

示例

每个能力一个可运行的页面

像 MapLibre 的示例库一样：左边看效果，下面看源码，复制就能用。

全部示例 →

宿主

一个时间契约，三种渲染宿主

地图页面暴露 window.__mapstageSeek(t)，宿主按帧调用、等 idle 后截图。调参台只负责调参，从不做终版渲染。

HyperFrames

页面声明 data-composition-id 与时长，HyperFrames 逐帧驱动。

await window.__mapstageSeek(frame / fps);

Remotion

共享一个地图组件，delayRender 等 seek 完成再放行。

const h = delayRender();
stage.seek(frame / fps).then(() => continueRender(h));

Playwright 截帧

分层截图、断点续拍、局部重拍；GPU 光栅化关掉防旧瓦片。

await page.evaluate(t => window.__mapstageSeek(t), t);
await page.screenshot({ path });

作品

用 MapStage 做的镜头

长征系列第 14 期《西路军》的地图段：古卷底图 + 真实地形 + 路线箭头 + 分级城池，预缓存后 jumpTo 逐帧录制。画面里没有省界、国界，这是现在的默认规则。

开始做第一段地图镜头

装好 skill，跟着快速上手做一段路线行进；或者直接打开调参台调一套自己的底图。

五分钟上手看路线图

gh skill install hopechen067/MapStage mapstage --scope user

让地图成为历史视频的舞台