1. 项目背景我为什么要把 AI Agent 接进 Unity 工具链先交代一下这个项目的来路。我手上有好几个长期维护的 Unity 项目其中有面向 iOS/Android 的移动端应用也有跑在 Windows 上的交互展厅项目。这类项目的痛点很一致构建、冒烟测试、日志排查这条链路又长又绕尤其是项目迭代到中期以后每次改完 C# 脚本都要走一遍“开编辑器、等编译、进 Play 模式、点几个界面、看 Console、关掉”的循环一天下来体力全耗在重复操作上了。一开始我试过用 Jenkins 做定时构建也试过写 Shell 脚本调 Unity 命令行接口也就是-batchmode -executeMethod那套。但它们本质上是“死”的脚本只能按预设流程走一旦中间冒出异常——比如编译报错、测试用例挂了、资源导入失败——整个流水线就停在那等人工介入。我要的不只是自动化而是能根据实际输出动态判断下一步做什么的智能体。所以这个项目的核心目标很直接让 AI Agent 具备“看懂 Unity 编译日志 → 定位问题 → 触发重新编译 → 跑测试 → 汇总结果”的全链路能力并且整个过程不需要人坐在编辑器前面。说白了就是把 AI Agent 从“聊天机器人”变成“能干活的项目成员”。如果你也在折腾 AI Agent 编程或者被 Unity 的批处理模式坑过这篇文章应该能帮你少踩不少坑。2. 整体方案设计先拆需求再选工具链2.1 核心需求拆解在动手之前我先把需求拆成了几个模块每个模块对应一条独立的能力链路模块要解决的核心问题输出物命令行编译让 Agent 能触发 Unity 编译编译日志、Build 产物自动化测试让 Agent 能跑 EditMode/PlayMode 测试XML 测试报告日志解析让 Agent 能“看懂”编译和测试结果可读的结构化结论决策执行让 Agent 能根据结果决定重试还是上报下一步动作一开始我做了一个很蠢的设计把编译、测试、日志解析全塞进一个巨大的 Python 脚本里然后让 Agent 只负责调用这个脚本。后来发现这根本行不通因为 Unity 的批处理模式有很多“隐藏规则”——比如同一个项目同时只能有一个 Unity 进程操作、Library 目录会被锁、编译失败时返回值并不一定是非零……这些细节如果不处理好脚本跑十次能挂八次。2.2 方案选型为什么是“命令行 编辑器扩展 Agent”三层架构我最终的方案分了三层第一层是 Unity 命令行接口负责最底层的编译和测试触发。这一层的核心优势是稳定-batchmode模式下的行为是官方保证的适合做无头化的 CI/CD 接入。第二层是编辑器扩展负责把 Unity 内部的状态暴露出来。很多信息在纯命令行模式下拿不到比如 AssetDatabase 的导入状态、编译错误的具体脚本行号这时候需要写自定义的MenuItem或者EditorWindow来辅助输出。第三层是 AI Agent负责决策和流程编排。Agent 不直接操作 Unity 进程而是通过“读日志 → 决策 → 调命令”的循环来驱动整个流程。这样可以保证 Agent 的输出是可控的即使它“想歪了”最坏的结果也就是多跑一次编译不会把项目文件搞坏。这个分层思路如果你用过 ROS机器人操作系统应该很熟悉——底层负责执行上层负责决策中间通过消息通信。Unity 的日志文件就是我们的“消息总线”。3. 环境准备与工具选型这部分最容易翻车3.1 Unity 命令行编译的“隐形规则”在配置环境之前我建议你先在本地手动跑一遍 Unity 命令行编译确认基本链路是通的。命令大概长这样/Applications/Unity/Hub/Editor/2022.3.20f1/Unity.app/Contents/MacOS/Unity \ -batchmode \ -nographics \ -projectPath /path/to/your/project \ -executeMethod BuildScript.PerformBuild \ -logFile - \ -quitWindows 上对应的是C:\Program Files\Unity\Hub\Editor\2022.3.20f1\Editor\Unity.exe \ -batchmode \ -nographics \ -projectPath D:\YourProject \ -executeMethod BuildScript.PerformBuild \ -logFile - \ -quit这里有几个非常容易被坑的点第一-quit参数的位置。很多人会把-quit放在-executeMethod前面结果方法还没执行完 Unity 就退出了。正确顺序是-executeMethod在前-quit在后。第二-logFile -的意思是输出到标准输出用减号代替文件路径。这个参数在调试时非常好用可以直接把日志管道给 Python 脚本解析。但要注意如果你在 Windows 的 PowerShell 里跑编码可能不是 UTF-8后面解析中文字符串时会乱码。第三-batchmode模式下 Unity 不会加载任何用户自定义的布局和偏好设置所以如果你的构建脚本依赖某些 EditorPrefs 存储的配置在这里是读不到的。解决方式是把所有必要配置都写成参数传进来比如// BuildScript.cs public static void PerformBuild() { var outputPath Environment.GetCommandLineArgs() .FirstOrDefault(arg arg.StartsWith(-outputPath)) ?.Replace(-outputPath, ); // 构建逻辑... }3.2 给 AI Agent 准备的“可读环境”命令行编译跑通之后下一步就是让 AI Agent 在这套环境里“生存”。Agent 需要三种能力执行命令、读文件、判断结果。我用的框架是自建的 Python 调度器配合 Anthropic 的 Claude API但整体思路不绑定具体厂商。在给 Agent 准备环境时有几件事特别重要第一把 Unity 的可执行文件路径做成环境变量。不要写死在 Python 脚本里因为 Unity Hub 升级后路径会变。我在.env文件里放了一个UNITY_EXE变量脚本启动时读取。第二给 Agent 提供“命令白名单”。AI Agent 最大的风险是它可能执行任意命令如果我让它直接用subprocess.run()跑 shell它可能把项目目录删了。所以我的实现里加了一个命令过滤层只允许 Agent 调用预设的几类操作ALLOWED_PREFIXES [ dotnet, python, git, Unity, ] def run_command(command_str: str, timeout: int 300): # 白名单校验 parts command_str.split() if not parts or parts[0] not in ALLOWED_PREFIXES: raise SecurityError(fCommand {parts[0]} not allowed) # 执行并捕获输出 proc subprocess.Popen( command_str, shellTrue, stdoutsubprocess.PIPE, stderrsubprocess.STDOUT, textTrue, encodingutf-8, errorsreplace, ) output, _ proc.communicate(timeouttimeout) return proc.returncode, output第三给 Agent 提供项目结构和关键文件的地图。Agent 是“瞎”的它不知道你的 Unity 项目里有哪些脚本、哪些测试。我写了一个scan_project.py每次 Agent 启动时自动扫描Assets/Scripts下的所有.cs文件整理成清单喂给 Agent。这样 Agent 在定位编译错误时至少知道去哪里找文件。3.3 编辑器扩展我没法绕过的“中间层”前面说过有些信息在纯命令行模式下拿不到。这里举一个具体例子Unity 在批处理模式下编译失败时并不会输出一个结构化的错误列表而是把错误信息混在日志流里。日志里既有普通日志又有警告还有报错格式还不统一。为了给 Agent 提供干净的“可读信息”我写了一个编辑器扩展用统一的格式输出编译结果// Editor/CompilationReporter.cs using System; using System.Linq; using UnityEditor; using UnityEditor.Compilation; using UnityEngine; public static class CompilationReporter { [MenuItem(Tools/Report Compilation Issues)] public static void ReportCompilationIssues() { var assembly EditorApplication.isCompiling ? Still compiling... : Compilation finished; var scripts AssetDatabase.FindAssets(t:MonoScript) .Select(AssetDatabase.GUIDToAssetPath) .Where(path path.StartsWith(Assets/)); foreach (var script in scripts) { var importer AssetImporter.GetAtPath(script) as MonoImporter; if (importer null) continue; // 这里可以检查脚本的编译错误 } // 通过日志输出 Debug.Log($[CompilationReporter] {assembly}); } }这个扩展在编辑器里跑一次就能把当前所有脚本的引用状态、编译状态汇总成一条日志Agent 只需要抓取[CompilationReporter]前缀的行就能拿到结论。4. AI Agent 驱动的核心实现从“读日志”到“做决策”4.1 UniRun.CoreAgent 的“大脑”调度逻辑我把 Agent 的核心逻辑封装成了一个名为UniRun.Core的 Python 模块它由四个关键组件构成任务解析器、命令执行器、日志分析器、决策引擎。任务解析器负责把用户的自然语言输入翻译成结构化任务。比如用户说“帮我编译测试版”解析器会提取出目标平台Android、构建类型Development、是否需要跑测试是。这一步我用的是 Claude 的函数调用能力function calling让模型直接输出 JSONtools [ { type: function, function: { name: compile_project, description: Compile Unity project for a given platform, parameters: { type: object, properties: { platform: {type: string, enum: [android, ios, windows]}, build_type: {type: string, enum: [development, release]}, run_tests: {type: boolean}, }, required: [platform, build_type], }, }, } ]这一层的设计思路是让模型少做自由发挥多做结构化决策。因为自由文本生成在工程场景下不够可靠但结构化的函数调用参数模型通常能填得比较准。4.2 日志分析器裁剪日志避免 Agent 上下文被刷爆做过 AI Agent 的朋友应该有经验把一堆原始日志直接丢给大模型效果通常很差。原因有两个一是日志太长了超出上下文窗口二是日志里大量冗余信息会稀释模型对关键错误的关注度。所以我的日志分析器做了一层“压缩提炼”def extract_critical_lines(log_text: str) - list[str]: lines log_text.splitlines() critical [] for line in lines: lower line.lower() if error in lower or exception in lower or failed in lower: critical.append(line.strip()) elif warning in lower and cs in lower: # 编译警告只保留前 20 条避免刷屏 if len([l for l in critical if warning in l]) 20: critical.append(line.strip()) return critical这个函数做的事很简单只保留包含error、exception、failed的日志行警告行则限制数量防止刷屏。Agent 拿到的不是 10 万行原始日志而是 50 行“高浓度问题摘要”决策准确率会高很多。还有一个细节处理 Unity 的“Warning as Error”。很多项目会把警告当错误处理导致编译失败。因此我把LogType.Error和LogType.Warning分成两个 bucket让 Agent 能根据上下文判断哪些警告是可以忽略的。4.3 决策循环Agent 怎么决定“重试”还是“放弃”这里是我整个项目中最重要的设计Agent 的决策循环。一个完整的决策循环大概是这样的Agent 收到任务 → 解析为结构化指令调用编译命令 → 拿到编译日志日志分析器提炼问题 → 返回给 AgentAgent 判断问题类型如果是“临时性错误”比如 Library 锁、网络超时→ 重试一次如果是“代码错误”比如 C# 语法错误、命名空间缺失→ 尝试自动修复如果是“无法处理的问题”比如插件授权失败→ 停止给人发报告如果 Agent 决定自动修复它调用git apply或者直接改.cs文件重新编译验证修复是否生效循环直到成功或达到最大重试次数实现代码如下def agent_loop(task: dict, max_retries: int 3): retries 0 while retries max_retries: result execute_task(task) if result[status] success: return {status: success, report: result[report]} issues analyze_log(result[log]) decision ask_agent( issuesissues, current_attemptretries 1, max_retriesmax_retries, ) if decision[action] give_up: return {status: failed, reason: decision[reason]} if decision[action] retry: retries 1 continue if decision[action] fix: apply_fix(decision[patch]) retries 1 continue return {status: failed, reason: max retries exceeded}这个循环有个好处它把“智能”限制在决策层而不是执行层。Agent 不会自己去重新设计构建流程它只负责在有限的动作空间里做选择。这大大降低了风险。5. 自动化测试接入让 Agent 不只是“编译工”5.1 Unity Test Framework 批处理模式接入编译跑通了下一步就是测试。Unity 自带的 Test Framework 支持命令行跑测试命令如下/Applications/Unity/Hub/Editor/2022.3.20f1/Unity.app/Contents/MacOS/Unity \ -batchmode \ -projectPath /path/to/project \ -runTests \ -testPlatform EditMode \ -testResults /path/to/results.xml \ -logFile - \ -quit-testPlatform参数指定测试平台常用值有两个参数值含义适用场景EditMode编辑器模式测试不进入 Play Mode纯逻辑测试、Editor 脚本测试PlayMode播放模式测试会加载场景并运行游戏逻辑集成测试、UI 测试、流程测试跑测试时有两个我踩过的坑这里重点说第一个坑测试结果文件的路径。如果-testResults指定的目录不存在Unity 不会自动创建测试会直接失败。所以脚本里要先确保目录存在import os results_dir /path/to/test_results os.makedirs(results_dir, exist_okTrue)第二个坑批处理模式下有些测试会假失败。具体来说是涉及AssetDatabase异步导入的测试因为批处理模式下资源导入是同步的时序和编辑器里不一样。如果你遇到“测试在编辑器里能过命令行跑就挂”优先检查测试里有没有依赖异步操作的代码。5.2 测试报告的解析与 Agent 可读化-testResults生成的 XML 文件是标准的 NUnit 格式结构大致如下test-run id2 testcasecount123 resultFailed total123 passed110 failed13 test-suite typeTestSuite nameUnity resultFailed test-case nameTests.PlayerTests.TestJump resultFailed failure messageExpected true but was false/message /failure /test-case /test-suite /test-run我写了一个parse_test_results.py把它解析成 Agent 更容易理解的摘要import xml.etree.ElementTree as ET def parse_test_results(xml_path: str) - dict: tree ET.parse(xml_path) root tree.getroot() failed_cases [] for test_case in root.iter(test-case): if test_case.get(result) Failed: failed_cases.append({ name: test_case.get(name, ), message: test_case.findtext(.//message, ).strip(), }) return { total: root.get(total), passed: root.get(passed), failed: root.get(failed), failed_cases: failed_cases[:20], # 只取前20条失败用例 }Agent 拿到这份摘要后可以根据失败用例的名字去定位对应的测试脚本再进一步分析失败原因。比如某个 UI 测试失败了Agent 会检查测试引用的 UI 元素是否存在、场景是否加载正确等。5.3 循环测试让 Agent 在“编译-测试-修复”之间闭环现在把编译和测试串起来就是一个完整的 Agent 驱动闭环compile_project()编译项目如果编译失败 → Agent 分析错误 → 修复 → 重新编译编译成功后 →run_tests(platformEditMode)跑测试如果测试失败 → Agent 分析失败用例 → 修复代码 → 回到第 1 步全部通过 → Agent 输出最终报告为了让 Agent 不会无限循环下去我设置了两个终止条件最大重试次数默认 3 次和最大修复文件数默认 5 个文件。一旦超过这些限制Agent 会停止操作并生成一份“半成品报告”由人工介入。这个设计的背后逻辑是AI Agent 的价值不是取代人类而是把人类的注意力从“盯过程”转移到“看结果”。Agent 自己处理那些“看一眼就知道怎么改”的小问题把真正疑难杂症留给人来处理。6. 实操过程实录从一个编译错误到全链路打通6.1 第一次运行被 Unity 的“进程中锁”教做人我来说一段真实的排查经历。当时我信心满满地把 Agent 接好跑第一个任务——“编译 Android 开发版”结果 Agent 二话不说就报错了。日志片段如下[UniRun.Core] Executing: Unity.exe -batchmode -projectPath ... -executeMethod BuildScript.PerformBuild -quit [UniRun.Core] Return code: 1 [UniRun.Core] stdout (last 30 lines): ERROR: It is not possible to have two Unity instances running with the same project.这个问题其实很经典我本地编辑器还开着同一个项目命令行试图开第二个 Unity 进程被锁了。解决方案有两个。第一在跑命令行编译前确保关闭编辑器。第二更友好一点用 Unity 的-quit参数配合-batchmode之前检查进程def is_unity_running(project_path: str) - bool: # 检查 Unity 进程是否占用项目 output subprocess.run( [powershell, -Command, Get-Process Unity | Select-Object Id], capture_outputTrue, textTrue, ).stdout return Unity in output我的最终方案是在调度器里加了一步“预检”如果检测到项目被占用就提示 Agent 等几秒后再试而不是直接报错。6.2 “路径里不能有中文”和“Library 损坏”的连环坑预检通过之后又遇到了第二个问题我的项目路径在D:\UnityProjects\游戏A包含中文字符结果 Unity 命令行模式直接罢工。日志里没有任何明确报错只是-quit静默退出。排查了半天最后发现是路径中的中文字符导致 Unity 的日志编码解析异常。解决方法很简单把项目目录改成纯英文路径。D:\UnityProjects\GameA就好。如果你的项目已经在中文路径下可以做一个符号链接junction指向英文路径。之后又遇到一次Library目录损坏的问题。起因是上一次构建时电脑断电Library/ShaderCache里的缓存文件损坏导致后续编译每次都卡在导入阶段。解决方法是删除Library目录重新导入但这个操作代价很大——一个中大型项目的Library目录重建可能需要 10~20 分钟。后来我让脚本在编译前执行一次“快速自检”检查几个关键目录是否存在required_dirs [ Assets, Packages, ProjectSettings, Library, ] missing [d for d in required_dirs if not os.path.isdir(os.path.join(project_path, d))] if missing: raise BuildError(fMissing required directories: {missing})6.3 日志解析从“大海捞针”到“定向提取”在 Agent 接手的早期最影响体验的是日志解析速度。Unity 的完整构建日志动辄 5~10 万行如果每次都将这 10 万行喂给模型响应时间会很长而且费用不低。我的优化思路是“三段式提炼”第一段粗过滤。用正则表达式把包含error、exception、assert的行提取出来。这一步可以过滤掉约 90% 的无用日志。第二段聚类。把错误信息按文件名和行号分组。比如用户代码里出现了 5 个语法错误它们都指向同一个.cs文件那么 Agent 只需要处理一个“根因”即可。第三段上下文补全。AI 模型处理“孤立错误行”时经常瞎猜因为它不知道上下文。所以我会为每个错误行额外补上它的前 3 行和后 1 行日志让模型有更多线索def extract_with_context(log_lines: list[str], error_indices: list[int], context: int 3): result [] for idx in error_indices: start max(0, idx - context) end min(len(log_lines), idx context 1) snippet log_lines[start:end] result.append(\n.join(snippet)) return \n----\n.join(result)这个细节听起来简单但对 Agent 的判断准确率提升非常明显。比如错误行只有一句NullReferenceException: Object reference not set to an instance of an object模型根本不知道是哪个对象为空但如果补全了前后几行就能看到是哪个脚本、哪个方法里出的异常。6.4 AI Agent 自动修代码的一次实战记录这里分享一个让人惊喜的时刻。有一次run_tests返回了一个测试失败失败用例名称是Tests.InventoryTests.TestAddItem_WhenFull_ShouldReturnFalse。Agent 分析日志后定位到Inventory.cs里的这段代码public bool AddItem(Item item) { if (_items.Count _capacity) { return true; // 这里应该是 false库存满了不应该再加 } _items.Add(item); return true; }Agent 给出的修复建议是public bool AddItem(Item item) { if (_items.Count _capacity) { return false; // 修复库存已满时返回 false } _items.Add(item); return true; }它修改了一行代码重新编译、跑测试全绿。这件事让我确信在“局部修改”这个级别AI Agent 的可靠性已经相当高了。当然也有 Agent 完全无能为力的场景。比如有一次测试失败是因为某个第三方插件在目标平台上不支持Agent 调研半天也没有结论最后判断为“无法处理”生成了一份带日志摘要的报告提交给我。这反而比它瞎改代码好得多。7. 常见问题与排查技巧实录7.1 问题速查表我把实践中遇到的高频问题整理成了速查表方便你照方抓药现象根因解决方案命令行编译静默退出无任何日志路径含中文或空格未转义项目目录改为纯英文参数加引号It is not possible to have two Unity instances编辑器已打开同一项目编译前检查并关闭现有 Unity 实例测试结果一直为空-testResults目录不存在脚本里用os.makedirs(exist_okTrue)PlayMode 测试在命令行下比编辑器里更慢无 GPU 渲染导致性能下降用-nographics 必要时加-force-glcore日志文件中文乱码PowerShell 默认编码问题让 Python 以utf-8读取或设置[Console]::OutputEncoding编译失败但命令返回码为 0-quit放在了-executeMethod前面调整参数顺序7.2 “Agent 不看警告”这个坑还有一个特别容易踩的坑——Agent 自动忽略了编译警告。因为在批量模式下编译警告数量太多我的粗过滤逻辑会丢弃大部分警告只保留前 20 条。但有些警告其实是“未来的错误”比如使用了过时的 API、引用了不存在的程序集等。如果 Agent 完全不看警告这些问题会在运行时才暴露更难排查。我的改进办法是“分级处理”如果编译结果是失败Agent 专注于错误如果编译结果是成功但存在某类特定警告Agent 会额外提取这些警告并评估是否值得修复。具体场景是当警告数量超过 100 条时Agent 只需要关注其中与CS0618API 过时和CS0649字段未赋值相关的警告因为这些往往意味着潜在的 bug。7.3 中断与恢复Agent 跑挂了怎么办最后说一下系统稳定性。AI Agent 驱动的自动化流程最大的风险不是“跑错”而是“卡死”。比如 Unity 进程崩溃了、Python 调度器异常退出了或者 Agent 调用 API 时超时了。为了应对这些情况我的方案是引入“状态文件”。每次任务开始前调度器会把任务状态写入一个 JSON 文件{ task_id: build-and-test-20250216, status: running, current_step: compiling, attempts: 1, project_path: D:/UnityProjects/GameA, logs: [] }Agent 重启后先读取状态文件判断上次任务进行到哪一步然后从断点继续。这个设计虽然简单但在实际使用中救了我不止一次——有一次电脑半夜自动更新重启了第二天早上我看状态文件发现 Agent 已经自动从“编译完成”阶段恢复继续跑测试了。8. 编辑器 UI 自动化绕过“不可命令行化”的最后一公里上面讲的主要是命令行模式下能做的自动化。但 Unity 编辑器里还有一类功能是命令行模式覆盖不到的——需要操作编辑器 UI 才能触发的东西比如打开某个窗口、点击某个按钮、检查 Inspector 上的某个值。这类操作在传统的 CI/CD 里几乎没法自动化但我发现配上 AI Agent 以后可以通过 UI 自动化框架来补齐。这里我用了pyautogui做鼠标键盘模拟配合 Unity 编辑器自身的EditorWindow布局信息来定位元素。大致思路是先让 Unity 编辑器进入-batchmode之外的正常模式带 UI用pyautogui定位并点击编辑器菜单栏的项通过读取编辑器日志来确认操作结果把结果反馈给 AgentAgent 决定下一步操作这个方法稳定性不算高因为编辑器 UI 的坐标在不同分辨率下会变我踩了不少坑比如# 一个不稳定的写法硬编码坐标 pyautogui.click(800, 450) # 一个稍微稳定点的写法先查找窗口位置再计算相对坐标 editor_window pyautogui.getWindowsWithTitle(GameA - Untitled)[0] x_center editor_window.left editor_window.width // 2 y_center editor_window.top editor_window.height // 2 pyautogui.click(x_center, y_center)这个方向的实用性目前还比较有限如果你只是做编译、跑测试完全可以不用 UI 自动化。但如果你希望 Agent 能帮忙调整编辑器设置、操作 Inspector、查看场景对象状态UI 自动化是绕不开的。后续我打算继续往这个方向优化尝试用 Unity 的EditorWindow反射 API 来直接调用内部操作少走鼠标模拟的路。9. 扩展方向与个人的一点体会项目到目前为止核心链路已经稳定运行了一段时间。最常用的场景是我每天回到工位前让 Agent 拉取最新代码、编译、跑一轮冒烟测试然后把测试结果写到项目的 README 里我到了公司直接看结论就行。省下的时间虽然不算多但心理负担的减少是明显的——以前每次提交代码后都担心“是不是又破坏了什么东西”现在这个担心交给了 Agent。后续我主要想扩展三个方向一是接入更丰富的测试场景比如把 PlayMode 测试在真机上跑起来二是支持多项目并行构建目前还是单项目串行三是在 Agent 的决策引擎中引入更多“项目特定知识”比如不同模块的历史出错规律这样它能更快定位到问题。如果你也想在团队里推动这件事我给一条建议先从“编译冒烟测试”这条最小闭环开始不要一上来就想让 Agent 做全自动修 bug。先把链路打通再逐步扩大它的自主权。这不仅是技术上的保险也是让你自己慢慢适应 AI Agent 工作方式的一个过程。回到最开始那个问题——“让 AI Agent 直接驱动 Unity 编辑器编译与测试”本质上不是把 Unity 的命令行参数抄一遍那么简单而是要让 Agent 具备理解工具输出、判断上下文、做出合理决策的能力。这段路走下来我觉得最有价值的不是那几百行 Python 代码而是那套“人 Agent 协作”的机制。工具本身一直在变但这个协作框架以后应该还能用在很多别的场景里。