Unity MCP 批量执行指南：用 batch_execute 把 10~100 次往返压缩成 1 次

Unity MCP 批量执行指南用 batch_execute 把 10~100 次往返压缩成 1 次【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcpbatch_execute是 Unity MCP 中位于core工具组服务端模块为services.tools.batch_execute的核心编排工具它允许在单次调用中批量执行多个 MCP 命令如manage_gameobject、manage_material、manage_components等。当 AI 助手需要创建/修改多个物体、为多个目标添加组件、或执行任何重复性操作时它是官方文档与源码中强烈推荐STRONGLY RECOMMENDED的首选方案——相比逐个串行调用可将延迟与 Token 成本降低 10~100 倍。阅读本文后你将掌握batch_execute的完整参数语义、请求/响应格式、源码级执行原理以及 CLI 批处理与 Unity 端配置方法能够直接写出高吞吐、可复制的批量操作。batch_execute 是什么一次往返的批量编排器batch_execute的核心设计目标只有一个减少 AI 助手与 Unity Editor 之间的往返次数round trip。它的 Python 侧注册描述Server/src/services/tools/batch_execute.py明确写道Executes multiple MCP commands in a single batch for dramatically better performance… Reduces latency and token costs by 10-100x compared to sequential tool calls.它并非一个新的业务工具而是一个元工具meta tool其参数commands中每个条目都是一条独立的命令规格toolparams服务端会校验这些条目后整体转发给 Unity Editor 侧的同名处理器MCPForUnity/Editor/Tools/BatchExecute.cs由 Unity 侧在主线程上顺序执行并聚合返回。为什么批量能带来 10~100 倍提升官方文档给出的量化对比非常直观10 次单独的manage_gameobject调用需要付出10 次到 Unity 的往返改用 1 次batch_execute只付出 1 次往返。对于多物体搭建场景批处理通常稳定快 10~100 倍。判断何时该用批处理的标准是只要下一步操作不需要依赖上一步的返回值就应尽量合并进同一个 batch。提示Unity 侧的工具描述文本Server/src/services/resources/gameobject.py在生成 AI 提示时同样会强调该建议——“⚡ Use batch_execute for multiple operations: Combine create/modify/component calls into one batch_execute call for 10-100x better performance”即创建 5 个立方体应使用 1 次包含 5 条manage_gameobject命令的 batch而非 5 次独立调用。参数说明batch_execute的完整签名来自官方工具注册表文档 website/docs/reference/tools/core/batch_execute.md 及 Python 实现参数类型必填说明commandslist[dict[str, Any]]是命令列表每个条目包含tool与params两个键parallelbool \| None否尝试并发执行只读命令读操作并行写操作仍串行以保证安全fail_fastbool \| None否在首个失败后立即停止处理后续命令max_parallelismint \| None否并行 worker 最大数量的提示值其中commands中每个条目的约束如下Python 侧逐一校验见 batch_execute.py必须是 JSON 对象dict且不能为空列表必须包含非空字符串类型的tool名称params必须是对象dict缺省时视为{}不允许在子命令内携带unity_instance字段——批内的单命令实例路由不受支持如需指定实例应在外层batch_execute调用上设置unity_instance以路由整个批次。关于 fail_fast 默认值的源码级说明官方文档示例块写作“Setfail_fast: true(default)”但从 Unity 侧实现看BatchExecute.cs实际解析逻辑为bool failFast params.Valuebool?(failFast) ?? false;即未显式传入时默认为false继续执行全部命令并收集逐条结果显式传入true才会在第一个失败步骤处中断。这与“尽力而为清理best-effort cleanup”模式相对应。建议以源码行为为准需要“整体要么全成要么快速失败”的强事务语义时显式传fail_fast: true需要“每步都尝试并汇总结果”时传false或省略。返回值结构batch_execute返回一个包含 Unity 响应的dict具体形状取决于所执行的动作。以 Unity 侧聚合结构BatchExecute.cs为准成功/失败响应的data部分统一包含字段类型说明resultslist每条命令的执行结果数组含tool、callSucceededbool、result或error命令条目非法时为错误信息callSuccessCountint成功条数callFailureCountint失败条数parallelRequestedbool是否请求了并行parallelAppliedbool实际是否并行当前恒为false见下文原理maxParallelismint \| null传入的并行度提示值整体判定只要存在任一失败命令batch_execute即返回ErrorResponse(One or more commands failed.)同时仍携带完整的data供上层逐条排查全部成功才返回SuccessResponse。实战示例一次往返创建三个彩色立方体官方文档给出的完整示例batch_execute.md是“创建红、蓝、黄三个立方体并赋予对应材质”整个过程合并为一次batch_execute调用Create a red, blue, and yellow cube at x -1, 0, 1.{ commands: [ { tool: manage_gameobject, params: { action: create, name: RedCube, primitive_type: Cube, position: [-1, 0, 0] }}, { tool: manage_gameobject, params: { action: create, name: BlueCube, primitive_type: Cube, position: [0, 0, 0] }}, { tool: manage_gameobject, params: { action: create, name: YellowCube, primitive_type: Cube, position: [1, 0, 0] }}, { tool: manage_material, params: { action: create, material_path: Materials/Red.mat, shader: Standard, properties: { _Color: [1, 0, 0, 1] } }}, { tool: manage_material, params: { action: create, material_path: Materials/Blue.mat, shader: Standard, properties: { _Color: [0, 0, 1, 1] } }}, { tool: manage_material, params: { action: create, material_path: Materials/Yellow.mat, shader: Standard, properties: { _Color: [1, 1, 0, 1] } }}, { tool: manage_material, params: { action: assign_material_to_renderer, target: RedCube, search_method: by_name, material_path: Materials/Red.mat }}, { tool: manage_material, params: { action: assign_material_to_renderer, target: BlueCube, search_method: by_name, material_path: Materials/Blue.mat }}, { tool: manage_material, params: { action: assign_material_to_renderer, target: YellowCube, search_method: by_name, material_path: Materials/Yellow.mat }} ] }这个例子同时示范了两类批内操作前 3 条是“创建物体”后 6 条是“创建材质并赋值”——它们之间没有返回值依赖赋值目标通过search_method: by_name按名称查找因此可以安全地放在同一个批次中。注意每条子命令的params采用下划线风格如primitive_typeUnity 侧会将其统一转换为 camelCase见下文原理。自由混用工具何时拆分为多个批次一个 batch 可以自由混用任何工具唯一约束是批内顺序不能依赖上一条调用的返回值。官方文档给出的判断规则如果步骤 N 的响应需要喂给步骤 N1 作为输入 →拆成两个 batch否则 → 放心合并哪怕混用manage_gameobject、manage_material、manage_components、manage_scene等不同工具。失败策略fail_fast vs 继续执行fail_fast: true首个失败步骤后中止剩余命令适合关键路径、避免在残缺状态下继续操作fail_fast: false尝试执行每一条命令并收集逐条结果适合“尽力而为的清理best-effort cleanup”类场景例如批量删除/还原多个对象希望尽量多地完成任务。Unity 侧还会把每条命令的成败计入callSuccessCount/callFailureCount并在整体响应中标记是否anyCommandFailed。并行只读传入parallel: true可让服务端尝试并发运行只读命令修改类mutating命令仍会串行执行以保证安全。可用max_parallelism调整并行 worker 数量的提示值。需要注意的是从当前 Unity 侧实现看并行请求会记录一条警告日志McpLog.Warn实际仍以主线程顺序执行为准见下文“顺序执行”因此请将parallel视为“性能提示”而非强约束。源码级原理从请求到逐条执行batch_execute的完整执行链路横跨 Python 服务端与 Unity 编辑器端理解两端的分工有助于排查问题。服务端Python校验、缓存限制、转发Server/src/services/tools/batch_execute.py 负责读取 Unity 配置的批次上限通过get_editor_state从编辑器状态中读取settings.batch_execute_max_commands对应 Unity 侧 EditorStateCache.cs 中暴露的BatchExecuteMaxCommands并做模块级缓存_cached_max_commands读取失败或值非法时回退到默认值DEFAULT_MAX_COMMANDS_PER_BATCH 25invalidate_cached_max_commands()用于重置缓存。超限校验len(commands) max_commands时抛出ValueError硬上限与 Unity 侧一致为ABSOLUTE_MAX_COMMANDS_PER_BATCH 100。逐条结构校验非 dict 条目、缺失/非字符串tool、params非 dict均抛出带索引的ValueError子命令内出现unity_instance直接拒绝对应集成测试 Server/tests/integration/test_inline_unity_instance.py 中的test_batch_execute_rejects_inner_unity_instance。转发构造{commands: [...], parallel: ..., failFast: ..., maxParallelism: ...}载荷通过send_with_unity_instanceasync_send_command_with_retry发送给指定的 Unity 实例。Unity 侧C#主线程顺序执行与安全保证MCPForUnity/Editor/Tools/BatchExecute.cs 是实际执行者要点如下顺序执行顺序确定性与 Unity API 安全类注释明确说明“Commands are executed sequentially on the main thread to preserve determinism and Unity API safety”。即使收到parallel: true也只会记录警告“commands will run sequentially on the main thread for safety”parallelApplied恒为false。数量限制DefaultMaxCommandsPerBatch 25、AbsoluteMaxCommandsPerBatch 100GetMaxCommandsPerBatch()从EditorPrefs.GetInt(EditorPrefKeys.BatchExecuteMaxCommands, 25)读取并Math.Clamp到[1, 100]。超过限制时返回明确错误信息提示可在 MCP Tools 窗口配置。禁用工具拦截每个命令执行前通过MCPServiceLocator.ToolDiscovery查询元数据并检查IsToolEnabled被禁用的工具在批内直接标记失败与TransportCommandDispatcher的检查逻辑保持一致。参数键归一化NormalizeParameterKeys会遍历子命令params的所有属性经StringCaseUtility.ToCamelCase统一转为 camelCase因此 JSON 中既可以写primitive_type也可以写primitiveType。分发与成败判定调用CommandRegistry.InvokeCommandAsync(toolName, commandParams)见 MCPForUnity/Editor/Tools/CommandRegistry.csDetermineCallSucceeded依据IMcpResponse.Success或响应对象中的布尔success字段判定单条成败并在failFast时中断剩余命令。聚合返回最终返回results、callSuccessCount、callFailureCount、parallelRequested、parallelApplied、maxParallelism六元组整体成功与否取决于是否存在任一失败。批次大小配置MCP Tools 窗口与 EditorPrefs批次上限可在Unity MCP Tools 窗口中配置默认 25硬上限 100。UI 侧实现在 MCPForUnity/Editor/Windows/Components/Tools/McpToolsSection.cs窗口中提供“Max commands per batch”整数字段tooltip 说明为1–100默认 25修改后即时写入EditorPrefs。对应的偏好键定义在 MCPForUnity/Editor/Constants/EditorPrefKeys.csMCPForUnity.BatchExecute.MaxCommands // EditorPrefKeys.BatchExecuteMaxCommands该值同时会通过编辑器状态EditorStateCache.cs 的BatchExecuteMaxCommands属性以batch_execute_max_commands字段暴露给服务端editor_state.py使 Python 侧可以在本地完成超限预检。超过上限时请拆分为多个批次——官方文档指出拆分后往返成本仍然被摊薄性能优势依旧成立。CLI 批处理命令把 batch_execute 带入终端除了 MCP 工具调用batch_execute还通过 CLI 提供了三个便捷子命令实现在 Server/src/cli/commands/batch.py同样支持--parallel并发执行只读命令与--fail-fast首个失败即停止两个选项。从 JSON 文件执行batch rununity-mcp batch run commands.json unity-mcp batch run setup.json --parallel unity-mcp batch run critical.json --fail-fastJSON 文件应为一个命令对象数组格式如下[ {tool: manage_gameobject, params: {action: create, name: Cube1}}, {tool: manage_gameobject, params: {action: create, name: Cube2}}, {tool: manage_components, params: {action: add, target: Cube1, componentType: Rigidbody}} ]执行结束后会打印成功/失败统计All N commands completed successfully或N succeeded, M failed。从内联 JSON 执行batch inlineunity-mcp batch inline [{tool: manage_scene, params: {action: get_active}}] unity-mcp batch inline [ {tool: manage_gameobject, params: {action: create, name: A, primitiveType: Cube}}, {tool: manage_gameobject, params: {action: create, name: B, primitiveType: Sphere}} ]生成模板batch templateunity-mcp batch template commands.json unity-mcp batch template -o my_batch.jsontemplate会输出一个包含manage_scene查询、manage_gameobject创建/修改、manage_components添加组件的 4 条命令示例文件。注意CLI 层面的单批上限为 40 条命令Maximum 40 commands per batch与 Unity 端默认 25、硬上限 100 的配置相互独立通过 CLI 批处理时应以 40 为限。相关 CLI 行为有测试覆盖见 Server/tests/test_cli.py 中的test_batch_inline、test_batch_run_file、test_batch_template等用例。限制与注意事项依赖限制批内命令之间不得存在返回值依赖需要串行取值的流程必须拆批。实例路由子命令内禁止出现unity_instance实例路由只能作用于整个批次在外层设置。并行是提示而非保证当前 Unity 侧实现将一切命令含只读统一在主线程顺序执行parallel: true仅记录警告写入类操作永远串行。数量上限Unity 端默认 25 / 硬上限 100MCP Tools 窗口可调CLI 端固定 40服务端会按各自上限预检并报错。失败语义不传fail_fast时实际行为为继续执行并聚合逐条结果以 BatchExecute.cs 源码为准。相关资源工具参考文档website/docs/reference/tools/core/batch_execute.md本文主体由tools/generate_docs_reference.py自动生成Unity 侧实现MCPForUnity/Editor/Tools/BatchExecute.cs服务端实现与校验Server/src/services/tools/batch_execute.pyCLI 批处理命令Server/src/cli/commands/batch.py上限配置 UIMCPForUnity/Editor/Windows/Components/Tools/McpToolsSection.cs相关测试Server/tests/integration/test_inline_unity_instance.py、Server/tests/test_cli.py【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考