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

package/RELEASING.md

@@ -0,0 +1,162 @@
+# 发版与贡献
+
+PR 到 GitLab `zhf/anov-gis-skills` 主仓。本文两件事：**改 skill 的规范**、**怎么发一个版**。
+
+---
+
+## 一、贡献规范
+
+### 新增 skill 要求
+
+- 目录名格式：`anovgis-<name>`（如 `anovgis-three-layer`）
+- `SKILL.md` 是入口，**本身 ≤ 400 行**；重的部分拆成同目录子文件（`REFERENCE.md` 速查表 / `DEMO-MAP.md` 场景路由 / `templates/` 工程骨架 / `examples/` 可跑示例），子文件仍是 skill 的一部分，靠 SKILL.md 里的指针跳转
+- frontmatter 必填字段：`name`、`description`、`anov-gis-baseline`、`cesium-baseline`
+- description 含 "Use when..." 短语列表 + 触发关键词
+- 必含章节：Out-of-scope / Version baseline / Quickstart / 类速查表 / Snippet / 反模式
+- 在 `skills/using-anovgis/DOMAINS.md` § 1 标注该 skill 拥有的类条目
+- 在 `skills/using-anovgis/DEMO-SKILL-MAP.md` 标注覆盖的 demo
+- 在 `skills/using-anovgis/SKILL.md` 路由表中添加该 skill
+
+### 修改现有 skill 要求
+
+- 保持 description 关键词密度（每 50 字至少 1 个具体 API / demo 文件名关键词）
+- 新增 snippet 必须带 `// 来源: ...` 注释
+- Out-of-scope 章节变动要同步更新 DOMAINS.md § 3 反归属清单
+
+### 铁律
+
+- **不要手工改版本号** —— `scripts/bump.mjs` 是唯一来源，`--check` 会把任何漏改 / 多改揪出来
+- **不要在 skill 里写逃出所属 skills 树的相对链接** —— skill 会被拷到 `<agent>/skills/<name>/` 单个目录，逃出去的链接必断。`scripts/check-structure.mjs` 与 `scripts/build-npm.mjs` 都会拦（`skills/` 与 `vendor/cesiumjs-skills/skills/` 各算一棵树）
+- **不要手改 `vendor/cesiumjs-skills/`** —— 那是上游 Apache-2.0 内容的原样副本，改动会在下次 `sync-cesium.mjs` 时被覆盖。要改就在上游改，再同步回来
+- **不要给 SKILL.md frontmatter 加 `version:` 字段** —— 非 schema 键，`bump.mjs --check` 会拒绝
+- **不要改 skill 目录名** —— 装到用户机器上后是按 `name` 字段寻址，目录名只是本地约定
+- **SDK 已封装的能力不要用 Cesium.\* 自拼** —— 天地图 / 地形 / 模型等一律走 `@anov/gis` 的封装
+
+---
+
+## 二、语义化版本纪律
+
+团队在 `.claude/settings.json` 的 `enabledPlugins` 里用 `anov-gis-skills@anov-gis-skills@^0.3.0` 这种 **锁 minor** 的方式安装，版本号怎么涨直接决定用户收到什么：
+
+| 变更类型 | 版本怎么涨 | 用户收到吗 |
+|---|---|---|
+| 修 bug、改 skill 内容、加 snippet | **patch**（0.2.x → 0.2.x+1） | ✅ 自动收到（`autoUpdate` 开着） |
+| 新增 skill、**改 skill 名或目录结构** | **minor**（0.2.x → 0.3.0） | ❌ 不自动跟，需显式改安装串 |
+| skill 目录内新增子文件（`REFERENCE.md` / `templates/` / `examples/`） | **patch** | skill 的 `name` 与顶层结构未变，对所有智能体的寻址方式无影响 |
+| 同步 vendor 的 Cesium skill（上游更新） | **patch** | 用户重跑 `setup` 即拿到 |
+| 改动 CLI 命令族 / 新增安装方式 | **minor** | 安装方式变了，需显式改文档与流程 |
+| 破坏性契约变更 | **major**（0.x → 1.0.0） | ❌ 不自动跟 |
+
+因为 skill 名和目录结构从 v0.1.1 至今没变过，**日常发版只用 patch**。
+
+**改版本号只有一个入口**：
+
+```bash
+node scripts/bump.mjs patch      # 例：0.2.15 → 0.2.16，同时插 CHANGELOG 条目
+node scripts/bump.mjs --check    # 校验所有版本位一致（发版前自检，不一致就 fail）
+```
+
+不要手工去改 `INSTALL.md` / `RELEASING.md` / `skills/using-anovgis/*.md` 里的版本号 —— `bump.mjs` 是唯一来源，`--check` 会把任何漏改 / 多改的地方揪出来（`skills/using-anovgis/DEMO-SKILL-MAP.md` 之前就长期停在 v0.2.0，正是这个闸门要防的事）。
+
+---
+
+## 三、发版流程
+
+`@anov/gis` 升级到 1.9.x 后（未来），或任何一次 skill 内容变更后：
+
+1. 在 ANOV-GIS 仓库拉新版源码：`git pull`
+2. 对比 ANOV-GIS 仓库 `src/` 与本仓库各 `skills/*/SKILL.md`：
+   - 新增类 → 加到对应 skill 的速查表 + snippet
+   - 删除类 → 从 skill 移除
+   - 改名 / 移动 → 更新 DOMAINS.md 归属表
+3. 检查行号是否漂移：v1.8.4 → v1.8.6 抽样核对显示 DEF_OPTS 等顶部声明稳定，但新文件（如 `PositonEditor`/`TilesetEditor`）需要作为新章节追加
+4. 检查 DOMAINS.md「空白域待补」清单是否需要更新
+5. 跑 `grep -r "v1.8.6" skills/` 确认每个 skill 顶部 baseline 字段同步
+6. 跑 trigger 复测：5 个真实提问覆盖新 API
+7. **改 skill 内容 + 更新 CHANGELOG.md**
+8. **bump 版本号**：`node scripts/bump.mjs patch`（或 `minor` / `major` / `--set <版本>`）—— 一次改掉所有版本位
+9. **自检**：`node scripts/bump.mjs --check` —— 不一致就 exit 1
+10. **结构自检**：`node scripts/check-structure.mjs` —— 相对链接 / 锚点 / frontmatter / 章节完整性，不一致就 exit 1
+11. **npm 包自检**：`node scripts/build-npm.mjs` —— 校验两棵 skill 树的相对链接、无本机绝对路径、vendor 齐全（15 个 skill + LICENSE + NOTICE），不一致就 exit 1
+11b. **vendor 一致性**（改动过 Cesium skill 时）：`node scripts/sync-cesium.mjs --check` —— vendor 与内网镜像不一致就 exit 1；需要更新时去掉 `--check` 重新同步，并核对 `vendor/cesiumjs-skills/NOTICE` 里的版本号
+12. **提交推送**：用 `npm run release` 时自动完成 —— 只 `git add` bump 改写的发版文件后 commit + push（`--no-commit` 可只改文件不提交）。手工流程则 `git add` 发版文件 + `git commit -m "chore: release v<X.Y.Z>"` + `git push`
+13. **打 tag**：用 `npm run release` 时自动打 `anov-gis-skills--v<版本>` 注解 tag 并推送；不走 release 时按 §四 手工打
+14. **发 npm 包**（方式 A 的分发源）：`npm publish` —— 发到哪由仓库根 `.npmrc` 决定（内网 / 公网），见 §五
+15. **验证已发布的包**：`node scripts/verify-published.mjs` —— 确认可安装、内容与源码一致、CLI 能发现全部 skill、链接全解析，不一致就 exit 1
+
+> v0.2.15 起，第 8 步之前的手工改版本号（各 manifest + DOMAINS.md + DEMO-SKILL-MAP.md）全部由 `scripts/bump.mjs` 代劳，避免版本漂移。
+>
+> 用 `npm run release` 时，第 8–13 步（bump · 版本校验 · 结构校验 · npm 包校验 · 提交推送 · 打 tag）会一并自动执行；两道结构校验在写文件之前跑，失败则什么都不会改。
+
+---
+
+## 四、tag
+
+本仓库**不跑 CI**（内网 GitLab 上没有 runner），没有流水线帮你打 tag —— `npm run release` 会自动打并推送，手工发版时用下面的命令。
+
+**打 tag** —— 带版本约束的安装串（`"anov-gis-skills@anov-gis-skills@^0.3.0"`）靠这个 tag 解析版本，没有匹配 tag 会报 `no-matching-tag`：
+
+```bash
+VERSION=$(node -p "require('./.claude-plugin/plugin.json').version")
+git tag -a "anov-gis-skills--v${VERSION}" -m "release ${VERSION}"
+git push origin "anov-gis-skills--v${VERSION}"
+```
+
+不带约束的安装（`"anov-gis-skills@anov-gis-skills": true`）只认 marketplace 里的版本号，**不依赖 tag** —— 但 tag 仍是不可变的发布点，建议每次发版都打。
+
+> tag 已存在时跳过重复打，避免覆盖历史注解。
+
+---
+
+## 五、npm 包发版
+
+跟 tag 一样要人工执行。**默认发到公网 npm**（`https://registry.npmjs.org/`）—— 内网直连公网即可安装，用户不需要配任何 registry。
+
+```bash
+npm publish
+```
+
+> ⚠️ **发布目标由仓库根 `.npmrc` 控制**（与 ANOV-GIS 仓库 `@anov/gis` 的做法一致）。`.npmrc` 里 `registry=` 那行启用哪个就发到哪个；两行都注释掉则回退到全局默认。
+>
+> ⚠️ **`package.json` 里不能有 `publishConfig.registry`** —— 它会**覆盖** `.npmrc`，把这个开关锁死。`scripts/bump.mjs --check` 会拦。
+>
+> ⚠️ **npmjs.org 账号开了双因素认证** —— `npm publish` 要 OTP 验证码：`npm publish --otp=<6位码>`。没带 OTP 会报 `EOTP`。
+>
+> ⚠️ **同版本号不能重发**（内网 Verdaccio 报 `409 Conflict`，`--force` 也不行）。改了内容就得 bump 一个新版本再发。
+
+### 发版前自检
+
+```bash
+node scripts/bump.mjs --check       # 版本一致性（含 package.json 与 manifest 同步）
+node scripts/check-structure.mjs    # 结构 / 链接 / 锚点
+node scripts/build-npm.mjs          # 包内容（链接不逃出 skills/ 树、无本机路径）
+```
+
+### 发完验证
+
+```bash
+node scripts/verify-published.mjs
+```
+
+验五件事：
+
+| # | 验什么 | 失败意味着 |
+|---|---|---|
+| 1 | registry 上查得到该版本，元数据齐全（version / bin / engines / license） | 包没发上去，或发到了别的 registry |
+| 2 | 能真的装下来（tarball 可下载可解包） | tarball 损坏 / registry 权限问题 |
+| 3 | 装出来的 skill 与仓库源码**逐字节一致** | `files` 白名单漏了文件，或发了旧版本 |
+| 4 | skills CLI 能发现**全部 12 个** skill | frontmatter 没被严格 YAML 解析（v0.2.17 踩过：只发现 10/12） |
+| 5 | skill 内相对链接在拷贝安装语义下**全部可解析** | 有链接逃出 `skills/` 树，别的机器上会断 |
+
+出问题时会逐条列出并以**退出码 1** 结束，可以直接挂到流水线里。
+
+指定 registry / 版本：
+
+```bash
+node scripts/verify-published.mjs --registry https://registry.npmjs.org/
+node scripts/verify-published.mjs --version 0.2.19
+```
+
+> ⚠️ **npm 包版本号与 plugin 版本号必须一致** —— `scripts/bump.mjs` 会同时改两处，`--check` 会把它们揪出来。别手工改 `package.json` 的 `version`。
+>
+> ⚠️ **公网包里的内网信息**：`skills/anovgis-imagery-terrain/SKILL.md` 的三处瓦片服务示例地址是内网真实服务，外部网络访问不到。README / package.json / CHANGELOG 里的内网 GitLab 地址已全部移除（改为占位说明）。

