Unity-Autorun-MCP

# Unity 自动运行工具 [English](./README.md) | [中文](./README_CN.md) Unity 自动运行工具是一款 Unity 编辑器扩展，用于自动执行 UI 启动流程、测试导航和 AI 辅助 UI 操作。它可以从编辑器预设点击 UGUI 和 FairyGUI 按钮，通过本地 HTTP 桥接器公开相同操作，并提供 .NET 8 MCP 服务器，以便 AI 客户端可以通过结构化工具检查和驱动 Unity UI 流程。 ## 功能 - 手动自动运行面板，用于可重复使用的“开始”和“停止”操作预设。 - 通过 GameObject 名称或按钮文本发现和点击 UGUI 按钮。 - 可选的 FairyGUI 支持，当 FairyGUI 安装在项目中时。 - 编辑器 Play 模式启动和关闭工作流的延迟操作序列。 - 本地 HTTP 桥接器，监听地址 `127.0.0.1:17331`。 - .NET 8 CLI 和 MCP 服务器，用于 Codex、Claude 或其他支持 MCP 的客户端。 - 通过 `mcp/ui-nav-map.json` 支持 UI 导航地图。 - 点击和等待基于 UI 转换的路由解析和执行。 - 导航地图工具，用于指导、源扫描、补丁验证、合并、摘要、子图和 HTML 预览。 - 窗口内控制台，支持 Debug、Info、Warning 和 Error 过滤。 ## 要求 - Unity 2021.3 或更新版本。 - UGUI 用于内置 Unity 按钮自动化。 - FairyGUI 仅在需要自动执行 FairyGUI 按钮时需要。 - .NET 8 SDK 用于 CLI 和 MCP 服务器。 ## 安装 推荐的安装方法是使用 Git URL 通过 Unity 包管理器安装。 1. 打开 `Window > Package Manager`。 2. 按 `+`。 3. 选择 `Add package from git URL...`。 4. 输入： ```text https://github.com/SHthemW/Unity-Autorun-Tool.git ``` 为了可重复安装，请使用版本标签： ```text https://github.com/SHthemW/Unity-Autorun-Tool.git#v0.1.0 ``` 也支持手动安装。将此存储库复制或克隆到 Unity 项目下的： ```text Assets/Editor/Unity-Autorun-Tool ``` 打开 Unity 并使用： ```text Window > Auto Run Window ``` 该扩展程序将手动自动运行配置存储在 Unity 编辑器进程基目录之外： ```text AutorunToolData/config.xml ``` 这将本地自动化预设与正常的项目版本控制分开。 ## 手动自动运行 打开 `Window > Auto Run Window`，然后使用 `Manual AutoRun` 面板。 1. 按 `First use? Press me to create an autorun action config :)`。 2. 在创建初始文件后按 `Save config`。 3. 使用 `Then, press me to create a new action preset` 创建预设，或在至少存在一个预设后，在预设下拉菜单旁使用 `+`。 4. 在 `Action - Go` 或 `Action - Stop` 下添加操作。 5. 填写操作字段。 6. 按 `Save config`。 7. 在需要启动自动化时使用 `Go!` 代替 Unity Play 按钮。 8. 在需要停止操作运行之前，使用 `Stop`。 操作字段： | 字段 | 含义 | | --- | --- | | `name` | 目标按钮 GameObject 名称。UGUI 查找还会通过忽略 `_`、`*`、结尾的 `GameObject` 和结尾的 `Button` 来规范名称。 | | `text` | UGUI 按钮的文本匹配（可选），当名称不明确时。默认为 FairyGUI，除非 FairyGUI 助手支持文本过滤。 | | `delay` | 此操作运行前的延迟。 | | `FGUI` | 使用 FairyGUI 点击代替 UGUI 点击。如果未安装 FairyGUI，则自动禁用。 | `Go` 操作在进入 Play 模式后运行。`Stop` 操作在编辑器退出 Play 模式前运行。 该工具会创建一个运行时 `AutoRunHandler` GameObject，并将其标记为 `DontDestroyOnLoad`。如果您在手动使用 `Go!` 后使用 Unity 原始 Play 按钮启动 Play 模式，则现有的处理程序仍将存在，直到被删除或重置。 ## MCP 和桥接面板 `Window > Auto Run Window` 中的 `MCP` 面板分组了桥接控件、检测到的 MCP 进程、安装控件和帮助工具。 - `Start` / `Stop` 控制本地 Unity 桥接器。 - `Publish MCP` 运行 MCP 服务器的 `dotnet publish`。 - `Install MCP` 更新选定的 `.codex/config.toml` 或 `.claude/.mcp.json`。 - `Open Terminal` 在工具根目录打开终端。 - `Open Root` 打开此工具文件夹。 - `Preview Nav Map` 将 `mcp/ui-nav-map.json` 渲染为 `mcp/ui-nav-map.preview.html`。 您也可以从以下位置启动或停止桥接器： ```text Window > Auto Run MCP Bridge > Start Window > Auto Run MCP Bridge > Stop ``` 桥接器监听： ```text http://127.0.0.1:17331/ ``` ## CLI 从工具根目录运行 CLI。最简单的方法是打开 `Window > Auto Run Window`，然后在 `MCP` 面板中按 `Open Terminal`。这适用于 UPM Git URL 安装和手动 `Assets/Editor` 安装。 ```powershell dotnet run --project mcp~/UnityAutorun.Mcp -- help dotnet run --project mcp~/UnityAutorun.Mcp -- status dotnet run --project mcp~/UnityAutorun.Mcp -- play dotnet run --project mcp~/UnityAutorun.Mcp -- stop dotnet run --project mcp~/UnityAutorun.Mcp -- list-buttons --framework all dotnet run --project mcp~/UnityAutorun.Mcp -- click --name StartButton --framework ugui dotnet run --project mcp~/UnityAutorun.Mcp -- run-sequence --json-file sequence.json dotnet run --project mcp~/UnityAutorun.Mcp -- nav-guidance dotnet run --project mcp~/UnityAutorun.Mcp -- scan-nav-sources --map mcp/ui-nav-map.json dotnet run --project mcp~/UnityAutorun.Mcp -- backfill-nav-map --map mcp/ui-nav-map.json --preview true dotnet run --project mcp~/UnityAutorun.Mcp -- routes --map mcp/ui-nav-map.example.json dotnet run --project mcp~/UnityAutorun.Mcp -- route --map mcp/ui-nav-map.example.json --from A --to C dotnet run --project mcp~/UnityAutorun.Mcp -- run-route --map mcp/ui-nav-map.example.json --from A --to C dotnet run --project mcp~/UnityAutorun.Mcp -- navigate-ui --map mcp/ui-nav-map.json --to TargetView dotnet run --project mcp~/UnityAutorun.Mcp -- mock-bridge ``` 环境变量： | 变量 | 默认值 | 含义 | | --- | --- | --- | | `UNITY_AUTORUN_HOST` | `127.0.0.1` | Unity 桥接器主机。 | | `UNITY_AUTORUN_PORT` | `17331` | Unity 桥接器端口。 | | `UNITY_AUTORUN_TOOL_ROOT` | 自动检测的安装 | MCP 导航地图操作使用的工具根目录。 | ## MCP 服务器 发布服务器： ```powershell dotnet publish mcp~/UnityAutorun.Mcp -c Release ``` 发布输出也存档为 zip 文件，位于： ```text mcp~/UnityAutorun.Mcp/bin/Release-Archives/ ``` 编辑器 `Install MCP` 流程为选定的客户端注册此命令： ```powershell dotnet mcp~/UnityAutorun.Mcp/bin/Release/net8.0/publish/UnityAutorun.Mcp.dll mcp ``` 可用的 MCP 工具： - `unity_status` - `unity_play` - `unity_stop` - `list_buttons` - `click_button` - `run_sequence` - `get_nav_map_guidance` - `get_current_ui_nav_map` - `save_ui_nav_map` - `get_nav_map_summary` - `scan_ui_nav_sources` - `backfill_ui_nav_map_from_sources` - `query_nav_map_items` - `get_ui_nav_subgraph` - `validate_ui_nav_map_patch` - `merge_ui_nav_map_patch` - `list_ui_routes` - `resolve_ui_route` - `run_ui_route` - `navigate_ui` ## HTTP 桥接器 首先启动桥接器，然后调用： ```powershell Invoke-RestMethod http://127.0.0.1:17331/status Invoke-RestMethod http://127.0.0.1:17331/rpc ` -Method Post ` -ContentType application/json ` -Body '{"id":"1","command":"click_button","payload":{"name":"StartButton","framework":"ugui"}}' ``` 桥接器命令包括： - `status` - `play` - `stop` - `list_buttons` - `list_open_views` - `click_button` - `run_sequence` - `navigate_route` - `cancel_navigation` ## UI 导航地图 导航系统使用 `mcp/ui-nav-map.json`。如果该文件不存在，编辑器将回退到 `mcp/ui-nav-map.example.json`。 地图描述： - `views`：UI 屏幕、面板或视图根。 - `controls`：按钮和相关 UI 控件。 - `transitions`：一个视图如何到达另一个视图。 - `routes`：跨过渡的可重复使用的路径。 - `unresolved`：已知的需要手动分析的空白。 编辑器 `Navigation AutoRun` 面板加载地图，列出可导航的目标视图，按搜索文本过滤它们，并使用 `Go!` 运行路由。如果 Unity 不已经在 Play 模式下，它会存储待处理的目标，进入 Play 模式，并在 Play 模式启动后继续。 路由执行支持： - 由 UGUI 或 FairyGUI 按钮操作支持的 `click` 步骤。 - `wait` 步骤，等待视图出现。 - 通过编辑器面板或桥接器命令取消。 对于 AI 辅助地图生成，首先向 MCP 服务器请求 `get_nav_map_guidance`，然后使用扫描、查询、验证和合并工具，而不是直接编写 `ui-nav-map.json`。 ## 控制台 自动运行窗口包含一个用于工具消息的本地控制台。条目按以下类别分组： - `Debug` - `Info` - `Warning` - `Error` 切换按钮仅过滤可见性。`Clear` 删除当前条目。消息不会镜像到 Unity 控制台。 ## 项目布局 ```text . |-- AutoRun*.cs # 共享运行时/编辑器自动化模型和处理程序 |-- package.json # Unity 包管理器 Git URL 安装的元数据 |-- Bridge/ # HTTP 桥接器模型、调度器、序列和导航执行 |-- Editor/ # Unity 编辑器窗口、菜单、MCP 安装、进程、导航自动运行 UI |-- Services/ # UGUI/FairyGUI 按钮和活动视图发现 |-- Util/ # XML 和可选的 FairyGUI 助手 |-- mcp/ # 公共导航地图文件和 MCP 用户文档 |-- mcp~/UnityAutorun.Mcp/ # .NET 8 CLI 和 MCP 服务器源代码 ``` ## 故障排除 - 如果 `Install MCP` 失败，请先按 `Publish MCP`，并确认所选文件夹名为 `.codex` 或 `.claude`。 - 如果 CLI 桥接器调用失败，请在 Unity 中启动桥接器，并验证 `http://127.0.0.1:17331/status`。 - 如果未找到 UGUI 按钮，请检查运行时 GameObject 名称、规范名称和可选文本字段。 - 如果路由无法运行，请使用 `route`、`resolve_ui_route` 或 `get_ui_nav_subgraph` 检查它，并检查不支持或未解决的转换。 - 如果 `Navigation AutoRun` 显示没有目标，请创建或合并真正的 `mcp/ui-nav-map.json`，或从示例地图开始验证工作流程。