# 安装细节

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 配置**、写一段 **跨智能体 GIS 协议**到 `CLAUDE.md` / `AGENTS.md` / `.cursor/rules`。
`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              # → 探测到的智能体各自的 skill 目录
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

# 不交互，直接装给探测到的全部智能体
npx @anov/gis-skills-cli setup -y

# 不碰 MCP
npx @anov/gis-skills-cli setup --no-mcp

# 不写跨智能体协议
npx @anov/gis-skills-cli setup --no-agent-protocol

# 只看要写什么，不落盘
npx @anov/gis-skills-cli setup --print
```

#### 装给谁：交互选择

没给 `--agent` 时，`setup` 会把**探测到的智能体列出来让你挑**（编号多选）：

```
检测到 5 个智能体，要装到哪些？
  [1] Claude Code       .claude/skills        上游安装
  [2] Codex             .codex/skills         拷贝 2.4M
  [3] OpenClaw          skills/               上游安装 · 落在仓库根目录
  [4] GitHub Copilot    .copilot/skills       拷贝 2.4M
  [5] 共享目录          .agents/skills        上游安装
输入编号（空格分隔，支持 1-5 区间；直接回车 = 全选）:
```

列里标了每个落点的**路径**和**安装方式** —— 自己拷贝的落点标真实体积，上游安装的由上游决定（它用「canonical 目录 + 软链」布局，字节落在哪不固定）。

**为什么值得选**：每个落点都是一份完整的 27 个 skill（2.4M），只装一个智能体 vs. 全装差 10M 以上。OpenClaw 的落点还会直接落在仓库根目录（`skills/`），多智能体共存的机器上尤其要挑。

跳过交互的三种方式：

| 情况 | 行为 |
|---|---|
| 给了 `--agent` | 直接装给点名的，不问 |
| 给了 `-y` / `--yes` | 装给探测到的全部，不问 |
| 非交互环境（管道 / CI，`stdin` 不是 TTY） | 装给探测到的全部，不问 |

输入非法会重新问；Ctrl+C / Ctrl+D 取消安装（退出码 130，不落盘）。

#### MCP 配置跟着选择走

**你点名了装给谁，MCP 配置也只写给那些** —— 否则会出现「skill 装给 Codex、MCP 却写进
Claude Code 的 `.mcp.json`」这种自相矛盾的状态（`doctor` 会把它报成半装）。

例外：`vscode` / `claude-desktop` 没有 skill 落点，用户没机会「排除」它们，它们仍按探测写。

没点名（`-y` / 非交互）时维持原样：MCP 写给所有探测到的智能体。

想让 MCP 写到别的智能体，用 `--mcp-agent` 显式点名：

```bash
npx @anov/gis-skills-cli setup --project --agent codex --mcp-agent claude-code
```

### A.3 各智能体的落点

`setup` 探测本机装了哪些智能体 —— **判定标准是「配置目录存在且非空」**（空目录不算），只装给探测到的那些：

| 智能体 | 探测目录 | skill 装到 | MCP 配置写到 |
|---|---|---|---|
| Claude Code | `~/.claude` | `~/.claude/skills/` | `~/.claude.json` 的 `mcpServers`（项目级 → `./.mcp.json`） |
| Codex | `~/.codex` | `~/.codex/skills/` | `~/.codex/config.toml` 的 `[mcp_servers.anov-gis]` |
| Cursor | `~/.cursor` | `~/.cursor/skills/` | `~/.cursor/mcp.json`（项目级 → `./.cursor/mcp.json`） |
| OpenClaw | `~/.openclaw` | `~/.openclaw/skills/` | 不支持 |
| Hermes Agent | `~/.hermes` | `~/.hermes/skills/` | 不支持 |
| Trae | `~/.trae` | `~/.trae/skills/` | 不支持 |
| Trae CN | `~/.trae-cn` | `~/.trae-cn/skills/` | 不支持 |
| Gemini CLI | `~/.gemini` | `~/.gemini/skills/` | 不支持 |
| Antigravity | `~/.gemini/config` | `~/.gemini/config/skills/` | 不支持 |
| GitHub Copilot | `~/.copilot` | `~/.copilot/skills/` | 不支持 |
| VS Code | `./.vscode` | 不支持 | `./.vscode/mcp.json` 的 `servers`（仅项目级） |
| Claude 桌面端 | `%APPDATA%/Claude` | 不支持（只能在 UI 里上传） | `claude_desktop_config.json` 的 `mcpServers` |
| 共享目录 | `~/.kimi-code` / `~/.cline` / `~/.dexto` / `~/.loaf` / `~/.warp` 等任一 | `~/.agents/skills/` | 不支持 |

> **落点为什么不全信上游。** 底层 `skills` CLI 把所有「项目级 skill 目录是 `.agents/skills`」的智能体归成一族，
> 用户级一律装到 `~/.agents/skills`。这对 Codex / Cursor / Gemini CLI / Antigravity / Copilot 都是错的 ——
> 它们各有自己的用户级目录（如 Codex 只读 `~/.codex/skills`）。这几个由本 CLI 直接复制到正确位置，
> 装完还会核对一遍落点，上游算错就兜底。

