claude-holo-unreal

# claude-holo-unreal **虚幻引擎的副驾驶工具，用于 [Claude Code](https://claude.com/claude-code)** — 打包为命令行接口、MCP 服务器、两个 Claude Code 技能和一个纯 Python 库。通过其自带的 `PythonScriptPlugin` 驱动正在运行的 UE 编辑器，以进行任何编程操作，并通过 [H 公司 Holo3](https://hub.hcompany.ai) 的视觉定位功能来完成最后一步的点击（仅限 Slate 菜单）。 > 用纯英文描述 UI 元素 — `"播放按钮"`、`"文件菜单中的全部保存"`、`"大纲面板标题"` — `holo-unreal` 截取编辑器窗口的截图，向 Holo3 查询其位置，然后合成点击。 > > 运行 `hue ue py "import unreal; ..."` 在正在运行的编辑器中执行任意 Python 代码，或注册 MCP 服务器，让 Claude Code 直接调用 `ue_py`、`ue_click`、`ue_errors`、`ue_launch`。 纯 Win32 `ctypes` 用于输入层。不使用 `pywin32`、`pyautogui` 或 Selenium（如果您还需要焦点助手，这些是可选的额外功能）。 --- ## 四种界面，一个软件包 | 界面 | 使用场景 | 入口点 | | ---------------- | ------------------------------------------------------------------------ | ------------------------------------------------------- | | **命令行接口** | Shell 脚本、临时终端使用、快速单次操作 | `hue …` / `holo-unreal …` / `python -m holo_unreal …` | | **MCP 服务器** | Claude Code 直接调用工具（无需 Shell 往返），适用于代理 | `claude mcp add -s user holo-unreal -- python -m holo_unreal.mcp_server` | | **技能** | Claude Code 发现 **何时** 使用该工具包以及如何使用它 | `hue skills install` | | **Python 库** | 自动化脚本、笔记本、基准测试、测试套件 | `from holo_unreal import UEToolkit, click_by_description` | 所有四种界面共用同一个后端。您可以选择最方便的界面，不必选择特定的界面。 --- ## 为什么 虚幻引擎的编辑器具有深层次的编程接口 — `PythonScriptPlugin`、`Editor Utility Widgets`、`AssetTools`、`EditorAssetLibrary`、`BlueprintEditorLibrary` — 可用于任何可表示为 `.uasset` 变更的操作。您应该尽可能使用它们：它们是确定性的，存活于焦点更改，运行于无头模式，并提供真正的错误。 但是，日间 UE 工作中的一部分内容存在于 Slate 渲染的菜单、市场插件设置面板和定制编辑器子窗口中，没有可用的脚本 API。对于这最后一步，`holo-unreal` 截取编辑器截图，并询问视觉语言模型以查找您要求的内容。 **经验法则** `hue` 技能文件编码： > 优先使用 `hue ue py "<python>"`。仅当不存在 API 路径时，才使用 `hue click "…"`。 --- ## 要求 - **Windows 10 / 11**（使用 `user32.dll`；欢迎 Linux/macOS 拉取请求） - **Python 3.11+**（测试至 3.13） - **虚幻引擎 5.x** 安装在 `C:\Program Files\Epic Games\UE_5.*`（可通过 `UE_ENGINE_BASE` 重写） - **H 公司 API 密钥** — 在 [portal.hcompany.ai](https://portal.hcompany.ai) 生成 — 仅适用于视觉方面（`hue click`、`hue locate`、`hue type`、`hue double-click`、`hue right-click`）。UE 工具包（`hue ue …`）无需此密钥。 - **Claude Code** 已安装，用于 MCP / 技能集成。CLI 或 Python 库无需此项。 --- ## 安装 ```bash git clone https://github.com/ethanke/claude-holo-unreal cd claude-holo-unreal # 推荐：可编辑安装，包含所有额外功能（MCP + 焦点助手）。 pip install -e .[all] # 或最小安装（仅限 CLI + 视觉功能）： pip install -e . # 或从 GitHub 安装，无需克隆： pip install "git+https://github.com/ethanke/claude-holo-unreal#egg=claude-holo-unreal[all]" # 配置 API 密钥 cp .env.example .env # 编辑 .env → 粘贴 HAI_API_KEY ``` 安装后，以下命令在 `$PATH` 上可用： - `hue` — 主 CLI 的简短别名 - `holo-unreal` — 同一 CLI，长名称 - `holo-unreal-mcp` — MCP 标准输入/输出服务器（您向 Claude Code 注册的内容） --- ## 一次性引导 ```bash hue claude ``` 就这样。`hue claude` 将两个已发布的技能安装到 `~/.claude/skills/`，在 `claude` 的用户范围配置中注册 MCP 服务器（如果它尚未注册），检查您的 `HAI_API_KEY`，然后移交给 `claude` CLI，以便您直接进入一个带有 `unreal-toolkit` + `unreal-vision` + `ue_*` MCP 工具的 Claude Code 会话。 幂等 — 可以重复运行。使用 `--force` 重新安装技能并重新注册 MCP 服务器。 ```bash hue # 裸 `hue` 别名为 `hue claude` — 真正的一键启动 hue claude # 显式形式 hue claude -- --continue # 将参数传递给 `claude` hue claude --force # 重新安装技能，重新注册 MCP，然后启动 hue claude --no-mcp # 跳过 MCP 注册步骤 hue claude --no-skills # 跳过技能安装步骤 hue claude --scope project # 而不是在用户范围内注册 MCP hue setup # 相同的引导程序，但不启动 ``` --- ## 快速入门 — 三种常见流程 ### 1. UE 工具包来自 Shell ```bash # 诊断设置（引擎、插件、远程执行、日志路径、运行的 PID） hue ue doctor --project "C:/Users/you/Projects/MyGame/MyGame.uproject" # 启动编辑器，分离 hue ue launch # 跟踪当前会话日志中的错误 hue ue errors --since-session # 一次性：启用 Python 远程执行 + 重启编辑器 hue ue enable-remote # 现在在正在运行的编辑器中执行 Python hue ue py "import unreal; print(unreal.SystemLibrary.get_project_directory())" # 或整个文件 hue ue pyfile examples/compile_all_blueprints.py # 无头命令 hue ue fixup # 修复重定向器 hue ue resave --path /Game/MMO hue ue cook --platform Windows hue ue package --platform Win64 --config Shipping --out C:/Builds ``` 在 `.env` 中设置 `UE_PROJECT` 后，您可以从每个命令中删除 `--project`。 ### 2. Holo3 视觉 — Slate 菜单、插件面板、模态窗口 ```bash # 发现窗口 hue list-windows # 预览定位（写入带有红色十字准星的注释 PNG） hue locate "主工具栏上的绿色播放按钮" --save preview.png # 真正点击它 hue click "工具栏中的蓝图菜单" # 右键 / 双击 hue right-click "视口中的选定演员" hue double-click "内容浏览器中的资产" # 点击然后输入 hue type "搜索框" "CharacterBP" # 仅限键盘的和弦（无点击，无定位调用） hue press "ctrl+s" hue press "alt+p" # 启动 PIE hue press "shift+escape" # 停止 PIE # 目标非默认窗口 hue click "编译" --window-title "MyProject" ``` 每个视觉命令都在 stdout 上为 JSON，并打印坐标，以便您可以将它们输入到第二个步骤中。 ### 3. 从 Claude Code 内部（MCP + 技能） 一个命令： ```bash hue claude # 设置 + 启动 ``` 或手动，如果您更喜欢分步： ```bash # 将已发布的技能复制到 ~/.claude/skills/ hue skills install # 注册 MCP 服务器 claude mcp add -s user holo-unreal -- python -m holo_unreal.mcp_server # 启动 Claude Code claude ``` 注册后，Claude Code 有以下 MCP 工具可用： | 组 | 工具 | | ----------- | ------------------------------------------------------------------------------ | | UE 生命周期| `ue_info`、`ue_launch`、`ue_close`、`ue_doctor` | | UE 日志 | `ue_log`、`ue_errors` | | UE 无头 | `ue_headless`、`ue_fixup`、`ue_resave`、`ue_cook`、`ue_package` | | UE Python | `ue_py`、`ue_pyfile`、`ue_enable_remote` | | 视觉 | `ue_focus`、`ue_list_windows`、`ue_locate`、`ue_click`、`ue_right_click`、`ue_double_click`、`ue_type`、`ue_press` | | 元 | `hue_info` | 已发布的技能（`unreal-toolkit`、`unreal-vision`）告诉 Claude Code **何时** 调用每个工具，并记录了难点（UE Slate 菜单忽略 Alt+F，PIE 捕获光标等）。 ### 4. 库使用 ```python from holo_unreal import ( UEToolkit, click_by_description, type_into, press_key, localize_in_window, focus_ue, ) # 绑定项目；所有工具包操作都针对它。 ue = UEToolkit(project=r"C:\Projects\MyGame\MyGame.uproject") print(ue.info()) print(ue.doctor()) # 在正在运行的编辑器中运行 Python。 ue.py("import unreal; print(len(unreal.EditorLevelLibrary.get_all_level_actors()))") # 适用于 Slate / 插件 UI 的视觉功能。 focus_ue() click_by_description("工具栏中的蓝图菜单") type_into("搜索框", "Paladin") press_key("s", modifiers=["ctrl"]) ``` --- ## 工作原理 ### 视觉路径 1. **查找窗口。** `user32.EnumWindows` + 窗口标题不区分大小写的子字符串匹配（默认为 `"Unreal Editor"`，可通过 `HOLO_UNREAL_WINDOW_TITLE` 重写）。 2. **截图。** `SetForegroundWindow` → 150 ms 结算 → `PIL.ImageGrab.grab` 带有窗口的 `GetWindowRect` 边界框（`all_screens=True` 用于多显示器）。 3. **定位。** 与 `api.hcompany.ai/v1/` 的 OpenAI 兼容的聊天完成： ```python extra_body={ "structured_outputs": {"json": {"type":"object","required":["x","y"],...}}, "chat_template_kwargs": {"enable_thinking": False}, } temperature=0.0, max_tokens=1024 ``` Holo3 返回 `{x, y}` 以截图本地像素。 4. **点击。** `SetCursorPos(screen_x, screen_y)` → `mouse_event(LEFTDOWN|LEFTUP)`。 #### 为什么使用 `extra_body` 而不是 `response_format` Holo3 受管端点具有三个非标准怪癖，所有怪癖都为您处理： - **`extra_body["structured_outputs"]["json"]`** 而不是 OpenAI 标准 `response_format={"type":"json_schema", ...}`。标准键返回误导性的 `400 "您必须提供模型参数"`。 - **平面架构。** `$defs`/`$ref` 被验证器拒绝；内联所有内容。 - **禁用思考。** Holo3 默认隐藏思维链。没有 `chat_template_kwargs={"enable_thinking": False}`，小 `max_tokens` 预算会因思维链而烧毁，并返回带有 `finish_reason=length` 的空内容。 ### 工具包路径 启动 / 关闭 / 日志 / 错误使用对 `UnrealEditor.exe` 和 `UnrealEditor-Cmd.exe` 的纯 `subprocess`，引擎从 `.uproject` 的 `EngineAssociation` 自动检测。`cook` / `package` 委托给 `RunUAT.bat`。 编辑器中的 Python 使用 `PythonScriptPlugin` 内置的 `remote_execution.py` 模块 — 与 UE 本身用于 **Python 交互控制台** 的协议相同。工具包从检测到的引擎路径导入它，启动 `RemoteExecution` 客户端，等待编辑器宣传节点，并使用 `MODE_EXEC_FILE` 执行代码。启用它一次，使用 `hue ue enable-remote` — 将 `bRemoteExecution=True` 写入 `Config/DefaultEngine.ini` 下的 `[/Script/PythonScriptPlugin.PythonScriptPluginSettings]` **和** 将 `PythonScriptPlugin` + `EditorScriptingUtilities` 添加到 `.uproject`。 --- ## UE 特有的注意事项 这些已内置到技能文件中，因此 Claude Code 自动尊重它们；如果您直接驱动工具，了解它们很有用： - **UE Slate 菜单不遵循 `Alt+F` 类型的和弦。** 使用 `hue click "顶部菜单栏中的 '文件' 字样"` 打开文件，而不是 `hue press alt+f`。 - **PIE（在编辑器中播放）捕获光标。** 一旦 PIE 运行，`hue click` 定位游戏而不是编辑器外壳。要稳健地停止 PIE：`hue press f8`（弹出）→ `hue press shift+escape` → `hue press shift+escape`。 - **UE Slate 小部件很少公开 UIA 可访问性名称。** 如果您想通过可访问性树驱动编辑器，请改用 Python API 或视觉功能。 - **密集工具栏上 ±15 像素的散射。** Holo3 是一个 3B 活跃的 VLM。对于紧密的目标，提供更多上下文（“工具栏上的保存所有图标，位于播放按钮的立即右侧”）或回退到键盘快捷键。 - **`SetForegroundWindow` 偷走焦点。** 每次截图之前。如果您在终端中输入，您的按键将落在 UE 上。`focus_ue()` 助手使用 alt-key 技巧来满足 Windows 最近的输入焦点策略。 - **`enable-remote` 需要编辑器重启** 以使 INI 更改生效。没有办法解决 — UE 在启动时缓存插件设置。 - **重定位后重定向器清理。** 对于因文件夹重命名而损坏的 `.uasset` 文件，`hue ue fixup` 不够 — 在 `Config/DefaultEngine.ini` 中使用 `CoreRedirects`（旧路径和新路径需要指向 **相同** 的类，而不是两个副本）。 --- ## 基准 `bench/bench_ue.py` 运行一套探测任务（定位播放、内容抽屉、保存全部、Outliner/Details + 一个真正的 File 菜单点击，并带有前后差异）并报告计时： ```bash python bench/bench_ue.py # 编写 bench_out/report.md python bench/bench_ue.py --dry-run # 仅定位 python bench/bench_ue.py --tasks locate-play-button,locate-save-all ``` 针对 2576×1048 的 UE 编辑器在 `holo3-35b-a3b` 上的典型数字： | 指标 | 值 | | -------------------- | --------- | | 平均定位 | ~970 毫秒 | | 中位数定位 | ~770 毫秒 | | 95% 定位 | ~900 毫秒 | | 任务到任务 | ~1.5 秒 | --- ## 示例 在 `examples/` 中查看已编写的脚本，它们通过 `hue ue pyfile` 在编辑器中运行： - `compile_all_blueprints.py` — 编译项目中的每个蓝图，报告失败 - `reparent_blueprint.py` — 在包更新后交换蓝图的父类 - `find_references.py` — 转储每个引用目标路径的资产 --- ## 包布局 ``` claude-holo-unreal/ ├── holo_unreal/ │ ├── __init__.py # 库导出 │ ├── __main__.py # `python -m holo_unreal` │ ├── cli.py # 统一 CLI（hue / holo-unreal） │ ├── toolkit.py # UE 生命周期、日志、命令、编辑器中的 Python │ ├── vision.py # Holo3 + Win32 ctypes 输入 │ ├── focus.py # UE 窗口前景助手 │ ├── scenarios.py # 精选的 UE 测试场景 │ ├── mcp_server.py # FastMCP stdio 服务器 │ └── _env.py # .env 加载器 + 默认值 ├── holo_unreal/skills/ │ ├── unreal-toolkit/SKILL.md │ └── unreal-vision/SKILL.md ├── examples/ # 编辑器端 Python 脚本 ├── bench/bench_ue.py # 定位延迟基准测试 ├── pyproject.toml ├── .env.example └── README.md ``` --- ## 相关 - [H 公司 Holo3 快速入门](https://hub.hcompany.ai/quickstart) — 视觉模型的官方 API 文档 - [`hcompai/surfer-h-cli`](https://github.com/hcompai/surfer-h-cli) — H 公司官方 Holo 浏览器代理。`claude-holo-unreal` 是 UE 编辑器模拟。 - [Unreal `PythonScriptPlugin`](https://docs.unrealengine.com/5.4/en-US/scripting-the-unreal-editor-using-python/) — 优先使用此功能以实现 `.uasset` 变更。 - [Unreal MCP 桥接项目](https://github.com/ChiR24/Unreal_mcp) — 用于结构化 Actor/Asset API 的替代方法。 - [Anthropic 模型上下文协议](https://modelcontextprotocol.io/) — 让 Claude Code 直接调用 `ue_*` 工具的协议。 --- ## 贡献 欢迎 PR — 尤其适用于： - Linux / macOS 端的 Win32 输入层端口 - 拖动 / 悬停 / 滚动轮基元（目前仅支持点击/输入/按键） - `scenarios.py` 下的编辑器场景 - `examples/` 下的示例 如果您不确定范围，请先开一个问题。 --- ## 许可证 MIT — 见 `LICENSE`。