@maptec/cli 1.0.0

package/skills/jsapi-skills/references/map-style.md

@@ -0,0 +1,123 @@
+# 样式切换参考
+
+当用户要求白天/黑夜地图、暗色地图、亮色地图、增加按钮切换模式时，使用本参考。
+
+## 能力范围
+
+- 初始化时通过 `style` 加载地图样式。
+- 运行时通过 `map.setStyle(styleID)` 切换地图样式。
+- 增加自定义按钮、开关或业务 UI 触发样式切换。
+- 切换前保存地图中心点、缩放、旋转、倾斜等视图状态，切换后恢复。
+
+## 样式配置
+
+不要伪造真实 `style_id`。如果项目已有样式常量，优先复用项目常量；如果没有，生成代码时使用清晰的占位常量。
+
+```js
+const MAP_STYLES = {
+  day: "YOUR_DAY_STYLE_ID",
+  night: "YOUR_NIGHT_STYLE_ID"
+};
+```
+
+初始化黑夜地图：
+
+```js
+Maptec.apiKey = "YOUR_MAPTEC_KEY";
+
+const map = new Maptec.Map({
+  container: "map",
+  style: MAP_STYLES.night,
+  center: [103.8198, 1.3521],
+  zoom: 12,
+  bearing: 0,
+  pitch: 0
+});
+```
+
+## 运行时切换
+
+`maptec-js` 的 `Map` 类公开了 `setStyle(styleID)`。切换前保存视角，切换后使用 `jumpTo` 恢复。
+
+```js
+function switchMapStyle(map, styleID) {
+  const viewState = {
+    center: map.center,
+    zoom: map.zoom,
+    bearing: map.bearing,
+    pitch: map.pitch
+  };
+
+  map.setStyle(styleID);
+  map.once("style.load", () => {
+    map.jumpTo(viewState);
+  });
+}
+```
+
+如果项目里样式加载完成事件名称不同，可在项目适配层里包装，但不要把不存在的 SDK 方法写进对外文档。
+
+## 按钮切换模板
+
+```js
+let currentStyle = "day";
+
+const button = document.createElement("button");
+button.type = "button";
+button.textContent = "切换昼夜";
+button.className = "map-style-toggle";
+
+button.addEventListener("click", () => {
+  currentStyle = currentStyle === "day" ? "night" : "day";
+  switchMapStyle(map, MAP_STYLES[currentStyle]);
+});
+
+document.body.appendChild(button);
+```
+
+## 与覆盖物配合
+
+切换底图样式可能导致样式资源重载。生成代码时要注意：
+
+- 业务覆盖物如在样式切换后丢失，应在样式加载完成后重新添加。
+- 自定义图片图标可能需要重新 `map.addImage`。
+- 切换前保存业务覆盖物数组，必要时统一恢复。
+
+```js
+const overlays = [];
+
+function addBusinessOverlay(overlay) {
+  map.addOverlay(overlay);
+  overlays.push(overlay);
+}
+
+function restoreOverlays() {
+  overlays.forEach((overlay) => {
+    if (!map.getOverlayById?.(overlay.id)) {
+      map.addOverlay(overlay);
+    }
+  });
+}
+```
+
+## 常见意图映射
+
+| 用户说法 | 实现方式 |
+|---|---|
+| “将地图切换为黑夜模式” | 使用黑夜样式初始化或调用 `map.setStyle(nightStyleID)` |
+| “增加一个按钮切换白天和黑夜地图” | 创建业务按钮，维护 `day/night` 状态，调用 `switchMapStyle` |
+| “默认白天，晚上自动黑夜” | 根据时间或业务状态选择 `MAP_STYLES.day/night` |
+
+## 注意事项
+
+- 不要把覆盖物颜色变化当作底图样式切换。
+- 不要硬编码未知 `style_id`。
+- 不要为了切换样式丢失用户当前视角。
+- 切换底图样式后关注自定义图标、业务图层和覆盖物是否需要恢复。
+
+## Agent 规则
+
+- 初始化样式通过 `style` 参数设置；运行时样式切换使用 `map.setStyle(styleID)`。
+- 切换样式前应保存中心点、缩放、旋转和倾斜等视角状态，切换后恢复。
+- 白天/黑夜样式 ID 或样式地址必须来自已确认配置，不要编造真实 `style_id`。
+- 若项目有统一样式常量或封装，优先使用项目已有命名。

