topview-3d-cli

topview-3d-cli

topview-3d-cli は、ローカルのディレクタープロジェクト（.topview-3d/ フォルダーを含むディレクトリ）を編集し、レンダリングします。目標は、動画生成のための抽象的で物理的に一貫した配置リファレンスを作成することです。シンプルな形状、適切なスケールと支持、明確なブロッキング、複数の静的カメラから見た同一の世界を扱います。まずキャラクターの位置を優先し、次に妥当性とカメラの連続性、その後に構図を考慮します。細かな視覚的ディテールは目標ではありません。スマートフォンは板状でもかまいません。ユーザーの言語で応答してください。

このバージョンの対象範囲：プリミティブな小道具、組み込みの4キャラクター（Child、Youth、Female、Man）、121種類の静的ポーズ、静的カメラ、ルートキーフレーム。モーションライブラリはありません。歩行サイクルやその他の身体アニメーションを決して約束しないでください。動きを示すには、キャラクターに適した静的ポーズ（たとえば、歩くような歩幅）を設定し、ユーザーが動きを求めた場合に限り、transform.position / transform.rotation キーフレームを追加します（references/edit.md を参照）。既存のアニメーションと編集データは拡張せず、そのまま保持してください。

ステップ 1：環境を確認する

セッションでは、何よりも先にこれを実行してください。

topview-3d-cli doctor --json

常に 0 で終了します。最上位の ok を基準に判定してください。ok が false の場合は、失敗した各 checks.<name>.hint を読み、references/doctor-browser.md に従ってください。

• topview-3d-cli が見つからない場合： マシンごとに一度だけ、すべてのプロジェクトで共有する環境にインストールします。何かをインストールする前に、次の場所を確認してください。macOS と Linux では ~/.local/share/topview-3d-cli/venv/bin/topview-3d-cli、Windows では $env:LOCALAPPDATA\topview-3d-cli\venv\Scripts\topview-3d-cli.exe です。 そのファイルがあり、doctor --json がこのスキルで固定されている cliVersion（topview-3d-cli==0.1.8）を報告する場合は、すべてのコマンドでそのパスを使用してください。 それ以外の場合は、references/doctor-browser.md の説明に従って一度だけインストールしてください（「topview-3d-cli のインストール」）。 ユーザーのプロジェクトやワークスペース内に仮想環境を作成しないでください。また、pip install --user は使用しないでください。
• node が失敗する場合： npm を含む Node.js 20.6 以降が必要です。ユーザーにインストールを依頼してください。
• チェックアウト： このスキルを格納しているフォルダーに agent/ と editor/ もある場合（プラグインのインストールはチェックアウトです）、その scripts/install.sh（Windows では install.ps1）を一度実行してインストールしてください。CLI を共有環境に配置し、レンダラーと Studio の Next.js をまとめてインストールします。レンダラーパッケージだけをインストールしないでください。
• playwright または chromium が失敗する場合： topview-3d-cli browser ensure を一度実行してください（ユーザーキャッシュに固定バージョンの Chromium がダウンロードされます）。
• doctor は通るのにエージェントのサンドボックス内でレンダリングに失敗する場合： サンドボックスがブラウザーをブロックしており、topview-3d-cli が原因ではありません。そのことを伝え、サンドボックスの外でレンダリングコマンドを実行する許可をユーザーに求め、ブラウザーを必要としない作業は続けてください。代替レンダラー（画像ライブラリ、SVG、手描きのフレームなど）は決して作成しないでください。

CLI の契約

