unity-cli

Unity CLI

1 つの CLI（cs）で Unity Editor／Player を操作します。既定のオーサリングサーフェスは、関連するスキーマだけがコンテキストに読み込まれるよう、エージェント向けの 6 つのドメインにまとめられています。コントロールプレーンとプロジェクト固有のカスタムコマンドには、明示的なビューを使用します。 cs list-commands はコントロールプレーンの CLI 検出操作であり、正規のパッケージ契約である command/list ではありません。この CLI のフラグが command/list の引数になることはなく、検出の呼び出しを正規のコマンドルートとして表現してはなりません。ユーザーがそのパッケージ契約を明示的に要求した場合に限り、command/list を使用してください。 検出によって返されるレコードには、オーサリング、カスタム、コントロールプレーンのいずれかのティアが付与されています。

cs の実行

以下で示す cs は、次の意味です。

python "<SKILL_DIR>/scripts/cli/cs.py"

<SKILL_DIR> は、このスキルの絶対ベースディレクトリで、スキルの読み込み時に提供されます。呼び出しのたびに cs をその絶対パスのコマンドに展開し、ディレクトリを変更せずに実行してください。

他のスキルのインストール先を列挙したり、このドキュメントに記載されている内容を再確認するために cs --help を実行したりしないでください。このファイルと、返される Route Card でルーティングに必要な情報はすべて網羅されています。

通常の使用時に --project を渡さないでください。CLI は作業ディレクトリと自身のコミット済みの場所の両方から上位ディレクトリをたどり、Unity プロジェクトを特定します。--project <path> は、別のプロジェクトを意図的に対象にする場合にのみ使用してください。

CLI はその場で実行され、ブートストラップやコピーの手順はありません。cs setup は便利な機能ですが、必須ではありません。パッケージが存在しない場合、または --update を使用した場合、setup は共通の Packages/manifest.json に書き込みます。書き込みを伴う setup を実行する前に、追加する正確なソースを伝え、ユーザーの承認を得てください。references/setup.md を参照してください。

入力の渡し方

シェル経由で C# コードや構造化されたコマンドパラメーターを直接渡さないでください。ファイルに書き込んでから、その絶対パスを渡してください。

• exec 用の生の C# は、--file を使って .cs ファイルに記述します。
• command と batch 用の構造化パラメーターは、--input を使って JSON ファイルに記述します。

必須のスクラッチディレクトリは次のとおりです。

<project-root>/Temp/CSharpConsole/AgentScratch/

これは Unity が管理する Temp/ 内にあり、インポートされず、通常は git の無視対象です。常に絶対パス全体を使用してください。ファイルにはタスクの内容が分かる名前を付け、順次修正する場合は同じファイルを上書きしてください。同じ Unity プロジェクトで別のエージェントが並行して作業していることが分かっている場合に限り、ランダムなサフィックスを使用してください。

スクラッチペイロードは使い捨てです。再利用可能な C# はスニペットライブラリに記述してください。クリーンアップするのは AgentScratch/ だけにしてください。サービスの状態が保存されている Temp/CSharpConsole/ は削除しないでください。REPL のペイロードを Assets/ に書き込まないでください。インポートされるとプロジェクトのコンパイルが壊れ、サービスが再起動できなくなる可能性があります。

cs exec --file "<project-root>/Temp/CSharpConsole/AgentScratch/inspect-camera.cs"
cs command --json --input "<project-root>/Temp/CSharpConsole/AgentScratch/req-create-cube.json"
cs batch --json --input "<project-root>/Temp/CSharpConsole/AgentScratch/req-batch.json"

REPL セッション

cs exec は、既定では新しいセッションを開始します。自己完結したコードでは、この既定値を維持してください。後続の送信内容が、前に作成した変数、using、型、またはヘルパーに意図的に依存する場合は、タスク固有の不透明な ID を 1 つ生成し、繰り返し使用してください。

