HyperFrames CLI
コマンドは、プロジェクトの指示にラッパーが指定されていない限り、npx hyperframes ... として実行してください。ラッパーがある場合はそれに従ってください。この CLI には Node.js 22 以降と FFmpeg が必要です。
開発ループ
- Scaffold:
npx hyperframes init <project>またはサイトをキャプチャします。TTY 以外のモードでは、--non-interactive --example=<name>を渡します。 - 動作を見つける: 手動でモーションを作成する前に、既に目的の動作を実現するプリミティブを検索します:
npx hyperframes catalog --query "readline one line at a timeにヘッドラインを表示"。頭にあるメカニズムではなく、実現したいエフェクトを指定してください。npx hyperframes add <name>でインストールします（/hyperframes-registryを参照）。何も適切なものが見つからない場合のみ、手動で作成します。 - 作成:
/hyperframes-coreを使用してコンポジションを記述します。 - 編集中の高速フィードバックを得る: 最初の HTML パス後、および構造変更後に
npx hyperframes lintを実行します。 - 最終ゲートを実行する:
npx hyperframes checkを実行します。これはブラウザを開く前に lint を再実行します。冗長な独立した lint 呼び出しを前置しないでください。注釈付きの概要フレームとクロップ検出のために--snapshotsを追加します。 - サブコンポジションを検査する:
index.htmlがdata-composition-srcをマウントする場合、中間点のスナップショットをキャプチャし、マウントされた各シーンを検査します。 - 最終 Studio プレビューを開く:
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 コントラストを監査します。永続的な問題は終了コードをゲートします。一時的な entrance または exit の問題は情報提供です。--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 を参照してください。
エージェント規約
-
モーションを手動で記述する前にカタログを検索してください。
npx hyperframes catalog --query "<ビートを平易な言葉で>"。検索は完全にローカルです: ホスト型ティアはなく、アカウントも不要で、クエリテキストがどこかに送信されることもありません。デフォルトでは、アイテムの名前、タイトル、説明と共有される語彙でランク付けされるため、カタログ自身の表現を再利用しないフレーズは見逃されます。代わりに意味でランク付けするには--on-deviceを追加します（以下のオフラインティアを参照）。 -
どのティアが回答したかを読んでください。結果が表示されたことから推測しないでください。
--jsonを使用すると、エンベロープにはquery、tier（on-deviceまたはwords）、tier_detail、dropped、unindexed、shown、total、resultsに加えて、回答ティアが生成する場合はtop_score、ティアが要求されたが実行できなかった場合はwarningsが含まれます。wordsでの弱い結果は予想通りです。on-deviceでの同じ結果はバグです。top_scoreはオンデバイスのみで、背後にしきい値はありません: ランカーはすべてのクエリに対してカタログ全体を何らかの順序で返すため、合格または不合格としてではなく、証拠として読み取ってください。 -
droppedとunindexedはレジストリとオンデバイスインデックスの間の逆の歪みであり、クエリを言い換えてもどちらも修正されません。droppedは、このレジストリがインストールできないランク付けされた名前をカウントするため、最も強い一致が失われていることを意味します。unindexedは、インデックスがまったく認識できないレジストリの移動をカウントするため、どのクエリでも返すことはできません。レジストリのリフレッシュはいずれの解決策でもありません: そのマニフェストは24時間のTTLを持ち、自己修復します。一方、ベクトルは個別に公開されたアーティファクトであり、~/.hyperframes/catalog/にフェッチされます。unindexedがゼロより大きい場合、--on-deviceを再実行するとそのインデックスが再フェッチされるため、ユーザーに提示する救済策はこれです。純粋なオーバーカバレッジの歪み（droppedがゼロより大きくunindexedがゼロ）は再フェッチをトリガーしません。~/.hyperframes/catalog/をクリアすることが唯一の解決策です。どちらのカウントも結果ではなく名前のカウントであるため、totalを超える可能性があります。 -
意味検索でインストールする価値のあるものが何も返ってこなかった場合は、その旨を伝えてください。
npx hyperframes feedback --search-miss "<実行したクエリ>" --wanted "<必要だった動作>" --tier on-device。これはクエリをどこかに送信する唯一のパスであり、catalog --queryが何も送信しないという約束を守るために、まさに別個の意図的なコマンドです。オンデバイスティアが回答し、トップヒットが依然として目的の動作を実行しない場合にミスを報告してください。wordsティアでの弱い結果は予想通りであり、報告する価値はありません。返されるのは、カタログにまだない動作のリストであり、インストール数から推測されるのではなく直接読み取られるため、重要なのは、想像したアイテム名ではなく、必要だったエフェクトの表現です。評価は含まれず、評価指標に記録されることもありません。 -
オフラインティアを提案してください。決してサイレントに有効にしないでください。 約33 MBの 1 回限りのダウンロード（
bge-small-en-v1.5の量子化 ONNX ビルドとそのトークナイザー、固定リビジョンにピン留め）とレジストリからのカタログベクトルで、両方とも~/.hyperframes/の下にキャッシュされ、プロジェクトやパッケージには追加されません。キャッシュされると、何も送信せずに意味でランク付けされます。サイズを声に出して伝え、ユーザーに決定を委ね、同意が得られたら--on-device（プロンプトをスキップするために-yを付ける）を渡します。インタラクティブな提案は TTY でのみ発火し、--jsonの下では何も出力されないため、エージェント実行では自分でユーザーに提起する必要があります。 -
エージェントおよび 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として秘匿します。秘匿を元に戻そうとしないでください。 -
ホスト型クラウドプロジェクトが200 MBのアップロード制限に近づいているか超えている場合は、
cloud render --dry-run --jsonを使用し、references/cloud.mdの.hyperframesignore調査に従ってください。アセットが大きいという理由だけで無視しないでください。 -
チェックが通過したという理由だけでレンダリングしないでください。最終プレビューで一時停止し、承認を待ちます。
Studio 指示編集
ユーザーが「この要素」または現在の選択範囲に言及した場合、推測する代わりに Studio にクエリします:
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 |
スキル属性は自動的です。上記の例には --skill は必要ありません。ワークフロー（hyperframes init --skill=<workflow>）によってスキャフォールドされたプロジェクトは、その所有スキルを hyperframes.json に記録し、その後のすべてのレンダリング（再レンダリング、npm run render、--batch など）は匿名テレメトリでそれを継承します。--skill=<slug> を明示的に渡すのは、ワークフローを介して作成されなかったプロジェクトにスタンプする場合のみです（最初のレンダリングで永続化されます）。
ユーザーがローカルの Chrome、FFmpeg、AWS なしでホスト型レンダリングを希望する場合は、クラウドレンダリングを使用します。AWS の所有権が要件の場合のみ Lambda を使用します。GCP の所有権が要件の場合のみ Cloud Run を使用します。クラウドパスを実行する前に、対応するリファレンスを読んでください。
レンダリングの成功を確認した後、テレメトリが無効化されていない限り、またはユーザーがオプトアウトしていない限り、1つのフィードバックレポートを送信します:
npx hyperframes feedback --rating <0-10> --comment "<具体的な結果または摩擦>"
クリーンラン時のフィードバックは簡潔にしてください。バグや摩擦については、送信前に再現パケットをキャプチャしてください。症状の要約のみを送信しないでください。再実行可能なコマンド（プロジェクトディレクトリからの相対パス。フィードバックは公開チャネルに送信されるため、絶対パス、ホームディレクトリプレフィックス、ユーザー/マシン識別子は貼り付けないでください）、期待される動作と実際の動作、正確なエラー（スタックトレースからも絶対パスを削除し、ベース名 + 行番号を保持し、先頭のディレクトリを削除）、出力が完了/フォールバック/失敗したかどうか、回避策、再現プロジェクトのステータスを含めてください。視覚的な欠陥（黒フレーム、ちらつき、破損出力、間違ったフレーム、空白出力、その他の視覚的異常）を説明する評価 ≤ 7 の場合は、COMPOSITION_STRUCTURE: ブロックも含めてください。これはプライバシーを保護する構造的詳細（要素の種類と数 + 属性の有無 + タイムラインの形状）であり、メンテナーがコンポジション ZIP なしで既知のバグファミリーとパターンマッチングできるようにします。エージェントは composition-census ヘルパーを介してこれを自動入力します。人間のユーザーは手動で記入しません。問題が再現しなかった場合は、その旨を記載し、それでも最後の失敗コマンドとログを含めてください。--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 |
既存プロジェクトの Studio ビートグリッド用 beats | references/beats.md |
preview、play、render、publish、Studio コンテキスト、フィードバック | 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 |
コンポジション変数の場合、al
…
[翻訳のために一部省略]