企业官网建设流程全解析

Unreal_mcp（EngineWire）是一个开源的 MCP（Model Context Protocol）服务器，通过原生 C++ 编辑器插件让 AI 助手直接控制 Unreal 编辑器：建关卡、写蓝图、截图验证，背后是 400+ 项能力。它最耐人寻味的设计是双传输架构——同一套编辑器操作，既能通过插件内置的 HTTP 服务直连，也能经 Node.js 服务器走 stdio + WebSocket 桥接。而所有路径最终都汇入同一个安全枢纽：游戏线程请求队列。

一、先认识主角：EngineWire 插件在系统里扮演什么角色 🧭

无论走哪条传输路径，真正"动手"的永远是运行在编辑器进程内的EngineWireC++ 插件。它注册为编辑器子系统（UEngineWireSubsystem），负责：

• 接收两条传输线送来的自动化请求
• 把请求排队、调度到游戏线程执行
• 调用编辑器 API 完成实际操作（生成 Actor、建蓝图、截图……）
• 把结果、进度、回执原路返回给客户端

也就是说：传输层只负责"传话"，EngineWire 才是真正驱动 Unreal 编辑器的大脑。这也是理解整个架构的钥匙。

核心子系统声明：EngineWireSubsystem.h

二、双传输架构全貌：两条路，同一个unreal工具 🛤️

两条传输路径对外暴露完全相同的单一unreal网关工具，区别只在于"客户端怎么找到插件"：

协议契约在 docs/protocol.md 中有完整定义，网关客户端使用方式见 docs/gateway-client-guide.md。

为什么要做两条路？一句话：让"只支持本地命令的 MCP 客户端"和"支持 HTTP 的 MCP 客户端"都能接入同一个编辑器，且行为完全一致。Route B 的 TypeScript 桥接端位于 src/automation/，其设计文档明确写着两条传输彼此独立、互不绕过（src/automation/AGENTS.md）。

三、关键问题：AI 指令如何安全地驱动编辑器？💡

Unreal 的编辑器 API不是线程安全的——在渲染线程或网络线程上直接调用会崩溃。EngineWire 的答案是一套"请求队列 + 游戏线程单车道"机制，分四步走：

1️⃣ 入队：传输线程只登记，不动手

无论请求从 WebSocket 还是原生 HTTP 进来，都先调用QueueAutomationRequest()进入待处理队列。这一步发生在传输线程上，加锁、限额、记录来源，绝不调用任何编辑器 API。队列上限 64 个请求，每个会话最多占 16 个，防止单个客户端把队列"灌满"饿死别人（见 McpQueueFairness.h 的注释）。

2️⃣ 心跳：Core Ticker 每帧检查一次

插件初始化时向 Unreal 的Core Ticker注册了一个每帧回调Tick()（EngineWireSubsystemLifecycle.cpp）。它有两个"安全阀门"：

• 编辑器正在保存、GC 或异步加载时，直接跳过排空——这些时刻调用对象解析可能崩溃
• 每个 tick 最多排空16 个请求，避免一帧内堆积过多编辑器操作

3️⃣ 排空：游戏线程上的"单条修改车道"

ProcessPendingAutomationRequests()是真正的工作者（EngineWireSubsystemRequestQueue.cpp）：

• 若不在游戏线程，它会AsyncTask(ENamedThreads::GameThread, ...)把自己投递到游戏线程——这是"排队请求最终必然跑在游戏线程"的第一个保证
• 每次派发前，代码硬性断言DispatchDepth == 1 && IsInGameThread()（同文件 L286-L290）。注释写得很直白：如果深度超过 1，就意味着有两条修改车道同时开着，这是调度器唯一可能出事的入口，所以在现场就炸

这套"单一修改车道"不变量是整套架构的承重墙：编辑器同一时刻只会被一个请求修改，绝不并行、绝不停叠。

4️⃣ 执行：派发前的最后三关

真正执行前（McpProcessRequest.cpp）还要过三道闸：

通过后，请求按action名查表找到对应处理器执行。执行期间还开着"错误捕获"：即使处理器自认为成功，只要引擎日志里出现 ensure 失败，响应就会被改写成ENGINE_ERROR——AI 拿到的结果永远和 Unreal 日志对得上。

四、长任务怎么办：8 秒报平安，27 秒给回执 ⏱️

编辑器操作（比如一次光照构建）可能远超 HTTP 客户端的耐心。原生传输有一条独立的保活线程专门处理这件事（设计见 plugins/EngineWire/Source/EngineWire/Private/MCP/AGENTS.md）：

• 静默 8 秒：向仍在执行的调用推送一次"心跳"，内容来自DescribeEditorWork()——当前在跑哪个 action、跑了多久、最后的进度百分比、还有多少 shader 在编译
• 27 秒：返回一个task.state = running的收据；工作继续，客户端可稍后用get_task_result取最终结果

这个设计让"慢"不再是"挂"：AI 客户端始终知道编辑器没死、在忙什么。

五、公平性：多客户端共享一个编辑器时 🤝

多个 AI 客户端同时连一个编辑器是 Route A 的常见场景。队列排空时不是"先来全办完"，而是按会话轮转选取一批请求：每个会话的旧请求一定先于新请求（会话内 FIFO），但任何会话都不会连续霸占队列头——轮转状态跨 tick 保持，上一批刚服务完的会话不能抢下一批的头位（McpQueueFairness.h）。效果：洪水式请求的客户端拿不到全部槽位，其他会话的请求在一个轮转周期内必被服务。

六、安全防线：本地、令牌、同意制 🔐

更多细节见 docs/security-and-receipts.md。

七、我该选哪条传输？🚀

• 选 Route A（原生 HTTP）：你的客户端支持 HTTP 传输（Claude Code、Cursor、VS Code），想省掉 Node.js，或需要多个客户端同时挂在一个编辑器上
• 选 Route B（stdio）：你用 Claude Desktop 这类只认command启动方式的客户端，或希望编辑器重启后自动恢复连接（Node.js 端在编辑器离线时返回NOT_CONNECTED，回来即通）

两条路殊途同归：同一个unreal工具、同一套search → describe → execute渐进发现流程、同一套回执与同意机制。完整配置对照表在 README.md 的Configuration一节，插件传输层的安全不变量清单见 plugins/EngineWire/Source/EngineWire/Private/Transport/AGENTS.md。

八、架构一句话总结 📌

传输层多线程、执行层单线程、排队层有公平、异常层有兜底。

EngineWire 用一条"游戏线程单修改车道"把 AI 的不确定性挡在编辑器之外：传输线程只管登记，Core Ticker 每帧安全排空，派发前连过三道闸，长任务有保活线程报平安。这正是"让 AI 安全驱动一个非线程安全的实时引擎"最务实的答案。