cs exec --session agent-a1b2c3 --file "<project-root>/Temp/CSharpConsole/AgentScratch/inspect-camera.cs"
cs exec --session agent-a1b2c3 --file "<project-root>/Temp/CSharpConsole/AgentScratch/use-camera.cs"

無関係なタスク間やエージェント間でセッションを共有しないでください。ドメインの再読み込みによりセッションの状態が消去されるため、cs refresh の後はコンテキストを再構築するか、新しい ID を使用してください。ライフサイクルとリセットの詳細については、references/exec-code.md を参照してください。

ルーティング

すべてのタスクで、正規の順序である 組み込みコマンド → プロジェクトカスタムコマンド → スニペット → 生の exec を使用してください。一致する組み込みコマンドがある場合、C# を優先してそれを飛ばしてはいけません。実行可能な契約の正式な情報源はパッケージレジストリです。コミット済みのカスタムカタログは、共有される候補リストにすぎません。

構造化された Unity 操作では、実行の詳細を読み込む前に、検出を完了してください。 通常の組み込みオーサリング検索の予算は、空でない各階層につき Route Card を 1 回呼び出し、その後、正確な ID を合計 1 回呼び出すことです。クローズ後に真に新しい要件が生じた場合に限り、理由を記録したうえで、範囲を絞った組み込み検索を 1 回行えます。

検索台帳を維持してください。台帳の適用範囲は、現在のエージェントセッションと解決済みのプロジェクトターゲットに限定してください。台帳のキーには、セレクターの種類（domain または id）、正規化されたビュー、階層、ソート済みのセレクター、解決モード（live、offline、または明示的な refresh）、投影／詳細モード（compact または verbose）を含めます。起動前にシグネチャを実行中としてマークし、成功後に完了としてマークしてください。完了済みまたは実行中のシグネチャは再利用するか、完了を待ってください。必須のライブ比較を満たすために、オフラインのエントリーを使用してはいけません。保存済みのライブまたはリフレッシュのエントリーは、同じプロジェクト、台帳の世代、詳細モードで cacheStored:true の場合に限り、他の条件が同一のオフラインリクエストを満たすことができます。これ以外のモード間または詳細モード間での再利用は認められません。台帳はエージェントのメモリ内での管理情報です。壁時計時刻を照会したり、台帳ファイルを作成したりしてはいけません。

リフレッシュは排他的なバリアです。そのプロジェクトに対して実行中のすべての検索が完了するまで待ち、その後、リフレッシュだけを起動してください。source:"live" と cacheStored:true を持つリフレッシュ結果だけが、新しい台帳世代を作成します。そのリフレッシュを最初のエントリーとして記録し、それより前の完了済みエントリーを無効にしてください。古いキャッシュやフォールバックによるリフレッシュでは世代を進めず、後続のオフライン検索も満たしません。古い台帳世代から遅れて返された結果は、記録も使用もせず、破棄してください。

タイムアウトまたは終端状態が不明の場合、ライブ検索またはリフレッシュ検索を再試行してはいけません。そこで停止し、状態が不確実であることを報告してください。結果がなく、終了コードがゼロ以外であることが確認されたオフライン検索に限り、同じ台帳エントリーの下で 1 回だけ再試行でき、その理由を記録してください。成功した検索を再送してはいけません。

