dsh-unity-mcp-bridge 0.8.0 → 0.9.0

package/README.md

@@ -9,7 +9,7 @@ A DeepSeek Harness (DSH) plugin that bridges a Unity MCP server (`com.ivanmurzak
 - Dormant from boot: no connection, no Unity tools — two hook tools, ~224 tokens.
 - `/unity-mcp-tools` then `unity_mcp_activate` connects and registers `mcp__unity__*`.
 - Enabled commands take effect on the **next** step; `unity_tools_restore` disables them and disconnects.
-- Ships the command catalog for plugin 1.6.0 (19 commands, RQL-first; regenerable from the offline package via `/unity-mcp-update-tools`) and the `/unity-mcp-install` / `/unity-mcp-check` / `/unity-mcp-update` / `/unity-mcp-update-tools` skills.
+- Ships the command catalog for plugin 1.6.0 (19 commands, RQL-first; regenerable from the offline package via `/unity-mcp-update-tools`) and the `/unity-mcp-install` / `/unity-mcp-delete` / `/unity-mcp-check` / `/unity-mcp-update` / `/unity-mcp-update-tools` skills.
 - `resyncAfterTools`: after a management-tool call the bridge re-fetches `tools/list` itself, because DSH's long-lived session never receives `list_changed`.
 
 ## Install
@@ -35,6 +35,7 @@ Uninstall: `dsh plugin --profile <profile> remove dsh-unity-mcp-bridge`
 | Entry | What it does |
 |---|---|
 | `/unity-mcp-install` | Installs the Unity-side plugin and the MCP Server into the workspace's Unity project |
+| `/unity-mcp-delete` | Uninstalls the Unity-MCP plugin and its extensions, cleaning config and cache leftovers |
 | `/unity-mcp-check` | Checks plugin install, port 20000, DSH bundle loading, minimal tool set and catalog version, then runs the connect test |
 | `/unity-mcp-update` | Checks the official CLI, the local `vendor/` offline package and the Unity plugin for updates; upgrades only after you agree |
 | `/unity-mcp-update-tools` | Refreshes the offline package and regenerates the `/unity-mcp-tools` command and extension indexes |

package/README.zh.md

@@ -9,7 +9,7 @@ English → [README.md](README.md)
 - 开机即休眠：不连接、不注册任何 Unity 工具，只有 2 个钩子工具（约 224 tokens）。
 - `/unity-mcp-tools` → `unity_mcp_activate` 才连接并注册 `mcp__unity__*`。
 - 开启的命令**下一步**才生效；`unity_tools_restore` 关闭它们并断开，回到休眠。
-- 随包发布插件 1.6.0 的命令目录（19 个命令，RQL-first；`/unity-mcp-update-tools` 可按新离线包重生成）与 `/unity-mcp-install`、`/unity-mcp-check`、`/unity-mcp-update`、`/unity-mcp-update-tools` 四个技能。
+- 随包发布插件 1.6.0 的命令目录（19 个命令，RQL-first；`/unity-mcp-update-tools` 可按新离线包重生成）与 `/unity-mcp-install`、`/unity-mcp-delete`、`/unity-mcp-check`、`/unity-mcp-update`、`/unity-mcp-update-tools` 五个技能。
 - `resyncAfterTools`：管理工具调用返回后桥接自己重拉 `tools/list`，不依赖 DSH 长会话收不到的 `list_changed` 通知。
 
 ## 安装
@@ -35,6 +35,7 @@ dsh plugin --profile <profile> add git+https://github.com/xiake-1/dsh-unity-mcp-
 | 入口 | 作用 |
 |---|---|
 | `/unity-mcp-install` | 给工作区里的 Unity 工程装上 Unity 侧插件与 MCP Server |
+| `/unity-mcp-delete` | 从工程里卸载 Unity-MCP 插件与扩展，并清理配置/缓存残留 |
 | `/unity-mcp-check` | 检查插件安装、端口 20000（不是就改）、DSH bundle 加载、工具集初始化、命令目录版本，再实测连通 |
 | `/unity-mcp-update` | 检查 CLI、本地离线包（`vendor/`）与 Unity 插件的新版本，问过你才更新 |
 | `/unity-mcp-update-tools` | 把离线包刷到最新并重生成 `/unity-mcp-tools` 的命令索引与扩展索引 |

package/docs/DETAILS.md

@@ -53,8 +53,9 @@ dsh plugin --profile <profile> add file:<path-to-this-checkout>
 | `keepEnabledTools` | `[]` | 恢复时额外保留的原始工具名（除 `tool-set-enabled-state` 之外）。 |
 | `registerCatalogSkill` | `true` | 是否注册随包的命令目录技能。 |
 | `skillName` | `unity-mcp-tools` | 技能名 / 斜杠命令。 |
-| `registerHelperSkills` | `true` | 是否注册四个辅助技能。 |
+| `registerHelperSkills` | `true` | 是否注册五个辅助技能。 |
 | `installSkillName` | `unity-mcp-install` | 安装 Unity 侧插件的技能名。 |
+| `deleteSkillName` | `unity-mcp-delete` | 卸载 Unity 侧插件（含扩展与残留）的技能名。 |
 | `checkSkillName` | `unity-mcp-check` | 检查「插件已装 / 端口 20000 / DSH bundle 加载 / 工具集 / 命令目录 / 能连上 DSH」的技能名。 |
 | `updateSkillName` | `unity-mcp-update` | 检查并（经用户同意后）更新官方 CLI、本地 `vendor/` 离线包与 Unity 插件的技能名。 |
 | `updateToolsSkillName` | `unity-mcp-update-tools` | 刷新本地离线包并重生成命令目录与扩展索引的技能名。 |
@@ -81,11 +82,12 @@ boot ──► DORMANT ──(/unity-mcp-tools ─► unity_mcp_activate)──
 | 技能 | 内容 |
 |---|---|
 | `/unity-mcp-install` | 检查 `unity-mcp-cli` 是否在本机（缺则 `npm install -g unity-mcp-cli`），并核对 **CLI / Unity 插件 / MCP Server 三者 lockstep**（老 CLI 的 AI agent 列表会缺项，例如没有 `kilo-code`）。在工作区内按 `ProjectSettings/ProjectVersion.txt` 定位 Unity 工程；`Packages/manifest.json` 里已有 `com.ivanmurzak.unity.mcp` 就报告，否则 `unity-mcp-cli install-plugin <project> --with-server`（同时把 `GameDev-MCP-Server` 二进制放进 CLI 托管目录 `~/.ai-game-dev/server/<rid>/`），再重读 manifest 验证。GitHub 下载失败时走本机系统代理（Clash）：端口从注册表读而不是猜，`NODE_USE_ENV_PROXY=1` 必需（Node 24 的全局 `fetch` 否则忽略 `HTTP_PROXY`），`NO_PROXY` 必须让 OpenUPM/npm 直连。最后手段：带断点续传的代理下载 + 对 release `SHA256SUMS` 校验 + `--server-source` 安装。仓库带 `vendor/` 离线包时优先离线：`tools/offline-package.mjs install` 写 Unity 官方支持的 `file:` 本地 tarball 依赖（自动备份 manifest），Server 来自缓存 zip，全新工程不联网即可装好。 |
-| `/unity-mcp-check` | 链路体检：**① Unity 工程里是否装了插件**（`Packages/manifest.json` 依赖 + `Library/PackageCache/com.ivanmurzak.unity.mcp@*`）；**② 端口是否为 20000**（Unity 侧读项目 `UserSettings/AI-Game-Developer-Config.json` 的 `host`，不是 20000 就 `bootstrap-local --url http://localhost:20000/` 改过来，先备份再改，改完必须让 Unity 重载；DSH 侧只看 profile 有没有把 url 覆盖成别的端口）；**③ DSH 依赖与 bundle**（`package.json` 依赖 + `dsh.profile.bundles` + bundle patch 里的 `unity-mcp` 行，确认没有第二份同 `serverName` 的 stock `dsh-mcp-client`）；**④ 工具集**（`configure --list` 确认只剩 `tool-set-enabled-state`；初始化必须分两条：先 `--disable-all-tools` 再 `--enable-tools tool-set-enabled-state`，合并会把唯一的开关一起关掉）；**⑤ 命令目录版本自检**（`skills/unity-mcp-tools/SKILL.md` 标题行版本 vs 项目 `PackageCache` 里的包版本，不一致就重生成 + 重启 `dsh web`）；**⑥ 连通性**（`unity_mcp_activate` 实测，`ECONNREFUSED` = 没人听、404/405 = 端点不对、401/403 = token 不对）。不做版本检查与升级（→ `/unity-mcp-update`），也不配 AI agent。 |
+| `/unity-mcp-delete` | 与 `/unity-mcp-install` 相反：定位工程 → 列出将删的 `com.ivanmurzak.unity.mcp` 与 `com.ivanmurzak.unity.mcp.*` 扩展 → 备份 `Packages/manifest.json` 与 `UserSettings/AI-Game-Developer-Config.json` → `unity-mcp-cli close --force` 关编辑器 → `unity-mcp-cli remove-plugin` 删基础包 → 手动从 manifest 移除扩展依赖 → 删配置、`Library/mcp-server` 与 `Library/PackageCache/com.ivanmurzak.unity.mcp@*` → 校验 manifest 干净。不动 DSH 桥接插件、CLI 托管 Server、其他工程与 agent 配置。 |
+| `/unity-mcp-check` | 链路体检：**① Unity 工程里是否装了插件**（`Packages/manifest.json` 依赖 + `Library/PackageCache/com.ivanmurzak.unity.mcp@*`）；**② 端口 20000 + 模式 Custom**（Unity 侧读项目 `UserSettings/AI-Game-Developer-Config.json` 的 `host` 与 `connectionMode`，不对就 `bootstrap-local --url http://localhost:20000/` 改过来并备份；Cloud 模式会跳过本地服务器自动启动，所以最后**统一重启一次编辑器**（`close --force` → `open` → `wait-for-ready`），只改 JSON 不生效；DSH 侧只看 profile 有没有把 url 覆盖成别的端口）；**③ DSH 依赖与 bundle**（`package.json` 依赖 + `dsh.profile.bundles` + bundle patch 里的 `unity-mcp` 行，确认没有第二份同 `serverName` 的 stock `dsh-mcp-client`）；**④ 工具集**（`configure --list` 确认只剩 `tool-set-enabled-state`；新工程 `tools: []` 时 `--disable-all-tools` 是空操作，必须用 `--disable-tools <命令目录里的显式名单>` 物化条目、再 `--enable-tools tool-set-enabled-state`，`tools/normalize-toolset.ps1` 封装并校验）；**⑤ 命令目录版本自检**（`skills/unity-mcp-tools/SKILL.md` 标题行版本 vs 项目 `PackageCache` 里的包版本，不一致就重生成 + 重启 `dsh web`）；**⑥ 连通性**（`unity_mcp_activate` 实测，`ECONNREFUSED` = 没人听、404/405 = 端点不对、401/403 = token 不对）。不做版本检查与升级（→ `/unity-mcp-update`），也不配 AI agent。 |
 | `/unity-mcp-update` | 检查并更新三样东西：**官方 CLI**（npm `unity-mcp-cli`）、**本地离线包**（插件自带 `vendor/`：插件 tarball + `GameDev-MCP-Server` zip + `SHA256SUMS` + `manifest.json`）、**Unity 内插件**（`com.ivanmurzak.unity.mcp`，Server 跟随插件钉住的版本）。`tools/offline-package.mjs check --project <proj> --cli-version (unity-mcp-cli --version)` 一次比「上游最新 / `vendor/` / 项目已装 / 本机 CLI」四层，只读不改。**有更新先问用户**（列出目标版本、会动哪些文件、需要重启什么），用户明确同意才更新：CLI `npm install -g unity-mcp-cli` → 离线包 `fetch --plugin-version <latest>`（只动 `vendor/`，可单独执行，不动工程、不用重启）→ 工程 `install --project`（自动备份 manifest）+ Server 按插件钉住的版本 `install-plugin --with-server --server-source <vendor zip>` → 重生成命令目录并重启 `dsh web`。用户不同意就只给报告与可复制命令。 |
 | `/unity-mcp-update-tools` | 只刷新「知识层」：把 `vendor/` 离线包升到上游最新（`offline-package.mjs fetch`，SHA256 校验 + 断点续传，Server 按新插件钉住的版本），再**依据新离线包**重生成 `skills/unity-mcp-tools/SKILL.md`、`reference/*.md` 与 `reference/extensions.md`。生成器直接读 tarball 解出的包目录（`-PackageRoot`，版本取自包内 `package.json`），不需要 Unity 工程。`extensions.md` 列出插件包 `extensions.catalog.json` 里的 10 个可选扩展及各自会带的命令（扩展命令本身仍不进索引，装完用 `unity-tool-list` 取实时清单）。只改 `<bridge>`，不碰工程内插件；最后提示重启 `dsh web`。 |
 
-四者都遵循官方安装流程 <https://ai-game.dev/engines/unity>。设 `registerHelperSkills: false` 可不发布它们。
+五者都遵循官方安装流程 <https://ai-game.dev/engines/unity>。设 `registerHelperSkills: false` 可不发布它们。
 
 ---
 

package/lib/index.js

@@ -845,13 +845,14 @@ const Config = z.union([z.object({
 	// model never sees or auto-loads it, and Unity capability never turns on by itself.
 	skillModelInvocable: z.boolean().default(false),
 	skillUserInvocable: z.boolean().default(true),
-	// Shipped helper skills: put the Unity-side plugin in (`/unity-mcp-install`), prove the
-	// bridge actually reaches it (`/unity-mcp-check`), check/offer updates (`/unity-mcp-update`),
-	// and refresh the offline package + this command catalog (`/unity-mcp-update-tools`).
-	// Model-visible by default: they are the on-ramp and the doctor, not the Unity capability
-	// itself.
+	// Shipped helper skills: put the Unity-side plugin in (`/unity-mcp-install`), remove it again
+	// (`/unity-mcp-delete`), prove the bridge actually reaches it (`/unity-mcp-check`),
+	// check/offer updates (`/unity-mcp-update`), and refresh the offline package + this command
+	// catalog (`/unity-mcp-update-tools`). Model-visible by default: they are the on-ramp and the
+	// doctor, not the Unity capability itself.
 	registerHelperSkills: z.boolean().default(true),
 	installSkillName: z.string().default("unity-mcp-install"),
+	deleteSkillName: z.string().default("unity-mcp-delete"),
 	checkSkillName: z.string().default("unity-mcp-check"),
 	updateSkillName: z.string().default("unity-mcp-update"),
 	updateToolsSkillName: z.string().default("unity-mcp-update-tools"),
@@ -880,13 +881,14 @@ const Config = z.union([z.object({
 	// model never sees or auto-loads it, and Unity capability never turns on by itself.
 	skillModelInvocable: z.boolean().default(false),
 	skillUserInvocable: z.boolean().default(true),
-	// Shipped helper skills: put the Unity-side plugin in (`/unity-mcp-install`), prove the
-	// bridge actually reaches it (`/unity-mcp-check`), check/offer updates (`/unity-mcp-update`),
-	// and refresh the offline package + this command catalog (`/unity-mcp-update-tools`).
-	// Model-visible by default: they are the on-ramp and the doctor, not the Unity capability
-	// itself.
+	// Shipped helper skills: put the Unity-side plugin in (`/unity-mcp-install`), remove it again
+	// (`/unity-mcp-delete`), prove the bridge actually reaches it (`/unity-mcp-check`),
+	// check/offer updates (`/unity-mcp-update`), and refresh the offline package + this command
+	// catalog (`/unity-mcp-update-tools`). Model-visible by default: they are the on-ramp and the
+	// doctor, not the Unity capability itself.
 	registerHelperSkills: z.boolean().default(true),
 	installSkillName: z.string().default("unity-mcp-install"),
+	deleteSkillName: z.string().default("unity-mcp-delete"),
 	checkSkillName: z.string().default("unity-mcp-check"),
 	updateSkillName: z.string().default("unity-mcp-update"),
 	updateToolsSkillName: z.string().default("unity-mcp-update-tools"),
@@ -1079,12 +1081,12 @@ function registerCatalogSkill(ctx, config) {
 	}
 }
 /**
- * The four shipped operational helper skills. `/unity-mcp-install` gets the Unity-side plugin
- * into the workspace's Unity project; `/unity-mcp-check` only proves the three things it owns
- * (plugin installed, port 20000, bridge reaches DSH); `/unity-mcp-update` checks the official CLI
- * and the Unity plugin for new versions and updates them once the user agrees;
- * `/unity-mcp-update-tools` refreshes the offline `vendor/` package and regenerates this
- * command catalog (index + extension list) from it.
+ * The five shipped operational helper skills. `/unity-mcp-install` gets the Unity-side plugin
+ * into the workspace's Unity project; `/unity-mcp-delete` removes it (and its extensions) again;
+ * `/unity-mcp-check` only proves the three things it owns (plugin installed, port 20000, bridge
+ * reaches DSH); `/unity-mcp-update` checks the official CLI and the Unity plugin for new versions
+ * and updates them once the user agrees; `/unity-mcp-update-tools` refreshes the offline
+ * `vendor/` package and regenerates this command catalog (index + extension list) from it.
  * Same best-effort contract as the catalog skill: no skill registry, no skills, no failure.
  */
 const HELPER_SKILLS = [
@@ -1093,6 +1095,11 @@ const HELPER_SKILLS = [
 		file: "../skills/unity-mcp-install/SKILL.md",
 		nameKey: "installSkillName"
 	},
+	{
+		label: "delete",
+		file: "../skills/unity-mcp-delete/SKILL.md",
+		nameKey: "deleteSkillName"
+	},
 	{
 		label: "check",
 		file: "../skills/unity-mcp-check/SKILL.md",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-unity-mcp-bridge",
-  "version": "0.8.0",
-  "description": "Opt-in Unity-MCP bridge for DeepSeek Harness: dormant by default, /unity-mcp-tools activates it, ships the 1.6.0 command catalog plus /unity-mcp-install, /unity-mcp-check, /unity-mcp-update and /unity-mcp-update-tools.",
+  "version": "0.9.0",
+  "description": "Opt-in Unity-MCP bridge for DeepSeek Harness: dormant by default, /unity-mcp-tools activates it, ships the 1.6.0 command catalog plus /unity-mcp-install, /unity-mcp-delete, /unity-mcp-check, /unity-mcp-update and /unity-mcp-update-tools.",
   "type": "module",
   "main": "lib/index.js",
   "repository": {

package/skills/unity-mcp-check/SKILL.md

@@ -42,17 +42,16 @@ Get-ChildItem (Join-Path $proj 'Library\PackageCache') -Directory -Filter 'com.i
 - 只有 manifest、没有 `PackageCache` → Unity 还没解析包：让 Unity 打开/重新加载项目一次再看。
 - 两处都没有 → **未装**：报告后交给 `/unity-mcp-install`，不要在这里装。
 
-## 2. 端口是不是 20000（不是就改）
+## 2. 端口是不是 20000、模式是不是 Custom（不对就改）
 
-**20000 是唯一标准端口。** 哪一端不是 20000，就把**那一端**改成 20000。
+**20000 是唯一标准端口；并且必须是 `connectionMode: Custom`** —— Cloud 模式不会启动本地服务器，DSH 永远连不上。
 
 ### 2.1 读现状
 
 ```powershell
-# Unity 侧：项目配置里的 host / token（configure --list 也会打印 Host）
-unity-mcp-cli configure $proj --list | Select-String 'Host'
-Get-Content (Join-Path $proj 'UserSettings\AI-Game-Developer-Config.json') -Raw |
-  Select-String '"host"|"token"|"connectionMode"'
+$cfgPath = Join-Path $proj 'UserSettings\AI-Game-Developer-Config.json'
+$cfg = Get-Content $cfgPath -Raw | ConvertFrom-Json
+$cfg.host; $cfg.connectionMode; $cfg.keepServerRunning
 
 # Unity 侧实际监听的端口（编辑器在跑时才有意义，取最后一条）
 Select-String -Path (Join-Path $proj 'Library\mcp-server\win-x64\logs\server-log.txt') `
@@ -66,23 +65,28 @@ Select-String -Path (Join-Path $prof 'cordis.patch.yml') -Pattern 'unity-mcp' -C
 
 `unity-mcp-cli status $proj` 会同时列出 **Config Server**（项目配置里的地址，就是 Unity 插件对外服务的地址）和它自己的 **Local MCP Server** 地址 —— **以 Config Server 为准**，不要被另一个端口带跑。
 
-### 2.2 Unity 侧不是 20000 → 改成 20000
+### 2.2 Unity 侧不是 20000 / 仍是 Cloud → 改配置（重启统一在 4.5）
 
-改写项目自己的配置，不是改 DSH。需要 `unity-mcp-cli`；缺了就按 `/unity-mcp-install` 第 2 步装（`npm install -g unity-mcp-cli`）。
+判定：`host` 不是 `http://localhost:20000` **或** `connectionMode` 不是 `Custom`，就执行下面整段。改写的是项目自己的配置，不是 DSH。需要 `unity-mcp-cli`；缺了就按 `/unity-mcp-install` 第 2 步装（`npm install -g unity-mcp-cli`）。
 
 ```powershell
-# 先看它会改什么，不落盘
-unity-mcp-cli bootstrap-local $proj --url 'http://localhost:20000/' --token '<项目现有 token>' --dry-run
+$cfgPath = Join-Path $proj 'UserSettings\AI-Game-Developer-Config.json'
+$cfg = Get-Content $cfgPath -Raw | ConvertFrom-Json
+$token = $cfg.token
+
+# 0) 执行前提醒用户保存未保存的场景/改动（close 会优雅退出，30s 不退则强杀）
+# 先看会改什么，不落盘
+unity-mcp-cli bootstrap-local $proj --url 'http://localhost:20000/' --token $token --dry-run
 
-# 备份后落盘
-Copy-Item (Join-Path $proj 'UserSettings\AI-Game-Developer-Config.json') `
-  (Join-Path $proj ("UserSettings\AI-Game-Developer-Config.json.bak-" + (Get-Date -Format yyyyMMdd-HHmmss)))
-unity-mcp-cli bootstrap-local $proj --url 'http://localhost:20000/' --token '<项目现有 token>'
+# 备份后落盘（Cloud → Custom，host → 20000）
+Copy-Item $cfgPath "$cfgPath.bak-$(Get-Date -Format yyyyMMdd-HHmmss)"
+unity-mcp-cli bootstrap-local $proj --url 'http://localhost:20000/' --token $token
 ```
 
-- 该命令把配置里的 `host` 改成 `http://localhost:20000`（`connectionMode` 保持 `Custom`，或从 Cloud 切到 Custom），**幂等**，可重复执行。
+- **这里先不重启**：第 4 步还要写工具集配置；所有文件改完后在 **4.5 统一重启一次编辑器**（直接 `close`/`open`，不再给别的选项）。
+- **为什么必须重启编辑器**：`McpServerManager` 是 `[InitializeOnLoad]`，静态构造函数只在**域重载**时读一次 `connectionMode`；Cloud 模式下 `StartServerIfNeeded()` 打印 `Cloud mode active, skipping local server auto-start` 后直接返回，并且该方法第一行就 `EditorApplication.update -= StartServerIfNeeded`（**只跑一次**）。所以只改 JSON 不会启动服务器。
+- `keepServerRunning` 必须是 `true`：false 时 `StartServerIfNeeded()` 同样会跳过（日志 `KeepServerRunning is false, skipping auto-start`）。
 - token 用**项目里已有的那个**，不要凭空生成；`--dry-run` 的 diff 要念给用户看。
-- **必须让 Unity 重新加载项目**（或重启编辑器），服务器才会在新端口上监听 —— 只改文件不算生效。
 - 用户明确要求保留项目原端口时**停下来问**，不要强行统一。
 
 ### 2.3 DSH 侧不是 20000 → 改回 20000
@@ -110,24 +114,46 @@ Select-String -Path (Join-Path $prof 'cordis.patch.yml') -Pattern 'unity-mcp' -C
 
 ## 4. 初始化工具集（参考 `reference/tool.md`）与命令目录版本自检
 
-Unity 侧**只留一个**可见工具 `tool-set-enabled-state`（1.6.0 起正式名 `tool-set-visibility`，旧名仍可用）：它既是唯一的"开关"，也是桥接 `unity_tools_restore` 的保留集，等于最小常驻状态。
+Unity 侧**只留一个**可见工具 `tool-set-enabled-state`（1.6.0 正式名 `tool-set-visibility`，旧名等价）：它既是唯一的"开关"，也是桥接 `unity_tools_restore` 的保留集，等于最小常驻状态。
+
+> **1.6.0 起是「可见性」而不是禁用**：默认只有 7 个核心工具可见，且管理开关本身默认隐藏。隐藏的工具仍可按名调用，但**不会出现在 `tools/list`**（不进入模型上下文，桥接激活后也注册不到），所以这一步必须把开关显式设为 visible。
 
-> **1.6.0 起是「可见性」而不是禁用**：默认只有 7 个核心工具可见，且管理开关本身默认隐藏。隐藏的工具仍可按名调用，但**不会出现在 `tools/list`**（不进入模型上下文，桥接激活后也注册不到），所以这一步必须把开关显式设为 visible，否则模型拿不到任何开关。
+**新工程不能先跑 `--disable-all-tools`**：CLI 1.6.0 的 `updateFeatures` 只修改配置里**已存在**的条目，`tools: []` 时 `--disable-all-tools` / `--enable-all-tools` 都是空操作；随后 `--enable-tools` 只 push 一条，结果仍是「默认 7 + 开关 = 8 个可见」。必须用**显式名单**把条目物化。
+
+先看现状：如果 `--list` 里已经只有开关一条 `[visible]`，且第 2 步判定无需改端口/模式，就不必重写配置，直接去 4.5（20000 已监听则连 4.5 也跳过）：
 
 ```powershell
-# 1.6.0 的 --list 打印 [visible]/[hidden]，旧版 CLI 打印 [enabled]/[disabled]
-unity-mcp-cli configure $proj --list | Select-String '\[(visible|enabled)\]'   # 先看当前状态
+unity-mcp-cli configure $proj --list | Select-String '\[(visible|enabled)\]'
+```
 
-# 必须分成两条执行 —— 见下面的顺序陷阱
-unity-mcp-cli configure $proj --disable-all-tools
+```powershell
+$prof = $env:DSH_PROFILE_DIR
+$bridge = Join-Path $prof 'node_modules\dsh-unity-mcp-bridge'
+$refDir = Join-Path $bridge 'skills\unity-mcp-tools\reference'
+$names = Get-ChildItem $refDir -Filter *.md |
+  Where-Object Name -ne 'extensions.md' |
+  ForEach-Object { Select-String -Path $_.FullName -Pattern '^- `([a-z0-9-]+)`' -AllMatches } |
+  ForEach-Object { $_.Matches } | ForEach-Object { $_.Groups[1].Value } |
+  Sort-Object -Unique
+
+# 1) 显式关掉全部基础工具（缺失条目会被 push 进配置）
+unity-mcp-cli configure $proj --disable-tools ($names -join ',')
+# 2) 只显示开关
 unity-mcp-cli configure $proj --enable-tools tool-set-enabled-state
-
-unity-mcp-cli configure $proj --list | Select-String '\[(visible|enabled)\]'   # 复验：恰好 1 条
+# 3) 复验：Tools 条目数 = 命令数（1.6.0 为 19），[visible] 恰好 1 条
+unity-mcp-cli configure $proj --list
 ```
 
-- ⚠️ **顺序陷阱（实测）**：`--disable-all-tools` 与 `--enable-tools` **不能写在同一条命令里** —— disable-all 会覆盖 enable，结果连唯一的开关 `tool-set-enabled-state` 都被隐藏（0 个可见），模型就再也看不到开关了。必须分两条：先 disable-all，再 enable-tools。
-- 万一已经被全部隐藏：单独跑一条 `unity-mcp-cli configure $proj --enable-tools tool-set-enabled-state` 即可救回，不用重装插件。
-- 复验结果应当**只有** `tool-set-enabled-state` 是 `[visible]`（旧版 CLI 显示 `[enabled]`），其余全是 `[hidden]` / `[disabled]`。注册总数随插件版本变：**1.6.0 = 19 个（默认 7 可见）**，1.2.0 = 18 个（默认 7），0.9x = 73。看到 19 不是「工具变多了」。
+- 等价脚本（插件目录 `tools\normalize-toolset.ps1`，存在时优先用）：它完成上面三步，并断言「条目数 = 目录命令数、只有开关可见」，失败返回非 0：
+
+  ```powershell
+  powershell -NoProfile -ExecutionPolicy Bypass -File "<bridge>\tools\normalize-toolset.ps1" -ProjectPath $proj
+  ```
+
+- 以上规避的是 **CLI 1.6.0 的已知行为**：`updateFeatures` 只改已有条目，空配置时 `--disable-all-tools` / `--enable-all-tools` 是空操作。上游修了之后这段仍安全（幂等）。
+- 扩展包的工具不在基础目录里：装完扩展后，激活连接再跑一次 `unity_tools_restore`，把剩余可见的扩展工具一并隐藏（开关保留）。
+- 万一被全部隐藏：单独跑 `unity-mcp-cli configure $proj --enable-tools tool-set-enabled-state` 即可救回。
+- 复验结果应当**只有** `tool-set-enabled-state` 是 `[visible]`（旧版 CLI 显示 `[enabled]`），其余全是 `[hidden]` / `[disabled]`。注册总数随插件版本变：**1.6.0 = 19 个（默认 7 可见）**，1.2.0 = 18 个（默认 7），0.9x = 73。
 - 这一步直接读写项目配置，**不需要 Unity 在运行**。
 - prompts / resources 默认全隐藏，保持关闭即可；除非用户明确要求，不要打开。
 - 需要别的命令时，交给 `/unity-mcp-tools` 的按需流程（显示 → 用 → `unity_tools_restore` 收回），不要在这里预先全开：每个可见命令的 schema 都会进入之后每一次模型请求。
@@ -145,6 +171,27 @@ unity-mcp-cli configure $proj --list | Select-String '\[(visible|enabled)\]'   #
 
   实测代价：目录停在 0.91.0 而项目已是 1.2.0 时，18 个分类文件里有 13 个写的是**已删除**的命令（`gameobject-*`、`assets-*`、`scene-*`、`profiler-*`、`console-*`、`editor-application-*`、`editor-selection-*`、`object-*`、`reflection-method-*`、`type-get-json-schema`），1.2.0 由 `rql-query` / `rql-mutate` / `rql-schema` 承担 —— 照旧目录调用必然 `tool not found`。
 
+### 4.5 重启编辑器让配置生效（直接重启，只一次）
+
+**只要第 2 步改过 host/connectionMode，或第 4 步写过工具集配置**，就在这里统一重启一次编辑器（不要在 2.2 里先重启一遍）：
+
+```powershell
+# 执行前必须让用户保存未保存的场景/改动；30s 内没优雅退出会强杀
+unity-mcp-cli close $proj --timeout 30 --force
+unity-mcp-cli open $proj
+unity-mcp-cli wait-for-ready $proj --timeout 300000
+
+# 复验
+unity-mcp-cli configure $proj --list | Select-String 'Host'
+Select-String -Path (Join-Path $proj 'Library\mcp-server\win-x64\logs\server-log.txt') `
+  -Pattern 'Start listening on port' | Select-Object -Last 1
+```
+
+- 为什么必须重启：`McpServerManager` 是 `[InitializeOnLoad]`，只在域重载时读 `connectionMode` 与工具集配置；Cloud 下 `StartServerIfNeeded()` 打印 `Cloud mode active, skipping local server auto-start` 后返回，且只跑一次。
+- Unity 本来没开时 `close` 无操作，`open` 会直接启动；首次解析包 + 起服务器可能超过 2 分钟，`wait-for-ready` 给 300s。
+- 什么都没改（第 2 步无需改 host/模式、`--list` 本就只有开关一条可见）且 20000 已在监听 → 跳过本节，直接去第 5 步。
+- 如果 `Host` 不是 20000 或日志没有 20000 监听 → 回第 2 步核对配置与模式，不要继续第 5 步。
+
 ## 5. 是否连接到 DSH（实测）
 
 ```powershell
@@ -165,7 +212,7 @@ unity-mcp-cli wait-for-ready $proj         # 最长 120s
 | 检查项 | 结果 |
 |---|---|
 | Unity 插件 `com.ivanmurzak.unity.mcp` | 已装（manifest 依赖 = …，PackageCache = …）/ 未装 → 交由 `/unity-mcp-install` |
-| Unity 侧端口 | 本来就是 20000 / 原 24009 → 已改 20000（附备份路径，需重载 Unity）/ 未改（用户要求保留） |
+| Unity 侧端口 | 本来就是 20000 + Custom / 原 24009 或 Cloud → 已改 20000 + Custom，并已重启编辑器（附备份路径） / 未改（用户要求保留） |
 | DSH 侧 url | `http://localhost:20000/mcp`（一致 / 已改 / 无覆盖行） |
 | 插件加载 | bundle 已插入 `unity-mcp` 行（0.5.0）/ bundle 为空 → 已补覆盖行 / `dsh.profile.bundles` 缺该包 |
 | 命令目录（`/unity-mcp-tools`） | 按 1.6.0 生成，与项目一致 / 按 0.91.0 生成 → 已重生成（需重启 `dsh web`） |
@@ -177,12 +224,14 @@ unity-mcp-cli wait-for-ready $proj         # 最长 120s
 
 | 现象 | 原因 | 处理 |
 |---|---|---|
-| 20000 没人听 | Unity 没开、改了配置但没重载、或服务器没启动 | 重载项目 / 在 Window → AI Game Developer 里启动服务器 |
-| 改了 host 但端口没变 | Unity 没重新加载项目 | 重启编辑器；`status` 再看 Config Server |
+| 20000 没人听 | Unity 没开、服务器没启动、或仍是 Cloud 模式 | 先看 `connectionMode`；Cloud 就 `bootstrap-local` 后**重启编辑器**（`close --force` → `open`） |
+| 日志有 `Cloud mode active, skipping local server auto-start` | 改完配置没触发域重载；`StartServerIfNeeded` 只跑一次 | `bootstrap-local` 后重启编辑器（`unity-mcp-cli close $proj --timeout 30 --force` → `open $proj` → `wait-for-ready`） |
+| 改了 host / 模式但服务器没起 | 插件静态构造只在域重载时读 `connectionMode`，只改 JSON 不生效 | 同上，重启编辑器后再看 `Start listening on port 20000` |
+| 全新工程的可见工具是 8 个（默认 7 + 开关） | `tools: []` 时 `--disable-all-tools` 是空操作（CLI 1.6.0 只改已有条目） | 按第 4 步用 `--disable-tools <显式名单>` 物化条目，再 `--enable-tools tool-set-enabled-state` |
 | manifest 里有包但连不上 | Unity 还没解析包 | 用 Unity 打开项目一次 |
 | 404 / 405 | 端点路径不对（`/mcp` ↔ `/p/<token>`） | 以 `http://localhost:20000/mcp` 为准；需要 token 路径时再补 |
 | 401 / 403 | token 缺失或过期 | 用项目配置里的 token；或 `bootstrap-local --url ... --token ...` 重新固定 |
-| 工具全被隐藏（含 `tool-set-enabled-state`） | 把 `--disable-all-tools` 与 `--enable-tools` 写进了同一条命令（上面的顺序陷阱） | 单独跑一条 `unity-mcp-cli configure $proj --enable-tools tool-set-enabled-state` 救回 |
+| 工具全被隐藏（含 `tool-set-enabled-state`） | 被 `--disable-all-tools` 或历史上写死的配置隐藏 | 单独跑一条 `unity-mcp-cli configure $proj --enable-tools tool-set-enabled-state` 救回 |
 | `mcp__unity__gameobject-find` 之类报 `tool not found` | 命令目录是按旧插件版本生成的（1.2.0 已移除 `gameobject-*` / `assets-*` / `scene-*` / `profiler-*` 等） | 按第 4 步做目录版本自检并重生成 + 重启 `dsh web`；读写 Unity 内容改走 `rql-query` / `rql-mutate` / `rql-schema` |
 | 工具名冲突 / 行为异常 | stock `dsh-mcp-client` 与桥接插件同时跑同一 `serverName` | 只留一个 |
 | 插件页显示「已安装，未生效」 | bundle 没有插入插件行（0.4.0 及以前 bundle patch 是 `[]`），或 profile 的 `dsh.profile.bundles` 里没有这个包 | 升级到 ≥0.5.0（行随 bundle 提供）；确认 `dsh.profile.bundles` 含 `dsh-unity-mcp-bridge`；重启 |

package/skills/unity-mcp-delete/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: unity-mcp-delete
+description: 从当前工作区的 Unity 工程里**卸载** Unity-MCP 插件（com.ivanmurzak.unity.mcp）及其扩展包：先备份 Packages/manifest.json 与项目配置，关闭正在运行的编辑器，用 unity-mcp-cli remove-plugin 删掉基础包，再手动移除 com.ivanmurzak.unity.mcp.* 扩展依赖，清理 UserSettings 配置与 Library 下的 mcp-server / PackageCache 残留，最后校验 manifest 已干净。与 /unity-mcp-install 相反；只删 Unity 工程里的插件，不动 DSH 桥接插件、不动 CLI 全托管 Server、不动其他工程。
+whenToUse: 用户要求「卸载 / 删除 Unity 项目里的 Unity-MCP 插件」「把 AI Game Developer 从工程里移除」「删掉后重装」时。只想删某个扩展、或只想停用连接，不要用本技能。
+---
+
+# 卸载 Unity 工程里的 Unity-MCP 插件
+
+本技能只处理**当前工作区**里的一个 Unity 工程；删除范围：
+
+| 删除 | 位置 |
+|---|---|
+| 基础包 `com.ivanmurzak.unity.mcp` | `Packages\manifest.json` 的 `dependencies`（`unity-mcp-cli remove-plugin` 负责） |
+| 扩展包 `com.ivanmurzak.unity.mcp.*`（Animation / Cinemachine / InputSystem / Navigation / ParticleSystem / ProBuilder / Splines / Terrain / Tilemap / Timeline） | 同一个 `dependencies`（CLI 不删，本技能手动删；它们依赖基础包，必须一起走） |
+| 插件配置 | `UserSettings\AI-Game-Developer-Config.json` |
+| 运行时残留 | `Library\mcp-server\`、`Library\PackageCache\com.ivanmurzak.unity.mcp@*` |
+
+**不动**：DSH 的 `dsh-unity-mcp-bridge` 插件、CLI 的全托管 Server `~\.ai-game-dev\server\<rid>\`（其他工程可能还在用）、别的 Unity 工程、`.kilocode\mcp.json` / `.agents\skills`（这些是 agent 配置，不是插件安装产物）。
+
+## 1. 定位 Unity 项目
+
+```powershell
+$ws = (Get-Location).Path
+$projects = Get-ChildItem $ws -Directory -Recurse -Depth 4 -ErrorAction SilentlyContinue |
+  Where-Object { Test-Path (Join-Path $_.FullName 'ProjectSettings\ProjectVersion.txt') } |
+  Where-Object { $_.FullName -notmatch '\\(Library|Temp|obj|node_modules|\.git)\\' } |
+  Select-Object -ExpandProperty FullName -Unique
+$projects
+```
+
+恰好 1 个 → `$proj = $projects[0]`；0 个或多个 → 停下来问用户，不要替他挑。
+
+## 2. 判断装了什么（只读）
+
+```powershell
+$manifestPath = Join-Path $proj 'Packages\manifest.json'
+$manifest = Get-Content $manifestPath -Raw | ConvertFrom-Json
+$manifest.dependencies.PSObject.Properties |
+  Where-Object { $_.Name -like 'com.ivanmurzak.unity.mcp*' } |
+  Select-Object Name, Value
+
+Get-ChildItem (Join-Path $proj 'Library\PackageCache') -Directory -Filter 'com.ivanmurzak.unity.mcp*' -ErrorAction SilentlyContinue |
+  Select-Object -ExpandProperty Name
+```
+
+- 两处都没有 → 报告「未安装，无需卸载」，**结束**。
+- 有基础包 + 扩展包 → 都要删；把将删除的包名列表念给用户。
+- 只有 `PackageCache` 残留、manifest 已无依赖 → 跳过 CLI，只清理残留（第 5 步）。
+
+## 3. 备份 + 关闭编辑器
+
+```powershell
+$stamp = Get-Date -Format yyyyMMdd-HHmmss
+Copy-Item $manifestPath "$manifestPath.bak-$stamp"
+$cfgPath = Join-Path $proj 'UserSettings\AI-Game-Developer-Config.json'
+if (Test-Path $cfgPath) { Copy-Item $cfgPath "$cfgPath.bak-$stamp" }
+
+# manifest 若带 UTF-8 BOM，CLI 的 JSON.parse 会报 "Unexpected token ''" —— 先去掉 BOM（上面已备份）
+$bytes = [System.IO.File]::ReadAllBytes($manifestPath)
+if ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
+  $text = [System.Text.Encoding]::UTF8.GetString($bytes, 3, $bytes.Length - 3)
+  [System.IO.File]::WriteAllText($manifestPath, $text, (New-Object System.Text.UTF8Encoding($false)))
+}
+
+# 正在运行就先存盘，再优雅退出；30s 不退则强杀
+unity-mcp-cli close $proj --timeout 30 --force
+```
+
+- `close` 会终止该工程的编辑器实例；**执行前必须提醒用户保存未保存的场景/改动**。
+- 编辑器没在运行 → `close` 无操作，忽略报错继续。
+- CLI 读 manifest 不做 BOM 容错；Unity 自己写出的文件通常无 BOM，但手改过的可能是 BOM UTF-8，所以上面先剥掉。
+
+## 4. 删除基础包 + 扩展包
+
+```powershell
+# 4.1 基础包（官方命令，只删 com.ivanmurzak.unity.mcp）
+unity-mcp-cli remove-plugin $proj
+
+# 4.2 扩展包（CLI 不删，手动从 manifest 移除；文件已在第 3 步备份）
+$manifest = Get-Content $manifestPath -Raw | ConvertFrom-Json
+$extIds = @($manifest.dependencies.PSObject.Properties.Name |
+  Where-Object { $_ -like 'com.ivanmurzak.unity.mcp.*' })
+foreach ($id in $extIds) { $manifest.dependencies.PSObject.Properties.Remove($id) }
+if ($extIds.Count -gt 0) {
+  $json = $manifest | ConvertTo-Json -Depth 100
+  [System.IO.File]::WriteAllText($manifestPath, $json + "`n", (New-Object System.Text.UTF8Encoding($false)))
+  "removed extensions: $($extIds -join ', ')"
+} else { 'no extension packages' }
+```
+
+- `remove-plugin` 是幂等的：已经删过会提示 not installed，不要当失败。
+- 只删 `com.ivanmurzak.unity.mcp` 与 `com.ivanmurzak.unity.mcp.*`，**不要**动 `com.unity.*`、`extensions.unity.*` 或其它依赖。
+- `scopedRegistries` 里的 OpenUPM 条目保留（其他包可能还在用），不清理。
+
+## 5. 清理项目内残留
+
+```powershell
+# 插件配置（token/host/tool 列表都在这里；重新安装时会重建）
+if (Test-Path $cfgPath) { Remove-Item $cfgPath -Force }
+
+# 插件下载的 Server 二进制与日志（Library 是生成目录，下次打开会重建）
+$serverDir = Join-Path $proj 'Library\mcp-server'
+if (Test-Path $serverDir) { Remove-Item $serverDir -Recurse -Force }
+
+# 已解析的包缓存（Unity 下次打开也会自动清；编辑器已关闭时手动删更干净）
+Get-ChildItem (Join-Path $proj 'Library\PackageCache') -Directory -Filter 'com.ivanmurzak.unity.mcp*' -ErrorAction SilentlyContinue |
+  ForEach-Object { Remove-Item $_.FullName -Recurse -Force }
+```
+
+- `Library\PackageCache` 其他包不要动。
+- `Packages\packages-lock.json` 里可能还留着条目，Unity 重新打开工程 sourcing manifest 后会自行修正；不手改。
+
+## 6. 校验
+
+```powershell
+# manifest 里不应再有该插件/扩展
+Select-String -Path $manifestPath -Pattern 'com\.ivanmurzak\.unity\.mcp'
+# 残留目录
+Get-ChildItem (Join-Path $proj 'Library\PackageCache') -Directory -Filter 'com.ivanmurzak.unity.mcp*' -ErrorAction SilentlyContinue
+# 配置与 server 目录
+Test-Path $cfgPath
+Test-Path (Join-Path $proj 'Library\mcp-server')
+```
+
+`Select-String` 无输出 + 目录都不存在 = 卸载完成。之后让用户用 Unity 打开工程一次，让包依赖重新解析（`Library/PackageCache` 会按新 manifest 重建）。
+
+## 7. 报告格式
+
+| 项 | 结果 |
+|---|---|
+| 定位到的工程 | `$proj` |
+| 已删除的包 | `com.ivanmurzak.unity.mcp` + 扩展列表（或「未安装，无需卸载」） |
+| 清理的配置/残留 | `UserSettings\AI-Game-Developer-Config.json`、`Library\mcp-server`、PackageCache 条目 |
+| 备份 | `Packages\manifest.json.bak-<stamp>`、`AI-Game-Developer-Config.json.bak-<stamp>` |
+| 未动的 | DSH 桥接插件、CLI 托管 Server、其他工程、`.kilocode`/agent 配置 |
+| 下一步 | 用 Unity 打开工程让其重新解析；之后 `/unity-mcp-check` 应报告「未装」 |
+
+## 常见故障
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| `remove-plugin` 报 not installed / 未删除 | manifest 里本来就没基础包（可能只剩扩展或文件缓存） | 正常继续第 4.2/5 步；把扩展与残留清掉 |
+| 删依赖后 Unity 仍能连上 20000 | 编辑器还开着旧域、或 `Library\mcp-server` 进程还在 | 先 `close --force` 再删；必要时任务管理器结束 `gamedev-mcp-server` |
+| 打开 Unity 后包又回来了 | 工程里还有 `Packages\packages-lock.json` 或别的 manifest 引用了该包；或误删了备份里的内容 | 检查 manifest 与 lock 文件；确认没有其他依赖指向 `com.ivanmurzak.unity.mcp` |
+| 重装后配置又出现旧 host/token | 第 5 步没删 `UserSettings\AI-Game-Developer-Config.json` | 删除该文件后重装；或重装后手工改 Custom/20000 |
+| `/unity-mcp-check` 仍显示已装 | 检查的是别的工程/`PackageCache` 还没重建 | 确认 `$proj` 路径；用 Unity 打开一次 |

package/skills/unity-mcp-install/SKILL.md

@@ -202,12 +202,26 @@ Push-Location $proj; & "$env:USERPROFILE\.ai-game-dev\server\win-x64\gamedev-mcp
 
 > ⚠️ 别对 Server 二进制跑裸 `--help`：`gamedev-mcp-server.exe --help` **不是打印帮助，而是直接启动 server**（默认 8080，会一直占着）。只有 `configure --help` 这类子命令帮助是安全的；误启动就按端口找到 PID 杀掉。
 
-然后告诉用户三条：
+然后告诉用户：
 
 1. 用 Unity 打开该项目（`unity-mcp-cli open $proj`）—— 包在编辑器里解析，`Library/PackageCache/` 才会出现。
 2. 在 Unity 里打开 **Window → AI Game Developer**，确认连接方式（自建本地端点选 Custom，或走 Cloud），并把顶部的 **AI agent** 选成要用的那个（如 **Kilo Code**）—— Skills 的自动生成只认这个下拉框，CLI 的 `setup-skills` 不支持 `kilo-code`。
-3. 回到 DSH 跑 `/unity-mcp-check`：它会检查插件是否装上、端口是否 **20000**、DSH 是否加载了插件行、工具集是否只剩 `tool-set-enabled-state`、命令目录是否与插件版本一致，最后实测连通。要查版本或升级用 `/unity-mcp-update`（检查后先问用户，同意才更新）。
-4. **本次装了或升级了插件版本 → 必须重生成桥接自带的命令目录**，否则 `/unity-mcp-tools` 会教模型去开不存在的命令（顺带刷新 `reference/extensions.md` 的可选扩展清单；也可以直接跑 `/unity-mcp-update-tools`）。命令名随插件版本变（实测 0.9x = 73 个；1.2.0 = 18 个；**分水岭是 1.0.0「RQL replaces the data tools」**，`assets-*` / `gameobject-*` / `scene-*` / `profiler-*` 等已被 `rql-query` / `rql-mutate` / `rql-schema` 取代）：
+3. **若客户端是 DSH（本地 20000）：新工程默认是 Cloud，而 Cloud 模式不会启动本地服务器。** 先让用户保存工程，再改配置并**直接重启编辑器**：
+
+   ```powershell
+   $cfgPath = Join-Path $proj 'UserSettings\AI-Game-Developer-Config.json'
+   $token = (Get-Content $cfgPath -Raw | ConvertFrom-Json).token
+   Copy-Item $cfgPath "$cfgPath.bak-$(Get-Date -Format yyyyMMdd-HHmmss)"
+   unity-mcp-cli bootstrap-local $proj --url 'http://localhost:20000/' --token $token
+   unity-mcp-cli close $proj --timeout 30 --force
+   unity-mcp-cli open $proj
+   unity-mcp-cli wait-for-ready $proj --timeout 300000
+   ```
+
+   - 插件 `McpServerManager` 是 `[InitializeOnLoad]`，**只在域重载时读一次 `connectionMode`**；Cloud 下 `StartServerIfNeeded()` 打印 `Cloud mode active, skipping local server auto-start` 后直接返回，而且该方法只跑一次 —— 只改 JSON 不会启动服务器，必须重启编辑器。
+   - 确认配置里 `keepServerRunning: true`；false 时自动启动同样会跳过。
+4. 回到 DSH 跑 `/unity-mcp-check`：它会检查插件是否装上、端口是否 **20000** 且模式是 Custom、DSH 是否加载了插件行、工具集是否只剩 `tool-set-enabled-state`、命令目录是否与插件版本一致，最后实测连通。要查版本或升级用 `/unity-mcp-update`（检查后先问用户，同意才更新）。
+5. **本次装了或升级了插件版本 → 必须重生成桥接自带的命令目录**，否则 `/unity-mcp-tools` 会教模型去开不存在的命令（顺带刷新 `reference/extensions.md` 的可选扩展清单；也可以直接跑 `/unity-mcp-update-tools`）。命令名随插件版本变（实测 0.9x = 73 个；1.2.0 = 18 个；**分水岭是 1.0.0「RQL replaces the data tools」**，`assets-*` / `gameobject-*` / `scene-*` / `profiler-*` 等已被 `rql-query` / `rql-mutate` / `rql-schema` 取代）：
 
    ```powershell
    # 桥接目录是按哪个版本生成的（SKILL.md 标题行）

package/tools/normalize-toolset.ps1

@@ -0,0 +1,107 @@
+#requires -Version 5.1
+<#
+.SYNOPSIS
+  把 Unity 工程的 MCP 工具集收敛成「只有管理开关可见」。
+
+.DESCRIPTION
+  unity-mcp-cli 1.6.0 的 updateFeatures 只修改配置里**已存在**的条目：
+  新工程的 tools 数组为空时，--disable-all-tools 是空操作，随后 --enable-tools
+  只会 push 一条，可见工具仍会是「默认 7 个 + 开关 = 8 个」。
+
+  本脚本改用显式名单（读 /unity-mcp-tools 的命令目录）把全部基础工具物化，
+  再只显示开关，最后用 `configure --list` 校验：
+    - Tools 条目数 >= 命令目录里的工具数
+    - [visible] 恰好 1 条，且就是管理开关
+
+.PARAMETER ProjectPath
+  Unity 工程路径。
+
+.PARAMETER BridgeRoot
+  插件目录（默认取本脚本上一级）。已安装副本在
+  %DSH_PROFILE_DIR%\node_modules\dsh-unity-mcp-bridge。
+
+.PARAMETER Cli
+  unity-mcp-cli 的命令名或绝对路径。
+
+.PARAMETER SwitchTool
+  要保留为可见的管理工具名（默认 tool-set-enabled-state）。
+
+.EXAMPLE
+  powershell -NoProfile -ExecutionPolicy Bypass -File tools\normalize-toolset.ps1 -ProjectPath D:\Work\Unity\MyProject
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][string]$ProjectPath,
+    [string]$BridgeRoot,
+    [string]$Cli = 'unity-mcp-cli',
+    [string]$SwitchTool = 'tool-set-enabled-state'
+)
+
+$ErrorActionPreference = 'Stop'
+
+if (-not $BridgeRoot) {
+    $BridgeRoot = Split-Path -Parent $PSScriptRoot
+    if (-not $BridgeRoot) { throw "无法推断插件目录，请用 -BridgeRoot 指定" }
+}
+
+$proj = (Resolve-Path $ProjectPath).Path
+$refDir = Join-Path $BridgeRoot 'skills\unity-mcp-tools\reference'
+if (-not (Test-Path $refDir)) {
+    throw "找不到命令目录: $refDir（先跑 /unity-mcp-update-tools 生成，或用 -BridgeRoot 指向插件目录）"
+}
+
+$names = @(Get-ChildItem $refDir -Filter *.md |
+    Where-Object { $_.Name -ne 'extensions.md' } |
+    ForEach-Object { Select-String -Path $_.FullName -Pattern '^- `([a-z0-9-]+)`' -AllMatches } |
+    ForEach-Object { $_.Matches } |
+    ForEach-Object { $_.Groups[1].Value } |
+    Sort-Object -Unique)
+
+if ($names.Count -eq 0) { throw "命令目录里没有解析到工具名: $refDir" }
+if ($names -notcontains $SwitchTool) {
+    throw "命令目录里没有 $SwitchTool —— 目录与插件版本不一致，先重生成命令目录"
+}
+
+if (-not (Get-Command $Cli -ErrorAction SilentlyContinue)) {
+    throw "找不到 $Cli；先 npm install -g unity-mcp-cli"
+}
+
+Write-Host "工程: $proj"
+Write-Host "命令目录: $($names.Count) 个工具（$BridgeRoot）"
+
+# 1) 显式名单：disable-tools 会为缺失条目 push 一条 visible=false
+& $Cli configure $proj --disable-tools ($names -join ',')
+if ($LASTEXITCODE -ne 0) { throw "configure --disable-tools 失败（exit $LASTEXITCODE）" }
+
+# 2) 只显示管理开关
+& $Cli configure $proj --enable-tools $SwitchTool
+if ($LASTEXITCODE -ne 0) { throw "configure --enable-tools 失败（exit $LASTEXITCODE）" }
+
+# 3) 校验：解析 --list 的 Tools 段（1.6.0 用 [visible]/[hidden]，旧版用 [enabled]/[disabled]）
+$list = (& $Cli configure $proj --list 2>&1 | Out-String)
+$inTools = $false
+$total = 0
+$visible = New-Object System.Collections.Generic.List[string]
+foreach ($line in ($list -split "`r?`n")) {
+    if ($line -match '^\s*Tools\s*$') { $inTools = $true; continue }
+    if ($line -match '^\s*(Prompts|Resources)\s*$') { $inTools = $false; continue }
+    if (-not $inTools) { continue }
+    $m = [regex]::Match($line, '^\s*\[(?<state>visible|hidden|enabled|disabled)\]\s+(?<name>\S+)')
+    if (-not $m.Success) { continue }
+    $total++
+    if ($m.Groups['state'].Value -in @('visible', 'enabled')) {
+        $visible.Add($m.Groups['name'].Value)
+    }
+}
+
+Write-Host "配置条目: $total  可见: $($visible.Count) [$($visible -join ', ')]"
+
+if ($total -lt $names.Count) {
+    throw "配置条目 $total 少于命令目录的 $($names.Count) —— 工具集没有完全物化"
+}
+if ($visible.Count -ne 1 -or $visible[0] -ne $SwitchTool) {
+    throw "工具集未收敛：期望只有 $SwitchTool 可见，实际可见 [$($visible -join ', ')]"
+}
+
+Write-Host "OK: 只有 $SwitchTool 可见（条目 $total / 目录 $($names.Count)）"
+exit 0