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-mcp

batch_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中每个条目都是一条独立的命令规格（tool+params），服务端会校验这些条目后整体转发给 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 实现）：

参数	类型	必填	说明
`commands`	`list[dict[str, Any]]`	是	命令列表，每个条目包含`tool`与`params`两个键
`parallel`	`bool \\| None`	否	尝试并发执行只读命令（读操作并行，写操作仍串行以保证安全）
`fail_fast`	`bool \\| None`	否	在首个失败后立即停止处理后续命令
`max_parallelism`	`int \\| 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.Value<bool?>("failFast") ?? false;

即未显式传入时默认为false（继续执行全部命令并收集逐条结果），显式传入true才会在第一个失败步骤处中断。这与“尽力而为清理（best-effort cleanup）”模式相对应。建议以源码行为为准：需要“整体要么全成要么快速失败”的强事务语义时显式传fail_fast: true；需要“每步都尝试并汇总结果”时传false或省略。

返回值结构

batch_execute返回一个包含 Unity 响应的dict，具体形状取决于所执行的动作。以 Unity 侧聚合结构（BatchExecute.cs）为准，成功/失败响应的data部分统一包含：

字段	类型	说明
`results`	`list`	每条命令的执行结果数组，含`tool`、`callSucceeded`（bool）、`result`或`error`（命令条目非法时为错误信息）
`callSuccessCount`	`int`	成功条数
`callFailureCount`	`int`	失败条数
`parallelRequested`	`bool`	是否请求了并行
`parallelApplied`	`bool`	实际是否并行（当前恒为`false`，见下文原理）
`maxParallelism`	`int \\| 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_type），Unity 侧会将其统一转换为 camelCase（见下文原理）。

自由混用工具：何时拆分为多个批次

一个 batch 可以自由混用任何工具，唯一约束是批内顺序不能依赖上一条调用的返回值。官方文档给出的判断规则：

如果步骤 N 的响应需要喂给步骤 N+1 作为输入 →拆成两个 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 = 25；invalidate_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_instance+async_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 = 100；GetMaxCommandsPerBatch()从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.cs）；DetermineCallSucceeded依据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.cs：

MCPForUnity.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 run`

unity-mcp batch run commands.json unity-mcp batch run setup.json --parallel unity-mcp batch run critical.json --fail-fast

JSON 文件应为一个命令对象数组，格式如下：

[ {"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 inline`

unity-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 template`

unity-mcp batch template > commands.json unity-mcp batch template -o my_batch.json

template会输出一个包含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 / 硬上限 100（MCP Tools 窗口可调），CLI 端固定 40，服务端会按各自上限预检并报错。
失败语义：不传fail_fast时实际行为为继续执行并聚合逐条结果（以 BatchExecute.cs 源码为准）。

企业官网建设流程全解析