虚幻编辑器桥接 hackmagic/dsh-unreal-agentlink

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Deutsch · Español · Français · Русский

dsh-unreal-agentlink

一个 DSH 插件，把你的 Unreal Editor 交到智能体手里。

纯桥接。智能体负责规划，这个插件只负责翻译。

DSH agent ──tool calls──► dsh-unreal-agentlink ◄──WebSocket── Unreal Editor
(plans, decides) (this plugin: server, translator) editor dials out

安装 · 环境要求 · 12 个工具 · 配置 · 文档

npm install && npm run check

你的智能体已经能读文件、跑命令。这个插件把编辑器本身也交给它：查询关卡、生成 Actor、编辑蓝图和材质、渲染序列、截图并且真的能看见，出了问题还能回滚自己做过的事。

它不负责任务规划。规划是 DSH 原生智能体的事。这个插件是个带安全层的翻译器——把智能体的意图翻成 UnrealAgentLink 命令，再把编辑器的回答翻成智能体能拿来行动的东西。

安装

分三部分：把 UnrealAgentLink 的 C++ 插件放进你的 UE 项目，把本插件装进 DSH，然后打开编辑器。就这些——不用 UEBox，不用 token，不用握手。

第 1 步——把 UnrealAgentLink 装进 UE 项目

1. 把整个 UnrealAgentLink 目录复制到项目的 Plugins/（想全局安装就放到引擎的 Plugins/）。
2. 重新生成项目文件，然后打开项目。
3. 在 Edit → Plugins 下确认 UnrealAgentLink 已启用。它会自动拉入两个引擎自带的依赖：IKRig 和 PythonScriptPlugin。

之后编辑器会自己主动连出去：StartupModule 无条件调用 Init("ws://127.0.0.1:17860")，每 5 秒重试一次，所以启动顺序无所谓。

端口被占了（比如被 UEBox 占了）？给编辑器换一个，这边也改成一样的： UnrealEditor.exe MyProject.uproject -UALServer=ws://127.0.0.1:17861

第 2 步——把本插件装进 DSH

git clone <this-repo> dsh-unreal-agentlink
cd dsh-unreal-agentlink
npm install
npm run check # typecheck (src + tests) + 189 tests + catalog + doc reconciliation, one command

继续往下之前，npm run check 必须全绿——它会验证源码和测试都能通过类型检查、行为测试全部通过，以及 170 条命令目录与 C++ 注册表逐条对得上。

然后把它注册成 DSH bundle。package.json 里声明了 dsh.bundle.patch: ./cordis.patch.yml，这个文件只做一件事：

- insert:
- id: unreal-agentlink
name: dsh-unreal-agentlink
配置分层：后一层会整体替换该行的 config，不做深度合并。想覆盖任何内容，都要把想保留的键全部重写。

DSH 没有提供安装本地、树外插件的命令，所以这个仓库自带一个安装器：它先把活干完，再交给真正的安装流程：

npm run status:dsh -- --profile web # what is registered right now (same script, npm passthrough)
node scripts/install-dsh-plugin.mjs --profile web # mirror, edit the manifest, install, verify

如果某个 manifest 正被运行中的 DSH 占用，它不会去碰；报告成功之前，它会先证明这一层已经组合进去：dsh --profile <profile> --dump-config 的输出里必须包含 # == dsh-unreal-agentlink。desktop 是例外，命令行不会组合它，这一层改由 dsh plugin --profile desktop list 证明，它读取的是同一份包依赖图。声明的 peer 范围既覆盖本插件构建所针对的版本，也覆盖当前 dsh 发布的 0.2.x 线，所以 peer 依赖检查不会拦住正常安装；如果将来的运行时落在范围之外，dsh 会打印出接受风险所需的确切命令——这个决定由你做，不由脚本做。

另外还有两条路径，都写清楚了：下面的手动安装，以及 INSTALL-ai.md——一份 AI 智能体能读懂、并逐步照做的版本。

