Unity 编辑器桥接 snakeazh/dsh-unity-2022

Unity 2022.3（DeepSeek Harness 插件）

在 harness 里直接操控正在运行的 Unity 2022.3.62f3 编辑器：读写场景、进出 Play 模式、截图、读 Console、打 Player 包，以及在编辑器进程内执行 C# —— 全部以普通 agent 工具的形式提供。

与只支持 Unity 6 的编辑器集成不同，本插件自带桥接：纯 2022.3 原生环境即可工作，不联网、不需要额外 UPM 包，unity_eval 也不会触发域重载。

环境要求

| Unity 编辑器 | 2022.3.62f3（国际版）为基准版本。桥接只读取编辑器版本做标记（isRequiredUnityVersion），2022.3 系其他补丁版（实测 2022.3.46f1、2022.3.62f1c1）同样可用，不阻断。 |
| Harness | 提供 tools 服务的任意 DSH 版本 |
| 平台 | Windows（macOS/Linux 编辑器可被发现但未验证） |

安装

git clone https://github.com/snakeazh/dsh-unity-2022
plugin_manager install_bundle .\dsh-unity-2022

cordis.patch.yml 会插入 unity-2022 这一行，工具在下一轮对话生效。卸载： plugin_manager remove_bundle dsh-unity-2022。

插件已在 awesome-dsh-plugin 精选列表的审核队列里；通过后可以直接在 DSH 的「插件 → 发现」里一键安装。

在其他工程里使用

插件装在 profile 里（整个 harness 一份），桥接包装在 工程 里（每个工程一份）—— 两者分开，所以同一套工具可以管任意多个 Unity 工程：

1. 让工程具备桥接（三选一）：
- unity_open { "projectPath": "D:\\Work\\OtherGame" } —— 自动安装 + 启动 + 等待就绪；
- unity_install { "projectPath": "..." } —— 只装包、不启动（适合把包提交进仓库）；
- 手动把插件的 unity-package/ 目录复制成 <project>/Packages/com.dsh.unity-bridge。
Packages/com.dsh.unity-bridge 是 embedded package：提交进 Git 后，团队里任何人打开该工程，编辑器都会自动起桥接，无需再调用任何工具。
2. 把请求路由到对的编辑器（按优先级）：
- 调用参数里的 projectPath；
- 插件配置里的 projectPath（默认工程）；
- 调用方 agent 的工作目录落在某工程内 → 自动匹配该工程；
- 只跑着一个编辑器 → 直接用它。
同时开着多个编辑器、又没给 projectPath 时，会返回 ambiguous_editor 并列出可连工程。
3. 工程版本：unity_open 会挑与工程 ProjectVersion.txt 匹配的 Hub 安装（本机三套 2022.3 都在候选里）；没有对应版本时回落到最近的 2022.3。工程版本与基准版本不同只是标记，不阻断。

发布到插件市场

市场只认「某个地址上的一份索引 JSON」+「索引里指向的可安装包」，所以发布 = 发包 + 上线索引。
两条路可以只做一条，也可以两条都做。

1. 发包到 npm

npm login
npm publish # 包名 dsh-unity-2022，publishConfig.access 已是 public
npm pack # 只想先自测时用：得到一个和发布内容完全一致的 .tgz

files 白名单已经包含运行所需的一切（index.js、lib/、unity-package/、locale/、图标、 patch、README）。plugin_manager install_bundle <某个 .tgz> 可以本地验证「发布产物能被装上」——本插件已用 dsh-unity-2022-0.1.0.tgz（24 个文件、61 KB）验证通过。

如果这个不带 scope 的名字在 npm 上已被占用，改 package.json 的 name 与 cordis.patch.yml 里的 name（两处必须一致），再同步 market/index.json 的 name 与
versions[].source。

2a. 进官方精选列表（社区市场的默认数据源）

市场 UI（dshmarket）和它的站点读的是精选列表 awesome-dsh-plugin：去那边提一个 PR，在列表里加一条本插件即可，站点 CI 每天刷新 plugins.json，市场与发现页会自动收录（通常一天内生效）。
这是「让别人在市场里搜到」最短的一条路。

2b. 自建索引源（format 1）

market/index.json 就是一份符合 format 1 的索引，已验证可被 DSH 的解析器接受：

本地预览（DSH 只接受绝对 URL，插件市场的 list 工具还只认已配置的索引源）
node tools/serve-market.cjs # 把仓库根目录挂在 http://127.0.0.1:8199/
校验用 market/index.json + market/icon.svg 这套文件本身

把这个目录（index.json + icon.svg）放到任意 HTTPS 地址——GitHub Pages、jsDelivr（配合发布到 npm 的 dsh-plugin-catalog 之类）、或自己的域名——然后在 DSH 里 设置 → 插件 → 发现 → 索引源 添加该 index.json 的 URL。之后任何人都能在那台 DSH 里搜到并一键安装。

