Communitygithub.com

simpletibr/simplicio-loop-marketing

HyperFrames CLI 開発ループを実行します。init、lint、inspect、preview、render の各コマンドを、`hyperframes` スキルで作成された作品に対して実行します。HTML コンポジションがディスクに書き込まれた後、作品完了とマークされる前に呼び出されます。

simplicio-loop-marketing とは?

このスキルは、マーケティングエンジンパイプライン向けの HyperFrames CLI (`npx hyperframes`) ラッパーです。Node.js 22 以上と FFmpeg が必要で、環境確認は `npx hyperframes doctor` で行います。`lint`、`inspect`、`preview`、`render` の各モードで構成され、デフォルトでは DRY_RUN-safe モードで動作します(`render` のみ MP4 出力)。`lint` と `inspect` でコンポジションの品質を検証し、問題があれば修正または `data-layout-allow-overflow` 等で要素単位で許可します。`render` では `--quality`(draft/standard/high)、`--fps`、`--variables` など細かなオプションを指定可能で、最終納品時は `--quality high` が必須です。render 完了後は出力ファイルの存在確認と、`data/video-usage.jsonl` へのログ記録を行います。構成ファイル (`composition.json`) の変数宣言との不一致は `--strict-variables` で厳密にチェックされ、エラーは必ず失敗として報告されます。このスキルは `hyperframes`、`hyperframes-prompt-builder`、`qa-tech-specs` と連携し、マーケティングビデオ生成パイプラインの中核を担います。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/hyperframes-cli

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

HyperFrames CLI

マーケティングエンジンパイプライン向けの npx hyperframes ラッパー。Node.js 22 以上と FFmpeg が PATH に必要です(npx hyperframes doctor で確認)。すべてのコマンドはデフォルトで DRY_RUN セーフモードで実行されます。lint/inspect パスは外部呼び出しを行いません。render のみ MP4 を書き込みます。

呼び出しタイミング

  • hyperframes-prompt-builder が outputs/<client>/<date>/<piece-id>/ 以下にプロジェクトを生成した直後。
  • コンポジションを公開前に検証する必要がある場合(lint + inspect)。
  • 作品の反復作業中にローカルプレビューを行う場合(preview)。
  • 公開ステップで受け取る成果物を生成する最終レンダリング時(render)。
  • レンダリングが失敗した場合の環境トラブルシューティング時(doctor、browser、info)。

入力

  • project_path: 文字列。HyperFrames プロジェクトへのパス(index.html と composition.json が含まれている必要があります)。
  • mode: "lint" | "inspect" | "preview" | "render" | "doctor"。
  • render_opts: オブジェクト、オプション、mode = "render" の場合のみ。認識されるキー:
    • fps: 24 | 30 | 60(デフォルト 30)。
    • quality: "draft" | "standard" | "high"(デフォルト "standard"。反復作業中は "draft" を使用)。
    • format: "mp4" | "webm"(デフォルト "mp4")。
    • variables: オブジェクト。変数 ID をキーとする JSON オブジェクトで、data-composition-variables のデフォルトを上書きします。
    • strict: ブール値。--strict にマッピング。パイプラインではデフォルト true — lint エラーでレンダリングを失敗させます。
    • strict_variables: ブール値。--strict-variables にマッピング。作品実行ではデフォルト true。
    • workers: 整数 1〜8 または "auto"。デフォルト "auto"。
    • output: 文字列。outputs/<client>/<date>/<piece-id>/ 内の出力ファイルパス。

