HyperFrames CLI は何をしますか?
特にプロジェクトの指示がラッパーを提供していない限り、コマンドは npx hyperframes ... として実行します。ラッパーがある場合はそれに従ってください。CLIにはNode.js 22以降とFFmpegが必要です。
開発ループ
- スキャフォールディング:
npx hyperframes init <project>またはサイトをキャプチャします。非TTYモードでは、--non-interactive --example=<name>を渡します。 - 作成:
/hyperframes-coreを使用してコンポジションを記述します。 - 編集しながら迅速なフィードバックを得る: 最初のHTMLパス後および構造変更後に
npx hyperframes lintを実行します。 - 最終ゲートを実行する:
npx hyperframes checkを実行します。これにより、ブラウザを開く前にlintが再実行されます。冗長なスタンドアロンのlint呼び出しを前置しないでください。--snapshotsを追加すると、注釈付きの概要フレームとクロップ領域の特定が可能です。 - サブコンポジションの検査:
index.htmlがdata-composition-srcをマウントする場合、中間点のスナップショットをキャプチャし、マウントされた各シーンを検査します。 - 最終スタジオプレビューを開く:
npx hyperframes previewを実行し、タイムラインプロジェクトURLをユーザーに渡し、修正するかレンダリングするかを尋ねます。 - 承認後にのみレンダリングする: 反復にはドラフト品質、納品には高品質を使用します。
- 出力を確認する: ファイルが存在し、空でなく、妥当な長さであることを確認します。
# 高速な反復チェック。作成中に必要に応じて繰り返します。
npx hyperframes lint
# 必須の最終ゲート。lintを含みます。
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check は最初にlintを実行し、次に1つのブラウザセッションと1回のシークパスを使用して、ランタイムエラー、失敗したリクエスト、レイアウト、*.motion.json アサーション、およびWCAGコントラストを監査します。永続的な(persistent)発見は終了コードに影響します。一時的な(transient)入口または出口の発見は情報提供のみです。警告をゲートするには --strict を使用します。validate、inspect、layout は互換性のためにエイリアスとして残されていますが、新しい指示やスクリプトには使用しないでください。
2つの異なるプレビュー画面
これらの状態を混同しないでください:
| 画面 | 開かれる条件 | 目的 |
|---|---|---|
| ストーリーボード | コンポジションチェック前、storyboard: yes の場合のみ | 計画カードとワイヤーフレームスケッチを確認します。?view=storyboard#project/<name> を開きます。 |
| 最終コンポジションプレビュー | check 合格後 | レンダリング前に組み立てられたタイムラインを確認します。#project/<name> を開きます。 |
初期のボードは最終ビデオの承認ではありません。レンダリングには常に、hyperframes-core/references/review-loop.md で定義された最終承認が必要です。
サブコンポジションスモークテスト
静的監査ではすべてのマウント障害を捕捉できるわけではありません。プロジェクトがサブコンポジションを使用する場合、各ホストスロットに対して少なくとも1つの可視中間点をキャプチャします:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
小さなスタイル未適用のコンテンツ、キャンバスサイズのアイコン、欠落したヒーロー要素、またはタイムライン登録のタイムアウトを、レンダリングをブロックするマウント不良として扱います。対応する修正については hyperframes-core/references/sub-compositions.md を参照してください。
エージェントの規約
-
エージェントおよびCI呼び出しでは
--jsonを優先します。サーバーモードのrender、preview、playは通常のJSON出力を提供しません。preview --selection --jsonおよびpreview --context --jsonはクエリモードの例外です。 -
doctor --jsonは常にゼロで終了します。そのペイロードでゲートします:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
非TTYモードは自動です。
initではそこに--exampleが必要です。TTY上で決定論的な動作を強制するには--non-interactiveを使用します。 -
同じ検証ループ内のすべてのコマンドには1つの
HYPERFRAMES_RUN_IDを使用します。 -
対応する警告、変数、またはCI条件がレンダリングをゲートする必要がある場合は、
--strict、--strict-all、--strict-variablesを使用します。 -
JSONパスはホームディレクトリを
$HOMEとして秘匿します。秘匿を解除しようとしないでください。 -
チェックが通ったからといってレンダリングしてはいけません。最終プレビューで一時停止し、承認を待ちます。
スタジオ経由の編集
ユーザーが「この要素」や現在の選択について言及した場合、推測する代わりにスタジオに問い合わせます:
npx hyperframes preview --context --json --context-fields selection
利用可能な場合は selection.target.hfId を、それ以外の場合はそのセレクタとソースファイルを使用します。結果が no-selection を報告した場合は、ユーザーに要素をクリックして再実行するよう依頼します。必要なコンテキストスライスのみを要求し、--context-detail full は計算済みスタイルや編集可能なテキストメタデータにのみ使用します。完全な動作と障害コードは references/preview-render.md にあります。
レンダリングの選択肢
| ニーズ | コマンド |
|---|---|
| 高速なローカル反復 | npx hyperframes render --quality draft |
| 最終ローカル納品 | npx hyperframes render --quality high --output out.mp4 |
| 再現可能なコンテナレンダリング | npx hyperframes render --docker --strict --output out.mp4 |
| ローカル変数駆動バッチレンダリング | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGenホスト型ゼロインフラレンダリング | npx hyperframes cloud render |
| 自己管理型分散AWSレンダリング | npx hyperframes lambda render <project> --width 1920 --height 1080 --wait |
| 自己管理型分散GCPレンダリング | npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait |
ユーザーがローカルのChrome、FFmpeg、AWSなしでホスト型レンダリングを希望する場合は、クラウドレンダリングを使用してください。AWSの所有権が要件である場合にのみLambdaを使用します。GCPの所有権が要件である場合にのみCloud Runを使用します。クラウドパスを実行する前に、対応するリファレンスを読んでください。
レンダリングの成功を確認した後、テレメトリが無効になっていない限り、またはユーザーがオプトアウトしない限り、1つのフィードバックレポートを送信します:
npx hyperframes feedback --rating <0-10> --comment "<具体的な結果または問題点>"
正常実行のフィードバックは簡潔に保ちます。バグや問題がある場合は、送信前に再現パケットをキャプチャします。症状の概要のみを送信しないでください。再実行可能なコマンドと作業ディレクトリ、期待される動作と実際の動作、正確なエラー、出力が完了したか/フォールバックしたか/失敗したか、回避策、再現プロジェクトのステータスを含めます。問題が再現しなかった場合はその旨を述べ、それでも最後に失敗したコマンドとログを含めます。--file-issue は同意がある場合にのみ使用します。同意がある場合、最小限の再現コードを公開URLに公開します。必須のパケット形式とプライバシー警告は references/preview-render.md にあります。
コマンドを実行する前に対応するリファレンスを読む
以下のリファレンスと所有スキルは必須のコマンド契約であり、オプションの背景資料ではありません。表のコマンドを実行する前に、対応する行を読んでください。
| ニーズ | リファレンス |
|---|---|
init、capture、skills | references/init-and-scaffold.md |
lint、check、モーションサイドカー、snapshot | references/lint-validate-inspect.md |
compare、grade-compare、変数駆動 render --batch | references/compare-and-batch.md |
既存プロジェクトのスタジオビートグリッド用 beats | references/beats.md |
preview、play、render、publish、スタジオコンテキスト、フィードバック | references/preview-render.md |
doctor、ブラウザ管理 | references/doctor-browser.md |
auth、HeyGenホスト型クラウドレンダリング、テンプレート変数 | references/cloud.md |
| AWS Lambda デプロイとレンダリング | references/lambda.md |
| Google Cloud Run デプロイとレンダリング | references/cloudrun.md |
info、upgrade、compositions、docs、benchmark、テレメトリ、メディア前処理 | references/upgrade-info-misc.md |
コンポジション変数については、/hyperframes-core → references/variables-and-media.md も読んでください。hyperframes add および hyperframes catalog については、/hyperframes-registry を使用します。hyperframes present の前は /slideshow を、hyperframes keyframes の前は /hyperframes-keyframes を読んでください。TTS、文字起こし、キャプション、または背景除去の選択肢については、/media-use を使用します。
専門コマンドは、それぞれの所有ワークフローによって意図的に文書化されています:
npx hyperframes present <project-dir> --port 3004 --no-open
npx hyperframes beats <project-dir> --json
npx hyperframes keyframes <project-dir> --json
present はプレゼンターと観客の同期を備えたナビゲーション可能なデッキを提供します。beats は references/beats.md で定義されたスタンドアロンのスタジオビートグリッドユーティリティです。keyframes はシークセーフなアニメーションおよびモーションパスの診断を提供します。