package/skills/jsapi-skills/references/map.md

@@ -0,0 +1,154 @@
+# 地图加载能力参考
+
+当用户要求创建地图实例、初始化加载地图、生成某个城市或国家的地图时，使用本参考。本文件只覆盖功能 **地图加载**。
+
+## 能力入口
+
+| 用户需求 | 优先实现 |
+|---|---|
+| “生成一个新加坡的地图” | 创建 `new Maptec.Map(...)`，设置容器、样式、中心点和缩放级别 |
+| “初始化地图” | 设置 `Maptec.apiKey`，创建地图实例，监听 `load` |
+| “打开某个地点的地图” | 明确中心点坐标；若只有地名，先使用地理编码能力 |
+
+## 初始化地图
+
+```js
+Maptec.apiKey = "YOUR_MAPTEC_KEY";
+
+const map = new Maptec.Map({
+  container: "map",
+  style: "YOUR_STYLE_URL",
+  center: [103.8198, 1.3521],
+  zoom: 11.5,
+  bearing: 0,
+  pitch: 0
+});
+
+map.on("load", () => {
+  console.log("地图加载完成");
+});
+```
+
+## MapOptions 常用字段
+
+- `Maptec.apiKey`: 全局 API Key，必须在创建 `new Maptec.Map(...)` 前设置。
+- `Maptec.workerCount` / `Maptec.workerUrl`: WebWorker 配置，如需调整也应在创建地图前设置。
+- `container`: `HTMLElement | string`，地图容器。
+- `style`: 地图样式地址或项目已确认的样式配置。
+- `center`: 地图中心点，坐标顺序必须是 `[lng, lat]`。
+- `zoom`: 地图缩放级别。
+- `bearing`: 地图旋转角度。
+- `pitch`: 地图倾斜角度。
+- `minZoom` / `maxZoom`: 缩放范围。
+- `minPitch` / `maxPitch`: 倾斜范围。
+- `maxBounds`: 限制地图平移范围。
+- `logoPosition` / `attributionPosition`: 内置标识和版权信息位置。
+
+## 坐标规则
+
+Maptec JSAPI 地理坐标统一使用 `[lng, lat]`，不要使用 `[lat, lng]`。
+
+```js
+const singapore = [103.8198, 1.3521];
+```
+
+常见坐标类型：
+
+- `LngLatLike`: `Maptec.LngLat`、`[number, number]`、`{ longitude, latitude }`。
+- `LngLatObject`: `{ longitude: number, latitude: number }`，常见于服务返回结果。
+- `LngLatBoundsLike`: `[southWest, northEast]` 或 `[west, south, east, north]`。
+- `PointLike`: 像素坐标，常用于 `panBy`、Marker 偏移、Popup 偏移。
+
+```js
+function toLngLat(input) {
+  if (Array.isArray(input) && input.length >= 2) {
+    return [Number(input[0]), Number(input[1])];
+  }
+  if (input && typeof input === "object") {
+    const lng = input.longitude ?? input.lng ?? input.lon;
+    const lat = input.latitude ?? input.lat;
+    if (lng != null && lat != null) return [Number(lng), Number(lat)];
+  }
+  return null;
+}
+```
+
+## 加载生命周期
+
+常用方法和事件：
+
+- `map.on("load", handler)`：地图样式和资源加载完成。
+- `map.once("load", handler)`：只监听一次加载完成。
+- `map.on("error", handler)`：监听地图错误。
+- `map.loaded()`：检查地图资源是否已加载。
+- `map.destroy()` 或 `map.remove()`：运行时支持时销毁地图。
+
+```js
+const onLoad = () => {
+  // 添加控件、Marker、矢量覆盖物、信息窗口、路线或检索结果。
+};
+
+const onError = (error) => {
+  console.error("地图加载错误", error);
+};
+
+map.on("load", onLoad);
+map.on("error", onError);
+```
+
+## 常用区域默认中心和缩放
+
+当用户提到以下地区时，使用对应的默认中心点和缩放级别初始化地图。数据加载完成后通过 `fitBounds` 适配实际视口。
+
+| 地区 | `center` | `zoom` |
+|---|---|---|
+| 新加坡 / Singapore | `[103.8198, 1.3521]` | `11.5` |
+| 泰国 / Thailand | `[100.5018, 13.7563]` | `6` |
+| 马来西亚 / Malaysia | `[101.6869, 3.1390]` | `6` |
+| 日本 / Japan | `[138.2529, 36.2048]` | `5.5` |
+| 韩国 / South Korea | `[127.9780, 36.5712]` | `7` |
+| 印度尼西亚 / Indonesia | `[106.8650, -6.1754]` | `5.5` |
+| 越南 / Vietnam | `[108.2772, 14.0583]` | `5.5` |
+| 中国 / China | `[108.9402, 34.3416]` | `4.5` |
+| 美国 / United States | `[-98.5795, 39.8283]` | `4` |
+| 英国 / United Kingdom | `[-3.4360, 55.3781]` | `5.5` |
+| 沙特阿拉伯 / Saudi Arabia | `[46.6753, 24.7136]` | `5.5` |
+| 巴西 / Brazil | `[-47.8822, -15.7939]` | `4.5` |
+| 墨西哥 / Mexico | `[-99.1332, 19.4326]` | `5.5` |
+
+> **重要**：不要使用 `center: [0, 0]` 或 `center: [0.0, 0.0]`（大西洋"空岛"）。必须根据用户提及的地区设置合理的默认中心。
+
+## 根据地名加载地图
+
+如果用户只给出地名，不能凭空编造精确坐标。可使用产品默认坐标，或先调用地理编码能力。
+
+```js
+geocode.getLocation("Singapore", { region: "SG" }, (error, result) => {
+  if (error) {
+    console.error("地理编码失败", error);
+    return;
+  }
+
+  const location = result?.results?.[0]?.geometry?.location;
+  if (!location) return;
+
+  const center = [location.longitude, location.latitude];
+  map.flyTo({ center, zoom: 11.5 });
+});
+```
+
+## 注意事项
+
+- 坐标顺序始终使用 `[lng, lat]`。
+- 设置 `Maptec.apiKey` 后再创建地图实例。
+- 不要在应用代码中依赖 SDK 内部工具类型。
+- 不要在地图实例创建前调用地图方法。
+- 依赖地图资源的控件、Marker、矢量覆盖物、信息窗口、路线结果应在 `load` 后添加。
+- 不要硬编码未知或未确认的 `style_id`。
+
+## Agent 规则
+
+- 生成地图加载代码时，必须先确认容器、样式、中心点和缩放级别。
+- 如果用户只提供地名，不要编造精确坐标；应使用地理编码能力或明确使用产品默认中心点。
+- 地图相关控件、覆盖物、路线、检索结果和动画对象应在 `load` 后添加。
+- 必须说明地图实例销毁方式，优先使用当前 SDK 支持的 `map.destroy()` 或 `map.remove()`。

