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

package/INSTALL.md

@@ -0,0 +1,478 @@
+# 安装细节
+
+README 的「安装」章节给了最常用的几条命令，本文是它们的完整版本：全部参数、MCP 接入方式、升级、卸载与排错。
+
+> **`<GITLAB_URL>`** = 本仓库的内网 GitLab 地址。在内网 GitLab 打开本仓库，点「克隆 / Clone」按钮即可拿到。
+> 本文档随 npm 包发到公网，所以**不写死内网地址** —— 每次用到的地方统一用这个占位符。
+
+---
+
+## 前置条件
+
+| 方式 | 需要什么 |
+|---|---|
+| A. npm 包 | Node.js ≥ 18，能访问公网 npm |
+| B. marketplace | Claude Code CLI ≥ 2.1（依赖自动安装 + `autoUpdate` 需要 2.1+），能访问内网 GitLab |
+| C. `npx skills` | Node.js ≥ 18，能访问内网 GitLab |
+| D. `install.sh` | bash（Git Bash / WSL / macOS / Linux），已 clone 本仓库 |
+
+外网 github.com 在团队网络不可达，这也是 `cesiumjs-skills` 打进包里的原因（见 §方式 A.4）。
+
+---
+
+## 方式 A：npm 包（推荐）
+
+不想 clone 仓库、或者在 CI 流水线里装 skill 时用这条路。**不依赖 GitLab，也不依赖 github.com。**
+
+包发在**公网 npm**（`https://registry.npmjs.org/`），内网直连公网即可装，**不需要配任何 registry**。
+
+### A.1 安装（一条命令，不用先 `npm i -g`）
+
+```bash
+npx @anov/gis-skills-cli setup
+```
+
+`setup` 做两件事：装 **27 个 skill**（12 anov-gis + 15 Cesium），然后写一条 **MCP 配置**。
+`npx` 会临时下载包并执行它的 `anov-gis-skills` 命令，**不需要预先 `npm i -g`**。想装成全局命令也行：
+
+```bash
+npm i -g @anov/gis-skills-cli
+anov-gis-skills setup
+```
+
+### A.2 参数
+
+```bash
+# 装到哪（默认用户级，任何项目都能用）
+npx @anov/gis-skills-cli setup              # → ~/.claude/skills/ 等
+npx @anov/gis-skills-cli setup --project    # → ./.claude/skills/，可提交进项目仓库
+
+# 装给谁（默认全部检测到的智能体）
+npx @anov/gis-skills-cli setup --agent claude-code
+npx @anov/gis-skills-cli setup --agent claude-code --agent codex
+
+# 不碰 MCP
+npx @anov/gis-skills-cli setup --no-mcp
+
+# 只看要写什么，不落盘
+npx @anov/gis-skills-cli setup --print
+```
+
+### A.3 各智能体的落点
+
+| 智能体 | skill 装到 | MCP 配置写到 |
+|---|---|---|
+| Claude Code | `~/.claude/skills/` | `~/.claude.json` 的 `mcpServers`（项目级 → `./.mcp.json`） |
+| Codex | `~/.codex/skills/` | `~/.codex/config.toml` 的 `[mcp_servers.anov-gis]` |
+| Cursor | `~/.agents/skills/` | `~/.cursor/mcp.json`（项目级 → `./.cursor/mcp.json`） |
+| VS Code | `~/.agents/skills/` | `./.vscode/mcp.json` 的 `servers` |
+| Cline / Windsurf / Continue 等 | `~/.agents/skills/` | 不支持（打印片段自行粘贴） |
+
+底层 `skills` CLI 版本**锁定在 `skills@1.5.18`**（不是 latest）：1.6.0+ 的 `engines` 要求 `node >= 22.20.0`，而团队环境实测是 node 22.19.0，锁低版本才能在 node ≥ 18 全覆盖。
+
+> ⚠️ 项目级安装会在项目根生成 `skills-lock.json`（skills CLI 用来记录来源）。**它不用提交**，可以加进 `.gitignore`。
+
+### A.4 Cesium skill 从哪来
+
+15 个 Cesium skill 是官方 `cesiumjs-skills` 的内容（Apache-2.0），**已经打进本 npm 包**（`vendor/cesiumjs-skills/`），装的时候不需要访问 github 或内网 GitLab。
+
+| 文件 | 作用 |
+|---|---|
+| `vendor/cesiumjs-skills/skills/` | 15 个 skill 实体（14 个领域 + `using-cesiumjs-skills` 入口） |
+| `vendor/cesiumjs-skills/LICENSE` | Apache-2.0 全文（再分发必须保留） |
+| `vendor/cesiumjs-skills/NOTICE` | 上游来源与版本说明 |
+| `scripts/sync-cesium.mjs` | 维护者用：从内网镜像重新同步（`--check` 只比对） |
+
+上游更新后由维护者跑 `node scripts/sync-cesium.mjs` 再发版，用户重跑 `setup` 即可。
+
+### A.5 MCP 接入
+
+`setup` 默认会写一条 MCP 配置（stdio 直连 `anov-gis-mcp`）。单独管理：
+
+```bash
+npx @anov/gis-skills-cli mcp show              # 看当前状态
+npx @anov/gis-skills-cli mcp add               # 补上（默认 Claude Code + 用户级）
+npx @anov/gis-skills-cli mcp add --mcp-agent codex
+npx @anov/gis-skills-cli mcp remove            # 拿掉
+```
+
+参数：
+
+| 参数 | 说明 |
+|---|---|
+| `--mcp-agent <名字>` | `claude-code`（默认）/ `codex` / `cursor` / `vscode` |
+| `--mcp-mode stdio\|http` | 默认 `stdio`（本地起进程）；`http` 连服务器 |
+| `--mcp-url <地址>` | HTTP 模式必填，例如 `http://192.168.11.164:3000/mcp` |
+| `--mcp-command` / `--mcp-arg` | 自定义 stdio 启动命令（默认 `npx -y anov-gis-mcp --stdio`） |
+| `--print` | 只打印配置片段，不写文件 |
+
+**凭据透传**：写配置时会把当前环境里这几个变量透传进 `env`（有值才写）——
+`ANOV_GIS_MINIO_ACCESS_KEY` / `_SECRET_KEY` / `_ENDPOINT` / `_BUCKET` / `_REGION`、
+`ANOV_GIS_PUBLIC_STATIC_BASE` / `_PUBLIC_API_BASE`、`ANOV_GIS_ANOVCITY_BASE`。
+
+> **写进项目级 `.mcp.json` 时注意**：如果 `env` 里带了 MinIO 账号，这份文件就含凭据，**不要提交**。
+> 更干净的做法是走 HTTP 模式（凭据只在服务端 `.env`），见 `anov-gis-mcp` 仓库的 README。
+
+**写入原则**：读现有文件 → 只改 `anov-gis` 这一个条目 → 原子写回。别人配的 MCP server 一律不碰。
+
+### A.6 验证
+
+```bash
+npx @anov/gis-skills-cli doctor
+```
+
+逐个目录报：
+
+```
+包内 skill 数：27
+
+── Claude Code ──  C:\Users\你\.claude\skills
+  ✓ 27 个 skill 齐全
+  ✓ frontmatter 全部可被严格 YAML 解析
+
+── MCP · Claude Code（用户级） ──  C:\Users\你\.claude.json
+  ✓ 已配置（stdio）
+```
+
+| 检查项 | 不通过意味着 |
+|---|---|
+| skill 齐全 | 装漏了，或只装了一部分（单独装部分 skill 时跨 skill 链接会失效） |
+| frontmatter 可被严格 YAML 解析 | 某些 agent 的 skill 加载器会**整个跳过**这个 skill（v0.2.17 踩过：只发现 10/12） |
+| MCP 已配置 | 少了条目 —— 跑 `mcp add` |
+
+有问题会逐条列出并以退出码 1 结束。
+
+### A.7 升级
+
+```bash
+npx @anov/gis-skills-cli setup          # 重新落地（npx 会拉最新版，幂等）
+```
+
+### A.8 卸载
+
+```bash
+npx @anov/gis-skills-cli uninstall              # 用户级
+npx @anov/gis-skills-cli uninstall --project    # 项目级
+
+# 移除包本身（如果当初 npm i -g 过）
+npm uninstall -g @anov/gis-skills-cli
+```
+
+`uninstall` **只删本包提供的 27 个 skill 与 `anov-gis` 这一条 MCP 配置**，别家的 skill / MCP 条目不动。
+
+> ⚠️ 别用 `skills remove --all`（等价 `--skill '*' --agent '*' -y`）—— 它会删掉**所有来源**的 skill。
+
+---
+
+## 方式 B：Claude Code 插件（marketplace）
+
+Claude Code 走 marketplace，多两个好处：**发版后自动升级**、**自动带出 `cesiumjs-skills`**。
+
+### B.1 安装
+
+在 Claude Code 中执行：
+
+```
+/plugin marketplace add <GITLAB_URL>
+/plugin install anov-gis-skills@anov-gis-skills
+```
+
+**这一条命令会同时装好两个插件**：
+
+| 插件 | 内容 |
+|---|---|
+| `anov-gis-skills` | 本仓库 12 个 `@anov/gis` 领域 skill |
+| `cesiumjs-skills` | Cesium 原生 15 个 skill（14 个领域 + 入口，内网镜像，**作为依赖自动带出**） |
+
+重启 Claude Code 会话生效。
+
+> ⚠️ **`/plugin` 只能在 Claude Code 终端里用**（VSCode 面板 / IDE 扩展 / headless 会报 "isn't available in this environment"）。
+> 等价 CLI 命令（在普通终端跑）：`claude plugin marketplace add <url>` / `claude plugin install <插件>@<市场>`。
+
+**验证安装成功**：
+
+1. `/plugin list` —— 应看到 `anov-gis-skills` **和** `cesiumjs-skills` 都在已安装列表
+2. 新开一个会话，提问"flowPolyline 颜色怎么改"，Claude 应自动激活 `anovgis-materials` skill 并给出溯源 snippet
+
+### B.2 项目级配置（团队协作，推荐）
+
+适合团队协作 —— 每个团队成员 clone 项目后首次启动自动加载。
+
+在被开发的项目根目录创建（或编辑）`.claude/settings.json`：
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "anov-gis-skills": {
+      "source": {
+        "source": "git",
+        "url": "<GITLAB_URL>"
+      },
+      "autoUpdate": true
+    }
+  },
+  "enabledPlugins": {
+    "anov-gis-skills@anov-gis-skills": true
+  }
+}
+```
+
+把这份 `.claude/settings.json` **提交到项目仓库**。
+
+**效果**：
+
+- 团队成员 clone 项目 → 首次启动 Claude Code → 自动拉取并安装 `anov-gis-skills`（连同依赖 `cesiumjs-skills`）
+- 之后每次启动 Claude Code 会**自动检查并拉取新版本**（`autoUpdate: true`）—— v0.2.15 新增的能力，此前第三方 marketplace 默认是关的，需要人工跑 `/plugin marketplace update`
+- 无需任何额外步骤
+
+### B.3 锁版本（可选）
+
+`enabledPlugins` 的 key 支持带版本约束的扩展格式：
+
+```json
+{
+  "enabledPlugins": {
+    "anov-gis-skills@anov-gis-skills@^0.3.0": true
+  }
+}
+```
+
+版本约束靠内网 GitLab 上的 git tag 解析（tag 格式 `anov-gis-skills--v0.2.15`）。没有匹配 tag 会报 `no-matching-tag`。
+
+> ⚠️ **版本约束只对 `enabledPlugins` 生效**。`/plugin install` 与 `claude plugin install` 的参数只接受 `插件名` 或 `插件名@市场名`（第三段会被丢弃），所以**命令行装的时候锁不住版本** —— 要锁版本就靠 settings 里的 `enabledPlugins`。
+
+**完全锁死（不推荐）**：把约束写成精确版本 `anov-gis-skills@anov-gis-skills@0.3.0`。精确锁定后**不会自动升级**，每次发版都要人工改这一行 —— 这正是 v0.2.15 之前"发完版还要挨个催"的原因。
+
+### B.4 插件缓存位置
+
+- `~/.claude/plugins/known_marketplaces.json`：marketplace 注册条目（含 `autoUpdate` 开关）
+- `~/.claude/plugins/cache/anov-gis-skills/<插件名>/<版本>/`：插件副本
+- `~/.claude/plugins/installed_plugins.json`：已安装插件清单（依赖自动装上的会标 `"auto": true`）
+
+### B.5 cesiumjs-skills 从哪来
+
+`cesiumjs-skills` 是 CesiumGS 的官方插件（Apache-2.0，原仓库 <https://github.com/CesiumGS/cesiumjs-skills>），提供 15 个 **Cesium 原生** skill（14 个领域 + `using-cesiumjs-skills` 入口）+ SessionStart hook + Chrome DevTools MCP。本仓库的 skill 都会引用它（"Cesium 入口（铁律）"）。
+
+**外网 github.com 在本团队网络不可达**，所以在内网 GitLab 建了一份镜像：
+
+```
+<cesiumjs-skills 内网镜像地址>
+```
+
+镜像内容与上游 commit `df881cf`（v0.3.0）一致，`LICENSE`（Apache-2.0）、`hooks/`、`.mcp.json` 全部保留。
+
+**你不需要做任何事** —— 装 `anov-gis-skills` 时它作为 `dependencies` 被自动装上并启用。装完 `/plugin list` 里应该有两个插件，其中 `cesiumjs-skills` 的 `installed_plugins.json` 条目带 `"auto": true`（表示是作为依赖被带出来的）。
+
+**已经装过官方版的同学**（在外网可达的机器上装的）：官方版和镜像版会**注册同名的 skill**，造成重复触发和路由歧义。二选一：
+
+```
+/plugin uninstall cesiumjs-skills@cesiumjs-skills
+/plugin prune
+/plugin install anov-gis-skills@anov-gis-skills
+```
+
+> **注意**：镜像里的 chrome-devtools MCP 走 `npx -y chrome-devtools-mcp@latest`，需要能访问 npm registry。内网不通的话 MCP 起不来，**但 skill 本身不受影响**。
+
+---
+
+## 方式 C：`npx skills`（跨智能体标准 CLI）
+
+[vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) 的 CLI。**它直接吃内网 GitLab URL**（不需要 github.com）：
+
+```bash
+# 装全部 skill 到本机检测到的所有智能体
+npx skills add <GITLAB_URL> --all
+
+# 只装到某个智能体
+npx skills add <repo-url> --agent claude-code
+npx skills add <repo-url> --agent codex
+
+# 先看看有哪些 skill（不装）
+npx skills add <repo-url> -l
+
+# 更新
+npx skills update
+```
+
+- 装到 `~/.claude/skills/`（Claude Code）、`~/.codex/skills/`（Codex）等标准位置
+- 默认**拷贝**（`--copy` 是显式开关，默认行为随版本变化）；加 `--copy` 强制拷贝
+- **不带 cesiumjs-skills** —— 这条路没有 marketplace 的 `dependencies` 机制，Cesium 原生 skill 要单独装（见 §方式 B.5）
+
+> ⚠️ 本仓库的 skill `description` 必须能被严格 YAML 解析，否则会被这个 CLI 跳过。`scripts/bump.mjs --check` 会校验这一点（v0.2.16 修过一次：`anovgis-imagery-terrain` / `anovgis-pitfalls` 的 description 未加引号且含 ASCII 冒号，导致 12 个 skill 只被发现 10 个）。
+
+---
+
+## 方式 D：`install.sh`（链接安装，git pull 原地更新）
+
+已经 clone 了本仓库的话，直接跑：
+
+```bash
+./install.sh                    # 链到 Claude Code（~/.claude/skills）
+./install.sh --codex            # 链到 Codex（~/.codex/skills）
+./install.sh --all-agents       # 两个都链
+./install.sh --list             # 列出可装的 skill
+./install.sh --uninstall        # 删掉指向本仓库的链接
+./install.sh using-anovgis      # 只装指定 skill（按 frontmatter name）
+```
+
+建的是**链接**不是拷贝（Windows 用 NTFS 目录联接 `mklink /J`，其它平台用 `ln -s`），所以 **`git pull` 之后所有已装 skill 原地更新**，不用重跑安装。
+
+- 需要 bash（Git Bash / WSL / macOS / Linux 都行）
+- 同样**不带 cesiumjs-skills**（没有 plugin marketplace 的依赖机制）
+
+---
+
+## 方式 E：Codex / Cursor / 通用 AGENTS.md
+
+本仓库**一份 skill，多智能体共用**。仓库根目录同时放了各智能体的清单：
+
+```
+anov-gis-skills/
+├── .claude-plugin/plugin.json      # Claude Code
+├── .codex-plugin/plugin.json       # Codex CLI / Codex App
+├── .cursor-plugin/plugin.json      # Cursor
+├── AGENTS.md                       # 通用 AGENTS.md 约定（兜底）
+├── skills/                         # 12 个 anov-gis skill，所有智能体共享
+└── vendor/cesiumjs-skills/skills/  # 15 个 Cesium skill（Apache-2.0）
+```
+
+各智能体的 `plugin.json` 都指向同一个 `./skills/`，**不需要为每个智能体单独维护一份 skill**。
+
+### Codex CLI / Codex App
+
+Codex 有自己的 plugin 机制，清单在 `.codex-plugin/plugin.json`。**当前本仓库未发布到 Codex 官方 marketplace**，所以用本地安装：
+
+**方式一：本地 plugin 安装（推荐）**
+
+```bash
+codex plugin install /path/to/anov-gis-skills
+```
+
+**方式二：手动 symlink skills 目录**（Codex 期望每个 skill 是独立子目录，本仓库已符合）
+
+**Windows (cmd)**：
+
+```cmd
+mklink /D %USERPROFILE%\.codex\skills\anov-gis-skills <本仓库>\skills
+```
+
+**macOS / Linux**：
+
+```bash
+ln -s <本仓库>/skills ~/.codex/skills/anov-gis-skills
+```
+
+**MCP 配置转换（可选）**：如果项目需要 Chrome DevTools MCP，将 `.mcp.json` 转换为 `~/.codex/config.toml`：
+
+```toml
+[mcp_servers.chrome-devtools]
+command = "npx"
+args = ["-y", "chrome-devtools-mcp@latest"]
+```
+
+### Cursor
+
+清单在 `.cursor-plugin/plugin.json`。Cursor 有自己的 plugin 目录（`~/.cursor/plugins/` 或项目级 `.cursor/plugins/`），把本仓库（或其中的 `skills/`）放进去即可：
+
+```bash
+# 项目级（推荐，随仓库走，团队共享）
+git clone <GITLAB_URL> .cursor/plugins/anov-gis-skills
+```
+
+Cursor 也支持在 Agent 聊天框里从 marketplace 装 —— 那需要发布到 Cursor marketplace，本仓库暂未发布。
+
+### 通用 AGENTS.md 约定（其它智能体）
+
+对于不认 plugin 机制、但会读 `AGENTS.md` 的智能体（Cline / Windsurf / Continue / 各类 IDE agent 等），仓库根的 `AGENTS.md` 就是入口：它说明本插件提供什么、每个智能体该读哪个 manifest、skill 实体在哪儿、触发关键词是什么。
+
+通用装法（把每个 skill 单独软链到 `~/.agents/skills/`）：
+
+```bash
+mkdir -p ~/.agents/skills
+for d in <本仓库>/skills/*/; do
+  ln -sfn "$d" ~/.agents/skills/$(basename "$d")
+done
+```
+
+> ⚠️ **Claude Code 不读 `~/.agents/skills/`**（该路径在 Claude Code 里无效）。Claude Code 请用 §方式 A / §方式 B。
+
+### 非 Claude Code 智能体的使用建议
+
+首轮对话**显式声明**：
+
+```
+参考 @anov/gis v1.8.6 + Cesium 1.143.0，使用 anov-gis-skills 提供的 skill。
+```
+
+后续提问 skill 会基于 description 关键词自动触发。
+
+---
+
+## 各智能体差异对照
+
+| 项 | Claude Code | Codex CLI | Cursor | 通用 AGENTS.md |
+|---|---|---|---|---|
+| 清单文件 | `.claude-plugin/plugin.json` | `.codex-plugin/plugin.json` | `.cursor-plugin/plugin.json` | `AGENTS.md` |
+| 安装方式 | marketplace（推荐） | 本地 plugin / symlink | plugin 目录 / marketplace | symlink |
+| 自动更新 | ✅ `autoUpdate: true` | ❌ 人工 re-install | ❌ 人工 re-install | ❌ `git pull` 后重链 |
+| 跨插件依赖 | ✅ `dependencies` | ❌ | ❌ | ❌ |
+| SessionStart hook | ✅ | ❌ | ⚠️ 部分支持 | ❌ |
+| skill 装到哪 | `~/.claude/plugins/cache/...` | `~/.codex/skills/` | `~/.cursor/plugins/...` | `~/.agents/skills/` |
+
+**`cesiumjs-skills` 依赖只在 Claude Code 上自动装**（靠 marketplace 的 `dependencies` 字段）。其它智能体需要单独装 CesiumGS 官方版：
+
+```bash
+# Codex / Cursor：单独装官方 cesiumjs-skills
+git clone https://github.com/CesiumGS/cesiumjs-skills.git ~/.codex/skills/cesiumjs-skills
+```
+
+> 外网 github.com 在本团队网络不可达时，改用内网镜像（地址见 §方式 B.5）
+
+---
+
+## 升级
+
+**Claude Code 走 marketplace 时默认就是自动的。** 项目级配置带 `autoUpdate: true`，Claude Code 每次启动会自动检查内网 GitLab 上的新版本并升级已安装的插件 —— **发版后不需要通知任何人**。
+
+### 手动命令（备用）
+
+```
+/plugin marketplace update anov-gis-skills      # 刷新 marketplace 目录（拉到新的 marketplace.json）
+/plugin update anov-gis-skills                   # 把插件本体更新到最新匹配版本
+```
+
+`/plugin update` 会提示 **restart required** —— 重开 Claude Code 会话生效。
+
+### 什么时候必须手动操作
+
+| 场景 | 说明 |
+|---|---|
+| 首次开启 `autoUpdate` | 2026-10 之前装的，`known_marketplaces.json` 里 `autoUpdate` 默认是 `false`（第三方 marketplace 的默认值）。改一次 §方式 B.2 的配置或跑一次 `/plugin marketplace update` 即可 |
+| 用了精确锁版本 | `anov-gis-skills@anov-gis-skills@0.3.0` 这种精确锁定**不会自动升级**，必须改这一行 |
+| 提示 restart required | 重开 Claude Code 会话 |
+| 想立刻跳到指定版本 | `/plugin install anov-gis-skills@anov-gis-skills@0.3.0`（降级同理） |
+
+### 查看当前版本
+
+```
+/plugin list
+/plugin details anov-gis-skills
+```
+
+### 破坏性变更
+
+**从 v0.1.1 升级到 v0.3.0 的破坏性变更**：无。所有 v0.1.1 skill 在 v0.3.0 仍然可用；v0.2.0 新增 3 个 skill + DOMAINS 强化；v0.2.1–v0.3.0 为修复性版本（skill 名称与目录结构未变）。
+
+---
+
+## 排错
+
+| 症状 | 多半是 | 怎么办 |
+|---|---|---|
+| `/plugin` 报 "isn't available in this environment" | 在 VSCode 面板 / IDE 扩展 / headless 里跑了 | 换成 Claude Code 终端，或用 `claude plugin ...` CLI |
+| `/plugin install` 报 `no-matching-tag` | 版本约束对应的 tag 没打 | 确认内网 GitLab 上有 `anov-gis-skills--v<版本>` tag |
+| 插件装了但 skill 一个都没出现 | frontmatter 没被严格 YAML 解析 | 跑 `npx @anov/gis-skills-cli doctor` 看哪几条断了 |
+| skill 只有一部分能用 | 单独装了部分 skill，指向兄弟 skill 的相对链接失效 | 全量装（12 个同级），别只装一个 |
+| `doctor` 报 skill 不齐 | 只装了一部分 | 重跑 `setup`；仓库侧跑 `node scripts/build-npm.mjs` 复查 |
+| 已装过官方 `cesiumjs-skills` 导致触发混乱 | 官方版与内网镜像版注册了同名 skill | 见 §方式 B.5 的卸载步骤二选一 |
+| Chrome DevTools MCP 起不来 | 内网访问不了 npm registry | 不影响 skill 本身，可忽略 |

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, zhf
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# anov-gis-skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 `@anov/gis` SDK（Cesium 1.143 二三维 WebGIS 二次开发框架）开发用的 **27 个领域 skill + 1 个 MCP 接入**，装到 Claude Code / Codex / Cursor 等智能体，AI 按你的意图自动路由。
+
+| 组成 | 内容 |
+|---|---|
+| **anov-gis skill ×12** | 按用户意图组织：Viewer / 影像地形 / 图层 / 图元 / Primitive / 3D Tiles / Popup / 材质 / 分析 / 特效 / 陷阱 / 引导初始化 |
+| **Cesium skill ×15** | 官方 `cesiumjs-skills`（Apache-2.0）的 Cesium 原生 API 知识，随包一起装，不用另找 |
+| **anov-gis-mcp** | 数据目录 / 接口契约 / 代码片段的 MCP 服务，可选接入 |
+
+- 每个 skill 含 类速查表 + 关键 API + 可跑 snippet + 反模式；snippet **强溯源**到 SDK 源码与 demo，**核心代码已内嵌**
+- 适用 SDK：`@anov/gis` **v1.8.6**（Cesium **1.143.0**）
+
+---
+
+## 安装
+
+### 一行装上（推荐）
+
+```bash
+npx @anov/gis-skills-cli setup      # 27 个 skill + MCP 接入
+```
+
+`setup` 做两件事：
+
+1. 把 **27 个 skill** 落到各智能体的标准目录（`~/.claude/skills/`、`~/.agents/skills/` 等）
+2. 写一条 **MCP 配置**（默认 Claude Code，stdio 直连 `anov-gis-mcp`）—— 不想要就加 `--no-mcp`
+
+不需要预先 `npm i -g`，也不需要 clone 本仓库。
+
+常用参数：
+
+```bash
+npx @anov/gis-skills-cli setup --project          # 装到当前项目（默认用户级）
+npx @anov/gis-skills-cli setup --agent cursor     # 只装给某个智能体
+npx @anov/gis-skills-cli setup --no-mcp           # 只装 skill，不碰 MCP
+npx @anov/gis-skills-cli mcp add --mcp-agent codex  # MCP 单独接到 Codex
+npx @anov/gis-skills-cli uninstall                # 清理（只删自己的）
+```
+
+完整参数见 [INSTALL.md](INSTALL.md)。
+
+
+### 验证
+
+```bash
+npx @anov/gis-skills-cli doctor
+```
+
+逐个目录报：27 个 skill 是否齐全、frontmatter 能否被严格 YAML 解析、MCP 条目写没写对。
+
+新开一个会话提问"flowPolyline 颜色怎么改"，应自动激活 `anovgis-materials` 并给出溯源 snippet。
+
+安装排错见 [INSTALL.md](INSTALL.md#排错)；地图黑屏 / Workers 404 / 材质不生效等问题看下面的「报错排查」。
+
+---
+
+## 使用
+
+### 触发机制
+
+**被动触发（推荐）**：prompt 里命中 skill `description` 的关键词就自动激活。
+
+| 你说 | 激活 |
+|---|---|
+| "flowPolyline 颜色怎么改" | `anovgis-materials`（命中 "PolylineFlowMaterial"） |
+| "地图黑屏了" | `anovgis-pitfalls`（命中 "黑屏"） |
+| "我要从零建项目" | `using-anovgis`（命中 "从零开始"） |
+
+**主动调用**：`/anovgis-materials`、`/anovgis-primitives`、`/anovgis-pitfalls` ……
+
+### 从零建项目
+
+直接说"用 anov-gis 初始化三维地球"，`using-anovgis` 会用 `AskUserQuestion` 问你 3 件事（默认底图 / 控件 profile / 部署方式），然后输出**复制粘贴即可运行**的 Vue 3 + Vite 工程骨架。
+
+技术栈固定 Vue 3 + Vite（v0.2.12 起不再询问）。详见 `skills/using-anovgis/SKILL.md`。
+
+### 改 SDK 自带 demo
+
+团队最常见的场景是「复制 SDK 自带 demo → 改成自己的业务」。137 个 demo 的路由表在 [`skills/using-anovgis/DEMO-SKILL-MAP.md`](skills/using-anovgis/DEMO-SKILL-MAP.md)。
+
+直接跟 AI 说文件名 + 想改什么，它会自动路由：
+
+```
+"帮我改 material/flowPolyline.html 把颜色改成红色"
+→ anovgis-materials 自动激活，给出改 flowPolyline 颜色的 snippet
+```
+
+### MCP 能补什么
+
+skill 讲**「怎么写 Cesium 代码」**，`anov-gis-mcp` 讲**「这份代码该填什么」**。接上之后 AI 能直接答：
+
+> 「北京这边到底有哪些数据？URL 是什么？写完的代码帮我验一下。」
+
+15 个工具，覆盖静态数据目录检索、行政区划解析、anovcity 接口契约、代码片段生成与校验。
+瓦片与矢量数据的字节不经过 MCP —— 只给 URL，浏览器直连。
+
+```bash
+npx @anov/gis-skills-cli mcp show      # 看当前接没接上
+npx @anov/gis-skills-cli mcp add       # 补上
+npx @anov/gis-skills-cli mcp remove    # 拿掉
+```
+
+> 需要 MinIO 只读账号才有实时目录；没有的话目录会退化成内置种子清单。
+> 服务本身的部署与参数见 `anov-gis-mcp` 仓库的 README。
+
+### 报错排查
+
+**第一反应调出 `anovgis-pitfalls`**：
+
+```
+/anovgis-pitfalls
+```
+
+它会列出 P0–P12 的高频陷阱。把报错截图 + console 输出 + 关键代码片段贴给 AI，skill 会基于陷阱库匹配根因。
+
+| 症状 | 陷阱 | 排查 |
+|---|---|---|
+| 地图黑屏，无报错 | P1 / P3 | `setBaseUrl` 时机；地形用 `setTerrain` 而非 `terrainProvider =` |
+| 模型不显示 | P2 / P5 | `tileset.ready(cb)` 是否异步；MaterialProperty 是否改子字段 |
+| Workers 404 | P3 / P4 | 检查 baseUrl；webpack 加 IgnorePlugin |
+| `punycode` / `IPv6` 报错 | P4 | webpack AMD IgnorePlugin |
+| 材质改值视觉无变化 | P5 | 整体赋新对象，不要改 `.red` / `.x` 等子字段 |
+| 双击 HTML 白屏 | P6 | 必须 HTTP 服务打开，不能 `file://` |
+| `Cesium.X` undefined | P7 | 用 `window.Cesium` 或 `ANOVGIS.Cesium` |
+
+---
+
+## 12 个 Skill 速览
+
+| # | Skill | 一句话 | 触发关键词（精选） |
+|---|---|---|---|
+| 1 | `using-anovgis` | 入口：CDN/npm 引入、最小 Viewer、12 skill 路由表、Demo 路由表 | ANOVGIS、@anov/gis、新建项目、quickstart、demo、xxx.html |
+| 2 | `anovgis-viewer` | Viewer 扩展参数、Util/Transform、事件枚举、flyTo、skybox | Viewer、坐标系、flyTo、skybox、defaultView |
+| 3 | `anovgis-imagery-terrain` | ImageryLayerFactory、TerrainFactory、卷帘、暗色、离线底图 | 天地图、WMS、WMTS、地形、卷帘、4490、deployConfig |
+| 4 | `anovgis-layers` | 14 个要素图层（GeoJSON / 3D Tiles 容器 / CZML / KML / ClusterLayer / 4490 矢量瓦片）| 图层、GeoJSON、CZML、KML、4490、cluster、HTML 图层 |
+| 5 | `anovgis-vector-graphics` | Vector 16 + Model 2 类 + bindPopup 基础用法 + customshader + ThreeLayer + divInfo | Point、Polyline、Polygon、Tileset、customshader、divInfo |
+| 6 | `anovgis-models-3dtiles` | Model + 3D Tiles + 抽壳 + 倾斜摄影 + TilesetEditor + 位姿编辑 | Model、Tileset、3dtiles、qingxieTileset、quShouBengZhan、TilesetEditor |
+| 7 | `anovgis-primitives` | Primitive 19 类（雷达 / 尾迹 / 流动 / 扩散墙 / 水面 / 云 / 光柱 / 弹跳）| Primitive、ScanCircle、TrailLine、FlowLine、WaterPrimitive、Cloud |
+| 8 | `anovgis-popup-widget` | Popup / Tooltip / bindPopup / bindTooltip / highlight / tilesetpopup / imagerylayerpopup | Popup、Tooltip、bindPopup、highlight、tilesetpopup、divInfo |
+| 9 | `anovgis-materials` | 18 个 MaterialProperty + shader 注册 + P5 陷阱 + 抛物线 / 图片雷达 / shadertoy | material、PolylineFlowMaterial、WaterMaterial、parabola、imgrader |
+| 10 | `anovgis-analysis` | 标绘 / 测量 / 剖切 / 热力图 / 风场 / 水淹 / 三轴编辑 / Geocoder / WFS | 标绘、measure、TerrainClipping、HeatMap、WindLayer、PositonEditor、geocoder |
+| 11 | `anovgis-effects` | 天气 / 漫游 / 动画 / 后期处理（Bloom / 夜视 / 景深 / 黑白）+ 天空盒 | weather、roaming、AroundPoint、FlyManager、bloom、skybox |
+| 12 | `anovgis-pitfalls` | Cesium 1.143 + v1.8.6 典型陷阱（P0–P12）+ 自定义图元报错 | 黑屏、白屏、不生效、报错、Workers 404、AMD、CustomPrimitive |
+
+完整路由（用户意图 → skill）见 `skills/using-anovgis/SKILL.md`；完整 demo 路由（demo 文件名 → skill）见 [`skills/using-anovgis/DEMO-SKILL-MAP.md`](skills/using-anovgis/DEMO-SKILL-MAP.md)。
+
+另外 15 个 Cesium skill 由官方 `cesiumjs-skills` 提供（`cesiumjs-3d-tiles` / `cesiumjs-camera` / `cesiumjs-primitives` …），
+`using-cesiumjs-skills` 是它们的入口 —— 由 `using-anovgis` 自动转过去，你一般不用直接调用。