1仕組みと動作原理
「デザイン主導のショートクリップ」（motion is the message）を志向しているため、ワークフローは自律モードに設定されています。確認の質問は最大1回（ディレクターの第1パート）にとどめ、その後は中間レビューを挟まずにビルドから検証まで一気に進めます。ユーザーによる承認ゲートはレンダリング時のみです。
skills/motion-graphics/SKILL.md
This workflow is **autonomous by design** — at most one clarifying question (`agents/director.md`), then build through verification without intermediate review.
ここでの処理内容: 多数のゲートやレビューを伴う product-launch-video / faceless-explainer とは異なり、短尺クリップでは絵コンテの作成や継続的なセッションの維持は費用対効果が低いと判断され、レビューは「プレビューかレンダリングか」という単一の判断のみに簡素化されています。
アセット優先（asset-first）: 先にアセット戦略を決定して実際の素材を取得し、その「手元にある素材」を軸にカットを設計した上で、最後にカタログの再利用可能なパーツを組み立てます。コードやテキストのみのカテゴリでは、素材取得ステップは完全にスキップされます。
skills/motion-graphics/SKILL.md
**Asset-first**: decide the asset strategy and source real material _before_ designing the shot, then design the shot around what you have, then compose by reusing catalog capabilities.
ここでの処理内容: 「デザインを決めてから素材を探す」という失敗しやすい順序を逆転させています。ステージテーブルには、該当カテゴリでアセットが必要と宣言されている場合にのみ `source ◇` が実行されることが明記されています（'Pure code/text categories (e.g. `kinetic-type`, most `charts`/`stat`) have `asset_needs: []` and skip straight from plan to design'）。
「検索が必要かどうか」でカテゴリが分岐します。フォーマット系（kinetic-type / stat / charts / logo-reveal / lower-thirds / maps）のコンテンツはユーザーから提供され、検索系（webpage / news / tweet / asset-fusion）は先に検索を行い、取得できたコンテンツの種類に応じてアニメーションを決定します。
skills/motion-graphics/SKILL.md
`plan`'s **first decision is: does this need a search?** That fork splits the categories into two groups; then the specific category is picked — for search-driven, **by the type of content the search returns**.
ここでの処理内容: 各カテゴリは `categories/<id>/module.md`（プランニング + ビルド規則）として独立しており、references/motion-vocabulary.md で語彙を共有しています。設計ノートには拡張方法として、フォルダを追加し、director.md にカテゴリ行を登録し、catalog-map.md に1行追加するだけで、パイプライン本体には手を加える必要がないことが記載されています。
ビルドは「再利用優先」に従います。まず `npx hyperframes add <block>` でカタログのコンポーネントを取得してその場でカスタマイズし、不足しているパーツや asset-fusion の独自の表現手法のみを手作業でコーディングします。
skills/motion-graphics/SKILL.md
**Reuse-first**: `npx hyperframes add <block>` + customize in place; hand-author only gaps + the asset-fusion affordance. Output `compositions/index.html` honoring the HF contract (paused GSAP timeline on `window.__timelines`, `class="clip"` + stable ids, `tl.seek(0)`, deterministic).
ここでの処理内容: 「LLMによるテンプレート生成」を「公式ブロックの組み合わせ + ルール」に置き換えており、Remotionエコシステムにおけるテンプレートに相当します。生成物はHyperframesが定めるGSAPタイムラインの一時停止制御、clipクラス、および決定論的契約を満たす必要があります。
座標指定はモデルの推測に頼らず、locate プロトコルを採用します。まずグリッドストリップによる離散選択を行い（ピクセル座標を直接回帰させるより遥かに高精度）、環境内に有効な検出器キーが存在する場合にのみ、1回呼び出しの auto パスを利用します。
skills/motion-graphics/grounding/PROTOCOL.md
Author models are unreliable at **regressing pixel coordinates** on a cluttered full image (measured: weak vision models ~16–24% center error → rings land off-target) but reliable at **picking a numbered strip** (~3–4% with the loop below). So: never eyeball coordinates; localize by discrete choice.
ここでの処理内容: ビジュアルグラウンディングを決定論的プロセス化しています: overlay（9×9ストリップ）→ region（詳細な6×6）→ final → mark（赤枠を描画して**画像上で視覚検証**）。失敗時は座標を推測するのではなく既知の方向に基づいて再試行します。auto パスの安全策として「**キーが存在すると決して仮定しないこと**。キーがなければ path 2 を使用する」と明記されています。
マップカテゴリのベースマップは、ヘッドレスChrome内で事前にMP4へ「ベイク」する必要があります。これは滑らかさのためではなく、Hyperframesがレンダリング時の外部通信を禁止し、決定論的出力を要求するためです（オンラインチルはレンダリングごとに内容が変わる可能性があるため）。
skills/motion-graphics/categories/maps/bake-basemap.mjs
// Why bake the imagery at all (this is the real reason, not "smoothness"): HF forbids render-time // network and requires deterministic output. Live raster tiles re-fetch every render and can change // → non-deterministic. Baking FREEZES the imagery into pixels = deterministic + offline-reproducible.
ここでの処理内容: スクリプトは puppeteer-core を介して MapLibre を制御し、カメラのズームとホールドを連番フレームとして録画するとともに、指定された国の境界線をスクリーン座標に投影して coords.json にエクスポートします。境界線、塗りつぶし、ラベルはHyperframes内の**リアルタイムSVG**レイヤーとして保持され、編集可能性が維持されます。全パラメータは環境変数（NAME/STYLE/CENTER/ZSTART/ZEND/FPS/DUR/COUNTRIES）で制御され、Chromeのパスは動的に解決されます。
検証フェーズでは「開始状態、キーアクション、最終フレームのホールド」の3つの証明モーメントを選択し、人間がコンタクトシートを目視確認します。失敗時の修正は1回限りのインプレース修復（finalizeサブエージェント）とし、再生時間を調整して不具合をごまかすことは禁止されています。
skills/motion-graphics/SKILL.md
Choose proof times that show the opening state, signature move, and final hold. Inspect the generated contact or snapshot sheet before continuing. On `lint`, `check`, or snapshot failure, dispatch the repair subagent (`agents/finalize.md`) for one in-place fix pass, then rerun the failed gate. Never change a fixed duration merely to hide a defect.
ここでの処理内容: 「修復は1度のみ」「尺調整によるごまかしの禁止」を明確なルールとし、Resumeテーブル（shot-plan.json がなければ plan へ、asset_needs があるのに assets/ がなければ source へ、index.html があるのにスナップショットがなければ verify へ…）を備えて中断からの再開をサポートしています。
2コア機能
01キネティックタイポグラフィ / 単一数値の統計 / チャートやデータの可視化 / ロゴアニメーションとブランドロックアップ / ローサードとソーシャルオーバーレイ
02アニメーションマップ（ベクターレーンまたはベイクドベースマップレーン。特定地域のハイライト、地点間の接続、特定地点へのズーム）
03検索駆動型表現: Webページ/UIアニメーション（スクロール、リビール、カーソル、コールアウト）、ニュースヘッドラインカード、ツイートカード、実画像の幾何学形状をチャートに融合する asset-fusion
04座標グラウンディングプロトコル（グリッドストリップ離散選択 + オプションの検出器高速パス + 枠線描画による自己検証）
05ベースマップの事前ベイク（MapLibre + ヘッドレスChrome → 連番フレーム + 国境のスクリーン座標出力）
06MP4または透過オーバーレイ出力（webm/mov）、および証明モーメントとコンタクトシートの生成
07中断からの再開（ディスク状態に応じたResumeテーブル）とカテゴリ拡張性（module.md の追加 + 2行の登録）
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | hyperframes CLI（init / doctor / add / lint / check / snapshot / preview / render / skills update） |
| cli | ffmpeg / ffprobe（探帧率与时长、抽帧、编码） |
| api | Google Generative Language API（可选的视觉检测快路径，仅在环境存在 key 时使用） |
| api | 可选图像生成 key（media-use resolve 的生成分支；未设置则只搜索或不生成） |
| network | 底图瓦片与矢量数据（仅在 maps 分类烘焙底图时联网；烘焙后离线可复现） |
| package | puppeteer-core + 无头 Chrome（底图烘焙录制） |
| network | GSAP CDN（示例资产 _ref-circle-highlight.html 引用） |
| package | 兄弟 skill 依赖（/media-use 的 resolve 与 search 提供者、/hyperframes-animation 的 rules/blueprints、/hyperframes-core 的 brief-contract、/figma） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: node grounding/locate.mjs overlay|region|final|mark|auto <img> …（ffmpeg/ffprobe を含む）
- 网络端点: 外部ネットワークアクセスの宣言: https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent
- 本地工作目录: ファイルの読み書きと成果物の出力: videos/<project>/hyperframes.json、context.log、shot-plan.json（IR）、composition.html
監査ノート： オレンジ判定（要確認）の2条件に該当しています: ① **認証情報/環境変数の読み取り** — grounding/locate.mjs が process.env.GEMINI_API_KEY を直接読み取り、URLクエリ文字列（`?key=${key}`）に埋め込んで generativelanguage.googleapis.com を呼び出しており、SKILL.md にも GEMINI_API_KEY/GOOGLE_API_KEY がオプションの機能キーとして記載されています。② **サードパーティ製リモートパッケージおよびミラーの利用** — maps カテゴリにおいて、ヘッドレスChrome内で jsdelivr から maplibre-gl/topojson-client/world-atlas を読み込み、ArcGIS（arcgisonline.com）や CartoCDN からタイルを取得します。また、素材検索プロバイダ（SerpAPI/Google Images/Noun Project）にも依存しています。これらは機能設計（地図タイルの取得や検出器の利用）に基づくものであり、フォールバックパス（キーがない場合はグリッド探索、検索不可の場合は素材なしに縮退）も備わっています。TLSダウングレードやスクレイピング回避、任意のコード実行リスクは確認されませんでした（サブプロセスが呼び出すのは固定バイナリと同梱スクリプトのみです）。
5二重目の独立検証
- [ok] GEMINI_API_KEY 是否真的被读取并外发（橙档判定的关键证据） — locate.mjs:192 `const key = process.env.GEMINI_API_KEY;`；紧接着 key 缺失即报错退出（'auto needs GEMINI_API_KEY; use the grid loop instead (overlay→region→final→mark)'）；存在时把 base64 图像与目标描述 POST 到 generativelanguage.googleapis.com（`?key=${key}`）。调用点真实存在，且仅在 `auto` 子命令触发。
- [ok] 『不假设有检测器』的守卫是否真的生效（避免第一遍误判为『总是联网』） — PROTOCOL.md 明写 '**Never assume the key exists.** No key → path 2.'，且把网格循环列为『the normal case』；SKILL.md 的可选键表也把 GEMINI_API_KEY 标为 optional 并给出 fallback（skip generate / search-only）。因此网络外发是有条件、可预期的，而非默认路径。
- [discrepancy] Step 2 引用的 resolve.mjs 是否随包分发 — SKILL.md Step 2 给出 `(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)`，但 **phases/source/ 下只有 guide.md，没有 resolve.mjs**（全量文件清单已确认）。guide.md 末尾也标了 '> Illustrative: … — or drive media-use's `resolve` procedure directly.'。结论：该命令是示意而非可执行入口，实际取材须由 /media-use 的 resolve 流程驱动；SKILL.md 自身有 'illustrative' 标注，故不算虚假声明，但读者若照抄命令会直接失败——这是对 pin commit 有效的真实出入。
- [ok] 底图烘焙是否真是本地行为而非渲染期联网 — bake-basemap.mjs 头注释与实现一致：在无头 Chrome 内加载 MapLibre + 瓦片，录帧到 frames-<NAME>/，导出 coords.json；SKILL.md 只在该分类下引用它。渲染期（hyperframes render）不触发任何取瓦片行为，符合 HF 的『渲染期禁网』契约——这也是文档给出的烘焙理由，自洽。
- [ok] 『外部资源』逐条回查调用点 — hyperframes init/doctor/add/lint/check/snapshot/preview/render 均在 SKILL.md 出现；ffmpeg/ffprobe 在 locate.mjs 与 bake-basemap.mjs 的 execFileSync/spawnSync 可验；瓦片 URL 与 CDN 在 bake-basemap.mjs:106-119 与 :153 原文；gsap CDN 在 samples HTML 原文；media-use resolve 在 guide.md 原文。
- [unlocatable] 验证：视觉定位协议的准确率声明是否可在源码内定位 — PROTOCOL.md 给出的误差数字（弱模型 16–24%、网格循环 3–4%、'eyeballing 6.5% → this protocol 2.3%'）引用的是一项测量结论，源码内无复现脚本或数据文件；本次为只读侦查且不得运行构建/渲染，故不验证这些数值，仅作为『文档声明』记录，不在结论中当作已核事实使用。
6結論
最適な用途： 単一の短いモーション演出（通常10秒未満、最大約30秒）で、ナレーションや実写映像を含まない制作に最適です: キネティックタイポグラフィのタイトル、数値・統計のインフォグラフィック、チャートによるデータ可視化、ロゴアニメーション/ブランドロックアップ、ローサード/注釈/ソーシャルオーバーレイ、アニメーション地図、ツイート/ニュース見出しカード、Web/UIのデモアニメーション、実画像の幾何形状をチャートに統合する asset-fusion。後工程での合成を目的とした透過オーバーレイ（webm/mov）の出力にも適しています。最小限の確認（最大1問）でパイプラインを自動実行させつつ、最終レンダリングの可否は自身で判断したいユーザーに向いています。
不向きな用途： 以下には適していません: ① 約30秒を超える長尺、ナレーション付き、または複数シーンで構成される作品（/general-video を使用してください）。② 実写映像や人物の出演が必要な動画。③ 単純な字幕生成タスク（/embedded-captions や talking-head-recut ワークフローを使用してください）。④ Windows または非x64環境（前提条件としてプラットフォームが明記されています）。⑤ 検索機能のない完全なオフライン環境（検索カテゴリが素材なし状態に縮退し、asset-fusion は利用できなくなります）。⑥ Google APIへの画像データ送信を許容しないユーザー（locate の auto パスを避け、ローカルのグリッド探索のみを使用する必要があります）。⑦ 厳格な著作権・ライセンス追跡が求められる商用素材の利用シーン（素材台帳は取得元のみを記録し、ライセンスの検証までは行いません）。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload motion-graphics.tar.gz
sha256:
Option B · Copy Guide for Agent7966ceeccd29cbdd…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b8328f9573.