プラグインインストール: セットアップまたはフレッシュネスコマンドの前に、このスキルが HyperFrames プラグイン内にある場合はプラグイン実行ルールに従ってください。スタンドアロンインストールでは以下の更新手順を維持します。
HyperFrames CLI
プロジェクトの指示にラッパーが指定されていない限り、コマンドは npx hyperframes ... として実行します。ラッパーがある場合はそれに従います。CLI には Node.js 22 以降と FFmpeg が必要です。
開発ループ
- スキャフォールド:
npx hyperframes init <project>（中央揃えの空白）。またはサイトをキャプチャします。名前付きの例から開始する場合にのみ--example=<name>を渡します。 - ムーブを見つける: リクエストがアセット、サウンド、画像、音声、または高速なビジュアル編集を指定している場合は、計画を提案する前に
/media-useを通じて解決します。それ以外の場合、手動でモーションを作成する前に、すでにそれを実行するプリミティブを検索します:npx hyperframes catalog --query "見出しを一度に1行ずつ表示する"。頭にあるメカニズムではなく、望むエフェクトを尋ねてください。npx hyperframes add <name>でインストールします（/hyperframes-registryを参照）。何も適合しない場合にのみ手動で作成します。 - オーサリング:
/hyperframes-coreを使用してコンポジションを記述します。プロジェクトのタイムライン（トラック、クリップ、開始、終了、再生内容）を知るには、index.htmlとすべてのサブコンポジションファイルを読む代わりに、npx hyperframes timeline --jsonを実行します。ネストされた行は、絶対メインタイムラインのabsStart/absEndと、それらが属するfileを持ちます（ローカルなサブコンポジションごとの時間だけではありません）。テキスト形式よりも--jsonを優先します。同じかより良い正確性でより少ないトークンで済みます。よくある質問に答えるワンライナーについてはreferences/upgrade-info-misc.mdを参照してください。全体を読む必要はありません。 - 編集中の高速フィードバック: 最初の HTML パス後および構造変更後に
npx hyperframes lintを実行します。 - 最終ゲートを実行:
npx hyperframes checkを実行します。これは lint を再実行してからブラウザを開きます。冗長なスタンドアロン lint 呼び出しを前置しないでください。--snapshotsを追加すると、注釈付きの概要フレームとクロップ検出ができます。 - サブコンポジションの検査:
index.htmlがdata-composition-srcをマウントする場合、中間点のスナップショットをキャプチャし、マウントされた各シーンを検査します。 - 最終スタジオプレビューを開く:
npx hyperframes preview --backgroundを実行し、URL が HTTP 200 を返すことを確認し、タイムラインプロジェクトの URL をユーザーに渡し、修正するかレンダリングするかを尋ねます。レビューが終了するまで起動したままにします。 - 承認後にのみレンダリング: イテレーション中は
--quality draft、最初の本番エンコード（CLI デフォルト）では--quality looks、最終納品では--quality deliveryを使用します。 - 出力を検証: ファイルが存在し空でないことを確認します。レンダリングサマリーの2行目（
beginframevsscreenshot、GPU、ステージタイミング）を読みます。screenshot+software gpuは Linux の低速パスです。ffprobe -v error -show_format -show_streamsを実行し、ルートのdata-durationと継続時間（および指示に fps があればそれ）を比較します。
ターン内のプロジェクト履歴
プロジェクトへのすべての書き込みは、元に戻せるエントリとして保存されます。毎ステップではなく、次の2つの瞬間にのみ使用します:
- ターンの開始:
npx hyperframes history begin --who <your-name> --label "<これから行うこと>"、次にnpx hyperframes history --since mine --who <your-name>で、前回のターン以降にその人物が変更した内容を確認します。彼らの編集を基に構築し、上書きしないでください。 - チェックに失敗した、またはユーザーが悪化したと言った場合:
npx hyperframes history undo --who <your-name>は最新のターンを元に戻し、その人物の編集はそのままにします。手動で戻さないでください。競合があった場合は exit 2 で終了し、両方の選択肢を表示します。
各ターンの終わりに npx hyperframes history end を実行して、自分の書き込みが「アプリ外で変更」ではなく自分のものとして記録されるようにします。ターンが開いている間は、プロジェクトへのすべての書き込みが10分間続けて行われなければ自分のものとみなされ、その後ターンは自動的に終了します。
必須のクリエイター編集相互参照
- ズーム、パンチイン/アウト、リフレーム、カメラ移動、または任意のキーフレームモーションを作成または診断する前に、まず
/hyperframes-keyframesを読んでください。 hyperframes keyframesの前に/hyperframes-keyframesを読んでください。このコマンドはアニメーショントラジェクトリを表示し、クリップカットを診断しません。- カット、トリム、スプライス、並べ替え、またはソースタイミング編集については、
/hyperframes-coreを読み、そのクリップ/タイムライン契約を使用します。 - フェードイン/アウト、クロスフェード、トラックゲイン、ボリュームオートメーション、ダッキング、ナレーションカーブ、または配置されたオーディオへの FX については、
/hyperframes-audioを読んでください。クリップ配置やピクチャタイミングも変更する場合は、同時にコアも読み込んでください。 - アセット、サウンド、画像、音声、または高速なビジュアル編集を指定するリクエストは、計画が提案される前に
/media-useを通じて解決します。/hyperframes-core→references/creator-editing-recipes.mdからクリエイター編集マークアップをコピーしてください。
# 高速イテレーションチェック; オーサリング中に必要に応じて繰り返し実行。
npx hyperframes lint
# 必須の最終ゲート; lint を含む。
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4
check は最初に lint を実行し、次に1つのブラウザセッションと1回のシークパスを使用して、ランタイムエラー、失敗したリクエスト、レイアウト、*.motion.json アサーション、および WCAG コントラストを監査します。永続的な問題は終了コードをブロックします。一過性のエントランス/イグジットの問題は情報提供のみです。--strict を使用して警告をブロックします。validate、inspect、layout は互換性のためにエイリアスとして残っていますが、新しい指示やスクリプトに現れてはいけません。
レンダリング前のプレビュー
check が合格した後でのみ、最終コンポジションプレビュー（#project/<name>）を開いて、組み立てられたタイムラインを確認します。チャットでの計画や storyboard.html スケッチシートは最終ビデオの承認ではありません。レンダリングには常に hyperframes/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は on-device のみで、背後にしきい値はありません: ランカーはすべてのクエリに対してカタログ全体を何らかの順序で返すため、合格/不合格としてではなく証拠として読んでください。 -
droppedとunindexedはレジストリとオンデバイスインデックスの間の逆の偏りであり、クエリの言い換えではどちらも修正できない。droppedはこのレジストリがインストールできないランク付けされた名前をカウントするため、最も強い一致が失われています。unindexedはインデックスがまったく見えないレジストリのムーブをカウントするため、どのクエリも決して返せません。レジストリの更新はどちらへの答えでもありません。そのマニフェストには24時間の TTL があり自動修復します。一方、ベクターは別途公開されたアーティファクトであり、~/.hyperframes/catalog/にフェッチされます。--on-deviceで再実行すると、unindexedが0より大きい場合にそのインデックスを再フェッチするため、それがユーザーに提供する救済策です。純粋な過カバレッジの偏り（droppedが0より大きくunindexedが0）は再フェッチをトリガーしません。その場合、~/.hyperframes/catalog/をクリアするのが唯一の方法です。両方のカウントは名前の数であり結果の数ではないため、どちらもtotalを超える可能性があります。 -
検索でインストールする価値のあるものが何も返ってこなかった場合は、その旨を伝えること。
npx hyperframes feedback --search-miss "<実行したクエリ>" --wanted "<必要だったムーブ>" --tier <回答したティア>。この行を自分で組み立てる必要はありません:catalog --queryはプリフィルされた形で表示し、すべての--json検索エンベロープはreport_gapとしてクエリとティアを正しく保持します。--wantedを入力して送信してください。これはクエリをどこかに送信する唯一のパスであり、平文のcatalog --queryが何も送信しないという約束を守るために、まさに別個の意図的なコマンドになっています。どちらのティアでも報告してください。 結果が目的の動作をしない場合は常に、オンデバイスティアのために待たないでください。オンデバイスティアは同意が必要な33MBのダウンロードを必要とし、ほとんどのエージェント実行ではオフになっています。待っていると決して報告されません。ティアはレポートに含まれるため、語彙ミスと意味ミスは、どちらに当たったかを自分で判断しなくても区別できます。返ってくるのは、カタログがまだ持っていないムーブのリストであり、インストール数から推測されるのではなく直接読まれるため、重要なのは想像したアイテム名ではなく、必要なエフェクトの表現です。評価は含まれず、評価メトリックに決して送られません。 -
オフラインティアを提供するが、黙って有効にしないこと。 一回限りの約33MBのダウンロード（
bge-small-en-v1.5の量子化 ONNX ビルドとそのトークナイザー、固定リビジョンにピン止め）とレジストリからのカタログベクターは、どちらも~/.hyperframes/の下にキャッシュされ、プロジェクトや任意のパッケージには追加されません。一度キャッシュされると、何も送信せずに意味でランク付けされます。サイズを声に出して伝え、ユーザーに決定させ、同意が得られたら--on-device（プロンプトをスキップするために-yを付けて）を渡します。対話型の提供は TTY でのみ発動します。--jsonの下ではプロンプトはありませんが、何も見つからなかった検索は同じ質問をwarningsに置くため、その配列を読み、ユーザーに自分で決断を委ねてください。ユーザーがダウンロード内容、このモデルが選ばれた理由、またはマシンから何が送信されるかを尋ねた場合は、https://hyperframes.heygen.com/developers/catalog-search を参照するよう指示してください。 -
エージェントおよび CI 呼び出しでは
--jsonを優先します。サーバーモードのrender、preview、playは通常の JSON 出力を提供しません。preview --selection --jsonとpreview --context --jsonはクエリモードの例外です。 -
doctor --jsonは常にゼロで終了します。そのペイロードでゲートしてください:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
非 TTY モードは自動で、中央揃えの空白をスキャフォールドします。名前付きの例から開始する場合にのみ
--exampleを渡します。TTY でフラグのみのモードを強制するには--non-interactiveを使用します。 -
同じ検証ループ内のすべてのコマンドに1つの
HYPERFRAMES_RUN_IDを使用します。 -
ディスク容量が少ない場合、
npx hyperframes cleanを実行します（--dry-runで一覧表示）。デッドレンダリングが残したものと、自己再構築するアイドルキャッシュを削除しますが、出力、ソース、実行中のレンダリングが使用するものは決して削除しません。QC フレームはプロジェクトではなく一時ディレクトリに書き込みます。 -
対応する警告、変数、または CI 条件がレンダリングをゲートする必要がある場合は、
--strict、--strict-all、--strict-variablesを使用します。 -
JSON パスはホームディレクトリを
$HOMEとして編集します。編集を元に戻そうとしないでください。 -
ホストされたクラウドプロジェクトが200MBのアップロード制限に近づく、または超える場合は、
cloud render --dry-run --jsonを使用し、references/cloud.mdの.hyperframesignore調査に従ってください。アセットが大きいという理由だけで無視しないでください。 -
チェックが通ったからといってレンダリングしないでください。最終プレビューで一時停止し、承認を待ってください。
スタジオ指示による編集
ユーザーが「この要素」や現在の選択を参照する場合、推測する代わりにスタジオに問い合わせます:
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 looks --output out.mp4 |
| 最終ローカル納品 | npx hyperframes render --quality delivery --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 l |