• すべてのコマンドは、標準出力に JSON オブジェクトを 1 つ出力します。失敗した場合は、標準エラー出力に {"ok": false, "code", "error"} を出力し、利用可能な場合は details（失敗した index など）も含めます。終了コード 0 は成功、2 は既存のノード、アセット、ポーズ、カメラを指さない ID を含む無効な入力（入力を修正してください）、1 はコマンドを実行できなかったこと（競合、依存関係の不足、レンダラーの失敗）を表します。
• 仕様ファイルは JSON オブジェクトです。- を指定すると標準入力を読み込みます。最初に一時ファイルへ書き込んでください。
• 書き込む前に検証してください。document apply、node batch、pose batch では --dry-run を使用し、プランの数値は topview-3d-cli evaluate <dir> plan.json で検証します。コマンドが失敗した場合、何も書き込まれません。
• 最新の結果から expectedSceneSequence を渡してください。SCENE_SEQUENCE_CONFLICT が発生した場合は、再読み込みして計画し直してください。数値をむやみに増やしてはいけません。
• ID（libraryId、poseId、presetId、ノード ID）はコマンド出力からそのままコピーしてください。ID、寸法、計測値を捏造してはいけません。
• レンダリング後は、返された PNG ファイルを開いて確認してから評価してください。表示していないレンダリングは視覚的な根拠になりません。
• 3D シーンは topview-3d-cli（node batch、pose batch、document apply）で変更してください。Studio ページをクリック、ドラッグ、入力したり、ブラウザー自動化でノードを移動または編集したりしてはいけません。In-App Browser は、ユーザーがシーンを確認できるように Studio を開く場合にのみ使用します。
• 書き込みを行うのは一度に 1 つだけです。Studio が同じプロジェクトを保存している間は、書き込みコマンドを実行しないでください。ユーザーが Studio で編集した後は、次の変更を計画する前に document get で再読み込みしてください。Studio は project adopt を通じて変更を書き戻すため、ディスク上のプロジェクトが編集後のシーンになります。

各セッションはコンテキストから始める

topview-3d-cli project status <dir>            # or: topview-3d-cli project init <dir> for a new scene
topview-3d-cli document get <dir> --summary    # nodes, cameras, sceneSequence
topview-3d-cli bom get <dir>                   # the plan record: intent, relations, cameras, verification

計画を立てる前にそれらを読み、再読み込みするのは、自分で書き込みを行った後、または競合が発生した場合だけにしてください。`topview-3d-cli document get

--entity ` は、ノードまたはクリップ全体を返します。

ワークフローの段階

各段階のリファレンスは、そのセッションで最初のコマンドを実行する前に一度だけ読んでください。

各段階の区切りでユーザーを案内する

基本原則：案内によって、次に取るべき有益な行動が明確になります。創造的な判断が必要な場面ではいったん止まり、すでに承認された作業の実行中は進捗を伝えてください。

デフォルトでは、以下の段階を 1 つ完了させ、その結果を確認できる状態にしてから、次に進むか現在の結果を修正するかをユーザーに尋ねます。回答を待ってから次の段階を開始してください。表のすべての段階を続けて実行し、レンダリング後にだけ尋ねることはしないでください。これは、新しいシーン、編集、修正に適用され、最終納品も含みます。 例外：現在のタスクでユーザーが動画生成を許可した場合、ステージ 10 は、追加の段階ごとの承認確認を行わずに、準備、サービスへの送信、納品まで進みます。この許可は現在の生成ラウンドに対するものであり、今後すべての 3D プランのバージョンに対するものではありません。 フィードバックによってシーン、モデル、ポーズ、またはカメラの段階に戻る場合は、修正したプレビューを完成させて検証し、そこから生成するか、さらに調整するかを尋ねてから止めてください。この判断の場面で、前のラウンドの「はい」を引き継いではいけません。修正と再生成の両方を明示的に求めるリクエストは、すでにその選択への回答になっています。references/generate.md を参照してください。

• 何が準備できているかを簡潔に伝え、該当するプラン、プレビュー、または結果を示し、次の選択に影響する未解決の制約があれば説明します。視覚的でない段階では、簡潔な要約で十分です。
• 具体的な次のアクションを提案し、その目的を一文で説明します。最後に、ユーザーの言語で明確な質問を一つだけします。「実際のアクション」と「変更できる内容」を挙げ、「続けますか？」や「次は何をしますか？」だけを尋ねるのは避けてください。例（英語で記載。回答時は各言語に合わせてください）：
  • レイアウトプランの提示後：「このシーンを3Dで作成しますか、それとも先にレイアウトを修正しますか？」
  • シーン構築後：「カメラの動きを設定しますか、それとも先にこのシーンを修正しますか？」
  • カメラ設定後：「プレビュー動画をレンダリングしますか、それとも先にカメラの動きを調整しますか？」
  • リファレンスと生成プロンプトの準備後：「動画生成に進みますか、このシーンを修正しますか、それとも先に生成プロンプトを編集しますか？」
  • フィードバックを受けて3Dプレビューを修正した後：「修正版のカメラプレビューができました。このプレビューから新しいリアルな動画を生成しますか、それともシーンやカメラの動きをさらに調整しますか？」 現在の結果と利用可能な機能に適した選択肢だけを提示してください。リファレンス動画がまだできていない場合は、生成への引き継ぎを提案する前に、レンダリングまたはエクスポートを提案してください。