第 3 步 — 打开项目并验证

打开 UE 项目，然后让智能体调用 ual_status，检查三个字段：

listening: true
url: ws://127.0.0.1:17860
editors: [ { sessionId: "ue-xxxxxxxx", project: "MyProject", ... } ]

- listening: false → 插件没有启动，或者端口被占用。去 DSH 日志里找 EADDRINUSE。
- listening: true 但 editors: [] → 桥接在等待。确认 UE 项目已打开，且 UnrealAgentLink 已启用。

编辑器刚连上的那一瞬间，它的记录里只有 sessionId / connectedAt / lastSeenAt / heartbeats / stale；project 这类字段要等编辑器推送 project.info 之后才出现。这是正常状态，不是错误。

然后试一次没有副作用的纯读取：

ual_call { method: "level.get_current" }

完整走查——工作流、读取失败、故障排查——见教程。

环境要求

| 项目 | 要求 |
| Unreal Engine | 5.0 – 5.8 |
| UnrealAgentLink | C++ 插件本体，放进项目的 Plugins/ |
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| DSH 运行时 | 本插件以 bundle 形式安装 |

你不需要 UEBox

UEBox 桌面应用不是依赖。它是同一家厂商的另一个客户端，恰好也用 17860 端口，所以同时运行两者就是端口冲突——关系仅此而已。证据：
- UnrealAgentLink.uplugin:25-34 只声明了两个依赖，都是引擎自带的：IKRig 和 PythonScriptPlugin。没有 uebox 模块。
- UnrealAgentLink.Build.cs 里每一条都是引擎模块（UnrealEd / AssetRegistry / MovieScene / Landscape……）。没有 uebox SDK。
- 字符串 uebox 在整个源码里出现三次，全部是 // Copyright uebox.ai 头注释。
- 源码里没有任何地方调用 uebox.ai。唯一用到 FHttpModule 的地方是读取本机代理设置（UAL_ProxyDiagnostics.cpp:167）。

插件放进项目后就会自己跑起来：StartupModule 无条件调用 Init("ws://127.0.0.1:17860")（Core/UnrealAgentLink.cpp:86-97），一连上就推送 project.info，没有握手、没有 token、也没有鉴权。

要改端口：编辑器侧加 -UALServer=ws://127.0.0.1:17861，这一侧改 port 设置。

不用脚本，手动安装

上面的脚本只是图方便；底层机制就是清单里四行加一条产品命令。下面 <profile> 取 web —— desktop 也行，只需按本节末尾说明替换一处 —— $DSH_HOME 默认是 ~/.dsh：

1. build once, then copy only what npm pack ships
npm run build
cp -r lib cordis.patch.yml package.json LICENSE README.md \
"$DSH_HOME/profiles/<profile>/.vendor/"

2. register the dependency and the bundle layer (both are required)
"$DSH_HOME/profiles/<profile>/package.json" # add the two entries shown below

3. let the real installer run
dsh plugin --profile <profile> install

4. prove the layer is composed
dsh --profile <profile> --dump-config | grep -A2 '# == dsh-unreal-agentlink'

第 4 步是 desktop 跑不了的那一步：命令行拒绝从命令行启动该配置档，改用 dsh plugin --profile desktop list 验证（见下文）。

这两条写在 <profile>/package.json 里：

"dependencies": { "dsh-unreal-agentlink": "file:C:/Users/you/.dsh/profiles/web/.vendor" },
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "dsh-unreal-agentlink"] } }

两条都必填，出错方式还不一样：列了包但没声明 dsh.bundle，启动时会大声报错；装了包但没列进去，则完全不贡献任何层，--dump-config 里什么也看不到。

