hopechen067/MapStage

MapStage 是做什么的？

在构建或调谐 MapStage 场景时使用此技能：地图/地球投影、卫星影像、分层设色、Mapterhorn 地形、区域隔离、CSS 颜色分级及 JSON 导出。

使用时机

• 需要实时 MapStage 调谐器（地图 vs 地球，卫星 vs 分层设色，区域隔离）。
• 需要锁定颜色 / CSS / 相机，然后将 JSON 导出到其他宿主。
• 需要分层的居民点（capital / large / medium / small / pass / station / ordos）。

不要将调谐器页面作为最终渲染宿主。

模式

模式	用途
生产栈	在应用中嵌入 MapStage：可选卫星/栅格 + Mapterhorn DEM（encoding: 'terrarium'）+ 山体阴影 + OpenFreeMap 矢量水系 + CSS 滤镜 + 城市拉伸。从导出的 JSON 驱动外观。
调谐器	tuner/ 目录下的本地 HTTP 页面，提供滑块、投影、区域隔离、预设加载/导出功能。

工作流程

1. 启动调谐器：cd tuner && python -m http.server 8765 → http://localhost:8765/
2. 瓦片：默认使用 EOX Sentinel-2 无云影像 + Mapterhorn（tuner/map-tiles.config.js）。可通过 .gitignore 中的 map-tiles.config.local.js 覆盖。
3. 应用默认预设 tuner/preset-antique-default.json（与 tuner/presets/antique-default.json 相同）。
4. 调整投影 / 卫星 / 分层设色 / 区域隔离 / CSS / 城市，直到外观锁定。
5. 从调谐器 导出 JSON（复制或下载）。
6. 将颜色、相机及 CSS 字段迁移到生产 MapStage 场景（参见参考文档）。
7. 在生产中：使用 jumpTo 控制相机；等待 idle 事件；可选地预缓存瓦片。对于记录帧，避免使用 easeTo / flyTo。
8. 始终使用 encoding: 'terrarium' 设置 DEM。错误的编码会破坏山体阴影/地形。
9. 最终帧从生产宿主渲染——而不是从调谐器 UI 渲染。

硬性规则

• 瓦片不捆绑——MapStage 仅在运行时从已配置的 URL 获取 DEM 和底图。
• 仅使用您有权使用的底图端点——默认是公开演示瓦片（EOX）；需要时通过配置切换。
• encoding: 'terrarium' 在地形源上使用——必须设置。
• 记录的生产路径中不要使用 easeTo / flyTo；优先使用 jumpTo + idle。
• 不要在调谐器上托管最终渲染。
• 水系是内置的 OpenFreeMap / OpenMapTiles 矢量图层。不要期待或提交 tuner/assets/water-data.js。

参考文档

• references/参数列表说明.md —— 参数表及默认值
• references/tested-config.md —— 数据源、图层顺序、jumpTo + idle
• references/tuner-workflow.md —— HTTP 调谐器 → 导出 → 生产
• references/city-tier-schema.md —— 居民点层级
• schemas/map-preset.schema.json
• schemas/sample-sites.schema.json
• tuner/ —— 实时页面、验证脚本、默认预设、示例站点

Agent 配置

参见 agents/openai.yaml 获取显示名称/默认提示词。