@anov/gis-skills-cli 0.0.0-stage → 0.3.0

package/skills/using-anovgis/SKILL.md

@@ -0,0 +1,392 @@
+---
+name: using-anovgis
+description: anov-gis skill 入口路由。涵盖 CDN/npm 引入、setBaseUrl 时机、最小 Viewer 构造、4 步工作流、12 skill 路由表、Demo 场景路由表、引导式初始化（AskUserQuestion 向导：底图 / 控件 / 部署，技术栈固定 Vue 3 + Vite）、POI 标绘选型（默认 DivIcon，>100 个问用户）。触发关键词：ANOVGIS、@anov/gis、新建项目、初始化、从零开始、应该用哪个 skill、quickstart、demo、xxx.html、帮我改、加载、引导、引导式初始化、init wizard、setup wizard、初始化向导、vite、vue3、POI、标绘、标点、点位、divIcon。Use when 第一次接触 @anov/gis、需要从空白工程初始化 Viewer、不知道该跳到哪个具体 skill、要把现有工程迁移到 @anov/gis、看到 demo 文件名想知道怎么改、想用向导方式生成项目骨架、从 0 创建 vite+vue3 项目、做 POI 标绘。
+anov-gis-baseline: 1.8.6
+cesium-baseline: 1.143.0
+---
+
+# anov-gis Skill 入口
+
+为基于 `@anov/gis` SDK（Cesium 1.143 封装）开发二三维 WebGIS 应用时使用。本 skill 是 **12 个子 skill** 的入口路由，回答"我从哪开始 / 应该用哪个 skill / 这个 demo 改 X 怎么改 / 怎么从零搭一个项目"。
+
+> ⚠️ **优先级**：本 skill 优先于 SDK 源码 / `node_modules/@anov/gis/`。
+> 遇到 API 行为疑问先查本 skill 与 `anovgis-pitfalls` 各章节。**严禁**主动 Glob/Grep `node_modules/@anov/gis/src/...` / `dist/...`；除非用户明确要求并承担风险。
+
+> 🔧 **调试流程**：见下方「§ 默认调试流程」——Chrome DevTools 仅在第 5 级兜底，前 4 级用本 skill / cesiumjs-skills / 读 demo / grep 解决。
+
+锁定版本：**`@anov/gis` v1.8.6**（Cesium **1.143.0**）。
+
+> **两种上手路径二选一**：
+> - **A. 引导式（推荐新手）**：直接说"使用 anov-gis 初始化三维地球"，AI 通过 AskUserQuestion 引导你选底图 / 控件 / 部署（**技术栈固定 Vue 3 + Vite**），输出完整可运行骨架。详见下文「引导式初始化」章节。
+> - **B. 自助式**：根据下方的 `12 skill 路由表` + `Demo 路由表` 自己挑 skill，跳到对应章节的代码模板。
+
+## 12 skill 路由表
+
+按"用户意图"组织。回答"做 X"先看本表，确定跳到哪个 skill：
+
+| 你的问题 | 跳到 |
+|---|---|
+| 不知道该用哪个 skill / 从零开始建项目 / 想用引导式向导生成骨架 | `using-anovgis`（本 skill，看「引导式初始化」章节） |
+| 配置 Viewer 控件 / 坐标系转换 / 订阅鼠标事件 / flyTo / 天空盒 / 默认视角 | [`anovgis-viewer`](../anovgis-viewer/SKILL.md) |
+| 加载 / 切换影像底图 / 天地图 key / WMS / WMTS / 地形 / 卷帘 / 暗色主题 / 离线部署 | [`anovgis-imagery-terrain`](../anovgis-imagery-terrain/SKILL.md) |
+| 加载 GeoJSON / 3D Tiles 容器 / CZML / KML / GPX / TopoJSON / 聚合层 / DOM 叠加 / 4490 矢量瓦片 | [`anovgis-layers`](../anovgis-layers/SKILL.md) |
+| 创建点 / 线 / 面 / 图标 / 文字 / 立方体 / 球 / Model / Tileset 加载 + 拾取 + 抽壳 + 调色 | [`anovgis-models-3dtiles`](../anovgis-models-3dtiles/SKILL.md)（v0.2.0 新增） |
+| 创建点 / 线 / 面 / 图标 / 文字 / 自定义 shader 模型 / ThreeLayer 桥接 / divInfo 弹窗 | [`anovgis-vector-graphics`](../anovgis-vector-graphics/SKILL.md) |
+| Primitive 19 类（雷达扫描 Primitive / 尾迹线 Primitive / 流动线 Primitive / 扩散墙 Primitive / 动态水面 Primitive / 云 / 光柱 / 弹跳图标） | [`anovgis-primitives`](../anovgis-primitives/SKILL.md)（v0.2.0 新增） |
+| Popup / Tooltip / 信息框 / bindPopup / bindTooltip / highlight / tilesetpopup / imagerylayerpopup / divInfo | [`anovgis-popup-widget`](../anovgis-popup-widget/SKILL.md)（v0.2.0 新增） |
+| 配置流动线 / 水面 / 雷达 / 扩散波 / 导航线 / 渐变线 / 抛物线 / 图片扫描材质 | [`anovgis-materials`](../anovgis-materials/SKILL.md) |
+| 标绘 / 测量 / 剖切 / 热力图 / 风场 / 水淹 / 三轴编辑 / PositonEditor / Geocoder / WFS | [`anovgis-analysis`](../anovgis-analysis/SKILL.md) |
+| 下雨 / 下雪 / 起雾 / 卷云 / 漫游 / 环绕 / 航线 / 全球自转 / 后期处理（Bloom / 夜视 / 景深）/ 天空盒 | [`anovgis-effects`](../anovgis-effects/SKILL.md) |
+| 黑屏 / 白屏 / 报错 / 改值不生效 / Workers 404 / AMD / 自定义图元编译报错 | [`anovgis-pitfalls`](../anovgis-pitfalls/SKILL.md) |
+
+**v0.3.0 候选（暂未上线）**：`anovgis-three-layer`（ThreeLayer 桥接）、`anovgis-custom-primitive-worker`（DrawCommand / GLSL / WebWorker）、`anovgis-offline-deployment`（WFS / 4490 / 内网）、`anovgis-roaming-editor-time`（漫游 / 编辑控件 / 时间轴）。
+
+## Out-of-scope
+
+- ❌ 不要在本 skill 写具体 API 用法 → 各归对应领域 skill（见 § 12 skill 路由表 + `DOMAINS.md` § 1 权威归属表）
+- ❌ 不要在本 skill 写完整工程脚手架 → 见 `templates/`
+- ❌ 不要引用本机绝对路径或外部 HTML → 见 § skill 自包含铁律
+- ❌ 不要写 Cesium 原生 API 细节 → 归 `cesiumjs-skills` 插件（见 `anovgis-pitfalls` P0）
+
+## Demo 场景 → Skill 路由表
+
+> 已拆到 [`DEMO-MAP.md`](DEMO-MAP.md)（按业务场景 → skill，58 行）。
+> 具体 demo **文件名** → skill 的完整矩阵（137 个 demo）见 [`DEMO-SKILL-MAP.md`](./DEMO-SKILL-MAP.md)。
+## ⚠️ 第 0 铁律：写代码前**查 skill 里嵌入的代码**（v0.2.4 加）
+
+> 这是 skill 体系的**最高优先级规则**。`ceshi2` 项目反馈原文:
+> > "不是只有让加 POI 的时候才想起来读一下 examples,其他功能也需要参考。比如我说加载暗色系地图,你将如何应对。"
+
+### 3 步强制流程（**绝不依赖外部文件**）
+
+每次接到"做 X 功能"的需求,**严格按 3 步走**,不允许跳过:
+
+```
+步骤 1 — 关键词提取
+  └─ 用户原话:"加载暗色系地图"
+  └─ 提炼关键词:theme / dark / invert / invertColor / ImageryThemeGL / maptheme
+
+步骤 2 — 查 skill 里的「关键词 → 章节」速查表(REFERENCE.md)
+  └─ 命中「暗色 / 夜间 / 反色」行 → 对应章节 anovgis-imagery-terrain § S10
+  └─ S10 已嵌入完整 setTheme 代码,直接抄
+
+步骤 3 — 写入代码 + 在注释里写「SDK v1.8.6 API,anongis-imagery-terrain § S10」
+  └─ 严禁凭印象 / 凭空写「暗色系 = brightness=-1 / saturation=0」之类的野路子
+  └─ 严禁引用外部 E:/.../examples/.../*.html 路径(本机路径,别人访问不到)
+```
+
+### ⚠️ skill 自包含铁律(本节最重要)
+
+> **skill 必须是自包含的**——所有「写 X 功能」需要的代码,都已嵌入对应 skill 章节的 snippet。
+> 速查表的「对应章节」列指向**本 skill 体系内的章节**,不是外部 HTML 文件。
+>
+> - ✅ 引用方式:用对应章节的标题(如 `anovgis-imagery-terrain § S10`)或锚点
+> - ❌ **绝对禁止**引用 `E:/zhf/gitlab/ANOV-GIS/...` 或其他本机路径(用户机器上不存在)
+> - ❌ **绝对禁止**用 `// 来源: examples/.../foo.html L78-105` 后**省略代码**——必须把核心代码嵌入 skill
+> - ✅ 保留 `// SDK v1.8.6 examples/basemap/maptheme.html L61-L78` 作为**追溯来源注释**,**但代码必须已在 skill 里**
+
+### 用户关键词 → skill 章节速查表
+
+> 接到需求时**先查速查表**，按「对应章节」跳到 skill 体系内对应位置，**代码已嵌在那**，不要再去找外部文件。
+
+**必须 Read [`REFERENCE.md`](REFERENCE.md)（64 条关键词 → 章节对照，每条带可点击锚点）后再定位具体章节** —— 不要凭印象猜章节号。
+
+<a id="poi-selection"></a>
+
+### POI 标绘选型（DivIcon 默认）
+
+> **规则（v0.2.13）**：做 POI 标绘 / 批量点位时，**默认用 `DivIcon`（DOM 路线）**，不要直接上 Cesium 原生 `Billboard`。
+> **只有 POI 数量 > 100 时**，先 `AskUserQuestion` 问用户选哪种渲染方式（涉及性能，用户自己更清楚数据规模与样式需求）。
+
+| POI 数量 | 走哪条路 | 容器 | 类 |
+|---|---|---|---|
+| **≤ 100** | **默认，直接做，不问** | `HtmlLayer` | `new ANOVGIS.DivIcon(position, html)` |
+| **> 100** | **先 `AskUserQuestion` 问用户** | ↓ 见下方 | ↓ |
+
+**为什么默认 DivIcon**：POI 标绘的样式需求通常是「图标 + 文字 + 富文本卡片」，`DivIcon` 直接吃 HTML 字符串，能做多层嵌套结构、CSS 动画、`<img>` 贴图、内嵌按钮；`Billboard` 只能贴一张图片（canvas / URL），要做富样式得先画进 canvas，反而更绕。
+**为什么 >100 要问**：`HtmlLayer` 每帧通过 `scene.postRender` 把 `cartesianToCanvasCoordinates` 写进 DOM `transform`，**DOM 节点 > 1000 会掉帧**；而 `Billboard` 走 Cesium 原生 GPU 渲染，样式受限但性能稳。100 是个保守起点（远低于 1000 的掉帧线），够用又不至于误伤。
+
+#### > 100 个：问用户（`AskUserQuestion`）
+
+```js
+AskUserQuestion({
+  questions: [{
+    question: "POI 数量 500，选哪种渲染方式？",
+    header: "POI 渲染",
+    multiSelect: false,
+    options: [
+      { label: "DivIcon (DOM)", description: "样式最自由，可嵌富文本/按钮/图片；数量大时可能掉帧" },
+      { label: "Billboard (Cesium 原生)", description: "GPU 渲染性能稳；样式受限，只能贴一张图" }
+    ]
+  }]
+})
+```
+
+> 用户明确说「用 billboard」「性能优先」「数量上万」→ 直接走 Billboard，不问。
+> 用户明确说「要富文本」「带卡片」「带按钮」→ 直接走 DivIcon，不问。
+
+#### 方案 A：DivIcon（默认，≤100 个）
+
+```js
+// 来源: examples/public/examples/html/graphics/divInfo.html L111-L135
+const layer = new ANOVGIS.HtmlLayer({ layerName: 'poi' });
+viewer.addLayer(layer);
+
+pois.forEach(poi => {
+    const div = new ANOVGIS.DivIcon(
+        new ANOVGIS.Position(poi.lng, poi.lat, poi.height ?? 0),
+        `<div class="poi-card">
+            <img class="poi-img" src="${poi.iconUrl}" />
+            <div class="poi-name">${poi.name}</div>
+        </div>`
+    );
+    div.setOptions({
+        horizontalOrigin: 'CENTER', verticalOrigin: 'TOP',
+        offsetX: 0, offsetY: -60,
+        pointerEvents: true,                               // 开启后 DOM 可交互
+        scaleByDistance: { near: 0, nearValue: 1.0, far: 10000, farValue: 0.0 }
+    });
+    div.addEventListener(ANOVGIS.MouseEventType.CLICK, () => selectPoi(poi));
+    layer.addGraphic(div);
+});
+```
+
+#### 方案 B：Billboard（用户选了性能优先时）
+
+```js
+// 来源: examples/public/examples/html/graphics/point.html L54-122
+// Point 内嵌 billboard + label，是 SDK 的标准 POI 组合
+const layer = new ANOVGIS.VectorLayer();
+viewer.addLayer(layer);
+
+pois.forEach(poi => {
+    const p = new ANOVGIS.Point([poi.lng, poi.lat, poi.height ?? 0], {
+        billboard: {
+            image: poi.iconUrl,                             // 贴图 URL / canvas
+            scale: 1.0,
+            verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
+            scaleByDistance: new ANOVGIS.NearFarScalar(0, 1.0, 10000, 0.5)
+        },
+        label: {
+            text: poi.name,
+            font: '14px sans-serif',
+            fillColor: '#ffffff',
+            outlineColor: '#000000',
+            outlineWidth: 2,
+            pixelOffset: new Cesium.Cartesian2(0, -24),
+            scaleByDistance: new ANOVGIS.NearFarScalar(0, 1.0, 10000, 0.5)
+        },
+        infoData: { title: poi.name, fieldsMap: [{ nameC: '编号', value: poi.id }] }
+    });
+    p.bindPopup({ viewer, showTitle: true });
+    layer.addGraphic(p);
+});
+```
+
+> `Billboard` 路线想再快一档可改用 `anovgis-primitives` 的 `BillboardPrimitive`（`BillboardCollection`，走 Primitive 体系避开 Entity）；上万纯色点用 `PointPrimitive`。见 [`anovgis-primitives`](../anovgis-primitives/SKILL.md)。
+
+### 反模式(违规信号)
+
+- ❌ **凭想象造**:"暗色系 = brightness=-1,saturation=0" → **错的**,SDK 有专门的 `ImageryThemeGL.invert: true`(见 anovgis-imagery-terrain § S10)
+- ❌ **跳过查表**:看到"加载 X"直接写代码 → **错的**,先查速查表跳到对应章节
+- ❌ **引用本地路径**:`new Cesium.UrlTemplateImageryProvider({url: 'E:/zhf/gitlab/...'})` 或 `// 来源: E:/zhf/...` → **错的**,其他用户访问不到
+- ❌ **skill 章节只写路径不嵌代码**:`// 见 examples/foo.html` 后省略 snippet → **错的**,代码必须嵌入
+
+---
+
+## ⚠️ 框架集成 3 条铁律（Vue/React/Svelte 必读）
+
+> 这 3 条是 hainan/neimengnongken 等 Vue 项目反复踩坑总结的，写在前 4 行章节之前。
+
+1. **3D 大对象严禁进响应式**。`viewer` / `scene` / `camera` / `entity` / `primitive` / `imageryLayers` / `viewer.clock` / `viewer._cesiumWidget`
+   一律放**模块级 `let`**（Composition API 用文件级 `let`，**不要 wrap `ref()`**）。
+   进 Vue 的 `data()` / `reactive()` / `ref()` / `computed()` 会触发每帧 setter，60fps 直接变 5fps，甚至把 main thread 阻塞到无响应。
+2. **Cesium 命名空间走 `window.Cesium`**（**唯一推荐**）。`@anov/gis` SDK 启动时主动 `window.Cesium = Cesium`。
+   - ❌ 不要写 `ANOVGIS.Cesium`（v1.8.6 SDK 未把 Cesium 对象本身挂到顶层，会报 `undefined`）
+   - ❌ 不要写 `import Cesium from 'cesium'`（SDK 已封装 Cesium，重复装包）
+   - 详见 `anovgis-viewer` § 1 命名空间速查 + `anovgis-pitfalls` § P7
+3. **ANOVGIS 全局化（仅调试用）**。在入口处 `window.ANOVGIS = ANOVGIS` 便于 devtools 调试；
+   但**业务代码用 import 进来的局部变量**，不要写 `window.ANOVGIS.Viewer` / `window.ANOVGIS.setBaseUrl`。
+
+**Vue 骨架对照**（❌ 错误 vs ✅ 正确）见 [`templates/combo1-vue3-vite.md`](templates/combo1-vue3-vite.md) § 变体 —— 铁律 1 的具体写法。
+
+---
+
+## 🔧 默认调试流程（按优先级，禁止越级）
+
+遇到 anov-gis 问题，按下面 5 级顺序排查；**前 4 级没解决才用 Chrome DevTools**。
+
+| 优先级 | 工具 | 何时用 |
+|---|---|---|
+| 1 | 读本 skill 的「陷阱」章节（[`anovgis-pitfalls`](../anovgis-pitfalls/SKILL.md)） | 覆盖 90% 常见报错（黑屏 / 不生效 / 报错 / 改值无变化 / Workers 404） |
+| 2 | 读 `cesiumjs-skills` 插件的 `using-cesiumjs-skills` skill（未安装见 anov-gis-skills INSTALL.md §方式 B.5） | 14 个子 skill，按需路由；覆盖 Cesium 原生 API 行为。**API 名与写法通用，但取法不同**：其 `import { X } from "cesium"` 一律换成 `const Cesium = window.Cesium` 后取 `Cesium.X`。**不要用相对路径找 cesiumjs-skills 的文件** —— 两个插件独立装到各自的缓存目录，目录不相邻；按 skill 名引用即可 |
+| 3 | 读已存在的 demo 源码（`examples/public/examples/html/...` 或用户项目 `src/`） | 参考成熟写法 |
+| 4 | Grep / Read 用户项目代码 | 定位上下文 |
+| 5 | Chrome DevTools MCP（`mcp__plugin_cesiumjs-skills_chrome-devtools__evaluate` / `navigate` / `screenshot`） | **仅当**用户明确说「打开页面看看」「截图给我看」「页面上 console 有 X 报错」才用 |
+
+**禁止用法**：
+
+- ❌ 写代码前先 `navigate` 到 demo URL 验证语法（用 Read skill 即可）
+- ❌ 解释 API 时 `evaluate` 一段代码探测运行态（用 skill snippet 即可）
+- ❌ 每次回答都 `screenshot`（用户没要求截图就别截）
+- ❌ 在 Write 工具之前 `evaluate` 探测 API 行为（应该用 skill / Read SDK 类型定义）
+
+**实战数据**：hainan 项目 session 中 Chrome DevTools 累计调用 **922 次**（最大会话单次 537 次），响应慢到分钟级。按本流程可降到 < 50 次。
+
+---
+
+## 快速上手
+
+**先判定走哪条路**（完整判定表与「已有项目接入 NPM」的写法见 [`templates/README.md`](templates/README.md)）：
+
+| 项目现状 | 走哪条路 |
+|---|---|
+| `package.json` 含 `@anov/gis`（Vite / Webpack / Vue CLI / Next） | **NPM**（首推）—— 见 [`templates/README.md`](templates/README.md) |
+| 只有 `index.html` + 静态目录 | **CDN** —— 仅 demo / 内网单文件调试，见 [`templates/combo3-html-cdn.md`](templates/combo3-html-cdn.md) |
+| 内网部署、无外网 CDN | NPM + `vite-plugin-static-copy` 把 `node_modules/@anov/gis/dist/resources/` 拷到 `public/anov-gis-sdk/` |
+| 已用 CDN 引入要迁移到 NPM | 先看 [`anovgis-imagery-terrain`](../anovgis-imagery-terrain/SKILL.md) 离线部署，再按 NPM 走 |
+
+> **首推 NPM**：90% 项目是 Vite/Vue/Webpack 工程，CDN 仅用于 demo 验证或内网单文件调试。
+## 最小 Viewer
+
+```js
+ANOVGIS.setBaseUrl('/anov-gis-sdk/resources/');   // 必须在 new Viewer 之前
+const viewer = new ANOVGIS.Viewer('cesiumContainer', { geocoderType: ANOVGIS.GeocoderType.TIANDITU });
+```
+
+完整参数（17 个）见 [`anovgis-viewer` § 2](../anovgis-viewer/SKILL.md#viewer-params)；`setBaseUrl` 时机见 [`anovgis-pitfalls` P3](../anovgis-pitfalls/SKILL.md#p3-setbaseurl)。
+## 集成方式与场景变体
+
+| 场景 | 去哪看 |
+|---|---|
+| UMD 全局方式（`<script>` 引入） | [`templates/combo3-html-cdn.md`](templates/combo3-html-cdn.md) § 变体 |
+| ESM 模块方式（`import` 引入） | [`templates/combo1-vue3-vite.md`](templates/combo1-vue3-vite.md) § 变体 |
+| Vue 2 + vue-cli | [`templates/combo2-vue2-cli.md`](templates/combo2-vue2-cli.md) § 变体 |
+| Vue 3 + Vite | [`templates/combo1-vue3-vite.md`](templates/combo1-vue3-vite.md) § 变体 |
+## 引导式初始化（交互向导）
+
+**触发关键词**（满足任一即进入）：「使用 anov-gis 初始化三维地球」「新建 anov-gis 项目」「从头搭一个 Cesium 工程」「anov-gis 引导式」「init wizard」「setup wizard」。
+
+**机制**：当用户在 prompt 中说以上任一关键词时，**主动调用 `AskUserQuestion` 工具**按下面 3 个问题并行询问，根据用户回答**一次性输出完整可运行的项目骨架**（含 `package.json` / 构建配置 / 入口文件 / 静态资源链接）。
+
+### 步骤 0（必读）：先判定该不该进入引导（v0.2.14 强化为双条件 AND）
+
+> ⚠️ **v0.2.14 关键改动**：skill_test 项目（2026-10-28，"参考图片 1.png 实现智慧水利数字孪生大屏"）实测，Claude 误判为「单 HTML + CDN 最快」，绕开了技术栈默认 Vue 3 + Vite 的约定。**根因**：原步骤 0 只看"项目是否空白"，没看"用户是否表达了三维地球意图"。
+>
+> **v0.2.14 改双条件触发（AND）**：
+
+#### 0.1 双条件判定（先做这步，再决定是否进入引导）
+
+| 条件 | 判定方式 |
+|---|---|
+| **空白项目** | 当前工作目录 `package.json` 不含 `@anov/gis` 依赖 **且** 代码全文无 `new ANOVGIS.Viewer` / `Cesium.Viewer` / `Cesium.CesiumWidget` 初始化痕迹 |
+| **明确意图** | 用户 prompt 含 `anov` / `@anov/gis` / `Cesium` / `三维地球` / `数字孪生` / `智慧XX` / `大屏` 等任意关键词 |
+
+| 满足情况 | 走什么流程 |
+|---|---|
+| 双条件都满足 | 进入「引导式初始化」（步骤 1~5，输出 Vue 3 + Vite 骨架） |
+| 仅空白项目，无明确意图 | **不触发引导**（用户可能在做别的事，硬引导反而打断） |
+| 仅明确意图，无空白项目 | 走「修改现有项目」流程（按 Demo 路由表或用户已有代码改） |
+| 都不满足 | 不进引导，正常回答 |
+
+> **设计意图**：参考图只描述业务 UI，不暗示技术栈——**单 HTML + CDN 不是默认路径**。数字孪生大屏 / 应急指挥 / 智慧 XX / 大屏 等场景统一走 Vue 3 + Vite 骨架（参见组合 1 模板）。HTML+CDN 仅在用户**明确**说「单文件 / 不用 npm / 没构建工具」时才走组合 3。
+
+#### 0.2 已确定要进引导后 → 跳过哪些问
+
+> 用户在 prompt 里说了具体技术栈 / 已有项目上下文时，**直接用该信息，不要再弹问**。
+
+| 用户 prompt 包含 / 项目现状 | 跳过哪些问 | 必问哪些 |
+|---|---|---|
+| `vue3`/`vite` + `本目录`/`本地`/`当前`（或任何技术栈 + 部署词） | **跳过全部 3 问**（直接出默认组合 1 骨架） | 无 |
+| `vue3`/`vite` 等具体技术栈（无部署词） | 跳过 Q1 底图（已指定时） | Q1 底图（如未指定）/ Q2 控件 / Q3 部署 |
+| 项目 `package.json` 已含 `@anov/gis` | 跳过 Q3（如未提及离线/CDN） | 仅 Q1 底图 / Q2 控件 |
+| 用户说「最小骨架」/「quickstart」/「3 行跑起来」/「hello world」 | 跳过 Q2（默认「极简」profile） + 跳过 Q3（默认「本地 SDK」） | 仅 Q1 底图 |
+| 完全空白，无任何线索（「帮我做个三维地球」） | 不跳过 | 全部 3 问 |
+
+**默认底图 key**：当用户选「天地图」时，**直接用 ANOV-GIS 官方 demo key** `b832b9764939cbb0919148c548b669ba`（SDK examples/src/mixins/mixin.js 硬编码）。**不要让用户去天地图控制台申请**，除非用户明确说「要自己的 key」或「正式部署」。
+
+**默认组合**（当步骤 0 跳过全部 3 问时直接用）：
+- 技术栈：**Vue 3 + Vite（固定，不再问）**
+- 底图：天地图（demo key）
+- 控件：标准 demo profile（顶部全开 / 时间轴关）
+- 部署：本地 SDK 包（`vite-plugin-static-copy` 拷贝 `dist/resources` → `public/anov-gis-sdk/`，**无需 `@anov/vite-plugins`**）
+- 对应模板见下方「§ 组合 1：Vue 3 + Vite + 推荐控件 + 天地图 + 内网本地 SDK ⭐ 推荐」
+
+**实战数据**：claude方式 项目 v0.2.2 / v0.2.6 修复前平均要问 3 问 + 引导 5+ 步，**用户每次都得回头指导修复**。skill_test v0.2.13 之前走单 HTML+CDN 路线 → 部署到内网 HTTP 失败 + 地球黑屏（baseLayerPicker:false 没显式 addImageryProvider，见 `anovgis-pitfalls` § P12）。按 v0.2.14 双条件触发 + 默认组合 1，1 轮 `Write` 即可得到可运行骨架。
+
+### 步骤 1：发起 3 个并行问题（一次 `AskUserQuestion` 调用）
+
+> **技术栈固定 Vue 3 + Vite**（v0.2.12 起不再询问）——从 0 创建项目默认就用 vite + vue3，团队事实标准。
+> 用户**明确点名**其它技术栈（Vue 2 / HTML+CDN / Vanilla webpack）时，才改用对应模板（见下文 § 模板 组合 2/3/4）。
+
+| 问题 | 选项（✓ = 推荐） | 决定什么 |
+|---|---|---|
+| **Q1 默认底图** | ✓ 天地图（需 key）/ 高德 / ArcGIS / 自定义 XYZ 或 WMS | `baseLayer` / `ImageryType` |
+| **Q2 控件 profile** | ✓ 推荐 / 极简 / 完整 / 自定义（追加 AskUserQuestion）| 11 个控件开关（顶部 / 底部 / 信息栏 / FPS 等）|
+| **Q3 部署方式** | ✓ 内网本地 SDK / 公网 CDN / 离线包 | `setBaseUrl` + 构建脚本拷贝策略 |
+
+### 步骤 2：（可选）追加 AskUserQuestion
+
+| 触发 | 追加问什么 |
+|---|---|
+| Q2 选「自定义」 | 11 个控件逐项开关（见下文 § Q2 自定义细分） |
+| Q1 选「自定义 XYZ/WMS」 | 瓦片 URL / 域名 / 坐标系（`EPSG:4326` 或 `EPSG:3857`）|
+| Q1 选了需要 key 的底图 | 天地图 / 高德 / Mapbox 的 key 值 |
+
+### 步骤 3：（可选）默认视角
+
+向用户索取初始中心点。接受 3 种格式：
+- 名称：「北京天安门」「上海陆家嘴」（AI 查表转坐标）
+- 坐标：「116.397,39.908,1000m」格式
+- 自定义：「使用默认（Cesium 默认地球视图）」
+
+### 步骤 4：输出项目骨架
+
+**必须 Read [`templates/combo1-vue3-vite.md`](templates/combo1-vue3-vite.md)（或 § 模板与控件 profile 表里对应的组合文件）之后再写文件** —— 不要凭记忆拼装 `package.json` / 构建配置 / 入口文件 / 静态资源链接，模板里带了逐条避坑注释。
+
+### 步骤 5：运行验证
+
+```bash
+cd <项目目录>
+npm install        # HTML+CDN 跳过
+npm run dev        # 启动 dev server
+```
+
+打开 `http://localhost:5173`（Vite 默认）/ `http://localhost:8080`（HTML 模板），看到三维地球 + 你选的控件 = 成功。遇报错调出 `anovgis-pitfalls`。
+
+---
+
+### 模板与控件 profile（按需读取）
+
+生成骨架前**必须先 Read 对应的模板文件**，不要凭记忆拼装工程配置 —— 模板里带了逐条避坑注释：
+
+| 场景 | 必须 Read 的文件 |
+|---|---|
+| **默认组合**（Vue 3 + Vite + 推荐控件 + 天地图 + 内网 SDK） | [`templates/combo1-vue3-vite.md`](templates/combo1-vue3-vite.md) |
+| Vue 2 + Vue CLI | [`templates/combo2-vue2-cli.md`](templates/combo2-vue2-cli.md) |
+| 纯 HTML + UMD CDN（仅 demo / 内网单文件调试） | [`templates/combo3-html-cdn.md`](templates/combo3-html-cdn.md) |
+| Vanilla JS + webpack 5 | [`templates/combo4-vanilla-webpack.md`](templates/combo4-vanilla-webpack.md) |
+| Q2 控件 profile 取值（极简 / 推荐 / 完整 / 自定义细分） | [`templates/wizard-profiles.md`](templates/wizard-profiles.md) |
+| 选模板（项目现状判定 + 已有项目接入 NPM） | [`templates/README.md`](templates/README.md) |
+### 反模式
+
+- ❌ **在 `new Viewer` 之后才 `setBaseUrl`** → Cesium 静态资源 404（P3 陷阱）
+- ❌ **HTML 模板双击 `index.html` 直接打开（`file://`）** → Workers / Assets 全部 404（P6 陷阱）
+- ❌ **`viewer.destroy()` 不调** → WebGL 上下文泄漏（多 Viewer 场景尤其严重）
+- ❌ **HTML 中不指定 `cesiumContainer` 高度** → 地球看不见（默认 0 高度）
+- ❌ **生产环境用 unpkg CDN** → 团队项目一律本地 SDK（外网 403 + 性能）
+- ❌ **webpack 5 没用 `IgnorePlugin`** → 报 `punycode` / `IPv6` / `SecondLevelDomains` 错（P4 陷阱）
+
+---
+
+## 关联资源
+
+- ANOV-GIS 源码：见 ANOV-GIS 仓库的 `src/` 目录（v1.8.6）
+- ANOV-GIS demo：见 ANOV-GIS 仓库的 `examples/public/examples/html/` 目录（共 137 个 .html，**仅作 SDK 追溯来源，skill 已嵌入核心代码**）
+- 关键词速查表：[`REFERENCE.md`](REFERENCE.md)（64 条，关键词 → 章节，每条带锚点）
+- 场景路由表：[`DEMO-MAP.md`](DEMO-MAP.md)（58 条，业务场景 → skill）
+- 工程骨架模板：[`templates/`](templates/README.md)（4 种组合 + 控件 profile）
+- 完整 demo 路由矩阵：[`DEMO-SKILL-MAP.md`](./DEMO-SKILL-MAP.md)
+- 权威归属与跨域路由：[`DOMAINS.md`](./DOMAINS.md)
+- ANOV-GIS 仓库（内网 GitLab，需完整 SDK 源码 / demo 原文时 clone；地址见内网 README）
+- 最小化示例：`anov-gis-demo-html` / `anov-gis-demo-vue2` / `anov-gis-demo-vue3`（在 ANOV-GIS 仓库 `other_system/` 目录）

package/skills/using-anovgis/templates/README.md

@@ -0,0 +1,154 @@
+> 本文件是 `skills/using-anovgis/SKILL.md` 的子文件 —— 模板总览（选模板 + 已有项目接入 NPM）。
+> 由 using-anovgis 路由进入，不要被别的 skill 直接引用。
+
+## 模板怎么选
+
+> 下面给出 4 个**代表性组合**的完整代码。**默认走组合 1（Vue 3 + Vite）**；用户明确点名其它技术栈时才用组合 2/3/4。其余组合（Vue 3 + CDN / Vue 2 + CDN / Vanilla JS + CDN 等）只需替换「技术栈」段 + 「setBaseUrl」段，其余通用。
+
+
+| 组合 | 技术栈 | 底图 / 控件 / 部署 | 文件 |
+|---|---|---|---|
+| **组合 1** ⭐ 默认 | Vue 3 + Vite 8 | 天地图 + 推荐控件 + 内网本地 SDK | [`combo1-vue3-vite.md`](combo1-vue3-vite.md) |
+| 组合 2 | Vue 2 + Vue CLI | 天地图 + 推荐控件 + 内网本地 SDK | [`combo2-vue2-cli.md`](combo2-vue2-cli.md) |
+| 组合 3 | 纯 HTML + UMD CDN | 天地图 + 极简 + 公网 CDN | [`combo3-html-cdn.md`](combo3-html-cdn.md) |
+| 组合 4 | Vanilla JS + webpack 5 | ArcGIS + 完整控件 + 内网 | [`combo4-vanilla-webpack.md`](combo4-vanilla-webpack.md) |
+
+## 项目现状探测
+
+| 项目现状 | 推荐路径 |
+|---|---|
+| `package.json` 含 `@anov/gis` 依赖（Vite / Webpack / Vue CLI / Next） | **走 NPM**（见下方「§ NPM 引入」） |
+| `package.json` 无 `@anov/gis`，仅有 `index.html` + 静态目录 | **走 CDN**（见下方「§ CDN 引入」），仅 demo / 内部测试用 |
+| 已用 `<script src="...">` CDN 引入，要迁移到 NPM | 先看 [`anovgis-imagery-terrain`](../../anovgis-imagery-terrain/SKILL.md) § 离线部署，再按 NPM 走 |
+| 内网部署，无外网 CDN | 走 NPM + `vite-plugin-static-copy` 把 `node_modules/@anov/gis/dist/resources/` 拷到 `public/anov-gis-sdk/` |
+
+> **首推 NPM**：90% 项目是 Vite/Vue/Webpack 工程，CDN 仅用于 demo 验证或内网单文件调试。
+
+
+## 已有项目接入（NPM）
+
+```bash
+npm install @anov/gis
+# 或 yarn add @anov/gis / pnpm add @anov/gis
+```
+
+```js
+// 入口文件（main.js / main.ts / app.ts）
+import '@anov/gis/dist/index.css'
+import ANOVGIS from '@anov/gis'
+
+// ⚠️ 必须在 new Viewer 之前调用
+ANOVGIS.setBaseUrl('/anov-gis-sdk/resources/')
+
+// devtools 调试用，业务代码用 import 进来的局部变量
+window.ANOVGIS = ANOVGIS
+
+const viewer = new ANOVGIS.Viewer('cesiumContainer', {
+  geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+  // ⚠️ 不要传 baseLayer（v0.2.10 实测 v1.8.6 枚举是字符串，会报 _layerIndex on string 错）——底图构造后 addImageryProvider
+})
+```
+
+**Vite + 已有项目骨架**（含静态资源拷贝）：
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { viteStaticCopy } from 'vite-plugin-static-copy'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    viteStaticCopy({
+      targets: [{
+        src: 'node_modules/@anov/gis/dist/resources/**/*',
+        dest: 'anov-gis-sdk',
+        rename: { stripBase: 5 },  // 去掉 resources/ 前缀
+      }],
+    }),
+  ],
+})
+```
+
+```vue
+<!-- src/App.vue（Vue 3 Composition API） -->
+<script setup>
+import { onMounted, onBeforeUnmount } from 'vue'
+import ANOVGIS from '@anov/gis'
+
+let viewer = null  // 模块级 let，绝不放 ref()/reactive()
+
+onMounted(() => {
+  const Cesium = window.Cesium  // 唯一推荐写法（@anov/gis 已封装 Cesium）
+  viewer = new ANOVGIS.Viewer('cesiumContainer', {
+    baseLayerPicker: false,
+    infoBox: false,
+    selectionIndicator: false,
+    geocoder: false,
+    animation: false,
+    timeline: false,
+    contextOptions: { id: 'cesiumCanvas' },
+  })
+  viewer.scene.globe.enableLighting = false
+})
+
+onBeforeUnmount(() => {
+  viewer?.destroy()
+  viewer = null
+})
+</script>
+
+<template>
+  <div id="cesiumContainer" style="width:100vw;height:100vh"></div>
+</template>
+```
+
+```ts
+// src/globalConfig.ts
+// ANOV-GIS 官方 demo 公开测试 key（与 SDK examples/src/mixins/mixin.js 一致）
+// 正式部署请替换为团队在 https://console.tianditu.gov.cn 申请的 key
+export const globalConfig = {
+  tdtKey: 'b832b9764939cbb0919148c548b669ba',
+}
+```
+
+```ts
+// src/main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import '@anov/gis/dist/index.css'
+import ANOVGIS from '@anov/gis'
+import { globalConfig } from './globalConfig'
+
+ANOVGIS.setBaseUrl(import.meta.env.BASE_URL + 'anov-gis-sdk/')
+window.ANOVGIS = ANOVGIS  // devtools 调试用，业务代码用局部变量
+
+createApp(App).mount('#app')
+```
+
+
+## 最小 Viewer（不想读整份模板时的最小骨架）
+
+## 最小 Viewer
+
+> ⚠️ **v0.2.10：Viewer 构造时不要传 `baseLayer`**。`ANOVGIS.ImageryType.*` 枚举本质是字符串（如 `ImageryType.TDT` === `'tdt'`），SDK v1.8.6 内部会把它当已建好的图层对象用，触发 `TypeError: Cannot create property '_layerIndex' on string 'tdt'`（playwright 实测）。
+> 官方 `anov-gis-demo-vue3-main` 模板根本不传 baseLayer。底图改用构造后 `addImageryProvider` 模式（见下方「§ NPM 引入 → Vite + Vue 3 骨架」），更清晰且支持自定义 key。
+
+```js
+new ANOVGIS.Viewer('cesiumContainer', {
+    contextOptions: {                  // 截图 / WebGL 错误
+        id: 'cesiumCanvas',            // 必须
+        webgl: { preserveDrawingBuffer: true },
+        showRenderLoopErrors: false,
+    },
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+    // ⚠️ 不要传 baseLayer（v0.2.10 实测 v1.8.6 会报 _layerIndex on string 错）——底图构造后 addImageryProvider
+    baseLayerPicker: true, fullscreenButton: true, homeButton: true,
+    sceneModePicker: true, navigationHelpButton: true,
+    copyRight: false, showMapInfo: true,
+    showFPS: false, drillPick: false,
+    defaultView: [lon, lat, lon, lat], // 四元数组框选初始视图
+});
+```
+