1. 呼び出し前にドメインを確定します。 要求されたすべての変更、前提条件、明示的な不変条件、独立した検証、フォールバック確認から、Core と Advanced のドメインセット全体を構成します。以下の表は通常のドメインインデックスです。フィルターなしのインデックス呼び出しは省略します。Advanced 専用リストは条件付きであり、チェックリストではありません。直接の prefab/asset_* 編集、prefab/unpack、アセットフォルダーの作成、Scene View のキャプチャは Advanced です。prefab/create と prefab/instantiate は prefabs/core に含め、一般的なプレハブ列挙は assets/core に含めます。同じドメインが両方のティアに属する場合もあります。フォルダーとマテリアルのワークフローでは、assets が両方のセットに入ります。フォルダーの作成は Advanced、マテリアルの作成、検査、割り当ては Core です。Advanced の意図によって、そのドメイン内で要求された別の Core 操作を置き換えてはいけません。プレハブドメインに関する意図がある場合、そのすべてが直接の prefab/asset_* 操作または prefab/unpack である場合に限り、prefabs/core を省略します。 すべてのドメイン／ティアの選択は、肯定的に要求された操作に対応していなければなりません。除外項目、例、並列処理によってクエリセットを広げてはいけません。明示的に指定された読み取りまたは検証は、そのティアを選択します。一方、変更に対する一般的な読み戻しは、正確なバンドルが直接の関係を示すため、選択理由にはなりません。後で詳細調査が必要になる可能性があっても、最初のドメインセットを広げてはいけません。上流の読み取りによって必要になるまで待ちます。用途がそのような後回しの詳細調査に限られるドメインは空なので、省略します。たとえば、階層全体のシーンスキャンでは、返されたオブジェクトの一つを後で検査する必要があるかもしれないというだけで objects を選択しません。スキャン／レポートの意図は階層の読み取りであり、オブジェクト単位またはコンポーネント単位の読み取りが暗黙に含まれるわけではありません。すべてのプレハブアセット階層をスキャンする場合、列挙は assets/core、階層の検査は prefabs/advanced です。prefabs/core は省略します。
2. ルートカードのラウンドを実行します。 空でない各ティアについて、複数ドメインのクエリをちょうど1回だけ使用します。コンパクトな結果には cacheStored が保持されます。これはキャッシュの世代の連続性を保証するためです。最初のライブ呼び出しで、このセッションにおけるフィンガープリント比較を1回実行します。ライブワークフローで両方のティアが空でない場合、最初のライブ呼び出しは Core です。Core が空の場合に限り、Advanced を最初にできます。そのライブ呼び出しが完了する前に、後続のオフラインティア呼び出しを行ってはいけません。source:"live" かつ cacheStored:false が報告された場合は、レジストリの世代を混在させず、停止して永続化の失敗を報告します。生成されたフォールバックを使って続行できるのは、計画のみです。明示的なオフライン／プロジェクトなしのドライランでは、直ちに --offline を追加し、両方のティアが空でない場合は、Core と Advanced のクエリを1回のツールラウンドで同時に開始します。提示されたコンテキストを再確認するために、status、ファイルシステム、作業ディレクトリを調べてはいけません。Core だけで、要求された操作に Advanced が必要だと判明した場合は、未解決の該当操作すべてについて Advanced の呼び出しを1回だけ行います。古いキャッシュまたは生成されたフォールバックは計画専用です。実行するには、その呼び出し中にレジストリがライブ状態であることを検証する必要があります。
3. 正確なラウンドを1回実行します。 すべてのルートカード呼び出しが完了するまで待ってから、IDを指定した唯一のコマンドを構成します。すべてのティアと分岐から選択されたIDの和集合を取り、すべての変更、生成元、利用先、ループ分岐、不変条件、検証を網羅するように閉包します。IDは返されたカードからのみコピーします。複数IDの正確なクエリを、シェル呼び出し1回で実行します。ドメインクエリの並列化ルールは、正確な検出には適用されません。和集合を並列呼び出しや後続呼び出しに分割したり、元のタスク要件について後から正確な検索を追加したりしてはいけません。将来の読み取り次第で必要性が決まる条件付きの詳細調査は、正確に読み込んではいけません。後回しにする詳細調査は、正確なセレクターセットと呼び出し計画の両方から省き、条件が満たされるまでは、そのトリガーだけを文章に記録します。呼び出し計画のルートは現在のフェーズで実行可能なものです。したがって、「if」や「when」を目的とする後回しのルートを追加してはいけません。広範なスキャンでは、必要な診断シグナルが契約に明記されていない項目単位のゲッターで、その不足を補うことはできません。そのゲッターを選択するのではなく、機能上の不足として記録します。ランタイムのセレクターバインドだけでは、既知の利用先は条件付きになりません。その契約を最初の閉包に含めます。読み取りによって正当化された新たな詳細調査IDがある場合は、それらをまとめて、絞り込んだ後続検索を最大1回だけ実行します。selected、related、denied は、一つの閉じた結果として扱います。selected と related は実行可能な完全な契約ですが、denied の項目は実行不可能なポリシー記録であり、契約ではありません。返されたすべてのIDを未解決セットから削除し、selected に昇格させる目的だけで再検索してはいけません。related は、重複を除いた直接の準備／読み戻しレイヤー全体であり、再帰的な展開ではありません。要求された意図が拒否された場合は終端です。ブロックされたものとして停止し、フォールバックに進んではいけません。契約の証拠は、タスク固有のシグナルについて閉世界です。一般的な結果コンテナーや要約は、明記されていないマーカーやフィールドを保証しません。実行可能なバンドルに必要な機能または検証がない場合、あるいは制限によって実行が妨げられる場合は、より強力な組み込み機能を探すのではなく、機能上の不足として記録します。selected と related の契約項目は機能であり、必ず呼び出す必要はありません。要求された変更、前提条件、または独立した検証に必要な場合にのみ使用します。
4. 具体的な呼び出しを計画します。 各事後条件を、最小の独立した検証に割り当て、完全に冗長な読み取りを取り除きます。契約は重複排除しますが、呼び出しは重複排除しません。明示された検証の制限は優先されます。別の一般的な読み取りでその制限を解消できるのは、その読み取り自身の契約に必要な事後条件が明記されている場合だけです。それ以外は検証上の不足として記録します。引数値やユーザー指定のセレクターが実質的に異なる場合、文章にまとめず、引数の異なる分岐ごとにテンプレートを1つ、明示的な読み戻し対象ごとに呼び出しを1つ残します。一様な生成列は、1つのカウント付きループにできます。一様なカウント付き生成列では、最初に生成される項目を具体的なテンプレートとして使用します。生成元が要求された既知の親の下にオブジェクトを作成できる場合は、その親の下に直接作成します。後から親を再設定する変更を追加してはいけません。引数の動作が偶奇性などの述語によって分岐する場合は、各分岐の最初の要素をテンプレートとして使用します。後の任意のサンプルで代用してはいけません。これらすべてを、追加の検出なしに1つの契約で支えられます。タスクまたは選択された契約で求められていない限り、存在、競合、上書きに関する推測的な事前確認を追加してはいけません。デフォルト値で厳密な不変条件を満たせる場合でも、その不変条件を任意扱いにはできません。 新しく作成された Cube には、すでに BoxCollider がちょうど1つあります。別のものを追加するのではなく、これを使用します。ただし、「ちょうど1つ」という明示的な要件と検証義務は維持します。現在値またはデフォルト値を理由に、明示的に要求された割り当てを省略してはいけません。たとえば、ユーザーが既存のコライダーの m_IsTrigger を設定するよう要求した場合、デフォルト値がすでに一致していても、引き続き component/modify を計画します。
5. 計画と実行を分離します。 ドライランでも、サポート対象の要求された変更をすべて計画します。何も実行していないことは、別途明記します。静的なバッチでは、呼び出し側が定義した決定的なパスを使用できます。Unity が識別子を決める場合は、生成元を別途実行し、返されたセレクターに利用先をバインドします。名前を予測してはいけません。修復は実行される可能性がある場合にのみ検出します。ルールが不足していて診断を読み取り専用に保つ場合は、修復コマンドをドメイン選択、正確な検索、呼び出し計画から除外します。変更後にトランスポートが失敗した場合は、状態が不確かになります。まず読み戻しを行い、非冪等の作成、複製、破棄、インポート、または同等の変更を決してむやみに再実行してはいけません。

