前言¶
在 DSH 里，智能体已经能读仓库、跑命令，但 Unreal 关卡、蓝图、材质、序列渲染仍往往要人手点编辑器。社区里也有通过 UnrealAgentLink 协议连编辑器的做法；dsh-unreal-agentlink 是 hackmagic 维护的 DSH 工作流类插件，在 DSH 与 Unreal Editor 之间做纯桥接：规划与决策交给 DSH 原生智能体，插件只负责把工具调用翻译成 UnrealAgentLink 指令，并把编辑器回包转成智能体可用的结果。
这是什么¶
一句话：纯桥接层，智能体规划，插件翻译。
连接关系如下：
DSH agent ──tool calls──► dsh-unreal-agentlink ◄──WebSocket── Unreal Editor
(plans, decides) (server, translator) editor dials out
插件不替智能体拆任务。它提供 WebSocket 服务、协议翻译和安全层，让智能体可以查询关卡、生成 Actor、改蓝图与材质、渲染序列、截屏（可被模型「看见」），并在出错时按会话做撤销等操作。底层 UnrealAgentLink 侧约有 170 条命令；插件通过 12 个 DSH 工具暴露能力，而不是把 170 个工具全部塞进上下文。
维护者与仓库：hackmagic，GitHub；社区目录页：skillhub.cn/plugins/hackmagic/dsh-unreal-agentlink。当前 package 版本为 0.1.0，许可证 MIT。目录站与 DeepSeek / 幻方无官方从属关系，属于 DSH「一切皆插件」生态下的独立收录。
核心功能¶
桥接与安全¶
- 编辑器主动拨出到本机 WebSocket（默认
ws://127.0.0.1:17860），启动顺序无关；UnrealAgentLink 在StartupModule里会每 5 秒重试连接。 - 无需 UEBox、token 或握手即可工作。UEBox 只是同厂商另一客户端，若与编辑器同时占用 17860 会端口冲突，并非运行时依赖。
- 未在目录中注册的 method 会被直接拒绝，不会发到编辑器；破坏性 / 危险操作经
tools/pre-execute走审批（ask），由会话策略决定是否执行。
12 个 DSH 工具（摘要）¶
| 工具 | 作用 |
|---|---|
ual_status |
连接、熔断、限流、会话等状态；排错时优先看 |
ual_tools |
列出 170 条命令（22 个 family），可按 family 或关键字过滤 |
ual_schema |
某条命令的精确参数名（UE 会静默忽略未知 key） |
ual_call |
执行单条命令，原样返回编辑器结果 |
ual_batch |
一批命令一次往返（受 maxBatchCalls 限制） |
ual_screenshot |
截图并返回智能体可看的图像 |
ual_logs |
读本地日志环 |
ual_undo / ual_undo_history |
按会话回滚 / 查看撤销缓冲 |
ual_locks |
资产锁，编辑器侧可显示 AI 编辑标识 |
ual_editor_bind |
多编辑器时绑定到指定 session |
ual_task |
长耗时阻塞命令转为后台任务，对话可继续 |
风险分级（README 统计）：read 65 / write 89 / destructive 2 / dangerous 14。
运行环境¶
| 项 | 要求 |
|---|---|
| Unreal Engine | 5.0 – 5.8 |
| UnrealAgentLink | C++ 插件，放入工程 Plugins/ |
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| DSH | 以 bundle 形式安装本插件 |
安装与启用¶
安装分三块：工程里启用 UnrealAgentLink、把 dsh-unreal-agentlink 注册进 DSH、打开编辑器验证。下面按官方 README 顺序说明。
1. 在 UE 工程中安装 UnrealAgentLink¶
- 将整个
UnrealAgentLink目录复制到工程的Plugins/（或引擎全局Plugins/）。 - 重新生成工程文件并打开工程。
- 在 Edit → Plugins 中确认 UnrealAgentLink 已启用；会依赖引擎自带的
IKRig与PythonScriptPlugin。
若 17860 已被占用（例如 UEBox），可在启动编辑器时改端口，并在 DSH 插件侧同步 port：
UnrealEditor.exe MyProject.uproject -UALServer=ws://127.0.0.1:17861
2. 安装并注册 DSH 插件¶
在插件源码目录中先完成构建与校验（npm run check 须全部通过，含类型检查、测试与 170 条命令目录一致性）：
npm install
npm run check
package.json 通过 dsh.bundle.patch 指向 cordis.patch.yml，向 DSH 插入 bundle 项 unreal-agentlink（名称 dsh-unreal-agentlink）。README 说明：DSH 本身没有「安装本地树外插件」的一条命令，因此仓库提供安装脚本：
npm run status:dsh -- --profile web
node scripts/install-dsh-plugin.mjs --profile web
脚本会镜像产物、改 manifest、安装并验证；若 DSH 仍在占用 manifest 则不会改写。web profile 可用 dsh --profile web --dump-config 检查输出中是否出现 # == dsh-unreal-agentlink。desktop profile 需先完全退出 Desktop 再执行 dsh plugin --profile desktop install，并用 dsh plugin --profile desktop list 验证（CLI 不能直接 --dump-config desktop）。
也可按 README「Manual install」将 lib、cordis.patch.yml、package.json 等复制到 $DSH_HOME/profiles/<profile>/.vendor/，在 profile 的 package.json 增加 dependencies 与 dsh.profile.bundles，再执行 dsh plugin --profile <profile> install。
配置分层：后一层会整体替换该 bundle 行的 config，不会深度合并；覆盖配置时需重写要保留的全部键。
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: []：桥在等待编辑器；确认工程已打开且 UnrealAgentLink 启用。
编辑器刚连上时可能只有 sessionId、connectedAt 等字段，project 等需等 project.info 推送，属正常现象。
再用无副作用的读操作试一条：
ual_call { method: "level.get_current" }
更完整的流程、故障排查见仓库 docs/01-tutorial.md。
典型用法¶
- 发现能力：
ual_tools按任务过滤命令族；对具体 method 先ual_schema核对参数名。 - 只读探查：
ual_call调用如level.get_current等 read 类命令。 - 批量改动：
ual_batch合并多次往返；其中任一 dangerous 项会使整批进入审批。 - 可视化：
ual_screenshot把视口变成智能体可分析的附件（默认受screenshotMaxBytes等限制）。 - 长任务：阻塞型命令用
ual_task，避免长时间占满游戏线程导致编辑器无响应（注意：协议层没有cancel_task，结束等待不等于引擎侧取消）。 - 回滚：
ual_undo/ual_undo_history配合会话；可选配置rollbackOnDispose（仅 LIFO 后缀可精确回滚，细节见架构文档）。
常用配置默认值（节选，完整说明见教程 §7）：
| 键 | 默认 | 含义 |
|---|---|---|
host / port |
127.0.0.1 / 17860 |
仅环回；无鉴权时暴露端口即等同于可驱动编辑器 |
timeoutMs |
180000 |
阻塞命令另有下限 |
rateLimitRps / rateLimitQueue |
5 / 32 |
限流（0 关闭） |
maxBatchCalls |
12 |
单次 ual_batch 上限 |
适用场景与注意¶
适合谁：已在用 DSH 做自动化或智能体工作流、并希望把 Unreal 5.x 编辑器能力（关卡 / 资产 / 序列 / 截图等）纳入同一对话与工具链的团队或个人。
协议侧约束（影响写法，非本插件可选）：
- 连接方向是编辑器拨出，不是 DSH 去连编辑器。
- 无认证；端口即凭证，默认只绑环回，不宜改为
0.0.0.0。 - 命令在游戏线程串行执行；阻塞命令执行期间编辑器可能无法响应其它查询。
- 没有协议级取消；
ual_task停止等待后引擎仍可能继续跑完。
权限与信任：插件随当前 DSH 进程运行，能调用的编辑器能力与 DSH 所在用户权限一致。安装前请自行审阅 源码与 MIT 许可证，确认审批策略（如对 destructive / dangerous 的 ask）符合你的 unattended 场景需求。
结尾¶
dsh-unreal-agentlink 把 UnrealAgentLink 的 170 条编辑器命令收敛为 12 个 DSH 工具，让原生智能体在「只翻译、不规划」的前提下操作关卡与资产。若要安装或查版本，可看社区目录 hackmagic/dsh-unreal-agentlink 与 GitHub 仓库 github.com/hackmagic/dsh-unreal-agentlink。
