dsh-unity-mcp-bridge 0.9.0 → 0.9.1

package/docs/DETAILS.md

@@ -113,7 +113,7 @@ unity-mcp-cli install-plugin <unity-project> --with-server --server-version 9.3.
   --server-source "<plugin>\vendor\gamedev-mcp-server-win-x64-9.3.0.zip"
 ```
 
-`install-plugin` **没有** `--plugin-source`；离线路径是 Unity 官方支持的 `file:` 本地 tarball 依赖。CLI 不会覆盖 `file:` / `git+` / `http:` 依赖（`dist/utils/manifest.js` 的 `nonSemverPrefixes`），所以之后重跑 `install-plugin` 也安全。
+`install-plugin` **没有** `--plugin-source`；离线路径是 Unity 官方支持的 `file:` 本地 tarball 依赖。`offline-package.mjs install` 默认（`--vendor project`）把 tarball 复制到工程根 `UnityMcpOffline/`，写相对 `Packages` 的依赖（`file:../UnityMcpOffline/…`，profile 重建/换机器都不断）；`--vendor bridge` 保留旧的插件目录绝对路径。CLI 不会覆盖 `file:` / `git+` / `http:` 依赖（`dist/utils/manifest.js` 的 `nonSemverPrefixes`），所以之后重跑 `install-plugin` 也安全。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-unity-mcp-bridge",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "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",

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

@@ -36,11 +36,21 @@ $projects
 $manifest = Join-Path $proj 'Packages\manifest.json'
 Select-String -Path $manifest -Pattern 'com\.ivanmurzak\.unity\.mcp'
 Get-ChildItem (Join-Path $proj 'Library\PackageCache') -Directory -Filter 'com.ivanmurzak.unity.mcp@*' -ErrorAction SilentlyContinue
+
+# 若依赖是 file:，解析目标是否存在（Unity 相对 Packages 目录；绝对路径直接用）
+$dep = (Get-Content $manifest -Raw | ConvertFrom-Json).dependencies.'com.ivanmurzak.unity.mcp'
+if ($dep -like 'file:*') {
+  $rel = $dep.Substring(5)
+  $target = if ($rel -match '^[A-Za-z]:' -or $rel.StartsWith('/')) { $rel } else { Join-Path (Split-Path $manifest) $rel }
+  "dep target: $target  exists=$(Test-Path $target)  points-into-node_modules=$($target -like '*node_modules*')"
+}
 ```
 
 - manifest 依赖 **和** `Library\PackageCache` 里都有 → 已装（依赖可能是 `file:` 本地包，属正常）。
 - 只有 manifest、没有 `PackageCache` → Unity 还没解析包：让 Unity 打开/重新加载项目一次再看。
 - 两处都没有 → **未装**：报告后交给 `/unity-mcp-install`，不要在这里装。
+- `file:` 目标 **不存在** → Unity 解析必失败：重跑 `/unity-mcp-install`（现在默认 `--vendor project`，会复制 tarball 到工程 `UnityMcpOffline/` 并写相对路径）。
+- `file:` 目标指向 **`node_modules`**（例如旧版写进 profile 的绝对路径）→ 现在能用，但 profile 重建/重装即失效：建议重跑 `/unity-mcp-install` 迁移到工程内相对路径。
 
 ## 2. 端口是不是 20000、模式是不是 Custom（不对就改）
 
@@ -229,6 +239,8 @@ unity-mcp-cli wait-for-ready $proj         # 最长 120s
 | 改了 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 打开项目一次 |