処理手順

  1. 環境確認 セッションの初回実行時:npx hyperframes doctor。FFmpeg または Chrome が不足している場合はハードブロックとして表示 — レンダリングを試行しない。
  2. Lint。 npx hyperframes lint <project_path> --json。error レベルのすべての検出結果をブロッカーとして扱う。警告はオーケストレーターに通知;オペレーターに判断させる。
  3. Inspect。 npx hyperframes inspect <project_path> --json。レンダリング前に、報告されたテキストあふれやキャンバスエスケープを解決する。あふれが要素の出入りの意図的なものである場合、その要素に data-layout-allow-overflow を(または装飾要素の場合は祖先に data-layout-ignore を)マークする — ルールをグローバルに抑制しない。
  4. プレビュー(オペレーターのみ)。npx hyperframes preview <project_path> --port <port>。Studio プロジェクト URL(http://localhost:<port>/#project/<project-name>)を返す。ソースの index.html パスではない。
  5. レンダリング。 npx hyperframes render <project_path> を render_opts から解決されたフラグとともに実行。render_opts.variables から --variables 引数を単一行 JSON 文字列で構築する。作品実行では常に --strict と --strict-variables を渡す。
  6. 出力確認。 レンダリング後、MP4 が存在し、サイズがゼロでないことを確認する。data/video-usage.jsonl に { ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms } の形式でログを記録する。

出力

  • lint: { pass: ブール値, errors: [...], warnings: [...] }。
  • inspect: { pass: ブール値, findings: [...] }。
  • render: { artifact_path: 文字列, duration_s: 数値, file_bytes: 数値, render_ms: 数値 }。
  • preview: { url: 文字列 }。

コマンドチートシート

npx hyperframes init <name>                            # スキャフォールディング(プロンプトビルダーが各作品で1回使用)
npx hyperframes lint <path>                            # マークアップの検証
npx hyperframes inspect <path>                         # レイアウト/あふれの監査
npx hyperframes preview <path> --port 3017             # ローカル開発
npx hyperframes render <path> \
  --fps 30 --quality standard --strict --strict-variables \
  --variables '{"leads":42,"delta_pct":12}' \
  --output outputs/<client>/<date>/<piece-id>/final.mp4
npx hyperframes doctor                                 # 環境チェック
npx hyperframes info                                   # バージョン/環境詳細

非交渉ルール

  • lint と inspect のパスが合格していない状態でレンダリングを行わないこと。パイプラインには、不正な構成に対する回復パスはない。
  • lint または inspect の検出結果をグローバルに抑制しないこと — マークアップを修正するか、特定の要素を data-layout-allow-overflow / data-layout-ignore で許可リストに追加する。
  • 変数が宣言されている作品では、常に --strict-variables を渡すこと。変数 ID のタイプミスは静かにデフォルトにフォールスルーするのではなく、明確に失敗しなければならない。
  • 最終納品用レンダリングでは --quality high。反復ループでは --quality draft を使用して計算リソースを節約する。
  • アセットの前処理(tts、transcribe、remove-background)はこのスキルの範囲外 — 将来の hyperframes-media スキルを通じて呼び出し、ここにインライン化しない。

障害モード

  • doctor が FFmpeg または Chrome の不足を報告:プロジェクトのセットアップ手順に従ってインストールする;回避策をとらない。
  • render が unknown variable で失敗:--variables で渡されたキーが data-composition-variables で宣言されていない。マークアップを修正するか、上書きを削除する。
  • render が壁時間予算を超過:--quality を standard に下げるか、コンポジションをサブコンポジションに分割し、--workers で並列化する。
  • 出力 MP4 のサイズがゼロ:doctor を再実行;ほとんどの場合、キャプチャ中の Chrome クラッシュが原因。

関連スキル

  • hyperframes: コンポジション作成ルール;このスキルが検証・レンダリングするプロジェクトを生成する。
  • hyperframes-prompt-builder: ブリーフ → コンポジション仕様;このスキルの前に実行される。
  • qa-tech-specs: このスキルの後に、レンダリングされた MP4 に対して実行され、プラットフォーム仕様を検証する。

アップストリームリファレンス

すべてのフラグ、トラブルシューティングマトリックス、パラメータ化レンダリングを含む完全なアップストリームスキル:https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

関連スキル