package/bin/anov-gis-skills.mjs

@@ -0,0 +1,470 @@
+#!/usr/bin/env node
+// @anov/gis-skills-cli —— 把 anov-gis 与 Cesium 两套 skill 装到 AI 编码智能体，
+// 并把 anov-gis-mcp 的 MCP 条目写进各智能体的配置。
+//
+//   anov-gis-skills setup        装全部 skill（+ 写 MCP 配置）
+//   anov-gis-skills mcp add      只写 MCP 配置
+//   anov-gis-skills mcp remove   删掉 MCP 配置
+//   anov-gis-skills mcp show      看当前配置状态
+//   anov-gis-skills doctor        自检
+//   anov-gis-skills uninstall     清理
+//
+// 底层用 vercel-labs 的 skills CLI（npm 包 `skills`）搬 skill —— 它管着 30+ 智能体的
+// skills 目录映射。锁 1.5.18 而不是 latest：1.6.0+ 的 engines 要求 node >= 22.20.0，
+// 而团队环境实测是 node 22.19.0，锁低版本才能在 node >= 18 全覆盖。
+//
+// MCP 配置由我们自己写（lib/mcp-config.mjs），不引第三方库 —— 只覆盖我们真正常用的
+// 几个智能体，且只动自己那一个条目。
+
+import { spawnSync } from "node:child_process";
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+import {
+  MCP_SERVER_NAME,
+  SUPPORTED_AGENTS,
+  agentTargets,
+  buildServerConfig,
+  collectEnv,
+  readServer,
+  removeServer,
+  writeServer,
+} from "../lib/mcp-config.mjs";
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const SKILLS_DIR = join(PKG_ROOT, "skills");
+const CESIUM_DIR = join(PKG_ROOT, "vendor", "cesiumjs-skills", "skills");
+const SKILLS_CLI = "skills@1.5.18";
+
+const MCP_PACKAGE = "anov-gis-mcp";
+const DEFAULT_MCP_AGENTS = ["claude-code", "codex"];
+
+// 用 npx 跑时脚本在 npm 缓存的 _npx 目录里，此时 `anov-gis-skills` 不在 PATH 上，
+// 提示语必须给回 npx 形式，否则用户会撞上「不是内部或外部命令」。
+const CLI_CMD = /[\\/]_npx[\\/]/.test(process.argv[1] ?? "")
+  ? "npx @anov/gis-skills-cli"
+  : "anov-gis-skills";
+
+// ---------------------------------------------------------------- 参数解析
+
+function parseArgs(argv) {
+  const out = { _: [], agents: [], mcpAgents: [], mcpArgs: [], unknown: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-g" || a === "--global") out.scope = "global";
+    else if (a === "--project") out.scope = "project";
+    else if (a === "--scope") out.scope = argv[++i];
+    else if (a === "-y" || a === "--yes") out.yes = true;
+    else if (a === "--print") out.print = true;
+    else if (a === "--no-mcp") out.noMcp = true;
+    else if (a === "--mcp") out.mcp = true;
+    else if (a === "-a" || a === "--agent") {
+      while (argv[++i] && !argv[i].startsWith("-")) out.agents.push(argv[i]);
+    } else if (a === "--mcp-agent") {
+      while (argv[i + 1] && !argv[i + 1].startsWith("-")) {
+        for (const v of argv[++i].split(",")) if (v.trim()) out.mcpAgents.push(v.trim());
+      }
+    } else if (a === "--mcp-mode") out.mcpMode = argv[++i];
+    else if (a === "--mcp-url") out.mcpUrl = argv[++i];
+    else if (a === "--mcp-command") out.mcpCommand = argv[++i];
+    else if (a === "--mcp-arg") {
+      while (argv[++i] && !argv[i].startsWith("-")) out.mcpArgs.push(argv[i]);
+    } else if (a === "-h" || a === "--help") out.help = true;
+    else if (a.startsWith("-")) out.unknown.push(a);
+    else out._.push(a);
+  }
+  return out;
+}
+
+const HELP = `${CLI_CMD} —— 装 skill + 接 MCP
+
+用法
+  ${CLI_CMD} setup              装全部 skill（默认顺带写 MCP 配置）
+  ${CLI_CMD} mcp add            只写 MCP 配置
+  ${CLI_CMD} mcp remove         删掉 MCP 配置
+  ${CLI_CMD} mcp show           看 MCP 配置状态
+  ${CLI_CMD} doctor             自检（skill 完整性 + MCP 配置）
+  ${CLI_CMD} uninstall          清理（只删本包与本 MCP 的东西）
+
+通用选项
+  --scope global|project   装到哪（默认 global = 用户级，任何项目都能用）
+  -g, --global             等价于 --scope global
+  --project                等价于 --scope project
+  -a, --agent <名字...>    只装给指定智能体（默认：共享目录 + 已装的 Claude Code）
+  -y, --yes                跳过所有交互
+  --print                  只打印要写的内容，不落盘
+
+MCP 选项
+  --mcp-agent <名字...>    写到哪个智能体（${SUPPORTED_AGENTS.join(" / ")}；默认 claude-code + codex）
+  --mcp-mode stdio|http    连接方式（默认 stdio）
+  --mcp-url <地址>         HTTP 模式的服务地址（stdio 模式不需要）
+  --mcp-command <命令>     stdio 模式的启动命令（默认 npx）
+  --mcp-arg <参数...>      stdio 模式的参数（默认 -y anov-gis-mcp --stdio）
+  --no-mcp                 setup 时不写 MCP 配置
+`;
+
+// ---------------------------------------------------------------- 基础工具
+
+function skillNames(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(dir, d.name, "SKILL.md")))
+    .map((d) => d.name)
+    .sort();
+}
+
+/** 本包提供的全部 skill：anov-gis 12 个 + Cesium 15 个。 */
+function allSkillNames() {
+  return [...skillNames(SKILLS_DIR), ...skillNames(CESIUM_DIR)];
+}
+
+function runSkillsCLI(extra, { quiet = false } = {}) {
+  const r = spawnSync("npx", ["-y", SKILLS_CLI, ...extra], {
+    stdio: quiet ? "pipe" : "inherit",
+    shell: process.platform === "win32",
+    encoding: "utf8",
+  });
+  if (r.error) {
+    console.error(`✗ 无法启动 npx：${r.error.message}`);
+    console.error("  若 npm registry 不可达，先确认：npm config get registry");
+    process.exit(1);
+  }
+  return r.status ?? 1;
+}
+
+/** skill 装到用户级还是项目级。 */
+function scopeFlags(scope) {
+  return scope === "global" ? ["--global"] : [];
+}
+
+// 上游的自动检测会把 57 个 universal 系智能体全拉进来，其中 PromptScript 没有全局
+// 目录却仍在名单里，每个 skill 刷一条 Failed。所以这里只显式点名：
+// 共享目录 .agents/skills（universal 系智能体本来就读这里）+ 实际存在的 Claude Code。
+function defaultSkillAgents() {
+  return existsSync(join(homedir(), ".claude")) ? ["claude-code"] : ["universal"];
+}
+
+// 传 [] 时不加 --agent：remove 的上游语义是从所有智能体删，正好用来清旧的 symlink。
+function targetFlags(agents) {
+  return agents.length ? ["--agent", ...agents] : [];
+}
+
+// ---------------------------------------------------------------- setup
+
+function cmdSetup(opts) {
+  const scope = opts.scope ?? "global";
+  const agents = opts.agents.length ? opts.agents : defaultSkillAgents();
+  const anov = skillNames(SKILLS_DIR);
+  const cesium = skillNames(CESIUM_DIR);
+
+  if (!anov.length) {
+    console.error("✗ 包内找不到 skill（skills/ 目录缺失或为空）");
+    process.exit(1);
+  }
+  if (!cesium.length) {
+    console.error("✗ 找不到 vendor/cesiumjs-skills/skills —— 重新发布本包，或手工同步 vendor");
+    process.exit(1);
+  }
+
+  console.log(`\n安装 ${anov.length + cesium.length} 个 skill`);
+  console.log(`  anov-gis  ${anov.length} 个`);
+  console.log(`  cesiumjs  ${cesium.length} 个`);
+  console.log(`  范围      ${scope === "global" ? "用户级（任何项目可用）" : "项目级（当前目录）"}`);
+  console.log(`  智能体    ${agents.join(", ")}`);
+
+  for (const [label, dir] of [["anov-gis", SKILLS_DIR], ["cesiumjs", CESIUM_DIR]]) {
+    console.log(`\n── ${label} ──`);
+    const code = runSkillsCLI(["add", dir, "--agent", ...agents, ...scopeFlags(scope), "-y"]);
+    if (code !== 0) {
+      console.error(`✗ ${label} 安装失败（退出码 ${code}）`);
+      process.exit(code);
+    }
+  }
+
+  if (!opts.noMcp) {
+    const mode = opts.mcpMode ?? "stdio";
+    const config = buildServerConfig({
+      mode,
+      url: opts.mcpUrl,
+      command: opts.mcpCommand,
+      args: opts.mcpArgs.length ? opts.mcpArgs : undefined,
+      env: collectEnv(),
+    });
+    writeMcp(mcpAgents(opts), scope, config, { printOnly: opts.print, strict: opts.mcpAgents.length > 0 });
+  }
+
+  console.log("\n✓ 完成");
+  if (!opts.noMcp) {
+    console.log(`  验证：${CLI_CMD} doctor`);
+  }
+}
+
+// ---------------------------------------------------------------- MCP
+
+/** 默认 Claude Code + Codex；`--mcp-agent` 指定时只用指定的那些。 */
+function mcpAgents(opts) {
+  return opts.mcpAgents.length ? opts.mcpAgents : DEFAULT_MCP_AGENTS;
+}
+
+/**
+ * strict = 用户显式点名了智能体：不支持当前 scope 就直接报错。
+ * 默认集合则静默跳过（如 Codex 没有项目级配置），不算失败。
+ */
+function mcpTargets(agents, scope, strict) {
+  const out = [];
+  for (const agent of agents) {
+    if (!SUPPORTED_AGENTS.includes(agent)) {
+      console.error(`✗ 不支持的智能体：${agent}（可用：${SUPPORTED_AGENTS.join(" / ")}）`);
+      process.exit(2);
+    }
+    const targets = agentTargets(agent, scope);
+    if (!targets.length) {
+      if (strict) {
+        console.error(`✗ ${agent} 不支持 ${scope === "global" ? "用户级" : "项目级"}配置`);
+        process.exit(1);
+      }
+      continue;
+    }
+    out.push(...targets);
+  }
+  return out;
+}
+
+/** --print 的片段按目标格式输出：Codex 是 TOML，其余是 JSON。 */
+function printTarget(target, config) {
+  console.log(`\n# ${target.label} → ${target.file}`);
+  if (target.key !== null) {
+    console.log(JSON.stringify({ [target.key]: { [MCP_SERVER_NAME]: config } }, null, 2));
+    return;
+  }
+  const toml = (v) =>
+    typeof v === "string"
+      ? `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+      : Array.isArray(v)
+        ? `[${v.map(toml).join(", ")}]`
+        : String(v);
+  const lines = [`[mcp_servers.${MCP_SERVER_NAME}]`];
+  for (const [k, v] of Object.entries(config)) {
+    if (k !== "env") lines.push(`${k} = ${toml(v)}`);
+  }
+  if (config.env) {
+    lines.push("", `[mcp_servers.${MCP_SERVER_NAME}.env]`);
+    for (const [k, v] of Object.entries(config.env)) lines.push(`${k} = ${toml(v)}`);
+  }
+  console.log(lines.join("\n"));
+}
+
+function writeMcp(agents, scope, config, { printOnly = false, strict = false } = {}) {
+  for (const target of mcpTargets(agents, scope, strict)) {
+    if (printOnly) {
+      printTarget(target, config);
+      continue;
+    }
+    writeServer(target, MCP_SERVER_NAME, config);
+    console.log(`  ✓ ${target.label}：${target.file} → ${MCP_SERVER_NAME}`);
+  }
+}
+
+function cmdMcp(opts) {
+  const action = opts._[0] ?? "show";
+  const scope = opts.scope ?? "global";
+  const agents = mcpAgents(opts);
+  const strict = opts.mcpAgents.length > 0;
+
+  if (action === "show") {
+    for (const target of mcpTargets(agents, scope, strict)) {
+      const existing = readServer(target, MCP_SERVER_NAME);
+      console.log(`\n${target.label} —— ${target.file}`);
+      if (!existing) {
+        console.log("  · 未配置");
+      } else {
+        console.log(`  ✓ 已配置：${JSON.stringify(existing)}`);
+      }
+    }
+    return;
+  }
+
+  if (action === "remove") {
+    for (const target of mcpTargets(agents, scope, strict)) {
+      const r = removeServer(target, MCP_SERVER_NAME);
+      console.log(r.removed ? `  ✓ 已删除：${target.file}` : `  · 本来就没有：${target.file}`);
+    }
+    return;
+  }
+
+  if (action !== "add") {
+    console.error(`✗ 未知的 mcp 子命令：${action}（可用：add / remove / show）`);
+    process.exit(2);
+  }
+
+  const mode = opts.mcpMode ?? "stdio";
+  const config = buildServerConfig({
+    mode,
+    url: opts.mcpUrl,
+    command: opts.mcpCommand,
+    args: opts.mcpArgs.length ? opts.mcpArgs : undefined,
+    env: collectEnv(),
+  });
+  console.log(`\n接入 MCP（${mode}）`);
+  writeMcp(agents, scope, config, { printOnly: opts.print, strict });
+  if (!opts.print) console.log("\n✓ 完成。重启智能体生效。");
+}
+
+// ---------------------------------------------------------------- doctor
+
+function frontmatterOk(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return { ok: false, why: "缺 frontmatter" };
+  const name = /^name\s*:\s*(\S+)\s*$/m.exec(m[1]);
+  const desc = /^description\s*:/m.exec(m[1]);
+  if (!name) return { ok: false, why: "frontmatter 缺 name" };
+  if (!desc) return { ok: false, why: "frontmatter 缺 description" };
+  const descLine = m[1].split(/\r?\n/).find((l) => l.startsWith("description:"));
+  const val = descLine.slice("description:".length).trim();
+  if (!val.startsWith("'") && !val.startsWith('"') && val.includes(":")) {
+    return { ok: false, why: "description 未加引号却含冒号（严格 YAML 解析会失败）" };
+  }
+  return { ok: true, name: name[1] };
+}
+
+/** 智能体的 skills 目录（用户级 / 项目级），与 skills CLI 的落点一致。 */
+function installedSkillDirs(scope) {
+  const home = homedir();
+  const bases =
+    scope === "global"
+      ? [
+          ["Claude Code", join(home, ".claude", "skills")],
+          ["Codex", join(home, ".codex", "skills")],
+          ["通用 / Cursor", join(home, ".agents", "skills")],
+        ]
+      : [
+          ["Claude Code", join(process.cwd(), ".claude", "skills")],
+          ["Codex / 通用", join(process.cwd(), ".agents", "skills")],
+        ];
+  return bases.filter(([, dir]) => existsSync(dir));
+}
+
+function cmdDoctor(opts) {
+  const scope = opts.scope ?? "global";
+  const expected = allSkillNames();
+  let problems = 0;
+
+  console.log(`\n检查 @anov/gis-skills-cli\n`);
+  console.log(`包内 skill 数：${expected.length}`);
+
+  for (const [label, dir] of installedSkillDirs(scope)) {
+    const present = expected.filter((n) => existsSync(join(dir, n, "SKILL.md")));
+    console.log(`\n── ${label} ──  ${dir}`);
+    if (!present.length) {
+      console.log("  · 该目录没装本包的 skill（跳过）");
+      continue;
+    }
+    if (present.length === expected.length) {
+      console.log(`  ✓ ${present.length} 个 skill 齐全`);
+    } else {
+      const missing = expected.filter((n) => !present.includes(n));
+      console.log(`  ! 只装了 ${present.length}/${expected.length} 个，缺：${missing.join(", ")}`);
+      problems++;
+    }
+
+    let bad = 0;
+    for (const n of present) {
+      const r = frontmatterOk(readFileSync(join(dir, n, "SKILL.md"), "utf8"));
+      if (!r.ok) {
+        console.log(`  ✗ ${n}: ${r.why}`);
+        bad++;
+      }
+    }
+    if (!bad && present.length) console.log("  ✓ frontmatter 全部可被严格 YAML 解析");
+    if (bad) problems++;
+  }
+
+  for (const agent of SUPPORTED_AGENTS) {
+    for (const target of agentTargets(agent, scope)) {
+      const existing = readServer(target, MCP_SERVER_NAME);
+      console.log(`\n── MCP · ${target.label} ──  ${target.file}`);
+      if (existing) {
+        console.log(`  ✓ 已配置（${existing.type ?? "unknown"}）`);
+      } else {
+        console.log(`  · 未配置 —— ${CLI_CMD} mcp add`);
+      }
+    }
+  }
+
+  console.log("");
+  if (problems) {
+    console.error(`✗ 发现 ${problems} 处问题 —— 重装：${CLI_CMD} setup\n`);
+    process.exit(1);
+  }
+  console.log("✓ 检查通过\n");
+}
+
+// ---------------------------------------------------------------- uninstall
+
+function cmdUninstall(opts) {
+  const scope = opts.scope ?? "global";
+  const names = allSkillNames();
+  if (!names.length) {
+    console.error("✗ 找不到包内 skill 清单");
+    process.exit(1);
+  }
+
+  console.log(`\n移除 ${names.length} 个 skill（${scope === "global" ? "用户级" : "项目级"}）`);
+  // 只按名字删本包提供的 skill —— skills remove --skill '*' 会连别的来源的一起删掉
+  const code = runSkillsCLI(["remove", ...names, ...targetFlags(opts.agents), ...scopeFlags(scope), "-y"]);
+  if (code !== 0) {
+    console.error(`✗ 移除 skill 失败（退出码 ${code}）`);
+    process.exit(code);
+  }
+
+  const agents = mcpAgents(opts);
+  for (const target of mcpTargets(agents, scope, opts.mcpAgents.length > 0)) {
+    const r = removeServer(target, MCP_SERVER_NAME);
+    console.log(r.removed ? `  ✓ 已删除 MCP 条目：${target.file}` : `  · 没有 MCP 条目：${target.file}`);
+  }
+
+  console.log("\n✓ 清理完成");
+}
+
+// ---------------------------------------------------------------- main
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0] && !argv[0].startsWith("-") ? argv[0] : "setup";
+  const opts = parseArgs(argv[0] && !argv[0].startsWith("-") ? argv.slice(1) : argv);
+
+  if (opts.help) {
+    console.log(HELP);
+    return;
+  }
+  if (opts.unknown.length) {
+    console.error(`✗ 未知选项：${opts.unknown.join(", ")}`);
+    console.error("  用 anov-gis-skills --help 看用法");
+    process.exit(2);
+  }
+
+  switch (cmd) {
+    case "setup":
+      cmdSetup(opts);
+      break;
+    case "mcp":
+      cmdMcp(opts);
+      break;
+    case "doctor":
+    case "verify":
+      cmdDoctor(opts);
+      break;
+    case "uninstall":
+    case "remove":
+      cmdUninstall(opts);
+      break;
+    default:
+      console.error(`✗ 未知命令：${cmd}`);
+      console.error("  用 anov-gis-skills --help 看用法");
+      process.exit(2);
+  }
+}
+
+main();