为什么 file: 指向副本而不是你的工作区：pnpm 在安装时复制它看到的内容，所以一个没保存完的源文件 —— 或者构建失败后被删掉的 lib/ —— 都会变成 DSH 加载的插件。先镜像，再安装。
desktop 配置档是受支持的目标，但命令行有一处缺口。 dsh --profile desktop … 会被直接拒绝（bin.js:112，rejectElectronProfile），因为这个配置档的生命周期归 Electron 应用管——但 dsh plugin 会刻意跳过这道守卫（bin.js:119），而应用自己调用的、随 Desktop 一起发布的命令行，恰好依赖这一点（dsh-desktop-host/lib/cli.js:91-104 传入 manageDesktopProfile: true）。所以按上面的步骤装进 desktop，只改两处：第 4 步改成 dsh plugin --profile desktop list，并且必须先完全退出应用。产品自己的提示词写得很清楚——"Open DeepSeek Harness Desktop once to initialize its profile, then fully quit it before running dsh plugin --profile desktop"——因为应用运行时会用内存里的插件列表重写 manifest，在它底下做的改动可能丢失。装完再启动 Desktop，挂载这一层。

文档

| 文档 | 内容 |
| 教程 | 端到端：安装插件、接通、常见工作流、故障排查 |
| 协议参考 | 消息结构、事件、13 个状态码、序列化规则、超时与并发语义 |
| 架构 | 门禁链、会话隔离与回滚、错误转换、验证策略、我们踩过的坑 |
| 命令参考 | 全部 170 条命令的参数 / 必填键 / 结果键 / 状态码（自动生成） |
| 安装指南（AI 可读） | 写给 AI 智能体阅读并执行的安装流程，附执行前后必须跑的检查 |

这五份文档在本文件顶部列出的每种语言里都有，放在 docs/<lang>/ 下——en（基准版，直接放在 docs/）、zh、zh-TW、ja、ko、de、es、fr、ru。

只翻译正文。命令名、参数键、结果键、状态码、配置键和 C++ 行号引用在任何语言里都原样保留，因为 UE 遇到不认识的键会静默忽略——翻译过的 asset_path 会变成一个静默失效的键，而不是本地化。tests/i18n.test.ts 强制校验几条不变量，让这件事可维护：每种语言都有对应文件，每个切换栏都列出所有语言，每个内部链接和 #anchor 都能解析。最后一条尤其重要，因为锚点是从翻译后的标题推导出来的，改动标题措辞会静默打断所有指向它的链接。

先确立四个事实

这些不是设计选择，而是 UnrealAgentLink 既有的约束，它们决定了每个操作怎么写。

1. 方向是反的。 这个插件不主动拨号编辑器——是编辑器向外拨号。启动顺序无所谓：先打开编辑器，它会每 5 秒重试一次，直到插件出现。
2. 没有认证。 没有 token，没有 header，没有子协议。端口就是凭证，所以默认只绑定回环地址。不要改成 0.0.0.0。
3. 命令在游戏线程上串行执行。 阻塞命令运行期间，编辑器不回应任何请求——连 sequence.render_status 这样的进度查询也不回。
4. 没有取消机制。 query_task 和 cancel_task 都不存在。杀掉 ual_task 任务只停止本插件的等待；引擎继续运行，结果照样返回。

12 个工具

把 170 条命令摊成 170 个工具，每次请求的提示词里就会有一大块花在当前任务根本用不到的能力上。所以发现能力要两步，而不是零步：

| 工具 | 用途 |
| ual_status | 编辑器连接 / 熔断器 / 速率限制 / 会话 / 孤儿命令。出问题时先读这个 |
| ual_tools | 列出全部 170 条命令（22 个族），可按族或关键词过滤 |
| ual_schema | 某条命令的精确键名——调用前先查；UE 会静默忽略未知键 |
| ual_call | 运行一条命令，原样返回编辑器结果 |
| ual_batch | 一次往返跑多条命令（受 maxBatchCalls 限制；只要有一项危险，整批都走审批） |
| ual_screenshot | 截图并返回真实图像，智能体能看到 |
| ual_logs | 读本地日志环（UE 侧转发默认关闭——见教程） |
| ual_undo / ual_undo_history | 按会话回滚 / 查看撤销缓冲区 |
| ual_locks | 申请资产锁；编辑器会画出「AI 正在编辑」徽标 |
| ual_editor_bind | 多个编辑器连接时，把会话固定到其中一个 |
| ual_task | 把长时间阻塞命令变成真正的后台任务，让对话继续 |