• 段階とは、ユーザーが成果を確認できる節目であり、CLI の呼び出しごとではありません。その段階の成果を確認できる状態にするため、読み込み、計測、ドライラン、レンダリング、必要な修正をすべて完了してから質問してください。各ツール呼び出しの許可を求めたり、未検証の中間結果で止めたりしないでください。
• ユーザーが変更を依頼した場合は、現在の段階内で変更を加えて検証し、更新した結果を提示してから、次の段階へ進むか修正するかを再び尋ねてください。修正の依頼だけでは、後続の段階に進む許可にはなりません。返答がないことを回答とみなしてはいけません。
• 依頼に関係する段階だけを適用してください。編集のために、完了済みのセットアップをやり直したり、関係のないオブジェクトを作り直したりしないでください。該当する最後の段階では、具体的な次の作業または追加の修正を提案してください。「停止」「今は不要」、または質問しないでほしいという要望を尊重してください。
• ユーザーが複数の段階、またはワークフロー全体を中断なしで完了するよう明示的に依頼した場合は、その範囲に従い、最後に質問してください。すでに承認済みの段階を何度も確認してはいけません。通常の「シーンを作成して」という依頼では、上記の段階ごとの進め方に従ってください。
• レンダリング結果を引き渡す際は、ステージ 10 に従って生成プロンプトを準備し、提示してください。ユーザーがこのバージョンからの生成をまだ許可していない場合に限り、生成するかどうかを尋ねてください。「レンダリングして動画を生成して」のような明示的な依頼は、すでに生成の許可を含みます。許可を得た後は、準備や実行について承認を繰り返し求めず、進捗を伝えてください。 | Stage | What to do | Reference | | --- | --- | --- | | 1. 理解 | 会話と現在の状態から意図を把握し、BOM に記録します | references/state-intent.md | | 2. レイアウト | 関係性、支え、向き、クリアランスを確認し、BOM のフィールドに記録します | references/layout.md | | 3. 小道具 | まず 1～4 個のプリミティブを使い、必要な場合のみインポートしたモデルを使います | references/add-prop.md | | 4. 人物 | 組み込みのキャラクターから選び、ポーズを付ける前に配置します | references/add-character.md | | 5. ポーズ | レビュー済みのテキストマッピングを使い、座席に合わせます | references/pose.md | | 6. カメラ | 必須の俯瞰ビューに加え、人物の人数に応じたストーリーをカバーします | references/camera.md | | 7. 編集 | 指示された内容のみを変更し、一括処理の構文とキーフレームを使います | references/edit.md | | 8. 確認 | 数値とレンダー結果を確認し、PNG を見て修正します | references/checks.md | | 9. Studio | In-App Browser で完成したシーンをローカルの Studio に開きます | references/doctor-browser.md | | 10. 生成 | プロンプトを作成して提示し、許可がない場合は一度だけ生成許可を得てから、繰り返し確認せずに生成して結果を記録します | references/generate.md, references/video-prompt.md |

フレームの準備ができたら

レンダリングした動画またはフレームで完了するすべてのワークフローでは、ステージ 10 を実施します。これを行わずに、 レンダー結果の段階でセッションを終了しないでください。references/generate.md を読み、その指示に従ってください。動画のレンダリングが完了したら、 依頼されていなくても、references/video-prompt.md に従って生成プロンプトを作成し、 ユーザーに提示します。このバージョンの生成許可がない場合は、生成してよいか確認します。許可が得られたら、 サービスの選択、生成、結果の記録まで、繰り返し承認を求めずに完了します。 動画の生成では、レンダリングまたはエクスポートした動画を参照として使用します。

ビルド、確認、レンダリングはオフラインで行います。ステージ 10 のみ、ユーザーが許可した生成タスクの範囲内で 外部サービスに接続できます。他のステージで生成サービスに接続してはいけません。

