/batch

name: unity-batch
description: Unified batch and async-job orchestration

> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Operating on many objects at once
• Running or polling long async jobs
• Preview-then-commit bulk edits
• 一次性操作大量对象、运行或轮询长时异步任务、先预览后提交的批量编辑

Unity Batch Skills

Batch workflow orchestration for query, preview, execution, reports, and async jobs.

POST /skills/batch — several skills, one HTTP call

This is an **HTTP endpoint, not a skill**: do not send `skills_batch` to `POST /skill/<name>`. It runs a sequence of ordinary skills inside one main-thread job, which removes one round-trip *and* one main-thread wakeup per step — the single largest efficiency lever in this protocol when you have more than two writes to make.

POST /skills/batch
{
  "steps": [
    {"skill": "gameobject_create", "args": {"name": "Cube", "primitiveType": "Cube"}},
    {"skill": "component_add", "args": {"instanceId": {"$ref": "$0.instanceId"}, "componentType": "Rigidbody"}}
  ],
  "continueOnError": false
}

| Body field | Type | Default | Meaning | |---|---|---|---| | `steps` | array | required | `{skill, args}` objects, executed in order. **Max 50** — more returns `400` + `SEMANTIC_INVALID`; split into several calls. | | `continueOnError` | bool | `false` | `false` = fail-fast; `true` = record the failure and keep going. | | `params` | object | none | Fills `{"$param":"name"}` placeholder nodes in step args (static substitution, resolved before `$ref`). |

Query: `?mode=dryRun` validates every step without executing anything and never interrupts (the batch counterpart of the dryRun gate); `?mode=transactional` is all-or-nothing with Undo rollback; `?diff=1` adds a net `sceneDiff`. `?mode=plan` is **not** supported. Inter-step `$ref` (`{"$ref":"$0.instanceId"}`) and transactional details → [SKILL_FULL.md](../../references/SKILL_FULL.md).

`mode`/`dryRun` may equally be set in the body (`"mode":"dryRun"|"transactional"`, `"dryRun":true`) — each of the two keys is resolved independently, query-first per key, so a query `?mode=` and a body `"dryRun"` never fight over the same slot. The response always echoes what actually ran: top-level `mode` (`"dryRun"`|`"transactional"`|`"execute"`) and `dryRun` (bool). An unrecognized query key or body top-level key (anything outside `mode`/`dryRun`/`diff`/`steps`/`params`/`continueOnError`) is rejected with `400 UNKNOWN_PARAM`; a **blank** value on a recognized key (`?mode=`, `?dryRun=`, `?diff=`) is treated as if that key were simply omitted — it falls through to the other location or the default, it is not itself a rejection.

**Reading the response.** Whenever the batch ran at all the status is HTTP `200` and the verdict is in the body — only a rejected *request* (malformed body, >50 steps, unknown `?mode=`) is a `4xx`.

{"status":"partial","dryRun":false,"executed":2,"failed":1,
 "results":[{"index":0,"skill":"...","status":"success","result":{...}},
            {"index":1,"skill":"...","status":"error","error":{"errorCode":"...","error":"..."}},
            {"index":2,"skill":"...","status":"skipped"}]}

• Top-level `status`: `completed` (nothing failed), `partial` (some step failed), or `rolled_back` (transactional mode reverted everything).
• Every step carries its `index` and `skill`, so a failure is locatable without diffing your input array. `status:"skipped"` means the batch had already halted before that step ran — it was never attempted, not "ran and did nothing".
• Fail-fast (`continueOnError:false`) stops at the first error and reports the rest as `skipped`. With `continueOnError:true` failures are recorded and later steps still run.
• **Authorization always interrupts**, `continueOnError` notwithstanding: a step answering `MODE_RESTRICTED` / `CONFIRMATION_REQUIRED` halts the batch and returns that step's full payload (grant token included) so you can complete the grant flow and resubmit the remaining steps.

> **Not the same thing as `batch_execute`.** `batch_execute(confirmToken)` commits *one* previewed bulk operation produced by a `batch_preview_*` skill (one verb over N objects, via a confirm token). `POST /skills/batch` composes *N different skills* over whatever targets you name, and takes no token. They do not substitute for each other, and `POST /skills/batch` is not a way to skip the preview/confirm gate — a `batch_execute` step inside a batch still needs its own `confirmToken`.

When a step returns a `jobId` (async batch execution, tests, compiles), poll it with **`GET /jobs/{id}`** rather than the `job_status` skill: it runs in the light lane instead of the main-thread skill queue, and its payload is far smaller than a skill response — an order of magnitude cheaper per poll on a long job.

Operating Mode

本模块共 22 个 skill，按 Operation 区分为两类：

• **18 个 SemiAuto**（query / preview / report / job 查询类）：`batch_query_gameobjects` / `batch_query_components` / `batch_query_assets` / `batch_preview_rename` / `batch_preview_set_property` / `batch_preview_replace_material` / `batch_report_get` / `batch_report_list` / `job_status` / `job_progress` / `job_logs` / `job_list` / `batch_fix_missing_scripts` / `batch_standardize_naming` / `batch_set_render_layer` / `batch_replace_material` / `batch_validate_scene_objects` / `batch_cleanup_temp_objects`。Approval 模式下可直接执行。
• **4 个 FullAuto**（Execute 类，C# 未标 `Mode` 走默认 `SkillMode.FullAuto`）：`batch_execute` / `job_wait` / `job_cancel` / `batch_retry_failed`。Approval 模式下首次调用返 `MODE_RESTRICTED`，走 grant 协议。
• Auto / Bypass：两类都直接执行。**不含 NeverInSemi 高危 skill**（无 Delete/MayEnterPlayMode/MayTriggerReload 标记）。

> 注意：`batch_execute(confirmToken)` 本身放行，但它执行的 preview 内容可能包括对场景对象的