+| `file:` 依赖找不到目标 | tarball 被删/工程从别的机器拷来但没带 `UnityMcpOffline/`，或旧版指向了已重建的 profile 路径 | 重跑 `/unity-mcp-install`（默认 `--vendor project`，复制 tarball 到工程并写相对路径） |
+| `file:` 路径里含 `node_modules` | 旧版 `install` 写的是插件目录绝对路径，生命周期绑在 profile 上 | 能连就先不动；建议重跑 `/unity-mcp-install` 迁移到 `UnityMcpOffline/` 相对路径 |
 | 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` 或历史上写死的配置隐藏 | 单独跑一条 `unity-mcp-cli configure $proj --enable-tools tool-set-enabled-state` 救回 |

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

@@ -102,6 +102,10 @@ if (Test-Path $cfgPath) { Remove-Item $cfgPath -Force }
 $serverDir = Join-Path $proj 'Library\mcp-server'
 if (Test-Path $serverDir) { Remove-Item $serverDir -Recurse -Force }
 
+# 新版 install 默认复制进工程的离线 tarball（UnityMcpOffline/，相对依赖用）
+$offlineDir = Join-Path $proj 'UnityMcpOffline'
+if (Test-Path $offlineDir) { Remove-Item $offlineDir -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 }
@@ -130,7 +134,7 @@ Test-Path (Join-Path $proj 'Library\mcp-server')
 |---|---|
 | 定位到的工程 | `$proj` |
 | 已删除的包 | `com.ivanmurzak.unity.mcp` + 扩展列表（或「未安装，无需卸载」） |
-| 清理的配置/残留 | `UserSettings\AI-Game-Developer-Config.json`、`Library\mcp-server`、PackageCache 条目 |
+| 清理的配置/残留 | `UserSettings\AI-Game-Developer-Config.json`、`Library\mcp-server`、`UnityMcpOffline\`、PackageCache 条目 |
 | 备份 | `Packages\manifest.json.bak-<stamp>`、`AI-Game-Developer-Config.json.bak-<stamp>` |
 | 未动的 | DSH 桥接插件、CLI 托管 Server、其他工程、`.kilocode`/agent 配置 |
 | 下一步 | 用 Unity 打开工程让其重新解析；之后 `/unity-mcp-check` 应报告「未装」 |

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

@@ -165,28 +165,33 @@ ERROR: fetch failed
 
    这是**兜底而非首选**：绕过了官方 zip 的哈希校验，必须向用户说明来源与版本。
 
-### 5.2 离线本地包（插件自带 `vendor/`；给「新的 Unity 工程」用时优先走这条）
+### 5.2 离线本地包（插件自带 `vendor/`；现在默认写工程内相对路径）
 
 插件目录下的 `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）
+# 1) 先看会复制什么、写什么依赖（不落盘）
+node "<bridge>\tools\offline-package.mjs" install --project $proj --dry-run
+
+# 2) 复制 tarball 到工程根并写相对依赖（自动备份 manifest）
 node "<bridge>\tools\offline-package.mjs" install --project $proj
 
-# 2) Server 也从 vendor 的 zip 装进 CLI 托管目录（不联网）
+# 3) Server 从 vendor 的 zip 装进 CLI 托管目录（不联网）
 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.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 project`**：把 tarball 复制到 `<工程>\UnityMcpOffline\`，manifest 写成 `"com.ivanmurzak.unity.mcp": "file:../UnityMcpOffline/com.ivanmurzak.unity.mcp-1.6.0.tgz"`。Unity 的 `file:` 相对路径**相对 `Packages` 文件夹**解析（[Unity 手册](https://docs.unity3d.com/2022.3/Documentation/Manual/upm-localpath.html)），所以 `../UnityMcpOffline/…` 就是工程根下的目录。这样 **profile 重建/删除、工程拷到别的机器都不会断**；tarball 约 1 MB，可以一起提交到版本库。
+- 旧工程（依赖指向 `node_modules\...\vendor\` 绝对路径）**重跑一次 `install` 就会迁移**到工程内相对路径；manifest 先备份。想保留旧行为用 `--vendor bridge`（绝对路径，profile 重建后需要重跑 install）。
+- `install` 检测工程内 tarball 的 SHA256；已存在且一致就跳过复制，不一致（换了插件版本）会覆盖。
+- `install-plugin` **没有** `--plugin-source`。离线靠的就是上面的本地 tarball 依赖；之后重跑 `unity-mcp-cli install-plugin` **不会**把它改回版本号（`dist/utils/manifest.js` 的 `nonSemverPrefixes` 跳过 `file:` / `git+` / `http:`）。
 - 目标版本从哪来：`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），换版本后照例重生成命令目录。
