1仕組みと動作原理
オーケストレーターパターン：PR から動画への変換を 7 つのステップ（Step 0 setup → 1 ingest → 2 design system → 3 storyboard/script → 3.1 audio → 4 visual design → 5 frames → 6 finalize）に分割。Step 5 のフレームワーカー割り当てを除き、すべてオーケストレーター自身が順次実行し、各ステップに明確なゲートを配置。
skills/pr-to-video/SKILL.md
User-gated steps are Step 0, Step 3, and Step 6.
ここでの処理内容：「誰が何を行い、いつ一時停止するか」を固定。3 箇所のユーザーゲート以外での途中レビューを禁止し、Step 5 の並列処理はフレーム単位のタスクでのみ実行。
入力を Web サイトではなく「コード変更」として定義：gh を通じて PR を読み込み、キャプチャ手順は存在せず、コントリビューターのアバター以外の実素材は不使用。
skills/pr-to-video/SKILL.md
The input is a **code change** (read via `gh`), not a website — there is **no capture step and no real assets** beyond the contributors' avatars.
ここでの処理内容：同リポジトリ内のサイト取得系ワークフロー（product-launch-video 等）と明確に分岐。「実素材なし」の制約により、以降のビジュアル表現をコード、図表、メカニズムアニメーションによって生成することを決定付け。
Step 1 は決定論的な取り込み処理：fetch-pr.mjs が gh を実行して PR の主要オブジェクトを取得し、ページネーション対応の gh api でファイル一覧（gh pr view では約 100 件上限）を補完。一時ディレクトリを作成せず capture/pr.json と capture/diff.patch のみを出力。MERGED 状態の PR からは実際の shipped_version を可能な限り解決。
skills/pr-to-video/scripts/fetch-pr.mjs
// gh pr view --json files caps at ~100 files; the REST endpoint paginates with no
ここでの処理内容：「エージェントによる手探りの取得」を決定論的スクリプトに置き換え（videos/ の汚染や再現性低下を防止）、終了カードのバージョン番号推測を排除。gh のエラー（未ログイン/存在しない/プライベート）時は gh 本来の stderr を出力して exit 1 で終了し、オーケストレーターが勝手に内容を創作せず停止。
プロジェクトは解決された外部ディレクトリに出力し、呼び出し元リポジトリ内に videos/ を作成しない：PR 参照の取得 → project-dir.mjs による解決（PR_TO_VIDEO_PROJECT_DIR で上書き可能）→ preflight で CLI 機能を検証 → hyperframes.json が存在しない場合のみ init を実行。
skills/pr-to-video/SKILL.md
Never create `videos/` in the caller repository:
ここでの処理内容：「呼び出し元のリポジトリを汚染しない」を実行可能な制約として定義。インストール済み CLI が必要なコマンド（check 等）をサポートしていない事態を防ぐため、事前検証（preflight）を最初に実行。
スタイルは code-editorial に固定し、ユーザーへの確認を省略：build-frame.mjs がプリセットの FRAME.md を複製してブランドトークンを合成（PR にブランドがない場合は colors:[]/fonts:[]）。その後 caption skin をコピーして自己検証を実行。
skills/pr-to-video/SKILL.md
The style is fixed — **code-editorial** (warm editorial; a navy code surface built for diffs).
ここでの処理内容：プロセスを停滞させる「スタイル選択」ゲートを排除（Step 2 はユーザー対話なし）。PR 解説には diff を明瞭に表示できるダーク調のコード画面が適しているため。
Step 3 のストーリー規律：順序は diff のファイル順ではなくストーリー構成に基づいて決定し、「単語数予算」で定量管理（TTS ≈2.2 単語/秒、1 フレームの推奨目安 ≤19 単語/≤9 秒、上限 >26 単語/>12 秒、動画全体の適正範囲 ~30–90 秒）。
skills/pr-to-video/references/story-design.md
Scene order comes from narrative design, not from the diff's file order or the commit list.
ここでの処理内容：最も典型的な失敗例（diff をファイル順に読み上げる構成）を禁止事項として規定。4 種類の PR 原型（changelog / feature-reveal / fix-explainer / refactor-walkthrough）と「価値を提示した後に証拠を示す」順序を提示。「PR 動画における最大の品質不具合は**長すぎるスクリプト**である」と明記。
コードの演出はレジストリの code-* プリミティブ（code-diff / code-morph / code-typing / code-highlight 等）に委譲し、自作前にライブカタログの確認を義務付け。非コード部分の「メカニズム演出」にはアニメーション/フローチャート/データ図の生成を要求。
skills/pr-to-video/references/code-vocabulary.md
**Reach for one of these first** for any code beat; fall back to hand-authored composition only when none fits.
ここでの処理内容：「diff アニメーションの個別実装」を「公式プリミティブの導入 + 実際の変更塊（hunk）の流し込み」に刷新。プリミティブは自己完結型のサブコンポジション（インラインエンジン + 一時停止された GSAP タイムライン）であり、決定論的かつシーク可能。Math.random や Date.now の使用は禁止。
Step 5 に境界付き並列処理を採用：frame-packets.mjs でフレームパケットを生成（### Source excerpt が不足しているコードフレームは即座にエラー、バイト数上限を厳格化）。最大 3 つのワーカーに分散し、各ワーカーは自身のパケットと frame.md のみを読み込み。フレーム生成失敗時は具体的な指摘事項（finding）を付与して該当フレームのみ最大 1 回再試行。
skills/pr-to-video/SKILL.md
Dispatch **at most three workers total**, balanced across the packet paths
ここでの処理内容：「パケット化 + ロールファイルの結合（_role.md = frame-worker-core.md + 本スキルの frame-worker.md）」によってコンテキスト消費を抑制。バッチ全体の再実行によるリソース浪費を防ぐため、再試行は 1 回に制限。
検証フェーズのスコープを限定：lint + check + snapshot コンタクトシートによる検証を実施し、既知の誤検知（字幕ハイライトの text_box_overflow 1–4px）は対応不要とドキュメントで事前指定。レンダリングにはユーザーの承認が必須。
skills/pr-to-video/SKILL.md
**Known false-positive — do not chase it.**
ここでの処理内容：「対応すべき警告と無視すべき警告」をワークフローに明記（フレーム要素に起因するオーバーフローのみ対処）。レンダリング実行前に、lint/check の合格、コンタクトシートの目視確認、ユーザーの承認を必須ゲートとして規定。
2コア機能
01PR の取り込み：gh による PR コアオブジェクトの取得、ページネーションによるファイル一覧の完全補完、完全な diff の抽出を行い、capture/pr.json と capture/diff.patch を出力（大規模 PR も切り捨てなし、一時ディレクトリ不使用、MERGED 時に実際の shipped_version を解決）
02capture パッケージのオフライン合成：ingest.mjs が pr.json + diff.patch から tokens.json（カラー → code-editorial パレット）、visible-text.txt（情報ソース要約）、people.json（コントリビューター、Bot 除外）を生成
03code-editorial デザインシステムの固定適用：build-frame.mjs が code-editorial プリセットをコピーしてブランドトークンを合成し、frame.md + .hyperframes/caption-skin.html を出力して自己検証
04絵コンテとスクリプト作成：4 つの PR 原型（changelog / feature-reveal / fix-explainer / refactor-walkthrough）、PR 専用フレーム種別（hook/problem/change/diff/before_after/mechanism/impact/evidence/credits/cta）、単語数で定量化されたフレーム時間予算の管理
05音声パイプライン：ナレーション生成（HeyGen またはローカル Kokoro）、単語単位のタイミング情報取得、BGM 検索、効果音取得、実音声尺の STORYBOARD への書き戻し、明示的な無音トークンに対応
06フレーム単位の並列構築：frame-packets.mjs による境界付きタスク生成（Source excerpt 欠落のコードフレームはエラー、厳格なバイト数制限）、最大 3 つのワーカーが各自のパケットと frame.md のみを参照して処理
07トランジションと結合：transitions.mjs によるフレーム間トランジションの注入と検証（crossfade / blur-crossfade / push-slide / zoom-through / squeeze）、assemble-index.mjs による再生可能な index.html の組み立てとコントリビューターアバターの冪等フォールバック配置
08字幕と納品前検証：captions.mjs がプロジェクトの caption skin を用いて字幕サブコンポジションを生成、snapshot による目視確認用コンタクトシートの出力後に MP4 をレンダリング
09コントリビューターのクレジットフレーム（唯一の実素材）：GitHub ホストのホワイトリストに基づくアバター取得、プロジェクト外へのパス逸脱防止検証、取得失敗時も exit 0 で継続、ナレーションは @handle ではなく氏名を読み上げ
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | GitHub CLI（gh）：pr view / pr diff / api 分页 / users/<login> 取显示名——摄取 PR 的唯一通道 |
| api | GitHub 用户 API（解析 null 显示名，供 credits 帧旁白念姓名） |
| network | 贡献者头像下载（白名单仅 GitHub 头像主机；github.com/<login>.png 302 到 avatars.githubusercontent.com） |
| cli | 官方 hyperframes CLI：init / add / catalog / lint / check / snapshot / preview / render（--skill=pr-to-video） |
| api | HeyGen 音频后端（BGM 检索；TTS 由同一个共享音频引擎承担，signed in 时走 HeyGen、离线走本地引擎） |
| package | 兄弟 skill 依赖（被指名调用）：/media-use（BGM/SFX/图像/logo 来源与音频引擎）、/hyperframes、/hyperframes-core、/hyperframes-animation（rules/blueprints）、/hyperframes-creative（帧 preset） |
| network | CDN 资源（产物期）：组装的 index.html/captions.html 引用 GSAP，带 SRI 与 crossorigin |
| package | 共享音频引擎路径可用环境变量覆盖（HF_MEDIA_ENGINE），默认指向 /media-use 的 audio.mjs |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" (プロジェクトディレクトリを解決。PR_TO_VIDEO_P で上書き可能)
- 网络端点: 外部ネットワークアクセスの宣言: GitHub: すべての PR 読み込みは gh（github.com + api.github.com）を経由し、gh 自身が認証とリトライを担当。大規模 PR のファイル一覧はページネーション API を利用
- 本地工作目录: ファイル I/O と成果物の出力: PROJECT_DIR 配下（呼び出し元リポジトリ内には一切出力しない）: capture/{pr.json,diff.patch,extracted/{tokens.json,
監査ノート： オレンジ区分に該当する 2 つの条件をいずれも満たしており、いずれも本スキルディレクトリ内で検証可能です：① **認証情報の取り扱い** — fetch-pr.mjs が事前に `gh auth status` を実行し、ユーザーの GitHub アカウント権限で PR を読み取ります（SKILL.md にプライベートリポジトリ対応を明記）。また、音声ステップでは TTS 共通の `~/.heygen` 認証情報を利用します。② **ユーザー素材の外部サービスへの送信** — 音声ステップでスクリプトや生成要件を HeyGen のバックエンド API に送信します（検索・合成処理によりアカウントクレジットを消費。オフライン時はローカルエンジンへのフォールバックが可能）。また、アバター画像を GitHub から実素材としてダウンロードします。同様に ~/.heygen を読み取る先行スキル（product-launch-video / media-use）もオレンジ区分に分類されています。レッド区分の挙動（TLS ダウングレード、サンドボックス無効化、検知回避、任意コード実行等）は見られず、スクリプトのサブプロセス呼び出しも固定バイナリ・固定スクリプトに限定されています。また、単なる公開エンドポイントへの問い合わせにとどまらず、認証を伴う書き込み可能バックエンドの利用やプライベートリポジトリの読み取りが含まれるため、イエロー区分を超過します。実行条件：gh および HeyGen にログインしている場合にのみ認証情報と外部バックエンドが利用されます。gh 未ログイン時は Step 1 で直ちに処理が停止します。
5二重目の独立検証
- [ok] gh 凭证是否真被使用（橙档证据之一） — fetch-pr.mjs 顶部注释写明「gh runs HERE so auth / not-found / private-repo errors surface with gh's own stderr and exit 1」，实现里第一步就是 `if (!ghTry(["auth", "status"]).ok) { die("gh is not authenticated — run: gh auth login"); }`，随后 pr view / api 分页 / pr diff 三处都用同一 execFileSync 包装。调用点真实存在。
- [ok] HeyGen 凭证与 TTS/BGM 实现到底在谁身上（避免把别家行为算进档位） — 本 skill 的 scripts/audio.mjs 头注释自述「The TTS / BGM / SFX implementation no longer lives here: it is the shared engine at ../../media-use/audio/scripts/audio.mjs」，实现只做 SCRIPT/STORYBOARD → audio_request.json 的映射与回写；凭证读取发生在被指名的姊妹 skill 内。按范式「他人 skill 被指名调用只写进 reason、不作档位依据」，橙档依据只用本目录自身可取证的两条：SKILL.md 明写音频共用 ~/.heygen 凭证，以及 fetch-pr.mjs 的 gh 凭证依赖。
- [ok] 头像下载的防护是否真实（是否只是口号） — fetch-people-avatars.mjs 里有 AVATAR_HOSTS 白名单 + isAllowedAvatarUrl（拒绝非 GitHub 主机）与 isUnderProject（写入路径必须在项目目录内，防 ../../ 逃逸），并以 softExit 保证任何失败都 exit 0；注释解释了 github.com/<login>.png 302 到 avatars.githubusercontent.com 属同主控重定向。防护与注释一致，非表面文章。
- [discrepancy] 「无 asset-staging 步骤」的声明与随包代码是否一致 — SKILL.md Step 4 明写 `There is **no asset-staging step** — the only real assets are the credits avatars, already in `assets/`。`，但 scripts/lib/assets.mjs 的头注释仍写着「Shared by stage-assets.mjs (Step 4 close, BEFORE the frame workers run) and assemble-index.mjs (Step 5, idempotent backstop)」，而 **pr-to-video 目录内并不存在 stage-assets.mjs**（该脚本只存在于同仓 product-launch-video 与 music-to-video），assemble-index.mjs 第 521 行也仍在注释里引用它。结论：这是复用姊妹 skill 时残留的过期注释（audio.mjs 自述该适配层在复用者之间「intentionally identical」，可解释来源）；实际行为与 SKILL.md 一致（只有 assemble-index 作为幂等兜底暂存头像），但读者若去找 Step 4 的 stage-assets 会找不到——对 pin commit 有效的真实出入。
- [ok] 是否漏掉未声明的网络调用 — 全目录 URL 命中仅 5 处：两处 gsap CDN（assemble-index.mjs 与 captions.mjs，产物期）、一处 ingest.mjs 的 `https://github.com/${login}.png?size=200` 头像 URL、两处测试文件里的 PR fixture URL；fetch( 仅出现在 fetch-people-avatars.mjs（带白名单）；无其它隐藏端点。
- [ok] 「Step 1 无 capture、只读 gh」与脚本能力是否相符 — fetch-pr.mjs 只写 capture/pr.json 与 capture/diff.patch（头注释明确 no scratch dir），ingest.mjs 是纯离线变换，两者都不抓网页；Quick Reference 亦写明「no Step 1 capture」。与 description「the input is a code change, not a website」一致，无夸大。
6結論
最適な用途： GitHub PR の内容を公開可能なコード変更解説動画（変更履歴 / 新機能紹介 / バグ修正の説明 / リファクタリングのウォークスルー）へ変換したいチームに最適です。PR の URL または owner/repo#N を入力するだけで、code-editorial スタイル、実際の diff スニペット、メカニズムアニメーション、コントリビュータークレジットを含む MP4（8 秒程度のショートから 1〜3 分の尺）を生成します。各フレームの単語数や時間に厳格な制約が設けられているため、安定した品質で動画を量産する「スクリプト化された PR 振り返り」ラインとしても適しています。
不向きな用途： 以下の用途には適していません：① PR が存在しないシナリオ（PR を伴わない一般的な解説は /faceless-explainer、製品プロモーションは /product-launch-video を利用してください）；② 既存の動画・画像素材（スクリーンショット、録画映像、ブランド動画など）を編集・合成したい場合（本フローで扱える実素材はコントリビューターのアバターのみであり、その他の視覚要素はすべてコードや図表アニメーションで新規生成されます）；③ gh コマンドが未認証でログインもできない環境（Step 1 で即座に停止します）；④ 独自のビジュアルスタイルを細かくカスタマイズしたい場合（スタイルは code-editorial に固定されており、選択肢はありません）；⑤ スクリプト内容を HeyGen に送信することを望まず、かつローカル音声合成の品質を許容できない場合。
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload pr-to-video.tar.gz
sha256:
Option B · Copy Guide for Agent8f260d47a576b3e2…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d2f0bc7f34.