cs list-commands [--offline] --domain scene --domain objects --tier core --json
cs list-commands --offline --id gameobject/create --id gameobject/get --json

返されたコントラクトで arguments: [] は、名前付きパラメーターがないことを意味します。args という引数を勝手に追加しないでください。外側の "args": {} ラッパーを使用するのは、実際の command リクエストだけです。

--domain と --id を併用しないでください。--tier はドメインと併用する場合にのみ使用します。あるビューから ID を正確に読み込む場合は、--view control または --view custom を維持してください。作成用 ID はデフォルトビューを使用します。

計画または探索のみの場合は、references/commands.md を読み込まないでください。これらのルーティング規則と、返される Route Cards および Contract Bundle で十分です。command または batch を呼び出す前に、リクエスト、事前チェック、再試行のプロトコルについて、references/commands.md を一度すべて読んでください。その後、必須のスクラッチ JSON ファイルに {"id":"<canonical-id>","args":{...}} を正確に記述し、cs command --json --input <file> を実行します。args は空の場合も必須です。

コントラクトの探索には list-commands のみを使用してください。コマンドの詳細を調べるために、scripts/cli、生成されたレジストリデータ、ルーティングメタデータ、Python 実装ファイルを読み込んだり検索したりしないでください。これらのファイルはエージェント向けではない実装データであり、選択されたコントラクトバンドルよりはるかに大きい場合があります。

