unity-batch

触发条件

• 一次性操作大量对象
• 运行或轮询长时异步任务
• 先预览后提交的批量编辑
• 一次性操作大量对象、运行或轮询长时异步任务、先预览后提交的批量编辑

Unity 批处理技能

POST /skills/batch 端点，用于查询 → 预览 → 执行批量编辑、查看执行报告和异步任务。参数来自 schema，而非技能名称；执行和 dryRun 规则请参阅根目录的 SKILL.md。

POST /skills/batch — 一次 HTTP 调用执行多个技能

这是一个 HTTP 端点，而不是技能：切勿将 skills_batch 发送到 POST /skill/<name>。它会在一个主线程任务中按顺序运行最多 50 次普通技能调用，每次都经过完整的单技能流程（验证、权限检查、独立的 Undo 组、审计）：只需一次往返和一次主线程唤醒，而不是 N 次；当写入操作达到 3 次或更多时，节省最为显著。

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

请求体字段	默认值	含义
steps	必填	按顺序排列的 {skill, args} 对象。超过 50 个 → 400 SEMANTIC_INVALID；请拆分调用。
continueOnError	false	false = 遇到第一个失败时停止；true = 记录失败并继续。
params	无	用于 {"$param":"name"} 或 {"$param":"name","default":X} 参数节点的值；静态值，在 $ref 之前解析；缺少值且无默认值时，该步骤失败。

• $ref：仅包含 $ref 键的 args 对象 {"$ref":"$N.path"}，会替换为此前成功步骤 N（从 0 开始）结果中 path 对应的值（例如 instanceId、results[0].path；单独使用 $N = 整个结果）。只扫描结构化 args，不扫描字符串。无法解析的引用（引用后续步骤、失败步骤或无匹配项）会使该步骤以 SEMANTIC_INVALID 失败。请通过 $ref（instanceId，或 Unity 6000.4+ 中的 entityId）引用已创建的对象，而不是按名称引用：名称查找可能会匹配到同名的现有对象。
• 查询参数：?mode=dryRun（批处理 dryRun 检查）会验证每个步骤，不执行任何操作，也不会中止；某个步骤可以指定前序步骤将创建的对象（警告会说明跳过了实时检查），而 $ref 参数只会进行结构检查（refsValidated）。?mode=transactional 会通过 Undo 回滚实现全有或全无；如果存在未知技能、可能触发域重载的步骤或 continueOnError:true，则会在执行前直接拒绝（400）。?diff=1 会添加净 sceneDiff；?wire=v2 会精简 dryRun 步骤负载；expectInstance / expectProject 的用法与 /skill 相同。不支持 ?mode=plan。mode / dryRun 也可以放在请求体中：每个键优先取查询参数，空值视为不存在。除此之外的任何键（请求体中的 steps、params、continueOnError、mode、dryRun 除外）都会导致 400 UNKNOWN_PARAM。

如何读取响应。 批处理已运行时，HTTP 状态码始终为 200；只有被拒绝的请求（请求体无效、步骤超过 50 个、模式或键未知）才会返回 4xx。

{"status":"partial","mode":"execute","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"}]}

• status：completed（没有失败）、partial 或 rolled_back（transactional：已执行步骤会变为 rolled_back，写入资源的步骤会标记 rollbackReliability:"partial"）。mode / dryRun 会回显实际运行的模式；每个条目都包含 index 和 skill。
• 部分失败：success 步骤已应用；失败步骤中由 Undo 记录的更改会被还原；skipped 步骤未运行。只需重新发送修正后的失败步骤和已跳过的步骤，切勿重新发送成功的步骤。
• 授权总是会中断执行，不受 continueOnError 影响：遇到 MODE_RESTRICTED / CONFIRMATION_REQUIRED 步骤时，批处理会停止并返回该步骤的完整负载（包括授权令牌）；完成授权后，再提交剩余步骤。

