dsh-unity-mcp-bridge 0.6.0 → 0.8.0

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

@@ -27,7 +27,7 @@ if ($cli) { unity-mcp-cli --version } else { 'NOT INSTALLED' }
 - 打印 `NOT INSTALLED` → 走第 2 步。
 - 命令在但执行报错，或怀疑「装了但不在 PATH」：`npm ls -g unity-mcp-cli`（全局 bin 目录一般是 `%APPDATA%\npm`）。
 
-**版本对齐（必查，别只看「能不能跑」）**：CLI、Unity 插件、MCP Server 三者版本是 lockstep 的 —— 实测 `unity-mcp-cli 1.2.0` ↔ 插件 `com.ivanmurzak.unity.mcp@1.2.0` ↔ Server `9.2.11`（CLI 的 `dist/utils/server-version.js` 里 `DEFAULT_SERVER_VERSION` 就是插件 `McpServerManager.ServerVersion` 的镜像）。**插件钉住哪个 Server，以插件源码为准，不要猜**：1.5.0 的 tarball 里 `Editor/Scripts/McpServerManager.cs` 写死 `public const string ServerVersion = "9.2.17"`。升到 CLI 1.5.0 后实测两边同步了：`DEFAULT_SERVER_VERSION` 也是 **9.2.17**；而 `install-plugin` 到 1.5.0 **仍然没有** `--plugin-source`（离线只能走 5.2 的 `file:` 依赖）。一条命令把三层（上游最新 / 本地离线包 / 项目已装）全查出来：
+**版本对齐（必查，别只看「能不能跑」）**：CLI、Unity 插件、MCP Server 三者版本是 lockstep 的 —— 实测 `unity-mcp-cli 1.2.0` ↔ 插件 `com.ivanmurzak.unity.mcp@1.2.0` ↔ Server `9.2.11`（CLI 的 `dist/utils/server-version.js` 里 `DEFAULT_SERVER_VERSION` 就是插件 `McpServerManager.ServerVersion` 的镜像）。**插件钉住哪个 Server，以插件源码为准，不要猜**：1.5.0 的 tarball 里 `Editor/Scripts/McpServerManager.cs` 写死 `public const string ServerVersion = "9.2.17"`。升到 CLI 1.5.0 后实测两边同步了：`DEFAULT_SERVER_VERSION` 也是 **9.2.17**；而 `install-plugin` 到 1.5.0 **仍然没有** `--plugin-source`（离线只能走 5.2 的 `file:` 依赖）。一条命令把四层（上游最新 / 本地离线包 / 项目已装 / 本机 CLI）全查出来（只为安装时对齐版本；单独查更新/升级用 `/unity-mcp-update`）：
 
 ```powershell
 # <bridge> = 插件目录：源码目录，或已安装副本 %DSH_PROFILE_DIR%\node_modules\dsh-unity-mcp-bridge
@@ -35,7 +35,7 @@ $env:HTTPS_PROXY = 'http://127.0.0.1:7897'; $env:NODE_USE_ENV_PROXY = '1'   #
 node "<bridge>\tools\offline-package.mjs" check --cli-version (unity-mcp-cli --version)
 ```
 
-老 CLI 的 **AI agent 列表会缺项**：实测 0.91.0、1.2.0 与 1.5.0 的 `setup-mcp --list` 都只有 14 个 agent，**不含 `kilo-code`**；而 Server 自己的 `configure --help` 有 16 个（含 `kilo-code`、`zoo-code`、`other-custom`）。所以 `/unity-mcp-check` 要配 Kilo Code 时，CLI 再新也用不了 `setup-mcp`，必须 `configure --agent`。
+老 CLI 的 **AI agent 列表会缺项**：实测 0.91.0、1.2.0 与 1.5.0 的 `setup-mcp --list` 都只有 14 个 agent，**不含 `kilo-code`**；而 Server 自己的 `configure --help` 有 16 个（含 `kilo-code`、`zoo-code`、`other-custom`）。所以要把 AI agent 配成 Kilo Code 时，CLI 再新也用不了 `setup-mcp`，必须 `configure --agent`。
 
 ```powershell
 npm view unity-mcp-cli version          # registry 上的最新版
@@ -91,12 +91,12 @@ Get-ChildItem (Join-Path $proj 'Library\PackageCache') -Directory -Filter 'com.i
 unity-mcp-cli install-plugin $proj --with-server
 ```
 
-**默认就带 `--with-server`**：它把与本机 RID 匹配的 `GameDev-MCP-Server` 二进制装进 CLI 的**托管目录** `~\.ai-game-dev\server\<rid>\`（含 `version` 标记文件）。`/unity-mcp-check` 里的 `configure --agent <id>` 是靠这个二进制跑起来的（`proxyConfigure` 直接执行 `<托管 exe> configure --agent <id> [--url …]`，cwd = 项目根），缺它就只能退回项目自带的 `Library\mcp-server\<rid>\gamedev-mcp-server.exe`。
+**默认就带 `--with-server`**：它把与本机 RID 匹配的 `GameDev-MCP-Server` 二进制装进 CLI 的**托管目录** `~\.ai-game-dev\server\<rid>\`（含 `version` 标记文件）。`configure --agent <id>`（给 Unity 里选中的 AI agent 写客户端配置，如 Kilo Code 的 `.kilocode/mcp.json`）就是靠这个二进制跑起来的（`proxyConfigure` 直接执行 `<托管 exe> configure --agent <id> [--url …]`，cwd = 项目根），缺它就只能退回项目自带的 `Library\mcp-server\<rid>\gamedev-mcp-server.exe`。
 
 | 开关 | 用途 |
 |---|---|
-| `--with-server` | 同时下载 GameDev-MCP-Server 二进制（CLI 1.5.0 默认 **9.2.17**，与插件 `McpServerManager.ServerVersion` 同步；1.2.0 时代是 9.2.11） |
-| `--server-version <version>` | 指定要下载的 Server 版本（CLI 1.5.0 默认 9.2.17） |
+| `--with-server` | 同时下载 GameDev-MCP-Server 二进制（CLI 1.6.0 默认 **9.3.0**，与插件 `McpServerManager.ServerVersion` 同步；1.2.0 时代是 9.2.11） |
+| `--server-version <version>` | 指定要下载的 Server 版本（CLI 1.6.0 默认 9.3.0） |
 | `--server-source <path-or-url>` | 离线兜底：从本地 zip 或 URL 装 Server（**跳过 SHA256SUMS 校验**，自己核对哈希） |
 | `--plugin-version <version>` | 指定插件版本（默认 latest；离线/代理场景下显式指定可省掉一次 OpenUPM 解析） |
 | `--enroll <code>` / `--enroll-stdin` | 兑换云端 enrollment code（用自建本地端点时不需要） |
@@ -167,26 +167,26 @@ ERROR: fetch failed
 
 ### 5.2 离线本地包（插件自带 `vendor/`；给「新的 Unity 工程」用时优先走这条）
 
-插件目录下的 `vendor/` 是一份离线包缓存：`vendor/README.md`（版本/大小/SHA256/来源）+ `vendor/manifest.json`（机器可读）。当前内容：插件 `com.ivanmurzak.unity.mcp@1.5.0`（833,033 B，SHA256 `7f32ec8e…417506`）与 Server `9.2.17` win-x64（45,558,728 B，SHA256 `cb48cae2…353a0f`，已对官方 `SHA256SUMS` 校验通过）。
+插件目录下的 `vendor/` 是一份离线包缓存：`vendor/README.md`（版本/大小/SHA256/来源）+ `vendor/manifest.json`（机器可读）。当前内容：插件 `com.ivanmurzak.unity.mcp@1.6.0`（960,306 B，SHA256 `13fd2579…c5178b`）与 Server `9.3.0` win-x64（44,088,479 B，SHA256 `53a79b42…e01dc2f`，已对官方 `SHA256SUMS` 校验通过）。
 
 ```powershell
 # 1) 把工程依赖指向本地 tarball（先 --dry-run 看 diff；正式跑会自动备份 manifest）
 node "<bridge>\tools\offline-package.mjs" install --project $proj
 
 # 2) Server 也从 vendor 的 zip 装进 CLI 托管目录（不联网）