組み込みの計画をすべて完了し、具体的な不足がある場合にのみ、フォールバックに進んでください。cs catalog list を実行し、候補の正確なカスタムコントラクトを読み込んでから、cs snippets search "<intent>" を試し、最後に生の exec を試してください。フォールバック前に把握できる要件について、組み込み探索に戻らないでください。本当に新しい要件が生じた場合は、理由を記録したうえで、範囲を絞った正確な検索を一度だけ許可します。Unity プロジェクトが利用できない場合は、カスタム段階とスニペット段階を、調査せずに利用不可として記録してください。利用できないフォールバック段階は選択されていません。その参照ファイルを読み込まないでください。フォールバックの順序を説明するだけでは、段階を選択したことにはなりません。選択した段階の参照ファイルは、その段階に記載された操作を実行する直前にのみ読み込んでください。選択されたカスタムコントラクトの検索は、組み込みコントラクトを一つだけ正確に検索するという制限の例外です。生の C# を作成する前に停止するドライランでは、references/exec-code.md を読まずに exec の判断を記録します。

コマンドリストの更新をユーザーが明示的に依頼した場合にのみ、cs list-commands --refresh … を使用してください。通常の作業中に、フィルターなしの62コマンドのパッケージレジストリを読み込んだり表示したりしないでください。

ドメイン	対象となる意図	除外／別のルート
editor	エディターの状態、プレイモード、テスト実行、コンソールの管理	シーンの内容、オブジェクトの選択、アセットファイル
scene	コンポーネントの概要を含む、シーンの一覧表示／開く／保存、および階層全体の読み取り	特定された GameObject／コンポーネントのプロパティ、プレハブの内容
objects	明示的に特定されたシーンの GameObject、コンポーネント、Transform、または選択対象に対する操作	階層全体のスキャン、未知の将来の対象、プロジェクトアセット、プレハブファイルの編集
assets	アセットの検索／インポート／CRUD、マテリアル、ScriptableObject	シーン階層、プレハブの内容
prefabs	プレハブの作成／インスタンス化／展開、またはプレハブの内容の直接的な調査／編集	一般的なプレハブの列挙（assets/core）および無関係なアセットパス
capture	シーン／ゲームのスクリーンショットと Profiler の記録	構造化された状態の調査

5つのコントロールプレーンコントラクトは、デフォルトの作成ビューには含まれません。ユーザーが求める機能自体がコントロールプレーンに属する場合にのみ、--view control --domain control --tier control-plane を指定して確認してください。探索に cs list-commands を使用しただけでは、コントロールビューの検索や command/list コントラクトの読み込み、計画の正当化にはなりません。

editor/menu.open と editor/window.open は、実行可能なコントラクトではなく、拒否ポリシー対象の意図です。明示的に list-commands --id で検索すると、invoke=false とともに denied の下に表示されます。その結果はブロックとして分類し、そこで停止してください。これらの意図を、スニペットや生の exec に自動的にフォールバックさせないでください。