条目里能填的展示元数据（都可选，en 必填、可加 zh）：

| 字段 | 说明 |
| title / description | 本地化文案，字符串或 { "en": ..., "zh": ... } |
| icon | 相对 index.json 的路径、HTTPS URL，或 ≤32 KiB 的 base64 data: URL |
| metadata.keywords | 搜索关键词（自由填写） |
| metadata.category / metadata.labels | 必须先在索引根部的 metadata.categories / metadata.labels 里声明 id |
| versions[].source | { "type": "npm" } 装 name@version；也可 { "type": "git", "url": "...", "commit": "<40 位 sha>", "path": "可选子目录" } 直接从仓库装，不必发 npm |
| versions[].engines.dsh | 要求的 DSH 版本范围，市场据此提示兼容性 |

3. 发版

改 package.json 的 version → npm publish → 在 market/index.json 的 versions 里追加一条（publishTimestamp 是 Unix 秒，整型），旧版本条目保留，市场按 SemVer 倒序展示最新版。

快速上手

unity_open { "projectPath": "D:\\Work\\MyGame" }
unity_status {}
unity_hierarchy { "includeComponents": true }
unity_create { "name": "Crate", "primitive": "Cube", "position": [0, 0.5, 0] }
unity_add_component { "target": "Crate", "type": "Rigidbody", "properties": { "m_Mass": 12 } }
unity_screenshot { "view": "game", "width": 1280, "height": 720 }

unity_open 会把内置的 com.dsh.unity-bridge 包复制进 <project>/Packages/、启动匹配版本的编辑器，并等到桥接应答为止。如果工程已经在编辑器里打开，其余工具会自动找到它 —— 只有在同时跑多个编辑器时才需要传 projectPath。

工具一览

| 工具 | 作用 |
| unity_status | 可连接的编辑器列表，以及版本、Play 状态、编译状态、当前场景、选中对象、本机已安装编辑器。 |
| unity_open | 安装桥接包并启动编辑器，等待端点就绪。 |
| unity_install | 只把桥接包装进工程的 Packages/（不启动编辑器），便于提交进仓库。 |
| unity_commands | 列出桥接命令表（名称、参数、示例、是否修改场景）。 |
| unity_command | 用原始参数执行任意桥接命令（兜底入口）。 |
| unity_hierarchy | 场景层级树，含路径、instanceId、激活状态，可选组件名。 |
| unity_find | 按名字子串、组件类型、tag 或 layer 查找 GameObject。 |
| unity_inspect | 逐组件返回 Transform、激活状态与全部序列化属性（即 Inspector 里的值）。 |
| unity_create | 新建空对象或基本体，可指定父级、变换、tag、layer、是否保留碰撞体；可撤销。 |
| unity_add_component | 添加组件，并可同时设置属性。 |
| unity_set_property | 按属性路径或纯名字（m_ 前缀可省）写序列化属性，支持嵌套结构体。 |
| unity_set_transform | 位置、旋转、缩放、改父级，世界或本地坐标系。 |
| unity_delete | 删除对象及其子级；可撤销。 |
| unity_scene | 列出 / 打开 / 保存场景，刷新脏资源。 |
| unity_eval | 在编辑器进程内执行 C#，由编辑器自带 Roslyn 编译，不触发域重载。 |
| unity_play | 进入、退出、暂停、恢复、单帧步进 Play 模式。 |
| unity_logs | 读取 Console 缓冲（错误、警告、日志），可带堆栈。 |
| unity_screenshot | 渲染场景或游戏相机的 PNG，可指定取景对象。 |
| unity_menu | 按路径执行编辑器菜单项，例如 File/Save Project。 |
| unity_build | 构建 Player，返回体积、耗时、错误与警告数。 |

所有工具返回同一个信封，失败也是数据而不是异常：

{ "ok": true, "command": "hierarchy", "ms": 2, "instance": { "...": "..." }, "result": { } }
{ "ok": false, "command": "find_objects", "ms": 0, "error": { "code": "not_found", "message": "No GameObject matches 'Crat'" } }

常见错误码：no_editor、ambiguous_editor、not_found、missing_param、invalid_param、 outside_project、compile_error、timeout、transport_error。

配置

插件从自己的行读取 config: 块。编辑 profile 的 patch 文件（%USERPROFILE%\.dsh\profiles\<profile>\cordis.patch.yml），追加覆盖项：

- id: unity-2022
config:
projectPath: D:/Work/MyGame
autoLaunch: true
requestTimeoutMs: 180000

