unity-batch

トリガー

• 多数のオブジェクトを一度に操作する
• 長時間かかる非同期ジョブを実行またはポーリングする
• 一括編集をプレビューしてから確定する
• 大量のオブジェクトを一度に操作する、長時間かかる非同期ジョブを実行またはポーリングする、プレビューしてから一括編集を確定する

Unity Batch Skills

POST /skills/batch エンドポイントでは、一括編集のクエリ → プレビュー → 実行、実行レポート、非同期ジョブを扱います。パラメーターはスキル名ではなくスキーマから取得します。実行と dryRun のルールについては、ルートの SKILL.md を参照してください。

POST /skills/batch — 1 回の HTTP 呼び出しで複数のスキルを実行

スキルではなく HTTP エンドポイントです。skills_batch を POST /skill/<name> に送信しないでください。1 つのメインスレッドジョブ内で、通常のスキル呼び出しを最大 50 件、順番に実行します。各呼び出しでは、単一スキルの全パイプライン（検証、権限ゲート、個別の Undo グループ、監査）を通過します。3 件以上の書き込みがある場合に特に効果が大きく、N 回のラウンドトリップとメインスレッドの起動が、それぞれ 1 回で済みます。

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	なし	args 内の {"$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) は、プレビュー済みの一括操作を 1 つ確定します（N 個のオブジェクトに対する 1 つの動詞）。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) を実行します。トークンは一度だけ使用でき、有効期限は 1 時間です。期限切れの場合は、再度プレビューしてください。大規模な実行では 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（prefix/suffix/replace/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 を使用してください。