风险分级

read 65 / write 89 / destructive 2 / dangerous 14（最后 16 条走审批）。

tools/pre-execute 对 destructive 和 dangerous 方法返回 {kind:'ask'}（包括 ual_batch 里的任何危险项），把决定权留给会话策略。未注册的方法直接拒绝，永远到不了编辑器。

注意，在 never 策略下，ask 会被自动拒绝——这正是「无人值守会话不得碰编辑器」的正确读法。

配置

默认值是「活着但懒」。完整表格和理由见教程 §7。

| 键 | 默认值 | 含义 |
| host / port | 127.0.0.1 / 17860 | 保持在回环地址上：没有认证，能连上端口就等于能驱动编辑器 |
| timeoutMs | 180000 | 阻塞命令会自行抬高下限 |
| cacheTtlMs / cacheMaxEntries | 2000 / 128 | 按会话的读缓存 |
| rateLimitRps / rateLimitQueue | 5 / 32 | 每秒命令数 / 队列上限（0 关闭速率限制） |
| breakerThreshold / breakerCooldownMs | 3 / 30000 | 连续传输失败多少次后熔断 / 冷却时长 |
| logCapacity / logMinLevel | 512 / Display | 日志环形缓冲区 |
| logForwardingEnabled | false | 只有在编辑器内运行过 ual.ForwardLogs 之后才设为 true |
| rollbackOnDispose | false | 只有 LIFO 后缀能精确回滚 —— 见架构文档 |
| notifyOnEditorChange | true | 编辑器连接或断开时，向智能体注入一行提示 |
| screenshotAttachments / screenshotMaxBytes | true / 12MB | 图像块 / 大小上限 |
| maxBatchCalls | 12 | 每次 ual_batch 的上限 |

开发

npm run build # tsc → lib/
npm run dev # tsc --watch
npm run check # typecheck + tests + catalog reconciliation (run before committing)
npm test # tests only
npm run typecheck # src and tests typechecked separately

源码结构

src/
index.ts Cordis lifecycle, approval gate, dispose-time rollback
config.ts Schemastery schema (the single source of default values)
service.ts call() gate chain: catalog → requires → read cache → breaker → rate limit → send → ledger → translate
protocol/{bridge,serialization,types}.ts WS server / outbound validation / wire types
catalog/{method-data,method-overrides,methods}.ts 170-command catalog (data extracted from C++)
errors/translate.ts Error classification (by class name / status code, never by message text)
resilience/breaker.ts Rate limiter + circuit breaker
sessions/state.ts Session ledger / LIFO test / lock merging / cache / log filtering
tools/ The 12 tools
scripts/ Catalog extraction and reconciliation, doc generation and normalization,
the language set, and the DSH profile installer
docs/ Tutorial / protocol / architecture / command reference / install guide,
in 9 languages
tests/ 189 tests

生成文件：不要手动编辑

src/catalog/method-data.ts 和 docs/<lang>/command-reference.md 都是生成的：

node scripts/extract-methods.mjs .ua-ref/plugin/UnrealAgentLink/Source # rebuild the catalog from C++
npm run build && node scripts/gen-docs.mjs # rebuild the command reference (all 9 languages)

没人引用的手工维护表格，是这个项目里反复出现的一类缺陷（REQUIRED_KEYS、EXTRA_PARAM_KEYS 和 UAL_CODES 都曾栽在它手上）。对策是让每项检查去问源头，而不是问表格 —— 见架构 §9。

测试与检查

