プラグインインストール: セットアップまたはフレッシュネスコマンドの前に、このスキルが HyperFrames プラグイン内にある場合は、プラグイン実行ルール に従ってください。スタンドアロンインストールの場合は、以下の更新手順を維持してください。
HyperFrames CLI
プロジェクトの指示でラッパーが提供されている場合を除き、コマンドは npx hyperframes ... として実行します。ラッパーが存在する場合はそれに従ってください。CLI には Node.js 22 以降と FFmpeg が必要です。
開発ループ
- スキャフォールディング:
npx hyperframes init <project>(中央揃えの空白)。またはサイトをキャプチャします。名前付きの例から開始する場合のみ--example=<name>を渡します。 - 適切なアクションを見つける: リクエストがアセット、サウンド、画像、音声、または高速ビジュアル編集を指定している場合は、計画を提案する前に
/media-useを通じて解決します。それ以外の場合、手動でモーションを作成する前に、それをすでに実行するプリミティブをカタログから検索します:npx hyperframes catalog --query "見出しを一度に一行ずつ表示する"。頭の中にあるメカニズムではなく、必要なエフェクトを指定してください。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をマウントする場合、中間点のスナップショットをキャプチャし、マウントされた各シーンを検査します。 - 最終的な Studio プレビューを開く:
npx hyperframes preview --backgroundを実行し、URL が HTTP 200 を返すことを確認し、タイムラインプロジェクトの URL をユーザーに渡し、修正するかレンダリングするかを尋ねます。レビューが終了するまでプレビューを維持します。 - 承認後にのみレンダリング: イテレーション中は
--quality draftを、最初の実際のエンコード(CLI デフォルト)には--quality looksを、最終納品には--quality deliveryを使用します。 - デスクトップアプリにプロジェクトを渡す(提供時): レンダリングの Framey 行が
hyperframes open …で終わる場合、npx hyperframes open [dir]を提供します。これによりプロジェクトが HyperFrames デスクトップアプリで開かれ、ホームに追加されます。Claude Code または Codex 下では、そのチャットがこの会話を引き継ぎます。アプリがない場合は終了コード 1 で終了し、ダウンロードリンクを出力します。エージェント用には--json。 - 出力を確認する: ファイルが存在し、空でないことを確認します。レンダリングサマリーの 2 行目(
beginframevsscreenshot、GPU、ステージタイミング)を読みます。Linux 上のscreenshot+software gpuは低速パスです。ffprobe -v error -show_format -show_streamsを実行し、ルートのdata-durationと期間(およびブリーフで設定されている場合は fps)を比較します。
ターン内のプロジェクト履歴
プロジェクトへのすべての書き込みは、元に戻せるエントリとして保持されます。すべてのステップではなく、以下の 2 つの瞬間にのみ使用します:
- ターンの開始:
npx hyperframes history begin --who <あなたの名前> --label "<これから行うこと>"、その後npx hyperframes history --since mine --who <あなたの名前>を実行して、前回のターン以降にその人が変更した内容を確認します。その人の編集を基に構築し、上書きしないでください。 - チェックが失敗した、またはその人が状況が悪化したと言った場合:
npx hyperframes history undo --who <あなたの名前>は最新のターンを元に戻し、その人の編集はそのままにします。手動で編集を戻さないでください。競合が発生した場合は終了コード 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 は互換性のためにエイリアスとして残りますが、新しい指示やスクリプトに表示してはなりません。
レンダリング前のプレビュー
最終コンポジションプレビュー(#project/<name>)は、check が成功した後にのみ開き、組み立てられたタイムラインを確認します。チャット内の計画と 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を追加します(以下のオフラインティアを参照)。 -
ビデオの言語に関係なく、英語でクエリを実行してください。 両方のティアが英語のカタログをインデックスしているため、別のスクリプトのクエリは検索可能な用語を生成せず、何も返しません。ムーブを英語で説明してください。画面上のコピーはビデオに必要な言語のままです。
No searchable words in queryはまさにこの状態を意味し、コンポーネントの欠落ではないため、カタログのギャップとして報告しないでください。 -
どのティアが回答したかを読み取ってください。結果が表示されたからといって推測しないでください。
--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/にフェッチされる別途公開されたアーティファクトです。unindexedがゼロより大きい場合、--on-deviceを再実行するとそのインデックスが再フェッチされるため、それがユーザーに提供する解決策です。純粋な過カバレッジの偏り(droppedがゼロより大きくunindexedがゼロ)は再フェッチをトリガーしません。~/.hyperframes/catalog/をクリアすることが唯一の解決策です。どちらのカウントも結果ではなく名前のカウントであるため、どちらもtotalを超える可能性があります。 -
検索結果にインストールする価値のあるものが何もない場合は、そう伝えてください。
npx hyperframes feedback --search-miss "<実行したクエリ>" --wanted "<必要なムーブ>" --tier <回答したティア>。この行を自分で組み立てる必要はありません。catalog --queryは事前に入力された状態でそれを出力し、すべての--json検索エンベロープはreport_gapとしてクエリとティアがすでに正しい状態でそれを運びます。--wantedに入力して送信してください。これがクエリをどこかに送信する唯一のパスであり、プレーンなcatalog --queryが何も送信しないという約束を守るために、正確に別個の意図的なコマンドです。結果が期待した動作をしない場合は、どちらかのティアで報告してください。 オンデバイスティアは同意が必要な 33 MB のダウンロードを必要とするため、ほとんどのエージェント実行ではオフになっています。それを待つことは、決して報告しないことを意味します。ティアはレポートに含まれるため、語彙のミスと意味のミスは、どちらに当たったかを自分で判断する必要なく区別可能です。返ってくるのは、カタログにまだないムーブのリストであり、インストール数から推測されるのではなく直接読み取られるため、重要なフレーズは想像したアイテム名ではなく、必要としたエフェクトです。評価は含まれず、評価指標に登録されることもありません。 -
オフラインティアを提供してください。ただし、静かに有効にしないでください。 約 33 MB の 1 回限りのダウンロード(
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として編集します。編集を元に戻そうとしないでください。 -
ホスト型クラウドプロジェクトが 200 MB のアップロード制限に近づいているか超えている場合は、
cloud render --dry-run --jsonを使用し、references/cloud.mdの.hyperframesignore調査に従ってください。アセットが大きいという理由だけで無視しないでください。 -
チェックが通ったからといってレンダリングしないでください。最終プレビューで一時停止し、承認を待ってください。
スタジオ指示による編集
ユーザーが「この要素」または現在の選択を参照する場合は、推測する代わりに 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 looks --output out.mp4 |
| 最終ローカル納品 | npx hyperframes render --quality delivery --output out.mp4 |
| 再現可能なコンテナレンダリング | `npx hyperframes render -- |