这与 batch_execute 不同。 batch_execute(confirmToken) 会提交一个已预览的批量操作（对 N 个对象执行同一个动词）。POST /skills/batch 会组合针对任意目标的 N 种不同技能，且不需要令牌；它不会跳过预览/确认检查 — batch_execute 步骤仍需提供自己的 confirmToken。

任务。 当某个技能或步骤返回 jobId（异步执行、测试、编译）时，请使用 GET /jobs/{id}?wait=<s> 等待（最长 120 秒；任务终止后返回结果，并包含 resultData；waitTimedOut:true = 再次 GET；域重载期间返回 503 = 重复使用相同 URL），或轮询 GET /jobs/{id}。这两种方式都不会占用主线程技能队列，且负载远小于 job_status；job_wait 会阻塞主线程（最多 2 秒）。

预览 → 执行

1. 使用 queryJson 进行筛选（筛选条件采用 AND 逻辑：name 子字符串、namePattern 正则表达式、path / parentPath 精确匹配、entityId、instanceId、tag、layer、componentType、sceneName、active、isStatic、prefabSource、includeInactive（false）、limit（500））；batch_query_* 会显示匹配结果。
2. 使用 batch_preview_* 或修复工具（batch_fix_missing_scripts、batch_standardize_naming、batch_set_render_layer、batch_replace_material、batch_cleanup_temp_objects）进行预览。预览为只读操作，并返回 {confirmToken, kind, summary, riskLevel, targetCount, executableCount, skipCount, sampleChanges: [{targetPath, action, before, after}], skipReasons}。
3. 检查样例和风险（执行操作可能会删除或修改大量对象），然后调用 batch_execute(confirmToken)。令牌为一次性令牌，有效期为一小时：之后请重新预览。大批量操作会返回 jobId；报告（batch_report_get）会列出失败项，batch_retry_failed(reportId) 只会重新运行失败项。

在 guide 表面配置下，预览仍可正常工作，但会带有 surfaceExclusion；此时调用 batch_execute 会返回 SURFACE_EXCLUDED，且不会消耗令牌。

运行模式

22 项技能中，除 4 项外，其他均为只读 SemiAuto（查询、预览、修复工具、验证、报告、作业状态/进度/日志/列表），可直接在 Approval 模式下运行；4 项 FullAuto 技能（batch_execute、job_wait、job_cancel、batch_retry_failed）会先在该模式下返回 MODE_RESTRICTED，需要授权。Auto/Bypass 可运行所有技能；没有技能属于 NeverInSemi → 运行模式。

技能概览

• 查询：batch_query_gameobjects、batch_query_components、batch_query_assets（类型/文件夹/名称正则表达式/标签）。
• 预览：batch_preview_rename（前缀/后缀/替换/regex_replace）、batch_preview_set_property、batch_preview_replace_material，以及上文的修复工具；batch_validate_scene_objects 仅生成报告（缺失脚本/引用、重复名称、空对象）。
• 执行和报告：batch_execute、batch_retry_failed、batch_report_get、batch_report_list。
• 作业：job_status、job_progress、job_logs、job_list、job_wait、job_cancel。

各技能的表格和结果格式：reference/<skill_name>.md —— 通常无需查阅，架构说明中已注明参数。

请勿（常见幻觉）：

• batch_execute 不能在没有预览或修复工具调用所返回的 confirmToken 时运行
• batch_run 不存在 → 请使用 batch_execute(confirmToken)
• job_poll / job_result 不存在 → 请使用 GET /jobs/{id}（或 job_status）获取状态；job_status 的 resultHint 会指出哪个技能可返回大型结果
• batch_delete / batch_move 不存在 → 资产级操作请使用 asset_* 技能

其他操作：资产批量移动/复制/删除 → asset_*；工作流会话撤销 → workflow_*。

精确签名

没有 Batch 类别：GET /skills/schema?category=Workflow 包含其中 16 项技能（查询、预览、执行、报告、作业），?category=Validation 包含 5 项修复工具和 batch_validate_scene_objects；也可使用 ?names=a,b。