+- `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**：40 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 …` 装出来的 `node_modules\dsh-unity-mcp-bridge\vendor\` 通常只有 tarball + manifest。`install` 会明确告诉你缺不缺；缺就先 `fetch`（代理优先）补齐再跑 `--server-source`，不要拿旧版本的 zip 顶。
 
 ## 6. 验证与下一步
 

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

@@ -139,7 +139,7 @@ node "<bridge>\tools\offline-package.mjs" fetch --plugin-version <latest>
 # 先看会改什么，不落盘
 node "<bridge>\tools\offline-package.mjs" install --project $proj --dry-run
 
-# 落盘（自动备份 Packages\manifest.json，写官方支持的 file: 本地依赖）
+# 落盘（自动备份 Packages\manifest.json；默认把 tarball 复制到工程 UnityMcpOffline/ 并写相对依赖）
 node "<bridge>\tools\offline-package.mjs" install --project $proj
 
 # Server 从 vendor 的 zip 装进 CLI 托管目录（不联网）

package/tools/offline-package.mjs

@@ -5,7 +5,7 @@
  * 三个子命令：
  *   check    比对「上游最新 / 本地 vendor 离线包 / 项目已装」三层版本，给出该不该更新
  *   fetch    下载插件 tarball + GameDev-MCP-Server zip 到 vendor/，校验 SHA256，写 vendor/manifest.json
- *   install  把一个 Unity 工程的 Packages/manifest.json 指向 vendor/ 里的本地 tarball（file: 依赖）
+ *   install  把 tarball 复制到 <工程>/UnityMcpOffline/ 并写相对 Packages 的 file: 依赖（--vendor bridge 则写插件目录绝对路径）
  *
  * 网络策略（实测）：
  *   - OpenUPM / npm registry 直连可达 → 插件 tarball 与版本查询优先直连，失败再走代理。
@@ -38,7 +38,7 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--no-proxy') { out.noProxy = true; continue; }
-    const flag = ['proxy', 'project', 'plugin-version', 'server-version', 'rid', 'cli-version', 'out'].find(f => a === `--${f}`);
+    const flag = ['proxy', 'project', 'plugin-version', 'server-version', 'rid', 'cli-version', 'out', 'vendor'].find(f => a === `--${f}`);
     if (flag) { out[flag] = argv[++i]; continue; }
     if (a === '--json') { out.json = true; continue; }
     if (a === '--force') { out.force = true; continue; }
@@ -53,7 +53,10 @@ function usage() {
   console.log(`用法:
   node tools/offline-package.mjs check   [--project <Unity工程>] [--cli-version <v>] [--json]
   node tools/offline-package.mjs fetch   [--plugin-version <v>] [--server-version <v>] [--rid <rid>] [--proxy <url>] [--force]
-  node tools/offline-package.mjs install [--project <Unity工程>] [--dry-run]
+  node tools/offline-package.mjs install [--project <Unity工程>] [--vendor project|bridge] [--dry-run]
+
+--vendor project（默认）把 tarball 复制到 <工程>/UnityMcpOffline/ 并写相对路径（可移植）；
+--vendor bridge 沿用旧行为，写 <插件目录>/vendor/ 的绝对 file: 路径。
 
 vendor/ 目录: ${VENDOR_DIR}`);
   process.exit(0);
@@ -394,20 +397,40 @@ function cmdInstall(args) {
   const actual = sha256(tgz);
   if (vendor.plugin.sha256 && actual !== vendor.plugin.sha256) fail(`离线包 sha256 与 manifest 不符: ${actual}`);
 
+  const mode = args.vendor ?? 'project';
+  if (mode !== 'project' && mode !== 'bridge') fail(`--vendor 只能是 project 或 bridge（收到 ${mode}）`);
+
   const proj = args.project || fail('需要 --project <Unity工程>');
   const manifestPath = path.join(proj, 'Packages', 'manifest.json');
   if (!fs.existsSync(path.join(proj, 'ProjectSettings', 'ProjectVersion.txt'))) fail(`不是 Unity 工程: ${proj}`);
   if (!fs.existsSync(manifestPath)) fail(`缺 ${manifestPath}`);
 
-  // Unity 的 file: 依赖用正斜杠；绝对路径直接跟在 file: 后面（Unity 手册：Local folder or tarball paths）
-  const spec = `file:${tgz.replace(/\\/g, '/')}`;
+  // 默认把 tarball 复制进工程，依赖写相对 Packages 的路径（Unity 手册：本地 tarball 路径相对 Packages 文件夹）。
+  // 这样 profile 重建、工程换机器都不会断；--vendor bridge 保留旧的绝对路径行为。
+  const offlineDir = path.join(proj, 'UnityMcpOffline');
+  const offlineTgz = path.join(offlineDir, path.basename(tgz));
+  const spec = mode === 'project'
+    ? `file:../UnityMcpOffline/${path.basename(tgz)}`
+    : `file:${tgz.replace(/\\/g, '/')}`;
+
   const mj = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
   mj.dependencies ??= {};
   const before = mj.dependencies[PKG_ID] ?? null;
   if (args.dryRun) {
-    console.log(`dry-run: ${PKG_ID}: ${before ?? '（无）'} → ${spec}`);
+    console.log(`dry-run (--vendor ${mode}): ${PKG_ID}: ${before ?? '（无）'} → ${spec}`);
+    if (mode === 'project') console.log(`  复制: ${tgz} → ${offlineTgz}`);
     return;
   }
+
+  if (mode === 'project') {
+    fs.mkdirSync(offlineDir, { recursive: true });
+    const same = fs.existsSync(offlineTgz) && sha256(offlineTgz) === vendor.plugin.sha256;
+    if (!same) fs.copyFileSync(tgz, offlineTgz);
+    const copied = sha256(offlineTgz);
+    if (vendor.plugin.sha256 && copied !== vendor.plugin.sha256) fail(`工程内离线包 sha256 与 manifest 不符: ${copied}`);
+    console.log(`已复制离线包到工程: ${offlineTgz}${same ? '（已存在且哈希一致，跳过复制）' : ''}`);
+  }
+
   // 与 unity-mcp-cli 一致：补 OpenUPM 作用域注册表（插件的传递依赖 extensions.unity.* 要它）
   mj.scopedRegistries ??= [];
   let reg = mj.scopedRegistries.find(r => r.name === 'package.openupm.com');
@@ -423,11 +446,17 @@ function cmdInstall(args) {
   console.log(`  ${PKG_ID}: ${before ?? '（无）'} → ${spec}`);
   console.log(`  备份: ${bak}`);
   console.log(`  插件版本 ${vendor.plugin.version}（钉住 Server ${vendor.plugin.pinnedServerVersion}）`);
+  if (mode === 'project') {
+    console.log('  提示: 依赖是相对 Packages 的路径；profile 重建/删除不会断，工程拷到别的机器也能离线解析。');
+    console.log('        tarball 在工程根 UnityMcpOffline/ 下（约 1 MB），可一起提交到版本库。');
+  } else {
+    console.log('  提示: 依赖是插件目录的绝对路径；重建 profile / 移动工程后会失效，需要重跑 install。');
+  }
   const serverZip = vendor.server?.file ? path.join(VENDOR_DIR, vendor.server.file) : null;
   if (serverZip && fs.existsSync(serverZip)) {
     console.log(`下一步：unity-mcp-cli install-plugin ${proj} --with-server --server-version ${vendor.server.version} --server-source "${serverZip}"`);
   } else {
-    console.log(`⚠ 本地缺 Server zip（${vendor.server?.file ?? '未记录'}；43 MB 级二进制不进 git/npm）。先补齐再装：`);
+    console.log(`⚠ 本地缺 Server zip（${vendor.server?.file ?? '未记录'}；40 MB 级二进制不进 git/npm）。先补齐再装：`);
     console.log(`  node tools/offline-package.mjs fetch --rid ${vendor.server?.rid ?? defaultRid()}   # 代理优先`);
   }
 }