npm run check # typecheck (src + tests) + 189 passed + catalog + doc reconciliation
npm test # 189 passed
node scripts/check-catalog.mjs # 170/170 零漂移；每个 requires 键都出现在 C++ 中；代码集与 C++ 一致
node scripts/gen-docs.mjs --check # 全部 9 种语言的命令参考是否最新
node scripts/normalize-doc-headers.mjs --check # 全部 54 个文件里的语言栏是否规范
node scripts/normalize-doc-links.mjs --check # 正文链接能否从所在位置解析
npm run docs # 重新生成并改写 54 个文档的标题栏与链接
npm run install:dsh -- --profile web # 把本插件注册到 dsh 配置档（见 Installation）

十个测试文件按能发现哪类缺陷划分，每个都有理由——见架构 §11。

requires 不是手写的：它来自各处理函数自己的 SendError(..., 400, "Missing field: X") 消息（28 处），因为必填键写错，桥接层会在引擎看到之前就拒掉一次有效调用。结果落到 method-data.ts 里的 REQUIRED_KEYS，再由 methods.ts 的 requiresOf() 合并进运行时使用（service.call() 里的提前拒绝、ual_schema 里的 REQUIRED: 行、错误提示，全都走这一个函数）。

它刻意只收窄，不放宽：消息里含 or（"Missing field: name or path"）就整条跳过；从同文件被调用函数里采到的键，按分支局部丢弃——见 scripts/extract-methods.mjs 里的 REQUIRED_DROPPED，每条都标了对应的 C++ 行号。所以「没采到键」是安全的默认值，不是漏检。

不用 Unreal Engine 也能测试

跑这个插件不需要编辑器，也不需要 UEBox——接缝就是协议本身：UEBox 主动拨出连到这个桥接层，所以假编辑器只要是个会应答的 WebSocket 客户端就行。
bash
npm run smoke # 启动真实服务，拨入假编辑器，

调用全部 12 个工具，校验每个结果

npm run smoke -- --out /tmp/ual # 把记录和 PNG 存到别处
npm run smoke -- --method actor.get # 单个目录方法，原样打印
npm run mock:ue # 只起假编辑器，方便手动试探

tools/mock-ue-editor.mjs 是真实进程，不是桩：它拨 ws://127.0.0.1:17860，推送 project.info 和 system.heartbeat，转发 log.entry 行，为 editor.screenshot 写出真正的 PNG，并应答全部 170 个编目方法——关键方法族给贴近真实的响应体，其余方法给带文档所述结果键的响应体。tools/ual-smoke.mjs 启动的是 apply() 启动的同一个 UalService，通过每个工具真实的 execute 调用它，用该工具自己的输出 schema 校验每个值，并打印模型本会看到的内容。它是 tests/mock-editor.test.ts 的手动孪生版；两者都在架构 §11 里讲。

协议要点

UE → plugin: { ver:"1.0", type:"req", method, id, params } // id is generated by the server
plugin → UE: { ver:"1.0", type:"res", id, code, result } // the key is omitted when empty
UE → plugin: { ver, type:"evt", method, payload }

- 失败只靠 code 表达。信封层没有 error 字段。
- 给人看的文本放在 result.message（中文还是英文，取决于编辑器文化——不要解析它）；给机器读的细节放在 result.details。
- 很多处理函数返回 200，同时 result.ok === false（editor.undo、blueprint.compile、pie.observe），所以插件用 judge() 判断成功，不能只看 code。14 个 C++ 文件里共有 55 处 SetStringField(TEXT("error"), ...)——这是常态，不是异常。
- content.import_folder / content.import_assets 是发完就走的出站推送：没有 id，也不期待回复。插件把它们转成日志和智能体通知，不会伪造 res——回一个 ok:false 只会给用户弹一个假的「导入失败」对话框，比沉默更糟。

完整细节（全部 13 个状态码、序列化规则、超时语义）见协议参考。

License

MIT