教程 2：WebUIStudio

相关：教程 1：用 AI 制作界面、教程 4：人工编写界面。

启动

第一次使用先下载依赖。 点击关卡编辑器工具栏上的 WebUIStudio 按钮；依赖缺失或与插件版本不一致时，会弹出“OrionBrowser 依赖”窗口，点“下载”，完成后点“打开 WebUIStudio”，见安装。依赖齐全之后，用下面两种方式启动：

• 从 Unreal 启动（推荐）：点击关卡编辑器主工具栏上的 WebUIStudio 按钮。Studio 打开当前工程并自动信任它。
• 直接启动：双击插件目录下的 Binaries/Win64/WebUIStudio.exe，选择 .uproject。这样打开的工程需要手动点一次“信任此工程”。

“设置”里的“本地数据”显示 Studio 数据占用的空间，并可以清理。

信任与运行环境

工程被信任之前，Studio 只列出界面；点提示条上的“信任此工程”之后，才会运行预览、安装依赖和发送请求。不要信任来历不明的工程。

Studio 自带 Node.js 和 npm。界面缺少依赖时，点提示条上的“一键安装环境”。发送标注和新建界面需要自行安装并登录 Codex 或 Claude 桌面应用；隔离草稿还需要它们的命令行工具和 Git。按 Ctrl+K 输入“检查运行环境…”可以重新检测。

认识窗口

打开一个界面

1. 在左栏点一个界面。工程自己的界面在“生产界面”，插件自带的 Showcase 和 Sample 在“插件示例”。
2. 界面有多个页面或视图时，展开行尾的箭头，点某一页或某个视图直接打开它。
3. 在上下文条里选择“来源”：

新增或移动界面后，点左栏的“重新扫描工程”。

页面按所选“分辨率”排版；拖动预览右下角外侧的手柄改变长宽比，双击恢复 1920 × 1080。缩放和移动见快捷键；工具坞的“截图并复制”把预览截图放进剪贴板。

预览里业务操作不执行，声音不播放，Native Surface、运行时图片和 Unreal 资产显示为占位；使用回退字体时，上下文条标出“字体/资源为回退”。蓝图或 C++ 逻辑、真实输入、声音、性能和叠在关卡上的可读性要在 Unreal 里检查。

预览底色

页面大部分是透明的。工具坞的“预览底色”决定透明处显示什么：透明网格（默认）、白色、黑色、灰色、自选颜色，或一张图片。放一张游戏截图作底，可以直接看出文字在画面上是否清楚。截图会带着同样的底色。

透明网格（默认）

白色

黑色

图片（这里是一张示意底图）

视图：webui-preview.json

一个页面常常有好几种样子：不同语言、空数据、弹窗打开。在 App 根目录放一份 webui-preview.json，把它们登记成视图，就能在左栏逐个打开。

例如各篇教程共用的设置面板：

{
	"schemaVersion": 1,
	"views": [
		{ "id": "default", "route": "", "title": "Default" },
		{ "id": "chinese", "route": "", "title": "Chinese", "patch": { "culture": "zh-Hans" } },
		{ "id": "muted", "route": "", "title": "Volume 0", "patch": { "volume": 0 } }
	]
}

"default" · 没有 patch

"chinese" · patch: { "culture": "zh-Hans" }

"muted" · patch: { "volume": 0 }

视图的数据来自 App 的预览状态：src 下名字同时含有 preview 和 state 的导出（例如 createSettingsPanelPreviewState），常量或没有必填参数的函数都可以；也可以用 state 字段指明。没有预览状态时页面停在空状态，“发现报告”会写明原因。

每个路由的第一个视图是默认视图。随附 Showcase 的 webui-preview.json 可以作为参考。

场景

上下文条的“场景”默认是“动态预览 · 工程源码”，每个视图一个。需要源码里没有的特殊状态时，从左栏底部打开“场景”，编辑 JSON（初始状态、操作的应答规则、按时间发出的事件），点“校验并保存”，之后就能在上下文条里选用这个自定义场景。

检查与日志

检查页签。 用“控件”工具点一个控件，右栏显示它的控件 Id、尺寸、源码文件与行号、组件层级和匹配到的样式规则。“在编辑器中打开”用系统默认程序打开源文件。

日志页签。 按时间倒序记录页面与宿主之间的消息、页面的 console 输出和被拦截的外部请求，可以按“全部”“警告”“错误”过滤。页面出错或操作被拒绝时，“日志”页签上出现红点。

“检查”页签：点的是 settings-reset 这个控件

“日志”页签：在“浏览”下点了 Low 和 Restore defaults 之后

标注并发给 Agent

Studio 可以把修改意见连同控件位置、截图和源码行一起交给 Codex 或 Claude。前提：工程已信任，并且已经安装并登录对应的桌面应用。

做标注

在工具坞选择一种标注工具：

选定后弹出标注浮层：

• 写下“想让这里怎么改”，按 Enter 保存，Shift+Enter 换行，Esc 取消。
• 评论为空时，“控件”工具可以用 ↑、↓ 改选父级或第一个子控件。
• 对单个控件可以展开“调整属性”，直接改文字、颜色、字体、间距、尺寸、边框等。这些调整只作用于预览，不改源码，它们作为目标值随标注交给 Agent。

保存的标注在页面上显示编号，可以在右栏“标注”页签里修改、“重新选择目标”和删除。一批最多 30 条。页面或源码变化后标注会标出“需要重新定位”，用“重新选择目标”指定新目标。

标注工具启用时，点击不会传给页面；要操作页面先切回“浏览”。

发送

1. 在右栏底部写这一批的整体要求。
2. 点“发送给”，选择 Codex 或 Claude 和方式。前三种直接修改当前工程：

3. 需要时调整模型与推理强度、修改范围，或打开“计划模式”（只写计划，不改文件）。
4. 点“发送标注”。

没有标注时，按钮变成“发送整页修改”，让 Agent 修改当前预览的整个页面。

右栏的发送记录显示每一条的状态；对方改完源码后，预览直接显示结果。“停止跟踪”只结束 Studio 的等待，不会停止桌面应用里已经开始的任务。

向 Claude 发送时，Studio 会在工程的 .claude/settings.json 里登记几条 statusMessage 为 Orion WebUI Studio bridge 的 Hook，用来接收回执。这个文件通常随版本库共享，提交前先看一眼这处改动。

新建界面

左栏第一行的“新建界面”打开一个弹窗：

1. 写“界面描述”：要做什么、显示什么、能操作什么。写法见教程 1。
2. “界面名”可选：大写字母开头，只含字母和数字，不能与已有界面重名。留空则由接收方命名。
3. 选择发给 Codex 还是 Claude，用新聊天还是专属聊天。
4. 点“发送给…”。或者点“复制提示词”，粘贴到任意对话里。

对方完成后，新界面出现在左栏；需要在 Editor 里完成的步骤由对方在回复里列出。

隔离草稿

想先看改动再决定要不要时，用“隔离草稿”：

1. 添加标注，在“发送给”里选 Codex 或 Claude 的“隔离草稿”，点“生成隔离草稿”。
2. Studio 在一份副本里让命令行工具修改，然后运行这个界面的类型检查、测试和构建。
3. 在“草稿”页签审阅差异，可以把草稿和原工程并排预览。
4. 满意后点“应用到工程”（之后可以“撤销这次应用”），再按需点“重建当前界面的 dist”。

所有标注必须属于同一个界面，并且来自“源码”来源。草稿只能改标注定位到的源码文件，以及你允许时的共享组件、入口与通信文件；只有工程 Content/UI/WebUI 下的界面能应用草稿。

快捷键

排查