package/vendor/README.md

@@ -33,11 +33,11 @@ node "<插件目录>\tools\offline-package.mjs" fetch
 ## 离线装进 Unity 工程
 
 ```powershell
-node "<插件目录>\tools\offline-package.mjs" install --project <Unity工程>   # 写 file: 依赖 + 备份 manifest
+node "<插件目录>\tools\offline-package.mjs" install --project <Unity工程>   # 复制 tarball 到工程 UnityMcpOffline/ + 写相对依赖 + 备份 manifest
 unity-mcp-cli install-plugin <Unity工程> --with-server --server-version 9.3.0 --server-source "<插件目录>\vendor\gamedev-mcp-server-win-x64-9.3.0.zip"
 ```
 
-`install` 写的是 Unity 官方支持的本地 tarball 依赖（`"com.ivanmurzak.unity.mcp": "file:D:/…/vendor/com.ivanmurzak.unity.mcp-1.6.0.tgz"`，见 Unity 手册 *Local folder or tarball paths*）。`unity-mcp-cli` **没有** `--plugin-source`，但它对 `file:` 这类非 semver 依赖**不会覆盖**（`dist/utils/manifest.js` 的 `nonSemverPrefixes`），所以两条命令可以并存。
+`install` 默认（`--vendor project`）把 tarball 复制到工程根的 `UnityMcpOffline/`，并写成相对 `Packages` 的依赖 `"com.ivanmurzak.unity.mcp": "file:../UnityMcpOffline/com.ivanmurzak.unity.mcp-1.6.0.tgz"`（见 Unity 手册 *Local folder or tarball paths*）。这样 profile 重建、工程换机器都不会断；旧行为用 `--vendor bridge` 写插件目录的绝对路径。`unity-mcp-cli` **没有** `--plugin-source`，但它对 `file:` 这类非 semver 依赖**不会覆盖**（`dist/utils/manifest.js` 的 `nonSemverPrefixes`），所以两条命令可以并存。
 
 ## 进 git 的边界