-unity-mcp-cli install-plugin $proj --with-server --server-version 9.2.17 `
-  --server-source "<bridge>\vendor\gamedev-mcp-server-win-x64-9.2.17.zip"
+unity-mcp-cli install-plugin $proj --with-server --server-version 9.3.0 `
+  --server-source "<bridge>\vendor\gamedev-mcp-server-win-x64-9.3.0.zip"
 ```
 
 要点（都实测过）：
 
-- `install-plugin` **没有** `--plugin-source`。离线靠的是 Unity 官方支持的本地 tarball 依赖：`"com.ivanmurzak.unity.mcp": "file:D:/…/vendor/com.ivanmurzak.unity.mcp-1.5.0.tgz"`（Unity 手册 *Local folder or tarball paths*：`file:` 允许绝对路径，Windows 用正斜杠）。
+- `install-plugin` **没有** `--plugin-source`。离线靠的是 Unity 官方支持的本地 tarball 依赖：`"com.ivanmurzak.unity.mcp": "file:D:/…/vendor/com.ivanmurzak.unity.mcp-1.6.0.tgz"`（Unity 手册 *Local folder or tarball paths*：`file:` 允许绝对路径，Windows 用正斜杠）。
 - 之后再跑 `unity-mcp-cli install-plugin` **不会**把它改回版本号：CLI 的 `shouldUpdateVersion` 对 `file:` / `git+` / `http:` 开头的依赖直接跳过（`dist/utils/manifest.js` 的 `nonSemverPrefixes`）。实测那行保持 `file:` 不变。
-- 目标版本从哪来：`vendor/manifest.json` 的 `plugin.pinnedServerVersion` —— 脚本从 tarball 里的 `Editor/Scripts/McpServerManager.cs` 读 `ServerVersion` 常量（1.5.0 钉住 **9.2.17**）。别拿「Server 上游最新」当目标。
-- 完全离线还剩一个小尾巴：插件的传递依赖 `extensions.unity.playerprefsex@2.1.5` 要 Unity 的 Package Manager 从 OpenUPM 解析（实测 OpenUPM 直连可达）。彻底断网的机器要么预先让 Unity 解析过一次，要么接受首次解析需要联网。
-- `file:` 依赖**不会自动升级**：升级 = 重新 `fetch` + 重新 `install`（见 `/unity-mcp-check` 的更新检查），换版本后照例重生成命令目录。
+- 目标版本从哪来：`vendor/manifest.json` 的 `plugin.pinnedServerVersion` —— 脚本从 tarball 里的 `Editor/Scripts/McpServerManager.cs` 读 `ServerVersion` 常量（1.6.0 钉住 **9.3.0**）。别拿「Server 上游最新」当目标。
+- 完全离线还剩一个小尾巴：插件的传递依赖 `extensions.unity.playerprefsex` 要 Unity 的 Package Manager 从 OpenUPM 解析（实测 OpenUPM 直连可达）。彻底断网的机器要么预先让 Unity 解析过一次，要么接受首次解析需要联网。
+- `file:` 依赖**不会自动升级**：升级 = 重新 `fetch` 刷新本地离线包 + 重新 `install` 进工程（见 `/unity-mcp-update` 的 4.2 / 4.3），换版本后照例重生成命令目录。
 - 换平台：`node "<bridge>\tools\offline-package.mjs" fetch --rid osx-arm64` 先补对应 zip，再 `--server-source` 指过去。
-- **profile 里的安装副本常常缺 zip**：43 MB 级二进制不进 git/npm，`dsh plugin add file:…` 装出来的 `node_modules\dsh-unity-mcp-bridge\vendor\` 通常只有 tarball + manifest。`install` 会明确告诉你缺不缺；缺就先 `fetch`（代理优先）补齐再跑 `--server-source`，不要拿旧版本的 zip 顶。
+- **profile 里的安装副本常常缺 zip**：40 MB 级二进制不进 git/npm，`dsh plugin add file:…` 装出来的 `node_modules\dsh-unity-mcp-bridge\vendor\` 通常只有 tarball + manifest。`install` 会明确告诉你缺不缺；缺就先 `fetch`（代理优先）补齐再跑 `--server-source`，不要拿旧版本的 zip 顶。
 
 ## 6. 验证与下一步
 
@@ -206,12 +206,12 @@ Push-Location $proj; & "$env:USERPROFILE\.ai-game-dev\server\win-x64\gamedev-mcp
 
 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**、把 AI agent 配成 **Kilo Code**（写 `.kilocode\mcp.json`）、把 Unity 工具集初始化成只留 `tool-set-enabled-state`、比对「上游 / `vendor/` / 项目」三层版本，再实测连通性。
-4. **本次装了或升级了插件版本 → 必须重生成桥接自带的命令目录**，否则 `/unity-mcp-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 跑 `/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` 取代）：
 
    ```powershell
    # 桥接目录是按哪个版本生成的（SKILL.md 标题行）
-   Select-String -Path (Join-Path $env:DSH_PROFILE_DIR 'node_modules\dsh-unity-mcp-bridge\skills\SKILL.md') `
+   Select-String -Path (Join-Path $env:DSH_PROFILE_DIR 'node_modules\dsh-unity-mcp-bridge\skills\unity-mcp-tools\SKILL.md') `
      -Pattern 'com\.ivanmurzak\.unity\.mcp@'
    # 与项目里的包版本不一致 → 重生成，然后重启 dsh web（技能在插件启动时注册，不重启不生效）
    powershell -NoProfile -ExecutionPolicy Bypass -File "<dsh-unity-mcp-bridge>\tools\generate-unity-mcp-catalog.ps1" -ProjectRoot $proj

package/skills/{SKILL.md → unity-mcp-tools/SKILL.md}

@@ -1,54 +1,59 @@
----
-name: unity-mcp-tools
-description: Unity-MCP 命令索引（分类 + 命令名），含「激活 → 按需开启 → 用完恢复休眠」工作流。需要某命令的用途或参数时，读 reference/<分类>.md。
-whenToUse: 由用户以 /unity-mcp-tools 调用：Unity 能力默认完全关闭，调用本技能后先激活，再按索引定位并开启所需命令，任务结束必须恢复休眠。
----
-
-# Unity-MCP 命令索引
-
-包 `com.ivanmurzak.unity.mcp@1.2.0` ｜ 命令 18 个（默认启用 7）｜ 生成 2026-10-19
-
-调用名 `mcp__unity__<命令名>`。**本文件只是知识，不产生能力**：Unity 侧未启用的命令无法调用（服务未运行则全部无法调用）。
-
-## 工作流程（必须遵守）
-
-**Unity 能力默认完全关闭**：插件处于休眠状态，不连接 Unity、不注册任何 `mcp__unity__*` 工具。本技能是唯一的开启入口，由用户显式调用。
-
-0. **激活** —— 先调用 `unity_mcp_activate`，建立连接并注册 Unity 工具（本技能被调用后的第一步）。
-1. **定位** —— 在本索引找到需要的能力，读对应的 `reference/<分类>.md`，拿到命令名与参数名。
-   - 索引之外的命令名（例如装了扩展包后新增的）先调 `mcp__unity__unity-tool-list` 核对，不要凭记忆猜。
-2. **开启** —— 调用 `mcp__unity__tool-set-enabled-state`，把需要的命令设为 `enabled: true`（可一次传多个）。
-   - 开启后**下一个步骤**才生效：工具注册表在请求边界重建，**不能在同一个步骤里开启并调用**。
-3. **使用** —— 下一步直接调用 `mcp__unity__<命令名>`。
-   - 读写 Unity 内容优先走 RQL：`rql-schema` 认类型 → `rql-query` 读 → `rql-mutate` 写（`dry_run: true` 先预览；改动在编辑器里 Ctrl+Z 可撤销，全有或全无）。
-4. **恢复（必做，任务结束时）** —— 调用 `unity_tools_restore`：关闭除 `tool-set-enabled-state` 以外的全部已开启命令，并断开连接、注销全部 `mcp__unity__*` 工具，回到休眠状态。
-   - 想保留个别命令：`unity_tools_restore({ "keep": ["rql-query"] })`（仍会断开休眠）。
-
-为什么必须恢复：**每个处于开启状态的命令，其完整 JSON Schema 都会进入之后每一次模型请求**（未开启的不会）。开启是临时的、可回收的成本；忘记关闭就等于把这个成本永久留在上下文里。
-
-## 版本适配（读索引前先确认）
-
-- 本索引由插件源码生成，**命令名随包版本变**；标题行的包版本就是本索引的依据。换版本后重新生成，不要沿用旧索引。
-- **1.2.0 起**：`gameobject-*`、`assets-*`、`scene-*`、`profiler-*`、`console-*`、`editor-application-*`、`editor-selection-*`、`object-*`、`reflection-method-*`、`type-get-json-schema` 已从插件中移除，改由 `rql-query` / `rql-mutate` / `rql-schema` 承担（见 `reference/rql.md`）。按旧名字调用必然失败。
-- 扩展包（Animation / Cinemachine / InputSystem / Navigation / ParticleSystem / ProBuilder / Splines / Terrain / Tilemap / Timeline）会新增命令，本索引不含它们 —— 用 `unity-tool-list` 取实时清单。
-- 插件的 `toolFormat`（`Rql` | `Json`，1.2.0 默认 `Rql`）决定工具参数与结果的数据表示；写参数前看 `reference/<分类>.md` 的参数说明。
-
-## Package Manager (4) → `reference/package-manager.md`
-package-add, package-list, package-remove, package-search
-
-## RQL (3) → `reference/rql.md`
-rql-mutate, rql-query, rql-schema
-
-## Screenshot (4) → `reference/screenshot.md`
-screenshot-camera, screenshot-game-view, screenshot-isolated, screenshot-scene-view
-
-## Script (4) → `reference/script.md`
-script-delete, script-execute, script-read, script-update-or-create
-
-## Tests (1) → `reference/tests.md`
-tests-run
-
-## Tool (2) → `reference/tool.md`
-tool-set-enabled-state, unity-tool-list
-
-
+---
+name: unity-mcp-tools
+description: Unity-MCP 命令索引（分类 + 命令名），含「激活 → 按需开启 → 用完恢复休眠」工作流。需要某命令的用途或参数时，读 reference/<分类>.md；可选扩展清单见 reference/extensions.md。
+whenToUse: 由用户以 /unity-mcp-tools 调用：Unity 能力默认完全关闭，调用本技能后先激活，再按索引定位并开启所需命令，任务结束必须恢复休眠。
+---
+
+# Unity-MCP 命令索引
+
+包 `com.ivanmurzak.unity.mcp@1.6.0` ｜ 命令 19 个（默认启用 7）｜ 生成 2026-11-01
+
+调用名 `mcp__unity__<命令名>`。**本文件只是知识，不产生能力**：Unity 侧未启用的命令无法调用（服务未运行则全部无法调用）。
+
+## 工作流程（必须遵守）
+
+**Unity 能力默认完全关闭**：插件处于休眠状态，不连接 Unity、不注册任何 `mcp__unity__*` 工具。本技能是唯一的开启入口，由用户显式调用。
+
+0. **激活** —— 先调用 `unity_mcp_activate`，建立连接并注册 Unity 工具（本技能被调用后的第一步）。
+1. **定位** —— 在本索引找到需要的能力，读对应的 `reference/<分类>.md`，拿到命令名与参数名。
+   - 索引之外的命令名（例如装了扩展包后新增的）先调 `mcp__unity__unity-tool-list` 核对，不要凭记忆猜。
+2. **开启** —— 调用 `mcp__unity__tool-set-enabled-state`（桥接保留的最小开关；1.6.0 起正式名 `tool-set-visibility`，两者等价），把需要的命令设为 `enabled: true`（或 `visible: true`；可一次传多个）。
+   - 1.6.0 起的“可见性”只决定工具是否出现在 `tools/list`（= 是否进入模型上下文）；隐藏的工具仍可按名调用，但不在索引可见列表里。
+   - 开启后**下一个步骤**才生效：工具注册表在请求边界重建，**不能在同一个步骤里开启并调用**。
+3. **使用** —— 下一步直接调用 `mcp__unity__<命令名>`。
+   - 读写 Unity 内容优先走 RQL：`rql-schema` 认类型 → `rql-query` 读 → `rql-mutate` 写（`dry_run: true` 先预览；改动在编辑器里 Ctrl+Z 可撤销，全有或全无）。
+4. **恢复（必做，任务结束时）** —— 调用 `unity_tools_restore`：隐藏除 `tool-set-enabled-state` 以外的全部已开启命令，并断开连接、注销全部 `mcp__unity__*` 工具，回到休眠状态。
+   - 想保留个别命令：`unity_tools_restore({ "keep": ["rql-query"] })`（仍会断开休眠）。
+
+为什么必须恢复：**每个处于可见状态的命令，其完整 JSON Schema 都会进入之后每一次模型请求**（隐藏的不会）。开启是临时的、可回收的成本；忘记关闭就等于把这个成本永久留在上下文里。
+
+## 版本适配（读索引前先确认）
+
+- 本索引由插件源码生成，**命令名随包版本变**；标题行的包版本就是本索引的依据。换版本后重新生成，不要沿用旧索引。
+- **1.2.0 起**：`gameobject-*`、`assets-*`、`scene-*`、`profiler-*`、`console-*`、`editor-application-*`、`editor-selection-*`、`object-*`、`reflection-method-*`、`type-get-json-schema` 已从插件中移除，改由 `rql-query` / `rql-mutate` / `rql-schema` 承担（见 `reference/rql.md`）。按旧名字调用必然失败。
+- **1.6.0 起**：`tool-set-enabled-state` 更名为 `tool-set-visibility`（旧名保留，等价；`Enabled` 字段即 `Visible`）；“启用/关闭”实际是**可见性**——只影响 `tools/list` 是否列出（即是否进入模型上下文），隐藏的工具仍可按名调用。默认只有少数核心工具可见，**管理开关本身也默认隐藏**，所以要先用 CLI 把它设为 visible，桥接激活后模型才拿得到开关。
+- 扩展包（10 个：Animation / Cinemachine / InputSystem / Navigation / ParticleSystem / ProBuilder / Splines / Terrain / Tilemap / Timeline）都是独立 UPM 包，装到工程后才新增命令；**本索引不含扩展命令** —— 可选哪些扩展、各带哪些命令见 `reference/extensions.md`，装完用 `unity-tool-list` 取实时清单。
+- 插件的 `toolFormat`（`Rql` | `Json`，1.2.0 默认 `Rql`）决定工具参数与结果的数据表示；写参数前看 `reference/<分类>.md` 的参数说明。
+
+## Package Manager (4) → `reference/package-manager.md`
+package-add, package-list, package-remove, package-search
+
+## RQL (3) → `reference/rql.md`
+rql-mutate, rql-query, rql-schema
+
+## Screenshot (4) → `reference/screenshot.md`
+screenshot-camera, screenshot-game-view, screenshot-isolated, screenshot-scene-view
+
+## Script (4) → `reference/script.md`
+script-delete, script-execute, script-read, script-update-or-create
+
+## Tests (1) → `reference/tests.md`
+tests-run
+
+## Tool (3) → `reference/tool.md`
+tool-set-enabled-state, tool-set-visibility, unity-tool-list
+
+## Extensions (10) → `reference/extensions.md`
+Animation, Cinemachine, InputSystem, Navigation, ParticleSystem, ProBuilder, Splines, Terrain, Tilemap, Timeline
+
+

package/skills/unity-mcp-tools/reference/extensions.md

@@ -0,0 +1,118 @@
+# Extensions — 10 个可选扩展
+
+来源：插件包 `com.ivanmurzak.unity.mcp@1.6.0` 内的 `extensions.catalog.json`（生成 2026-11-01）。
+
+这些是**可选扩展**，每个都是独立 UPM 包；装进 Unity 工程后才会新增命令，**且不会出现在本索引其余分类里**：
+
+- 安装：Unity 的 AI Game Developer 窗口 → Extensions → Install；或 `unity-mcp-cli install-extension <名称> <Unity工程>`。
+- 装完用 `mcp__unity__unity-tool-list`（可带 `regexSearch` / `includeInputs`）取实时清单，再用 `mcp__unity__tool-set-enabled-state` 按需开启。
+- 扩展工具随扩展版本变，本文件只保证「依据哪个插件版本的 catalog 生成」；换离线包后由 `/unity-mcp-update-tools` 重生成。
+
+## Animation — `com.ivanmurzak.unity.mcp.animation`
+
+AI-driven animation control and playback tools.
+
+- `animation-create` — Create AnimationClip assets with keyframes
+- `animation-get-data` — Inspect clip curves, events, and properties
+- `animation-modify` — Edit curves, events, and settings on a clip
+- `animator-create` — Create AnimatorController assets
+- `animator-get-data` — Inspect controller layers, states, and parameters
+- `animator-modify` — Edit parameters, states, and transitions
+
+## Cinemachine — `com.ivanmurzak.unity.mcp.cinemachine`
+
+AI-assisted Cinemachine camera setup and configuration tools.
+
+- `cinemachine-camera-create` — Create a CinemachineCamera in the scene
+- `cinemachine-set-targets` — Set the Follow and LookAt targets
+- `cinemachine-set-lens` — Configure FOV, clip planes, and dutch
+- `cinemachine-set-body` — Set the position-control component (Follow/Orbital/...)
+- `cinemachine-set-noise` — Add camera shake via Perlin noise
+
+## InputSystem — `com.ivanmurzak.unity.mcp.inputsystem`
+
+AI-assisted Unity Input System authoring: InputActionAssets, maps, actions, bindings, and control schemes.
+
+- `inputsystem-asset-create` — Create a new .inputactions InputActionAsset
+- `inputsystem-actionmap-add` — Add an ActionMap to the asset
+- `inputsystem-action-add` — Add an Action (type + expectedControlType)
+- `inputsystem-binding-add` — Add a binding path to an Action
+- `inputsystem-binding-composite-add` — Add a composite binding (2DVector/1DAxis)
+- `inputsystem-controlscheme-add` — Add a control scheme with device requirements
+- `inputsystem-get` — Read the asset's maps, actions, and bindings
+
+## Navigation — `com.ivanmurzak.unity.mcp.navigation`
+
+AI-driven NavMesh navigation: surfaces, baking, agents, and links.
+
+- `navigation-surface-add` — Add and configure a NavMeshSurface
+- `navigation-set-bake-settings` — Set agent radius/height/slope/step and voxel size
+- `navigation-surface-bake` — Bake or clear a NavMeshSurface
+- `navigation-modifier-add` — Add a NavMeshModifier (override area / ignore)
+- `navigation-modifier-volume-add` — Add a NavMeshModifierVolume
+- `navigation-link-add` — Add a NavMeshLink between two points
+- `navigation-agent-add` — Add and configure a NavMeshAgent
+- `navigation-agent-set-destination` — Set a NavMeshAgent's destination
+- `navigation-list` — List NavMeshSurfaces and NavMeshAgents
+- `navigation-get` — Serialize any NavMesh component
+- `navigation-modify` — Modify any NavMesh component via ReflectorNet
+
+## ParticleSystem — `com.ivanmurzak.unity.mcp.particlesystem`
+
+AI-powered particle system creation and control tools.
+
+- `particle-system-get` — Inspect ParticleSystem modules and settings
+- `particle-system-modify` — Modify emission, shape, color, noise, and more
+
+## ProBuilder — `com.ivanmurzak.unity.mcp.probuilder`
+
+AI-assisted ProBuilder geometry modeling tools.
+
+- `probuilder-create-shape` — Create editable 3D primitives in the scene
+- `probuilder-get-mesh-info` — Retrieve faces, vertices, and edges data
+- `probuilder-extrude` — Extrude faces along their normals
+- `probuilder-delete-faces` — Remove faces to create holes or trim geometry
+- `probuilder-set-face-material` — Assign materials to individual faces
+
+## Splines — `com.ivanmurzak.unity.mcp.splines`
+
+AI-assisted Spline authoring: containers, knots, tangents, and evaluation.
+
+- `splines-container-create` — Create a SplineContainer in the scene
+- `splines-add-knot` — Append a knot to a spline
+- `splines-set-knot` — Set a knot's position, tangents, and rotation
+- `splines-set-tangent-mode` — Set a knot's tangent mode
+- `splines-evaluate` — Evaluate position/tangent/up along a spline
+- `splines-modify` — Modify any Splines component via ReflectorNet
+
+## Terrain — `com.ivanmurzak.unity.mcp.terrain`
+
+AI-powered Unity Terrain authoring tools.
+
+- `terrain-create` — Create a Terrain GameObject backed by new TerrainData
+- `terrain-set-heights` — Sculpt heightmap values over a region or the whole terrain
+- `terrain-paint-layer` — Paint a TerrainLayer onto the alphamap (splatmap)
+- `terrain-place-trees` — Scatter or place trees from a tree prototype
+- `terrain-set-neighbors` — Stitch neighbor Terrains so Unity blends seams
+
+## Tilemap — `com.ivanmurzak.unity.mcp.tilemap`
+
+AI-assisted 2D Tilemap creation, painting, and tile/RuleTile asset tools.
+
+- `tilemap-create` — Create a Grid + Tilemap + TilemapRenderer
+- `tilemap-set-tile` — Paint a tile into a cell
+- `tilemap-box-fill` — Fill a rectangular region with a tile
+- `tilemap-create-tile-asset` — Create a Tile asset from a Sprite
+- `tilemap-create-rule-tile` — Create a RuleTile asset (2D Tilemap Extras)
+
+## Timeline — `com.ivanmurzak.unity.mcp.timeline`
+
+AI-assisted Timeline cutscene and sequence authoring tools.
+
+- `timeline-create` — Create a TimelineAsset (.playable)
+- `timeline-track-add` — Add Animation/Activation/Audio/Signal/Control tracks
+- `timeline-clip-add` — Add clips to a track with start and duration
+- `timeline-director-bind` — Bind a TimelineAsset to a scene PlayableDirector
+- `timeline-modify` — Modify any Timeline object via ReflectorNet
+
+

package/skills/{reference → unity-mcp-tools/reference}/package-manager.md

@@ -1,6 +1,6 @@
 # Package Manager — 4 个命令
 
-调用名 `mcp__unity__<命令名>`；`[on]` = Unity 侧默认启用（可直接调），`[off]` = 默认关闭 —— 用 `mcp__unity__tool-set-enabled-state` 开启后，**从下一个步骤起可调用**（工具注册表在请求边界重建）。
+调用名 `mcp__unity__<命令名>`；`[on]` = Unity 侧默认可见（可直接调），`[off]` = 默认隐藏 —— 用 `mcp__unity__tool-set-enabled-state`（1.6.0 正式名 `tool-set-visibility`，等价）设为 visible 后，**从下一个步骤起可调用**（工具注册表在请求边界重建）。
 
 - `package-add` [off] — Install a package from the Unity Package Manager registry, Git URL, or local path.
   - 参数: packageId, requestId?

package/skills/unity-mcp-tools/reference/rql.md

@@ -0,0 +1,131 @@
+# RQL — 3 个命令
+
+调用名 `mcp__unity__<命令名>`；`[on]` = Unity 侧默认可见（可直接调），`[off]` = 默认隐藏 —— 用 `mcp__unity__tool-set-enabled-state`（1.6.0 正式名 `tool-set-visibility`，等价）设为 visible 后，**从下一个步骤起可调用**（工具注册表在请求边界重建）。
+
+- `rql-mutate` [on] — Change the live Unity Editor scene with an RQL query whose last stage is set or call.
+  - 参数: query, dry_run?, max_targets?
+  - 源码: `Editor/Scripts/API/Tool/Rql.Mutate.cs`
+- `rql-query` [on] — Run a read-only RQL query against the live Unity Editor scene and return compact rows.
+  - 参数: query
+  - 源码: `Editor/Scripts/API/Tool/Rql.Query.cs`
+- `rql-schema` [on] — Without a type: RQL sources, asset functions, the installed extensions (always active) with their guide topics, and the component types p...
+  - 参数: type?
+  - 源码: `Editor/Scripts/API/Tool/Rql.Schema.cs`
+
+### `rql-mutate` 的完整用法（插件喂给模型的原文，已按段落去重）
+
+```text
+Change the live Unity Editor scene with an RQL query whose last stage is set or call. All-or-nothing: every target and value is checked before anything is written; a failure changes nothing. Undoable: one Undo step per call (Ctrl+Z; from an agent: script-execute UnityEditor.Undo.PerformUndo(), then editor | call SaveScenes() and editor | call SaveAssets()). Changed assets, scenes and the open prefab are saved to disk automatically; an untitled scene needs SaveAs(path). dry_run=true returns the receipt ($ref, member, old, new) without changing anything. Do exactly the change requested; a read-only member fails with readonly-member instead of being approximated.
+  set path = expr, ...   assign members (paths may go through structs: set transform.position.y = transform.position.y + 1)
+                         values see each target: $ and $index (its position in the stream entering set / call)
+  call Method(args)      invoke a method the tools expose
+Examples:
+  objects | where name == "Player" | set transform.position = "(0, 1, 0)"
+  objects | get components | where $ is Light | set intensity = intensity * 2, color = "#ffcc88"
+  objects | where tag == "Enemy" | set active = false
+  objects | where name starts-with "Pillar_" | set name = name.replace("Pillar_", "Column_")   bulk rename
+  objects | where name starts-with "Crate" | sort name | set transform.position.x = $index * 2   spread along x
+  objects | where name starts-with "Coin" | set transform.localScale = transform.localScale * 1.5   vectors / colors compute per component (a color's alpha too)
+  objects | where name starts-with "Lamp" | set transform.position = transform.position + [0, 2.5, 0]
+  objects | where name starts-with "Rock" | set transform.position = [transform.position.x, 0, transform.position.z] * 2   lists of numbers are vectors
+  objects | where name starts-with "Enemy" and distance(transform.position, unity.find("Player").transform.position) < 10 | set active = false   (units: meters)
+  objects | where name == "Drone" | set transform.position = transform.position + normalize(transform.forward) * 3   also length(v), dot(a, b), lerp(a, b, t)
+  unity.asset("Assets/Mats/Red.mat") | get properties | where Key ends-with "Color" | set Value = "#ffffff"   map entries write through
+  unity.asset("Assets/Mats/Red.mat") | set properties["_Color"] = "(1, 0, 0, 1)"
+  unity.asset("Assets/Mats/Red.mat") | set parent = unity.asset("Assets/Mats/Base.mat")   make it a Material Variant of Base
+  unity.asset("Assets/Data/Items.asset") | get rows | where Category == "Tool" | set Price = round(Price * 1.15)   data asset (ScriptableObject list rows)
+  objects | where name starts-with "Pillar" | get components | where $ is MeshFilter | set sharedMesh = "Cylinder"   built-in mesh
+  objects | get components | where $ is MeshRenderer and sharedMaterial == null | set sharedMaterial = "Default-Material"   built-in material
+  objects | where name == "Crate" | get components | where $ is MeshRenderer | set sharedMaterial = {$type: "Material", color: "#ff8800"}   a new material (saved with the scene)
+  objects | where name == "Shop" | get components | where $ is ShopStock | set item = {$type: "ItemData", price: 3}   a new data ScriptableObject
+  unity.asset("Assets/Art/hero.png") | get importer | set textureType = "Sprite", spriteImportMode = "Single"   import settings (reimported)
+  objects | where name == "Spawner" | set targets = append(targets, ref("GameObject#1234"))
+Create / add / remove (call; the receipt's result column holds the new object's $ref for follow-up queries):
+  editor | call CreateGameObject("Props")                                   new root GameObject
+  editor | call CreateGameObject("Crate", ref("GameObject#1234"), "Cube")    child of a parent, optional primitive
+  range(0, 300) | call editor.CreateGameObject("Cube_" + $, {primitive: "Cube", position: [($ % 15) * 2, 0, floor($ / 15) * 2]})   with max_targets=300:
+                         bulk create, one call per item: a 15x20 grid in ONE request and ONE Undo step; the receipt lists the first 50 new objects' $refs (query the rest by name)
+  [["Crate", [0, 0, 0]], ["Barrel", [2, 0, 0]]] | call editor.CreateGameObject($[0], {primitive: "Cube", position: $[1]})   one per entry
+                         {placement}: primitive, parent: ref(…), position / rotation (Euler degrees) / scale as [x, y, z], local to the parent
+  editor | call CreateGameObject({name: "Crate", primitive: "Cube", position: [1, 0, 2], scale: [2, 2, 2]})   arguments by name: one literal, any order, the rest default
+  objects | where name == "Crate" | call AddComponent("Rigidbody")           add a component by type name
+  objects | where name == "Old" | call Destroy()                             remove a GameObject (components: get components | where $ is X | call Destroy())
+  objects | where name == "Lamp" | set transform.parent = ref("GameObject#1234")   reparent (keeps the world position)
+  objects | where name == "Crate" | call Duplicate()                          copy next to it (returns the copy)
+  objects | where name == "Main Camera" | call LookAt(unity.find("Player"))   aim at a GameObject (or a position "(0, 1, 0)")
+Scenes, prefabs, assets, Editor state:
+  editor | call OpenScene("Assets/Scenes/Level.unity")          editor | call NewScene("Assets/Scenes/New.unity")
+  scenes | where path == "" | call SaveAs("Assets/Scenes/New.unity")   scenes | where name == "Level" | call SetActive()
+  editor | call InstantiatePrefab("Assets/Prefabs/Enemy.prefab", {parent: ref("GameObject#1234"), position: [0, 0, 5]})
+  range(0, 10) | call editor.InstantiatePrefab("Assets/Prefabs/Coin.prefab", {position: [$ * 2, 1, 0]})   ten instances, one Undo step
+  objects | where name == "Crate" | call SaveAsPrefab("Assets/Prefabs/Crate.prefab")   (on a prefab instance: a Prefab Variant)
+  objects | where name == "Coin_3" | call RevertPrefabOverrides()   or ApplyPrefabOverrides() (read: select prefabSource prefabOverrides)
+  editor | call OpenPrefab("Assets/Prefabs/Enemy.prefab")  then  prefab | recurse children | …  then  editor | call ClosePrefab()
+  editor | call CreateMaterial("Assets/Mats/Glow.mat")        editor | call MoveAsset("Assets/A.mat", "Assets/Mats/A.mat")
+  editor | call RefreshAssets()   after files changed on disk: imports them, reloads a changed open scene (keeps one with unsaved edits and says so)
+  editor | set selection = [ref("GameObject#1234")]         editor | set isPlaying = true   (scripts reload: retry a call that fails right after)
+  editor | call AddLayer("Pickups")  then  objects | where name starts-with "Pickup" | set layerName = "Pickups"   (read: editor | select layers tags)
+  editor | call AddTag("Interactive")  then  objects | where name starts-with "Barrel" | set tag = "Interactive"
+  profiler | call Start()      profiler | call Save("Logs/profile.json")      (read: profiler | select memory frame)
+  settings | set physics.gravity = "(0, -12, 0)", time.fixedDeltaTime = 0.01   Project Settings (saved, undoable)
+  settings | set build.scenes = append(build.scenes, "Assets/Scenes/Level2.unity")   scenes in the build
+Object literals build values: set settings = {speed: 2, $type: "FastSettings"}, and so do Materials and data ScriptableObjects (into a scene object; an asset or the open prefab cannot hold a new one: create the asset and pass its path). GameObjects, components and other assets are never built from a literal: pass unity.find("Name"), ref("Type#id") or an asset path. At most 200 targets (or bulk-create items) per call; max_targets raises the limit (up to 1000) for an intended bulk change. The receipt lists the assignments that change a value; "N unchanged" counts the ones whose target already held it (written anyway). A misspelt member that empties the stream of set / call fails with unknown-member (nothing changed); a real member that no matched item has is a no-op.
+Agent rules: Deleting (DeleteAsset, Destroy, script-delete, or AssetDatabase / File deletes in script-execute) takes two turns unless the user named the exact items or you created them yourself in this task: first list the exact candidates (rql-query, a dry_run=true mutation or a read-only snippet), show them and end your turn; delete only that list, in a separate call, after the user confirms. Otherwise never find and delete candidates in the same turn. After project files change outside the Editor (written to disk by you, a script or the user), run editor | call RefreshAssets() before reading or changing them: it imports them and reloads an open scene whose file changed (changed .cs files recompile and the scripts reload: retry a call that fails right after). When you map a name the user misspelt to a real one (an object, component or member), say so. Unity units are meters, degrees (rotation) and seconds.
+
+Query part: the RQL of rql-query (full guide and the sources in its description); unity.assets("t:Material"), unity.asset(path), unity.find("Name"), ref("Light#1234"). Stages: where, select, sort, first N, get <path>, recurse children. Operators: == != < > and or not, contains, starts-with, $ is Light. Paths a.b.c, list[0], map["key"]. Vectors/colors as "(1, 2, 3)" or "#ff8800"; enums as strings.
+```
+
+### `rql-query` 的完整用法（插件喂给模型的原文，已按段落去重）
+
+```text
+Run a read-only RQL query against the live Unity Editor scene and return compact rows. One precise query beats many exploratory calls. Changes need rql-mutate.
+
+RQL: source | stage | stage ...
+Sources: objects (every GameObject in the loaded scenes, inactive included), roots, scenes, selection, prefab (the prefab open in prefab editing mode), console (Editor log entries), shaders, componentTypes, profiler (memory / rendering / frame snapshots; call Start / Stop / Save), tests (test methods; run a selection with tests-run query), testResults (last run), editor (Editor state and operations), settings (Project Settings: physics, time, quality, player, build). Assets: unity.assets("t:Material") or unity.assets("t:Prefab", "Assets/Enemies"), unity.asset("Assets/Mats/Red.mat"). ref("Light#1234") resolves a $ref; unity.find("Player") or unity.find("Level/Pillar_1") a GameObject by unique name or path.
+Stages:
+  where <condition>                  filter (a boolean: where sharedMaterial != null, not where sharedMaterial)
+  select a b.c alias=(expr)          project columns (wrap computed expressions in parentheses)
+  sort <expr> [desc], ...            stable sort (computed keys in parentheses: sort (a * b) desc)
+  first N | skip N | count
+  get <path>                         replace each item by a member (lists are flattened)
+  recurse children [max-depth=N] [include-self=false]   walk the hierarchy (input items included by default)
+  distinct [expr] | sum expr | min expr | max expr | avg expr   (distinct keeps whole items; values: get tag | distinct)
+  group-by expr                      rows key|count; group-by a, b (or kind=$type) gives one column per key, then count;
+                                     items = the group's items: … | where $ is Light | group-by type | select key count avg=(items.avg(intensity))
+Expressions: == != < <= > >= and or not + - * / %; contains, starts-with, ends-with (case-insensitive); matches "regex"; x in [a, b]; x is null; x is not null; $ is Light (includes subclasses); has(member); c ? a : b or if(c, a, b) (only the taken branch runs; where a stage takes one expression, wrap it: select kind=($ is Light ? "light" : "other")). Literals: numbers, "strings", true/false/null, lists [a, b], objects {x: 1, y: 2}. Text functions: lower upper len, replace(s, from, to) (case-insensitive), replace-regex(s, pattern, repl) ($1 = group 1), substring(s, start[, length]), split(s, sep), trim(s), pad(v, width[, fill]) — also as methods: name.replace("Old", "New"), name.substring(0, 4).
+Paths: a.b.c, list[0], map["key"]; .member on a list maps over its elements. List methods: .any(pred) .all(pred) .count([pred]) .sum(e) .avg(e) .min(e) .max(e) .first([pred]); inside them bare names refer to the element, falling back to the outer item.
+Meta: $ (current item), $ref (stable id such as Light#1234), $type, $path (the item's place in this query, e.g. roots[0].children[2]), $index, $depth. Enums compare to strings (type == "Spot", or the Inspector's name: shadowCastingMode == "Two Sided"); == on strings is case-sensitive.
+Unity: GameObject has components (list), children (list), active, name, path (hierarchy path "Level/Props/Crate"), tag, layer, layerName, transform (position, localPosition, eulerAngles, localScale, parent; call LookAt(target) turns it toward a GameObject or a position). Component members are the C# members (public + [SerializeField]); find them via objects | get components | where $ is Light. Vectors/colors print as (x, y, z); write "(1, 2, 3)", [1, 2, 3] or {x: 1, y: 2, z: 3}; colors also "#ff8800". An asset's file: assetPath; its import settings: get importer. Material shader properties: properties["_Color"] (the main color / texture: color, mainTexture); a Material Variant has a parent. A Mesh value also takes a primitive's name ("Cylinder"), a Material value a built-in material's ("Default-Material"). Prefab instances: prefabSource, prefabOverrides (all of the instance's on its root, an object's own on a part). Destroyed objects read as null; a GameObject's missingReferences lists references to deleted assets or objects (where missingReferences.count() > 0). Navigate with paths or get; select only projects output columns.
+Results come back as compact rows (header line, then col|col). Long results are truncated — refine with where/first or use count. Unknown members produce warnings with suggestions; rql-schema(type) lists a type's members.
+Language rules:
+- Conditions are booleans. where, and / or / not, ?: and the predicates of .any() .all() .count() .first() take a comparison or has(), never a bare value: where material != null (or has(material)), where count > 0, where name != "", where len(tags) > 0. A number, string, object or list there fails with type-mismatch; null counts as false.
+- cond ? a : b (the same as if(cond, a, b)) picks a value and evaluates only the taken branch: set y = (y < 0 ? 0 : y). Inside select, wrap computed values in parentheses: select kind = (intensity > 2 ? "bright" : "dim").
+- Lists compare by value, in order: tags == ["a", "b"], x in [[1, 2], [3, 4]]; distinct and group-by merge equal lists.
+- group-by gives rows with key (or one column per key), count and the group's items: group-by kind | select key, count, avg = items.avg(weight); also items.sum(e), items.min(e), items.max(e), items.count(pred), items.first().name. Group by the item's type with $type (group-by $type); a bare type is a member that most items do not have.
+- Receipts list only real changes: a set row whose value stayed the same is left out and counted as unchanged, so no rows with N unchanged means the values already matched.
+- call Method(args) runs the method of each item (the items must be objects). call source.Method(args) runs the method of that one source object once per stream item, with $, $index, $path and $depth in the arguments being the item's; every call counts against the target limit, and every argument is checked before the first call (a dry run checks without calling).
+- Bulk create: range(start, end[, step]) streams numbers (end excluded), and a list literal streams its elements, so one call creates many objects: range(0, 150) | call editor.CreateGameObject("Cube_" + $, {primitive: "Cube", position: [($ % 15) * 2, 0, floor($ / 15) * 2]}) builds a 15-wide grid, [["Crate", [0, 0, 0]], ["Barrel", [2, 0, 0]]] | call editor.CreateGameObject($[0], {primitive: "Cube", position: $[1]}) one object per entry. The receipt has one row per call with the $ref of the created object.
+- Vectors and colors the host marks as component-wise compute component by component: set Scale = Scale * 1.5, Position + [0, 1, 0], Position - Offset, -Velocity, v / 2. Adding a number to a vector is a type-mismatch (add [x, y, z] instead); quaternions and other types without that mark stay type-mismatch. Lists of numbers are vectors too: [x, 0, z] * k, [1, 2] + [3, 4]. Vector functions work on both: length(v) (or v.length(), magnitude), normalize(v), distance(a, b), dot(a, b), lerp(a, b, t); len(x) stays the size of a string or list.
+- Trigonometry is in radians: sin, cos, tan, asin, acos, atan, atan2(y, x), pi(), deg(x), rad(x); trigonometric results are rounded (sin(pi()) is 0). In a set value or call argument $count is the number of items entering the stage ($index runs 0 to $count - 1), so set position = [5 * cos(2 * pi() * $index / $count), 0, 5 * sin(2 * pi() * $index / $count)] lays the items out on a circle of radius 5.
+- A missing map entry reads as null: props["k"] == null and props["k"] is null are true without the entry, and has(props["k"]) tests whether it exists. A misspelt member is not null: it stays unknown and is reported.
+- Arguments by name: call Method({name: value, ...}) with one object literal that no overload takes as a whole binds each key to the parameter of that name; parameters left out keep their defaults, and an unknown name fails listing the parameters: range(0, 10) | call editor.CreateGameObject({name: "Tile" + $, primitive: "Cube", position: [$ * 2, 0, 0]}). Engine objects (scene objects, nodes, actors) are never built from an object literal: pass an existing one, e.g. ref("Type#id"). Value-like assets and owned subobjects that the host marks are built from a typed literal: set mesh = {$type: "TypeName", size: 2}.
+
+Examples:
+  objects | where name contains "Enemy" and active | select $ref name transform.position
+  objects | get components | where $ is Light and intensity > 2 | select gameObject.name intensity color
+  roots | recurse children | where components.count() == 1 | select $path name
+  unity.assets("t:Material") | select name shader.name properties["_Color"]
+  console | where logType == "Error" | sort sequence desc | first 5 | select message
+  scenes | select name path isDirty rootCount
+  componentTypes | where name contains "Collider" | select name
+  editor | select isPlaying isPaused selection
+  settings | select physics.gravity time.fixedDeltaTime quality.levels
+```
+
+### `rql-schema` 的完整用法（插件喂给模型的原文，已按段落去重）
+
+```text
+Without a type: RQL sources, asset functions, the installed extensions (always active) with their guide topics, and the component types present in the loaded scenes (with counts), plus GameObject and Transform members. "guide:<topic>" prints one of the listed guides. With a type name (e.g. "Light", "Enemy", "Vector3"): that type's members (name type; ro = read-only) and methods. Use it before querying an unfamiliar component.
+```
+
+

package/skills/{reference → unity-mcp-tools/reference}/screenshot.md

@@ -1,6 +1,6 @@
 # Screenshot — 4 个命令
 
-调用名 `mcp__unity__<命令名>`；`[on]` = Unity 侧默认启用（可直接调），`[off]` = 默认关闭 —— 用 `mcp__unity__tool-set-enabled-state` 开启后，**从下一个步骤起可调用**（工具注册表在请求边界重建）。
+调用名 `mcp__unity__<命令名>`；`[on]` = Unity 侧默认可见（可直接调），`[off]` = 默认隐藏 —— 用 `mcp__unity__tool-set-enabled-state`（1.6.0 正式名 `tool-set-visibility`，等价）设为 visible 后，**从下一个步骤起可调用**（工具注册表在请求边界重建）。
 
 - `screenshot-camera` [off] — Captures a screenshot from a camera and returns it as an image.
   - 参数: cameraRef?, width?, height?

package/skills/{reference → unity-mcp-tools/reference}/script.md

@@ -1,12 +1,12 @@
 # Script — 4 个命令
 
-调用名 `mcp__unity__<命令名>`；`[on]` = Unity 侧默认启用（可直接调），`[off]` = 默认关闭 —— 用 `mcp__unity__tool-set-enabled-state` 开启后，**从下一个步骤起可调用**（工具注册表在请求边界重建）。
+调用名 `mcp__unity__<命令名>`；`[on]` = Unity 侧默认可见（可直接调），`[off]` = 默认隐藏 —— 用 `mcp__unity__tool-set-enabled-state`（1.6.0 正式名 `tool-set-visibility`，等价）设为 visible 后，**从下一个步骤起可调用**（工具注册表在请求边界重建）。
 
 - `script-delete` [off] — Delete the script file(s).
   - 参数: files, requestId?
   - 源码: `Editor/Scripts/API/Tool/Script.Delete.cs`
-- `script-execute` [on] — Compiles and executes C# code dynamically using Roslyn.
-  - 参数: csharpCode, className?, methodName?, parameters?, isMethodBody?
+- `script-execute` [on] — Compiles and runs C# in the Unity Editor: plain statements with the last expression as the result (own usings, local classes, await allow...
+  - 参数: csharpCode, className?, methodName?, parameters?, isMethodBody?, usings?, include?, timeout?
   - 源码: `Editor/Scripts/API/Tool/Script.Execute.cs`
 - `script-read` [off] — Reads the content of a script file and returns it as a string.
   - 参数: filePath, lineFrom?, lineTo?

package/skills/{reference → unity-mcp-tools/reference}/tests.md

@@ -1,9 +1,9 @@
-# Tests — 1 个命令
-
-调用名 `mcp__unity__<命令名>`；`[on]` = Unity 侧默认启用（可直接调），`[off]` = 默认关闭 —— 用 `mcp__unity__tool-set-enabled-state` 开启后，**从下一个步骤起可调用**（工具注册表在请求边界重建）。
-
-- `tests-run` [on] — Execute Unity tests and return detailed results.
-  - 参数: testMode?, testAssembly?, testNamespace?, testClass?, testMethod?, query?, result?, includePassingTests?, includeMessages?, includeStacktrace?, includeLogs?, logType?, includeLogsStacktrace?, requestId?
-  - 源码: `Editor/Scripts/API/Tool/Tests.Run.cs`
-
-
+# Tests — 1 个命令
+
+调用名 `mcp__unity__<命令名>`；`[on]` = Unity 侧默认可见（可直接调），`[off]` = 默认隐藏 —— 用 `mcp__unity__tool-set-enabled-state`（1.6.0 正式名 `tool-set-visibility`，等价）设为 visible 后，**从下一个步骤起可调用**（工具注册表在请求边界重建）。
+
+- `tests-run` [on] — Execute Unity tests and return detailed results.
+  - 参数: testMode?, testAssembly?, testNamespace?, testClass?, testMethod?, query?, result?, includePassingTests?, includeMessages?, includeStacktrace?, includeLogs?, logType?, includeLogsStacktrace?, requestId?
+  - 源码: `Editor/Scripts/API/Tool/Tests.Run.cs`
+
+

package/skills/unity-mcp-tools/reference/tool.md

@@ -0,0 +1,15 @@
+# Tool — 3 个命令
+
+调用名 `mcp__unity__<命令名>`；`[on]` = Unity 侧默认可见（可直接调），`[off]` = 默认隐藏 —— 用 `mcp__unity__tool-set-enabled-state`（1.6.0 正式名 `tool-set-visibility`，等价）设为 visible 后，**从下一个步骤起可调用**（工具注册表在请求边界重建）。
+
+- `tool-set-enabled-state` [off] — DEPRECATED, use tool-set-visibility.
+  - 参数: tools, includeLogs?
+  - 源码: `Editor/Scripts/API/Tool/Tool.SetEnabledState.cs`
+- `tool-set-visibility` [off] — Show or hide MCP tools by name.
+  - 参数: tools, includeLogs?
+  - 源码: `Editor/Scripts/API/Tool/Tool.SetVisibility.cs`
+- `unity-tool-list` [on] — List all Unity-MCP tools registered in the connected Unity Editor instance, hidden ones included (each with Visible).
+  - 参数: regexSearch?, includeDescription?, includeInputs?
+  - 源码: `Editor/Scripts/API/Tool/Tool.List.cs`
+
+