小道具、キャラクター、ポーズのアセット検索ルールについては references/asset-selection.md を参照してください。 インストール、ブラウザー、サンドボックスの制限については references/doctor-browser.md を参照してください。

コマンド

Need	Command
新しいプロジェクト／状態	topview-3d-cli project init <dir>、topview-3d-cli project status <dir>
ドキュメントを読む	topview-3d-cli document get <dir> --summary、topview-3d-cli document get <dir> --entity <id>
ノードの追加、変更、削除	topview-3d-cli node batch <dir> changes.json [--dry-run]、topview-3d-cli node delete <dir> <id>
低レベル操作（シーン設定、キーフレーム）	topview-3d-cli document apply <dir> ops.json [--dry-run]
アセットを検索	topview-3d-cli asset search <words> --kind character|pose|prop、topview-3d-cli asset show <id>
ポーズ一覧	topview-3d-cli pose catalog [--category sit]
人物にポーズを付ける	topview-3d-cli pose batch <dir> poses.json [--dry-run]、topview-3d-cli pose apply <dir> <nodeId> <poseId>
カメラのプリセット	topview-3d-cli camera presets
ブラウザーを使わずに数値を確認	topview-3d-cli evaluate <dir> [plan.json] [--frames 0,24] [--camera <id>]
メッシュの計測値	topview-3d-cli inspect nodes <dir> <id>... [--frame N]
カメラごとの数値とレンダー結果	topview-3d-cli inspect views <dir> --camera <id> ... --primary <id>
レンダリング 1 回	topview-3d-cli render <dir> [payload.json]
レンダリングした PNG を探す	topview-3d-cli renders list <dir>、topview-3d-cli renders show <dir> [runId] [--frame N]
計画の記録	topview-3d-cli bom get <dir>、topview-3d-cli bom checkpoint <dir> patch.json
構造の検証	topview-3d-cli document validate <dir>
Studio で開く	topview-3d-cli studio open <dir> を実行し、返された url を In-App Browser で開きます

厳守事項

1. 座標系は右手系で、Y軸が上、単位はメートルです。回転はオイラー角の度数で、スケールは正の倍率です（軸を紙のように薄くする場合は0.001）。ノード ID は[A-Za-z0-9_-]{1,128}に一致します。
2. 配置や着席を行う前に測定します（topview-3d-cli inspect nodes）。evaluateでの視錐台チェックと接地チェックでは、ノードの原点とプリミティブのボックスのみを使用します。
3. すべてのシーンに、専用の俯瞰カメラ（BOM のカメラロールはlayout_overview）を1台設け、レイアウトの変更後に再調整します。これはレイアウトの証拠であり、メインのストーリー画像には使用しません。
4. inspect viewsの--primaryには、BOM のstoryカメラを1台選びます。ユーザーが数を指定しない限り、複数人のシーンはreferences/camera.mdの最小要件に従ってカバーします（3人以上の場合：グループ全体を捉えるマスターショット、交流するグループごとのビュー、主要キャラクターごとのクローズアップ）。
5. 通常、「座る」とは、床に座る、あぐらをかく、またはひざまずくことが明示されていない限り、椅子、ソファ、ベンチ、またはスツールに座ることを意味します。まず既存の座席を再利用するか、1～4個のプリミティブで作成します。
6. 不足点は正直に報告します。簡略化した代替物はその旨を説明し、検証されていない制約はunknownのままにします。
7. 細い線、縞模様、Z ファイティング、エイリアシングはレンダラーのアーティファクトであり、欠陥ではありません。測定値または失敗した BOM のハード制約が根拠としてある場合に限り、修正します。修正パスごとにinspect viewsを1回実行します。
8. タイムラインのデフォルトは24 fps、120フレームです。画像データや Base64 をメッセージに貼り付けないでください。パスを提示します。
9. 3D シーンは CLI で変更します。Studio ページやブラウザーの自動操作では編集しません。
10. ユーザーが表示できるよう、In-App Browser でローカルの Studio を開きます。studio openはサーバーを起動してurlを返すだけです。そのurlはシステムブラウザーではなく、In-App Browser で開きます。Next.js がインストールされていないために失敗した場合は、チェックアウトのeditor/ディレクトリで一度pnpm installを実行し、studio openを一度再試行します。references/doctor-browser.mdを参照してください。