package/skills/jsapi-skills/references/marker.md

@@ -0,0 +1,136 @@
+# Marker 能力参考
+
+当用户要求添加 Marker、点击地图增加点标记、拖拽点标记、设置 Marker 样式或绑定 Marker 事件时，使用本参考。
+
+## 能力范围
+
+- 创建 `Maptec.Marker`。
+- 设置 Marker 位置、颜色、缩放、透明度、旋转、拖拽、偏移和锚点。
+- 使用自定义 HTMLElement 作为 Marker 外观。
+- 绑定 Marker 点击、拖拽等事件。
+- 与 `Maptec.Popup` 组合，但信息窗口细节优先读取 `popup.md`。
+
+## 基础 Marker
+
+```js
+const marker = new Maptec.Marker({
+  position: [103.8198, 1.3521]
+});
+
+map.addOverlay(marker);
+```
+
+## 点击地图增加 Marker
+
+```js
+const markers = [];
+
+const onMapClick = (event) => {
+  const position = Maptec.LngLat.convert(event.lngLat).toArray();
+  const marker = new Maptec.Marker({
+    position,
+    color: "#2563eb",
+    scale: 1
+  });
+
+  map.addOverlay(marker);
+  markers.push(marker);
+};
+
+map.on("click", onMapClick);
+
+function cleanup() {
+  map.off("click", onMapClick);
+  markers.forEach((marker) => {
+    map.removeOverlay(marker);
+    marker.destroy?.();
+  });
+}
+```
+
+## 样式和属性
+
+已确认的常用配置：
+
+- `position`: `LngLatLike`
+- `anchor`: `"center"`、`"top"`、`"bottom"`、`"left"`、`"right"`、`"top-left"`、`"top-right"`、`"bottom-left"`、`"bottom-right"`
+- `color`: 默认 Marker 颜色
+- `scale`: 缩放比例
+- `draggable`: 是否可拖拽
+- `element`: 自定义 HTMLElement
+- `offset`: 像素偏移，接受 `PointLike`
+- `opacity`: 透明度
+- `rotation`: 旋转角度
+- `popup`: 绑定的 `Maptec.Popup`
+
+Marker 支持的辅助方法：
+
+- `addClassName(className)`
+- `removeClassName(className)`
+- `togglePopup()`
+- `destroy()`
+- `isDestroyed()`
+
+```js
+marker.position = [103.7764, 1.2966];
+marker.draggable = true;
+marker.opacity = 0.85;
+marker.rotation = 45;
+marker.offset = [0, -10];
+```
+
+## 事件绑定
+
+```js
+const onMarkerClick = () => {
+  marker.togglePopup?.();
+};
+
+const onDragEnd = () => {
+  console.log("Marker 新位置", marker.position);
+};
+
+marker.on("click", onMarkerClick);
+marker.on("dragend", onDragEnd);
+
+function cleanupMarkerEvents() {
+  marker.off("click", onMarkerClick);
+  marker.off("dragend", onDragEnd);
+}
+```
+
+## 数据绑定
+
+业务数据建议单独保存，不要只依赖 DOM 属性。
+
+```js
+const markerRecords = places.map((place) => {
+  const marker = new Maptec.Marker({
+    position: [place.longitude, place.latitude],
+    color: "#16a34a"
+  });
+
+  map.addOverlay(marker);
+
+  return {
+    id: place.id,
+    data: place,
+    marker
+  };
+});
+```
+
+## 注意事项
+
+- Marker 坐标始终使用 `[lng, lat]`。
+- 不要用 DOM 绝对定位伪造地图 Marker。
+- 大量点位优先考虑 `GeoJSONOverlay`，不要无上限创建 Marker。
+- Marker 绑定 Popup 时优先设置 Popup `offset`，避免遮挡 Marker。
+- 组件卸载时移除 Marker，并取消事件监听。
+
+## Agent 规则
+
+- Marker 必须通过 `new Maptec.Marker(...)` 创建，并通过 `map.addOverlay(marker)` 添加到地图。
+- 点击地图添加 Marker 时，必须从 `event.lngLat` 获取坐标，不要使用屏幕像素点作为地理坐标。
+- 大量点位或需要聚合时，优先使用 `GeoJSONOverlay`，不要生成无限 Marker。
+- 绑定 Marker 事件时必须提供解绑逻辑，清理时移除 Marker 并取消事件监听。

