自动测试工具Unity-Autorun-Tool的演进(2026)
2024 年底，我做了一个很小的 Unity 自动点击工具。原因也很简单：每次进游戏都要等待场景加载，再依次点几个连接、登录和进入游戏的按钮。这段流程大约持续半分钟，操作不复杂，却要一直盯着。
工具后来尝试过 UI 导航图，现在的 0.3.4 则把流程交给可编译的 C# 业务脚本：AI 根据项目源码和运行时证据准备代码，Unity 编译并执行，脚本自己说明从哪里开始、做哪些动作，以及用什么结果判断成功。日常重复自测时，我直接运行已有脚本。
新版在隔离 Unity 演示工程中的实际界面，展示工具操作，不含宿主项目的业务数据；点击图片可打开仓库。本文使用方式按 0.3.4 更新。
从点击预设到业务脚本
第一版只保存顺序操作：找到按钮、必要时核对文字、等待一段时间，再执行下一步。它没有缩短游戏加载时间，只是让我不必守着完成那几次固定点击。
界面多起来以后，我用过导航图来整理界面、控件和跳转关系。共享的登录流程可以复用，但仅有“从主界面能打开背包”的关系还不够：入口可能受等级限制，可能要等待异步数据，同一个终点也可能有不同起点和业务流程。这些条件最终仍然需要落实到项目代码里。
现在我把这部分逻辑写进业务脚本，由 Unity 编译。旧导航图、图路由和手动 XML 导航入口已经移除，下文的使用方式都以 C# 脚本为准。旧数据不会被静默转换或删除，从旧版升级时需要重新检查自己的流程。
一个脚本要说明完整的一次自测
AI 生成代码之前，要先查看宿主项目的源码、Prefab 和实际运行状态。工具核心只提供脚本契约、编译与运行、UI 状态和基础交互，具体界面名称、业务 API 与操作顺序留在宿主的业务脚本里。
新脚本放在宿主项目的 Assets/Editor/AutorunScripts/，由 Unity 编译后注册。对我来说，脚本至少要回答四个问题：
| 内容 | 要说明什么 |
|---|---|
| 起点 | 需要什么场景、界面和业务状态，动作前如何检查 |
| 动作 | 调用什么已核实的宿主 API，等待什么状态 |
| 依赖 | 复用了哪些脚本，各自需要什么参数 |
| 断言 | 最终观察到什么，才能说明这次目标完成 |
每个业务脚本声明 Preconditions，并实现 CheckPreconditions。起点不符就直接失败，不在执行时另猜一条路线。调用依赖也必须提前声明；缺失依赖、重复 ID、循环和未声明调用都会被检查。
复用的单位是起点、动作和结果都一致的完整业务片段。同样是打开背包，从登录页开始和从主界面开始就是两条不同流程，应使用独立 ID 和文件；不能为了复用，临时修改原脚本或降低起点要求。
冷启动先准备 Play Mode
需要从未运行状态开始的根脚本声明 PreparePlayMode=true。运行器先准备 Play Mode，再检查实际场景和 UI 起点；脚本同时声明并调用 start-play-mode 基础脚本，复用准备结果的校验。停止状态下，面板会直接显示 Start Game & Run。
子脚本有这个声明，不会隐式把整个父流程变成冷启动流程。已经开始执行的 C# 迭代器也不能跨 Domain Reload 恢复；运行中意外重编译或切换 Play Mode，会留下失败结果，不自动重放前面已经完成的操作。
接入与运行
工具需要 Unity 2021.3 或更新版本、Git 和 .NET 8 SDK。在 Package Manager 中选择 Add package from git URL...，输入：
1 | https://github.com/SHW2002/Unity-Autorun-MCP.git |
导入并编译完成后，打开 Window > Auto Run Window：
- 展开
Connection > MCP Settings & Diagnostics，点击Publish MCP。 - 在
Install中选择项目的.codex或 Claude Code 的.claude目录，分别安装Install MCP和Install Skills。 - 重新连接 AI 客户端，核对 Bridge 的
Running状态和对应 MCP 进程，再检查Versions中各组件的状态。
隔离演示工程中的安装界面。客户端 MCP、三个 Skill 和宿主 Agent Rules 分别展示状态，版本号不要求完全一致。
三个 Skill 分工如下：
| Skill | 用途 |
|---|---|
gen-script |
创建新业务流程，编译、自测，并修正本次生成的代码 |
edit-script |
维护用户指定的已有业务脚本，保持原有起点、流程与目标契约 |
run-script |
查找并运行已有脚本，等待终态并核对断言，不生成或修改代码 |
例如，要明确授权新增一个流程，可以这样描述需求：
1 | $gen-script 从启动游戏后的主界面打开背包，验证金币文本非空，并保存截图 |
这是需求示例，不代表本文已经验证了某个宿主的背包流程。生成过程会根据实际项目落实起点和断言，失败时默认最多修正三轮，修改范围仅限本次生成代码。
已有脚本需要修复时，edit-script 先读取指定脚本、依赖和反向调用者，确认没有运行中的任务、Unity 也未在编译，才开始修改。修改后重新编译，使用新的 runId 自测，并从各自起点回归受影响的调用者。若需求改变了起点、流程或目标，应交给 gen-script 新建独立脚本，而不是把旧脚本改成另一条流程。
平时我在 Autorun Scripts 中搜索并选择脚本，点击 Run Script 或 Start Game & Run。默认界面保留运行入口和简短结果，需要时再展开 Script Details、Run Options、Result Details 与 Recent Runs 查看起点、依赖、参数、日志和产物。外部调用则通过 start_script 启动，再用 get_script_status 等待终态；同一次请求的传输重试沿用 runId，新的自测另用新 ID。
Install Skills 会把三个自包含安装包作为整批处理：先验证与暂存，再备份和替换，失败时回滚；已安装版本更高就拒绝覆盖。Codex 的目标是所选 .codex 同级的 .agents/skills/，Claude Code 使用 .claude/skills/。旧 unity-autorun Skill 会保留，检查过用户定制后再手动卸载。Claude Desktop 在这里仅支持安装 MCP，不通过其配置目录加载这三个文件系统 Skill。
自测之前，先找已有脚本
我不希望 Agent 每次需要操作游戏时，都重新生成一份相近的代码。因此，Agent Rules 是独立于 MCP 和 Skill 安装的入口：明确点击 Install Agent Rules 或 Update Agent Rules 后，才会把规则写进当前宿主 Unity 项目根目录的 AGENTS.md，不跟随客户端目录变化。
规则要求 Agent 在游戏或 UI 操作自测前，先用 list_scripts 和 get_script(includeSource=true) 核对已有脚本的起点、完整流程、断言、参数与依赖。找到匹配且有效的脚本，就交给 run-script 直接执行；没找到时，说明缺少什么覆盖，再询问是否需要创建自测脚本，不能静默新建。用户已经明确授权创建时，不重复确认。
MCP、Unity 或 Bridge 不可用属于检查阻塞，不能据此声称“没有脚本”；起点不匹配也不能随手拼一条替代流程。
写入内容由 unity-autorun:agent-instructions:begin / end HTML 注释标记识别，并记录区块版本。更新只替换管理区块，保留其他用户规则；内容一致时无需重写。标记重复、单侧缺失、顺序错误或已安装版本更高时会报告问题，避免覆盖用户文件。
从脚本直接打开宿主配置
有些流程运行前要先核对项目配置。我给脚本面板加了“打开配置界面”入口，沿用宿主已有的编辑器菜单，不在工具里再做一份业务配置 UI。
业务脚本可以提供带公开 getter 的 public static string ConfigurationMenuPath 属性，值填写宿主实际存在的 [MenuItem] 路径。编译并刷新后，选中这个脚本即可打开对应菜单；未声明或返回空值时不显示入口。属性不合规或菜单无法执行时会显示错误。Run Options 仍用于本次运行的参数和超时，两者用途不同。
这里打开的是隔离演示工程提供的配置窗口。具体配置内容与保存方式由宿主实现，不是工具内置的业务界面。
留下结果，也留下现场
发送过点击不代表界面已经打开，脚本正常结束也不代表业务目标通过。get_ui_state 和 wait_for_ui_state 能读取、等待支持范围内的结构化 UI 值；它们不能替代宿主业务断言，也不能证明动效和不同设备的视觉表现。需要视觉证据时，仍然要检查实际截图。
默认运行截图放在宿主的 Temp/UnityAutorunTool/Screenshots/。清理发生在下一次默认截图之前：尽力删除超过 24 小时的文件，并为新截图腾出位置，使总量维持在最多 20 份；文件被占用等情况可能使清理不完整，它也不是后台定时任务。显式指定 path 不触发这项自动清理；需要长期留存的证据，应指定宿主项目内、临时目录之外的 .png 路径。
正常完成、异常、超时和取消都会保留当时的游戏现场与 Play Mode。停止游戏必须是明确动作，不在失败后自动重置或回退。脚本自己的事件订阅、临时对象等资源由自己的退出路径清理。
对一次自测，我需要看到实际编译结果、运行终态和目标断言。编译通过不能替代自测通过；缺少正确起点、依赖或调用者回归条件时，就保留证据，写清楚哪些部分没有验证。
这个工具仍然服务于最初的需求：少重复几次固定操作，把时间留给正在检查的问题。现在我更看重的是，把这次操作的前提和结果一起留下，让下一次能可靠地复用。
项目地址：Unity-Autorun-MCP。后续安装方式和接口以对应版本的 README 为准。