実行中のプレイヤーをデバッグする

プレイヤーが実際に何をしているかについて質問された場合は、ほかの調査を始める前にランタイムチャネルを開いてください。cs health --mode runtime で応答するプロセスがわかります。状態を調査するときは、コマンド優先の順序に従ってください。利用可能なコマンドでは読み取れない状態には、cs exec --mode runtime --file <file> を使用します。

ランタイムの状態を確認する際は、実行中のプロセスを主な情報源にしてください。実行ができない場合や、ビルドにどのコードが含まれているかが質問の対象である場合は、ログ、ソース、ビルド成果物を補助的な証拠として調べてください。利用できる場合はビルド GUID を照合し、現在のソースと出荷済みのコードを区別して、推論にはその旨を明記してください。部分文字列の一致やファイルのタイムスタンプだけでは、どのコードが実行されたかを特定できません。

プレイヤーが報告するビルドのコンパイルセットがエディターにない場合、ランタイムへの送信は [REPL ALIGNMENT REQUIRED] として拒否されます。その場合は、該当するビルド名を挙げて、そのビルドのコンパイルセット ZIP をすぐにユーザーに依頼してください。デフォルトでは、ビルドマシン上のビルド出力先と同じ場所に CSharpConsoleCompileSet.zip としてエクスポートされます。Project Settings > C# Console で保存先を変更したり、エクスポートを無効にしたりできます。該当する ZIP はビルドを行った人に依頼してください。候補の ZIP がすでにある場合は、ビルド GUID の確認が有用な証拠になりますが、ユーザーの判断なしに登録したり、スキップを選択したりしないでください。ファイルを調べても、ランタイム実行のゲートは回避できません。

プレイヤーのログを読むには、まず収集してください。cs logs --mode runtime --background は書き出したファイルのパスを返すため、その後ローカルで検索できます。フォアグラウンドで追跡すると、シェーダー関連の出力も含めてログ全体がストリーミングされます。

その他のサブコマンド

タスク	サブコマンド	詳細
生の C# フォールバック	cs exec --file	references/exec-code.md
再利用可能な C#	cs snippets …	references/snippets.md
スニペットの監査	cs snippets doctor / stats	references/snippets-audit.md
更新とコンパイル	cs refresh	references/refresh.md
準備状況の診断／待機	cs doctor / cs wait-ready	references/refresh.md
Unity Test Framework の実行	cs test	references/tests.md
エディターログの確認	editor/console.mark + ローカルで読み取り	references/logs.md
実行中のプレイヤーとそのファイル	--mode runtime / cs pull	references/player.md
プレイヤーのビルド用にコンパイル	cs compile-set	references/player.md
書き込み中のログを追跡	cs logs	references/player.md
カスタムコマンドのカタログ	cs catalog sync / list	references/catalog.md
パッケージ／接続状態	cs status / cs health	references/status.md
パッケージのセットアップ	cs setup	references/setup.md

出力規約

• command、list-commands、batch では --json を使用してください。デフォルトの簡潔な形式では、ok と CLI プロセスの終了ステータスを確認します。--verbose は診断時にのみ追加してください。詳細なエンベロープには exitCode も表示されるため、プロセスのステータスと一致している必要があります。
• その他のサブコマンドは、より簡潔なテキスト形式で出力します。構造化されたエンベロープが明確に必要な場合に限り、exec に --json を追加してください。
• バージョン不一致とは、インストール済みパッケージと CLI の major.minor の系列が異なる状態です。一致するまで、Unity を操作するすべてのコマンドが拒否されます（終了コード 1）。cs setup と cs status は不一致の修正と確認に使用するため例外です。Unity に接続しないコマンド（cs doctor、cs wait-ready、オフラインでの一覧表示）には影響しません。references/setup.md に従ってください。
• CLI コマンドの展開内容と JSON ペイロードは、エージェント内部向けです。Unity を開くかフォーカスする必要がある場合は、必要な操作をわかりやすい言葉でユーザーに伝えてから、自分で cs status を実行して結果を確認してください。