> **几个容易搞混的读法。**
> - Cursor 同时读 `~/.agents/skills/` 和 `~/.cursor/skills/`，但**只有 `~/.cursor/skills/` 会同步到 Cloud Agents**。
> - Codex 只读 `~/.codex/skills`（`~/.agents/skills` 是项目级路径）。
> - Antigravity 的 App / CLI / IDE 现在共用 `~/.gemini/config/skills/`，**App 不读 `~/.gemini/skills/`**。
> - Claude Code 桌面版（Code 标签页）与 CLI 共享 `~/.claude/skills`，装一次两边都有。
> - 「Claude 桌面端」指 claude.ai 桌面聊天端，它的 skill 只能在 UI 里上传，本 CLI 只能帮它写 MCP。

底层 `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`）—— 没装的智能体不会留配置，避免「MCP 配好了但一个 skill 都没有」的半装状态。单独管理：

```bash
npx @anov/gis-skills-cli mcp show              # 看当前状态
npx @anov/gis-skills-cli mcp add               # 补上（默认写给检测到的智能体 + 用户级）
npx @anov/gis-skills-cli mcp add --mcp-agent cursor
npx @anov/gis-skills-cli mcp remove            # 拿掉
```

参数：

| 参数 | 说明 |
|---|---|
| `--mcp-agent <名字...>` | `claude-code` / `codex` / `cursor` / `vscode` / `claude-desktop`，可指定多个；不指定就只写检测到的 |
| `--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

── skill 落点 ──
  ✓ Claude Code      C:\Users\你\.claude\skills —— 27/27 齐全
  ✓ frontmatter 全部可被严格 YAML 解析
  ✓ Codex            C:\Users\你\.codex\skills —— 27/27 齐全
  ✓ frontmatter 全部可被严格 YAML 解析
  · Cursor           C:\Users\你\.cursor\skills —— 未安装该智能体

── MCP ──

  Claude Code（用户级） —— C:\Users\你\.claude.json
  ✓ 已配置（stdio）

  Codex（用户级） —— C:\Users\你\.codex\config.toml
  ✓ 已配置（stdio）

── 一致性 ──
  ✓ 没有「MCP 配了但 skill 缺失」的半装状态
```

| 检查项 | 不通过意味着 |
|---|---|
| skill 齐全 | 装漏了，或只装了一部分（单独装部分 skill 时跨 skill 链接会失效） |
| frontmatter 可被严格 YAML 解析 | 某些 agent 的 skill 加载器会**整个跳过**这个 skill（v0.2.17 踩过：只发现 10/12） |
| MCP 已配置 | 少了条目 —— 跑 `mcp add` |
| 一致性 | 该智能体 MCP 配了但一个 skill 都没有 —— 跑 `setup` 补上 |

有问题会逐条列出并以退出码 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 应先加载 `using-anovgis`，再路由到 `anovgis-materials` 并给出溯源 snippet

> ⚠️ `/plugin` 安装不会自动写 `CLAUDE.md` / `AGENTS.md` 协议。需要强制入口加载时，把 [`skills/using-anovgis/AGENT-PROTOCOL.md`](skills/using-anovgis/AGENT-PROTOCOL.md) 的内容加到项目 `CLAUDE.md` / `AGENTS.md`，或运行 `npx @anov/gis-skills-cli setup --no-mcp`。

### 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.11`。精确锁定后**不会自动升级**，每次发版都要人工改这一行 —— 这正是 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）、`~/.agents/skills/`（Codex / Cursor / Cline 等共用一个目录）等位置
  —— 上游把「项目级目录是 `.agents/skills`」的一族都归到共享目录，Codex 的 `~/.codex/skills`、Cursor 的 `~/.cursor/skills` 不会被填；要装对请用 §方式 A
- 默认**拷贝**（`--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.7 + 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.11` 这种精确锁定**不会自动升级**，必须改这一行 |
| 提示 restart required | 重开 Claude Code 会话 |
| 想立刻跳到指定版本 | `/plugin install anov-gis-skills@anov-gis-skills@0.3.11`（降级同理） |

### 查看当前版本

```
/plugin list
/plugin details anov-gis-skills
```

### 破坏性变更

**从 v0.1.1 升级到 v0.3.11 的破坏性变更**：无。所有 v0.1.1 skill 在 v0.3.11 仍然可用；v0.2.0 新增 3 个 skill + DOMAINS 强化；v0.2.1–v0.3.11 为修复性版本（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` 复查 |
| `doctor` 报「MCP 配了但 skill 缺失」 | MCP 写了但 skill 没装上（0.3.3 的 bug：只装 Claude Code，MCP 却写了 Codex） | 重跑 `setup`（当前版本起按检测结果装齐） |
| Codex 里看不到 skill | skill 被装到了 `~/.agents/skills`，而 Codex 只读 `~/.codex/skills` | 重跑 `setup`（当前版本起直装到 `~/.codex/skills`） |
| 已装过官方 `cesiumjs-skills` 导致触发混乱 | 官方版与内网镜像版注册了同名 skill | 见 §方式 B.5 的卸载步骤二选一 |
| Chrome DevTools MCP 起不来 | 内网访问不了 npm registry | 不影响 skill 本身，可忽略 |