Unity Batch

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.

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

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.

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.

jsonCopy code
{"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 内容可能包括对场景对象的删除/改属性等高影响动作 —— 请确保 batch_preview_* 返回的 sample/risk 字段已审阅。confirmToken 一次性消费、过期需重新 preview。

Surface profile (guide tier): batch_preview_* stays callable under every profile — a preview is read-only. When the operation a preview minted its confirmToken for lands in a category the active profile withdraws (GameObject / Component / Material under guide), the preview still succeeds and still returns its diff, but adds a surfaceExclusion object (manualDoc, hint, plus blockedSkill/blockedBy/surfaceProfile/category) warning that execute will be refused. At that point batch_execute / batch_retry_failed return SURFACE_EXCLUDED with surfaceProfile/category/operation/manualDoc/userControlled/hint at the top level of the response (not nested under details). The refusal does not consume the confirmToken — switch the profile back to full and the same token still executes, no new preview needed.

DO NOT (common hallucinations):

• Always call a batch_preview_* skill first — batch_execute requires a confirmToken from a preview, it cannot be called directly
• batch_run does not exist → use batch_execute(confirmToken)
• job_poll / job_result do not exist → job_status (or the cheaper GET /jobs/{id}) for state, then the skill named in its resultHint for the payload
• batch_delete / batch_move do not exist → use asset module for asset-level operations

Routing:

• For running several different skills in one call → POST /skills/batch (section above), not batch_execute
• For asset-level bulk operations (move, copy, delete) → asset module
• For workflow session/task undo tracking → workflow module
• For scene object validation → batch_validate_scene_objects (this module)
• For async job polling → job_status / job_wait (this module)

Skills

batch_query_gameobjects

Query GameObjects with unified batch filters. queryJson supports name/path/instanceId/tag/layer/active/componentType/sceneName/parentPath/prefabSource/includeInactive/limit.

batch_query_components

Query components with unified batch filters. Optional componentType narrows the result.

batch_query_assets

Query project assets by type, path pattern, and labels. Read-only.

batch_preview_rename

Preview batch renaming. mode supports prefix / suffix / replace / regex_replace.

batch_preview_set_property

Preview setting a component property or field across queried targets.

batch_preview_replace_material

Preview replacing Renderer materials across queried targets.

batch_execute

Execute a previously previewed batch operation by confirmToken. Large operations return a jobId.

runAsync: true (the default) or an item count above chunkSize returns status: "accepted" plus a jobId — poll it like any other job. Only the inline path (runAsync: false and items ≤ chunkSize) blocks, and its wait is bounded: 50ms per item with a 5s floor and a hard 30s ceiling (the shared main-thread wait cap — the inline wait spin-sleeps on the main thread, so it can never be allowed to freeze the Editor for as long as the item count would imply). When that ceiling hits first, the job is still running: you get success: false with a non-completed status and the jobId, not a frozen Editor. That is not a failure — carry on with job_status / GET /jobs/{id}, and prefer runAsync: true for anything big enough to risk it.

batch_report_get

Get a batch execution report by reportId.

batch_report_list

List recent batch reports.

job_status

Get status for an asynchronous UnitySkills job. Built for repeated polling, so the job's result payload is not inlined by default (v2.7+) — a completed test or compile job can carry tens of KB, and polling used to resend all of it every call.

Instead you get two fields:

• resultAvailable (bool) — whether a payload exists at all.
• resultHint (string, null when resultAvailable is false) — where to fetch it: test_get_result(jobId) for kind: "test", test_discover_get_result(jobId) for kind: "test_discovery", batch_report_get(reportId=...) for any job that produced a reportId (the hint quotes the id), and for every other kind a note to re-call with includeDetails=true, which is then the only route to that payload.

The details key is still present either way — it is simply null unless you asked for it, so a client reading response["details"] gets null rather than a missing-key error. Set includeDetails=true on the one call where you actually want the data, never on the polling loop.

job_progress

Get fine-grained progress events for a job via incremental polling. Use offset to fetch only new events since the last call (pass previous totalCount as next offset).

Note: Also exposed as HTTP GET /jobs/{id}/progress and Python client.get_job_progress(job_id, offset) — all three paths share the same response shape.

Response fields: jobId, status, totalCount, offset, events[] (timestamp ms, progress, stage, description), terminal.

An empty events[] is not a malfunction. Fine-grained, per-item progress exists only for batch-executor jobs (rename / set_property / replace_material / set_render_layer / cleanup_temp_objects / fix_missing_scripts / standardize_naming), which emit one event every progressGranularity items because only they own a countable item list. Other kinds emit at most coarse lifecycle events (queued → stage change → terminal), and test_discovery emits none at all — totalCount: 0 there means "this kind has no progress stream", not "the job is stuck". For those, poll status via GET /jobs/{id} instead of watching for events.

job_logs

Get structured logs for a UnitySkills job.

Note: Also exposed as HTTP GET /jobs/{id}/logs?limit=N (server clamps limit to [1, 500]) and Python client.get_job_logs(job_id, limit) — both are the lightweight route (bypasses the skill router and the main-thread skill queue), preferred over the job_logs skill for repeated polling. Response fields: jobId, count, totalCount, logs[] (timestamp, level, stage, message, code).

job_list

List recent UnitySkills jobs.

job_wait

Wait for a UnitySkills job to finish or until timeoutMs elapses. Blocks the Unity main thread while waiting, so timeoutMs is clamped server-side to [0, 2000] regardless of the value you pass — a 10000/60000 request will actually wait at most 2s.

For job kinds whose progress depends on Unity's own engine loop rather than this plugin's own pump (compile, package, test, playmode, play_capture, build_player), blocking this thread cannot make them advance — Unity's compiler/domain-reload, PackageManager Request resolution, TestRunner callbacks, PlayMode state machine, and BuildPipeline all need the main thread free to tick. For those kinds job_wait does not enter a wait loop: it returns the current snapshot immediately with waitNotSupported: true and a hint pointing at the non-blocking alternatives below. Self-driven kinds (batch executor jobs such as rename / set_property / replace_material / set_render_layer / cleanup_temp_objects / fix_missing_scripts / standardize_naming, and test_smoke) still block up to the clamped timeout since each job_wait tick genuinely advances their state.

Recommended pattern for compile/package/test/playmode/play_capture/build_player jobs: poll GET /jobs/{id} every 200-500ms, or long-poll GET /events. GET /jobs/{id} skips the main-thread skill queue (it runs in the light lane, drained every frame and exempt from the frame budget), but it is still answered by the Editor main thread between frames — while a long operation holds that thread, polling stalls and resumes once the thread ticks again. To stay responsive throughout a long job, use GET /events: it is a true HTTP-thread long-poll that never enters the main-thread queue at all.

Response adds terminal (bool) and waitNotSupported (bool) to the fields listed under job_status; hint is populated only when waitNotSupported is true. Like job_status it reports resultAvailable + resultHint and leaves details null unless you pass includeDetails=true — same semantics, same key set.

job_cancel

Cancel a UnitySkills job if the job supports cancellation.

batch_fix_missing_scripts

Preview batch removal of missing scripts. Execute with batch_execute(confirmToken).

batch_standardize_naming

Preview standardizing names by trimming whitespace and normalizing separators. Execute with batch_execute(confirmToken).

batch_set_render_layer

Preview setting GameObject layers in batch. Execute with batch_execute(confirmToken).

batch_replace_material

Preview replacing materials in batch. Execute with batch_execute(confirmToken).

batch_validate_scene_objects

Analyze scene objects for missing scripts, missing references, duplicate names, and empty objects.

batch_cleanup_temp_objects

Preview deleting temporary helper objects by common temp-name patterns. Execute with batch_execute(confirmToken).

batch_retry_failed

Re-run only the failed items from a previous batch execution report. Returns a new jobId and originalReportId.

Exact Signatures

Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.