| 键 | 默认值 | 含义 |
| unityPath | "" | 要启动的编辑器可执行文件；留空则自动匹配工程版本对应的 Hub 安装。 |
| projectPath | "" | 工具调用省略 projectPath 时使用的默认工程。 |
| requestTimeoutMs | 120000 | 单条桥接命令的超时。 |
| launchTimeoutMs | 600000 | unity_open 等待桥接就绪的时长。 |
| autoLaunch | false | 工具执行时若没有可用编辑器则自动启动。 |
| installPackageOnLaunch | true | 启动前复制内置桥接包。 |

工作原理

agent tool ──▶ index.js ──▶ lib/client.mjs ──TCP 127.0.0.1:<临时端口>──▶ Unity 编辑器
│ (com.dsh.unity-bridge)
└─ 发现文件: %LOCALAPPDATA%\DSHUnityBridge\instances\<sha1>.json

* 编辑器侧的包在每次域重载后于临时端口上启动回环 TCP 服务，并为每个工程写一份发现文件（工程路径哈希、pid、端口、版本号）。Host 每次请求都重新读取该文件，因此 Play 模式、脚本编译、编辑器重启都是透明的 —— 命中已关闭套接字时会换新端口重试一次。
* 一个连接一个请求，双方各写一行 JSON。命令在编辑器主线程执行；不能阻塞主线程的（eval、build）自己起线程，再把结果回传给应答。
* unity_eval 在 <project>/Temp/DSHUnityBridge/ 下生成一段 C#，用编辑器自带的 Roslyn 针对编辑器与工程程序集编译成 DLL，再加载并调用 —— 因此既能用 UnityEngine/UnityEditor，又不会往 Assets/ 写东西或触发重编译。

截图由插件自己摆放一台临时相机渲染，不使用编辑器自带的 Scene view 相机：后者的变换只在 repaint 时跟随 pivot，同一帧内取景会是旧的。

桥接命令

共 25 条：status、list_commands、hierarchy、find_objects、inspect_object、 create_object、delete_object、add_component、remove_component、set_transform、 set_property、save_scene、open_scene、save_assets、refresh_assets、write_file、 import_package、execute_menu、selection、undo、play、screenshot、get_logs、 clear_logs、eval、build。

参数以 unity_commands 的实时返回为准 —— 编辑器侧的包才是唯一事实源。编辑器内通过 Tools/DSH/Unity Bridge 打开状态窗口，可看端口、请求数，重启桥接或跑自检。

测试

只编译 C#：对着本机 Unity 编辑器编译桥接 powershell -NoProfile -ExecutionPolicy Bypass -File tools\compile-bridge.ps1

端到端（加 --launch 会自己启动编辑器）
node test/smoke.mjs --project <unity 工程> --launch

生成一个场景并截图
node test/visual-check.mjs --project <unity 工程>

test/harness.mjs 是这些脚本用的胶水层，直接调用 lib/client.mjs，不依赖 harness 是否加载。

排错

| 现象 | 处理 |
| no_editor | 用 unity_open 启动编辑器，或手动打开工程；unity_status 可看有没有残留的发现文件。 |
| ambiguous_editor | 同时开了多个编辑器，传 projectPath 指定。 |
| 加包后桥接没起来 | Unity 需要导入一次该包：切到编辑器窗口等编译完成，再调 unity_status。 |
| unity_eval 返回 compile_error | 消息里带 file(line,col): error CSxxxx。片段可以用 C# 9、UnityEngine、UnityEditor。 |
| 其他 Unity 版本 | 只是标记：unity_status 里 isRequiredUnityVersion: false、expectedUnityVersion 为基准版本，功能照常（实测 2022.3.46f1）。 |
| editor_blocked | 编辑器主线程超过 15 秒没有 tick：通常是弹了模态框（保存对话框、导入进度、许可证窗口）。到 Unity 窗口里点掉它，再重试。 |
| bridge_unavailable | 编辑器进程起来了但一直没发布发现文件，几乎都是原生对话框挡住了主线程：最常见的是上一个编辑器被强杀后残留 <project>/Temp/UnityLockfile 触发的「工程已被打开」。关掉对话框，或退出该编辑器、删掉锁文件后重新 unity_open（返回里的 staleLockfile: true 表示启动前就存在锁文件）。 |
| editor_exited | 编辑器进程在桥接就绪前退出，看返回的 logFile（%LOCALAPPDATA%\Unity\Editor\Editor.log）。 |
| unity_scene save 报 missing_param | 当前场景还没存过（untitled），必须给 path，例如 Assets/Scenes/Main.unity；桥接故意不无参保存，否则 Unity 会弹窗卡住编辑器。 |
| unity_build 报 no_scenes | Build Settings 为空且当前场景未保存；传 scenes: ["Assets/Scenes/Main.unity"] 或先 unity_scene save。 |

桥接跑在编辑器主线程上，任何会弹模态对话框的编辑器 API 都会把请求卡住；上面这些命令都已经做了防弹窗处理（预建 asset 目录、拒绝无路径保存、主线程停摆时快速失败）。

许可

MIT