package/skills/jsapi-skills/references/operate.md

@@ -0,0 +1,138 @@
+# 地图交互能力参考
+
+当用户要求控制地图拖拽、缩放、旋转、倾斜、手势控制、交互开关或视角约束时，使用本参考。本文件只覆盖功能 **地图交互**。
+
+## 能力入口
+
+| 用户需求 | 优先实现 |
+|---|---|
+| “禁止用户旋转或拖拽地图” | 设置 `dragRotate: false`、`dragPan: false` |
+| “禁止滚轮缩放” | 设置 `scrollZoom: false` |
+| “限制地图缩放范围” | 设置 `minZoom`、`maxZoom` |
+| “限制地图倾斜” | 设置 `minPitch`、`maxPitch` |
+| “限制地图拖动范围” | 设置 `maxBounds` |
+| “运行时开关交互” | 更新 `map.interactive` |
+
+## 初始化时配置交互
+
+```js
+const map = new Maptec.Map({
+  container: "map",
+  style: "YOUR_STYLE_URL",
+  center: [103.8198, 1.3521],
+  zoom: 12,
+  dragPan: false,
+  dragRotate: false,
+  scrollZoom: true,
+  doubleClickZoom: true,
+  keyboard: true,
+  boxZoom: true
+});
+```
+
+已确认的常用交互字段：
+
+- `boxZoom`
+- `doubleClickZoom`
+- `dragPan`
+- `dragRotate`
+- `keyboard`
+- `scrollZoom`
+- `cooperativeGestures`
+
+`cooperativeGestures` 通常用于协作手势：桌面端缩放需要 Cmd/Ctrl，移动端需要双指操作。具体表现以 SDK 运行时为准。
+
+## 运行时开关交互
+
+使用 `map.interactive` 更新运行时交互配置。
+
+```js
+map.interactive = {
+  ...map.interactive,
+  dragPan: false,
+  dragRotate: false,
+  scrollZoom: true,
+  doubleClickZoom: true,
+  keyboard: true,
+  boxZoom: true
+};
+```
+
+## 视角约束
+
+```js
+map.minZoom = 8;
+map.maxZoom = 18;
+map.minPitch = 0;
+map.maxPitch = 60;
+
+map.maxBounds = [
+  [103.6, 1.18],
+  [104.05, 1.48]
+];
+```
+
+清除平移范围：
+
+```js
+map.maxBounds = null;
+```
+
+## 视角控制
+
+地图交互需求经常伴随主动移动视角，可使用相机方法：
+
+- `jumpTo(options)`：立即切换视角。
+- `easeTo(options)`：平滑过渡。
+- `flyTo(options)`：飞行动画。
+- `panTo(lngLatLike)`、`panBy(pointLike)`。
+- `zoomIn()`、`zoomOut()`、`zoomTo(zoom)`。
+- `rotateTo(bearing)`。
+- `fitBounds(boundsLike, options?)`。
+
+常见相机参数：
+
+- `center?: LngLatLike`
+- `zoom?: number`
+- `bearing?: number`
+- `pitch?: number`
+- `padding?: number | { top; right; bottom; left }`
+- `duration?: number`
+- `maxZoom?: number`，常用于 `fitBounds`
+
+```js
+map.flyTo({
+  center: [103.7764, 1.2966],
+  zoom: 15,
+  bearing: 0,
+  pitch: 0,
+  duration: 1000
+});
+```
+
+## 交互事件
+
+如果需求是监听用户交互，而不是开关交互能力，应读取 `events.md`。
+
+常见事件：
+
+- `dragstart`、`drag`、`dragend`
+- `zoomstart`、`zoom`、`zoomend`
+- `rotatestart`、`rotate`、`rotateend`
+- `pitchstart`、`pitch`、`pitchend`
+- `movestart`、`move`、`moveend`
+
+## 注意事项
+
+- 不要使用未在当前 Maptec 文档确认的交互字段。
+- 禁止旋转通常需要关闭 `dragRotate`；如果触控旋转有单独字段，必须以 SDK 文档为准，不能编造。
+- `maxBounds` 使用 `[southWest, northEast]`，每个点仍是 `[lng, lat]`。
+- `PointLike` 是像素坐标，不是地理坐标；只用于偏移、`panBy` 等屏幕空间操作。
+- 运行时更新交互时保留不需要改变的旧配置。
+
+## Agent 规则
+
+- 交互开关只能使用已确认字段，例如 `dragPan`、`dragRotate`、`scrollZoom`、`doubleClickZoom`、`keyboard`、`boxZoom`。
+- 用户要求禁止旋转或拖拽时，优先更新对应交互字段，不要用覆盖透明层阻止操作。
+- 运行时修改交互配置时，应保留 `map.interactive` 中未修改的原有字段。
+- 涉及触控手势或协作手势时，如 SDK 能力不明确，必须标记为 `需确认 Maptec 是否支持`。