船讯网 JSAPI 地图任务调度

要解决的具体问题

船讯网 JSAPI 的文档体量不小，但真正写代码时麻烦的不是文档太多，而是不知道当前任务该看哪一段。一个「在地图上显示区域船舶并支持轨迹回放」的需求，可能同时涉及地图初始化、鉴权、船舶服务、轨迹管理和清理逻辑。如果不分场景就通读全部参考，既浪费时间，也容易把 Demo 的页面结构、按钮交互复制进业务代码。

另一个高频问题是边界不清：公开入口只定义了一组明确的类、方法和配置项，而内部实现、名称含 Impl 的类、未列入公开方法的函数都不应触碰。坐标顺序也容易踩坑——ShipxyAPI.latLng(lat, lng) 和 Leaflet 坐标数组是 [纬度, 经度]，GeoJSON 的 coordinates 却是 [经度, 纬度]。

技能如何工作

它定位为任务调度器，而不是完整 API 手册。工作方式是先判断任务类型，再选一个最接近的 Recipe，最后按 Recipe 指向读取必要的 Reference。

标准流程大致是：

1. 确认是新建、修改、排错、代码审查还是 API 查询。
2. 检查前端框架、JSAPI 加载方式、运行页面和部署来源。
3. 从场景路由中选择最接近的 Recipe，提取业务流程。
4. 从知识路由读取对应 Reference，核对签名、配置、单位和生命周期。
5. 只生成业务所需的 JavaScript，不复制 Demo 的 HTML、CSS 或事件代码。
6. 完成后检查鉴权、坐标、时间单位、事件解绑和资源清理。

比如要做区域船舶展示，就走「展示区域船舶」Recipe；要做历史轨迹回放，就选「轨迹回放」。组合需求再叠加必要 Recipe，而不是一次性加载全部文档。

适用边界与注意点

• 授权 Key 必须通过地图配置的 ak 传入，并绑定当前页面实际部署的域名或 IP。
• 只使用 HTTPS JSAPI 包和 HTTPS 服务地址；status: 14 优先排查域名绑定关系。
• 示例、日志和截图中不得保留真实 Key，用占位符替换。
• 不实例化名称含 Impl 的类，不调用未列入公开方法的内部函数。
• 保留官方字段拼写，包括历史兼容拼写，不擅自「纠正」。
• 时间戳、速度等单位以目标 Reference 为准，不确定是否公开的成员视为不可用。
• 若文档未证明某能力公开可用，会明确说明边界，不根据内部源码猜测。