pr-to-video

插件安装： 如果此技能位于 HyperFrames 插件中，请在运行设置或检查新鲜度的命令前，遵循插件执行规则。独立安装请按下方的更新说明操作。

首先，保持此技能为最新状态——运行前请先向用户确认： npx hyperframes skills update pr-to-video。如果所有内容均为最新版本，此命令会快速无操作退出；否则会刷新此技能及其依赖的核心领域技能，然后再使用它们。

media-use：在获取音频／图片／徽标之前，调用 /media-use，从 HeyGen 目录获取背景音乐和图片，从 Openverse 获取音效，并从官方来源获取品牌徽标。先运行 --adopt，登记已有资源。请参阅 /media-use 技能。如果宿主应用提供自己的音乐或音效工具，请使用这些工具处理音乐和音效。

PR 转 HyperFrames

使用此技能来导入 GitHub 拉取请求、理解更改、规划代码更改解说视频，并在 HyperFrames 中逐帧制作。输入是代码更改（通过 gh 读取），而非网站——无需捕获步骤，也没有真实素材，贡献者头像除外。

入口是 /hyperframes。 你是协调者。运行每个步骤，验证其关卡，然后再继续。此技能适用于 GitHub 拉取请求（代码更改）。任何其他意图、单纯的“制作视频”要求，或任何不确定情况 → 请先阅读 /hyperframes——意图层负责所有路由决策；即使是全新创作，如果没有 BRIEF.md，也会先经过该层（设置阶段的首条规则）。

你是协调者。请在解析出的外部 PROJECT_DIR 中工作，默认情况下绝不要在调用方仓库中工作。按顺序运行各步骤，并通过每个关卡后再继续。需要用户确认的步骤是 Step 0、Step 3 和 Step 6。开始 Step 0 前，请阅读 ../hyperframes/references/brief-contract.md——其中定义了关卡类型，以及 BRIEF.md 的 flow／storyboard 如何决定模式，进而影响 Step 3／4／6 的关卡。除 Step 5 外，所有步骤都由你亲自完成；Step 5 则分派给一组有明确任务范围的帧工作者。不要在此处编写设计或动态规则；这些规则位于帧工作者子代理、本技能的本地 ../hyperframes-animation/rules/ 和 ../hyperframes-animation/blueprints/ 目录，以及 hyperframes-creative 中。

工作流：Step 0 设置 → hyperframes.json；Step 1 导入 → capture/extracted/ + assets/<login>.png；Step 2 设计系统 → frame.md；Step 3 分镜／脚本 → STORYBOARD.md 和 SCRIPT.md；Step 3.1 音频 → audio_meta.json；Step 4 视觉设计 → 丰富后的 STORYBOARD.md；Step 5 帧 → compositions/frames/NN-*.html 和 index.html；Step 6 最终渲染 → renders/video.mp4。

---

步骤 0：设置

目标：使用已确认的简述开始——其中包括 PR 引用（完整 URL、<owner>/<repo>#<N> 引用，或在已检出的仓库中写“此 PR”）——创建 HyperFrames 项目，并将简述持久保存。风格始终为 代码编辑风格（在步骤 2 中固定，不会询问）。

简述由意图层确认，而不是通过此处提出的问题确认。 开始时按以下顺序处理：(1) 存在 BRIEF.md → 读取，不提问——简述已确定，其 flow/storyboard 决定模式（简述约定 § 1）。(2) 不存在 BRIEF.md，但项目已存在（磁盘上有 hyperframes.json / STORYBOARD.md）→ 根据分镜脚本的 frontmatter 和记录的偏好继续；绝不重新询问已构建一半的项目。(3) 两者都不存在——直接到达此处的新建请求 → 阅读 /hyperframes 并运行其意图层（references/intent-interview.md）：检查配方和已记忆的默认值，并提出此路径所需的问题——包括 PR 大小 → 视频长度的原则，该原则完整写在 ../hyperframes/references/routes/pr-to-video.md 中——然后返回锁定后的简述。编辑请求跳过以上所有步骤——直接进行编辑。

在进行任何其他工作之前，先确定项目目录。保留用户提供的项目目录；否则使用解析器输出的持久外部缓存位置。绝不要在调用方仓库中创建 videos/：

PR="<url | owner/repo#N>"
if [ -n "${EXPLICIT_PROJECT_DIR:-}" ]; then
  PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" --project-dir "$EXPLICIT_PROJECT_DIR")"
else
  PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR")"
fi
echo "PR-to-video project: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs

能力预检必须在获取内容、故事工作、音频或帧分发之前运行。如果已安装的 CLI 无法运行此技能要求的验证命令，则停止并提供升级说明，不要先消耗本次运行的上下文。

仅当 $PROJECT_DIR/hyperframes.json 不存在时才初始化。其基本名称取自 PR，例如 acme-sdk-pr-1842；绝不要使用工作区名称或时间戳。

npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init 会检查已安装技能是否为 GitHub 上的最新版本；如果有任何技能已过期，就会更新全局技能集。

以下每条相对路径命令都以 $PROJECT_DIR 为工作目录。未明确写出子 Shell 的示例都表示 (cd "$PROJECT_DIR" && …)；绝不要更改调用方仓库的工作树。

初始化后立即写入 BRIEF.md（绝不要提前写入——init 会拒绝非空目录）：写入意图层锁定的简述，格式参照 ../hyperframes/references/brief-format.md。将 <MEDIA_DIR> 解析为已安装的 /media-use 技能目录。然后使用 node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . 记录每项由偏好支持的回答（brief-format.md 中列出了相应子集）。如果意图层采用了配方，则运行 node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>；它会将其 frame.md 复制到项目中（因此跳过步骤 2），并返回步骤 3 起草所用的骨架。配方会填入回答，但不代表获得批准；仍须通过审核关卡。

继续离开设置阶段之前，先显示登录状态——运行 npx hyperframes auth status 并原样转达其输出。输出会说明语音/背景音乐将使用 HeyGen 还是本地引擎；如果尚未登录，也会说明如何登录。按以下分支处理：

• 协作模式： 等待用户登录，或明确选择 offline / go。
• 自主模式： 说明当前状态，并继续使用可用的本地引擎。

如果没有离线提供方，不要默默省略必需的能力；应明确指出阻碍。不要将此决定并入其他问题，也不要把密钥写入仓库专属的 .env。认证归属和离线回退方案：/media-use references/setup-providers.md § Providers。

关卡：hyperframes.json 和 BRIEF.md 均已存在；PR 引用已记入简述；偏好支持的回答已记录（简述约定 § 2）；登录状态已显示（已登录，或选择离线继续）。

步骤 1：摄取 PR（不进行捕获）

目标：获取 PR 的事实，并将其纳入项目，作为信息来源。不会进行网站捕获。fetch-pr.mjs 会确定性地运行 gh——通过分页调用 gh api 补全文件列表，避免大型 PR 在约 100 个文件处被截断；并且只写入 capture/pr.json + capture/diff.patch（不创建临时目录）。对于已合并的 PR，它还会尽可能解析出 shipped_version（以及 version_source）并写入 pr.json，这样片尾卡片就能引用真实版本，而非凭空编造。然后，ingest.mjs 会离线将这些内容纳入合成捕获包。

PR="<url | owner/repo#N | N>"

# Fetch the PR deterministically: runs gh, completes the files list via paginated
# gh api (so a big PR doesn't truncate at ~100 files), writes only capture/pr.json +
# capture/diff.patch — no scratch dir. gh auth / not-found / private errors exit 1 here.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)

# Offline transform → capture/extracted/{tokens.json (colors:[] → code-editorial palette),
# visible-text.txt (the brief), people.json (contributors, bot-filtered, name+login,
# avatarFile=assets/<login>.png)}.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
  --pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)

# The people front's one network step — download each contributor's GitHub avatar to
# assets/<login>.png for the credits close. Best-effort; always exits 0.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
  --people ./capture/extracted/people.json)

如果 fetch-pr.mjs 以状态码 1 退出（gh 认证失败／未找到／私有），请报告其标准错误输出并停止——不要伪造 PR 内容。如果 ingest.mjs 以状态码 1 退出，请读取其标准错误输出（通常是 pr.json 格式错误），修复后重新运行（结果具有确定性）。fetch-people-avatars.mjs 总是以状态码 0 退出；缺少头像只意味着作者附近不会显示鸣谢信息。

people.json 会为 gh 已提供姓名的贡献者（PR 作者、提交作者、mergedBy）记录 name；其余人（审阅者／评论者／受指派者，gh pr view 对他们只会提供一个 login）的 name 为 null。在步骤 3 撰写片尾鸣谢前，请自行解析最终会出现在该画面中的 1–6 位人员中所有 name 为 null 的人：运行 gh api users/<login> --jq .name（你已经有 gh，无需为此编写脚本）。如果 GitHub 也没有该用户的公开姓名，就在屏幕上使用其登录名，并将此人从口播内容中删去（参见 story-design.md 的鸣谢部分——旁白仍必须说出姓名，不能直接读原始账号名）。

检查项：capture/pr.json、capture/diff.patch、capture/extracted/tokens.json、capture/extracted/visible-text.txt 和 capture/extracted/people.json 均已存在；你能用一句清晰的话说明 PR 的改动。assets/<login>.png 尽力获取即可——缺少它不算失败。

---

步骤 2：设计系统

目标：采用代码编辑风格的画面预设；脚本会将其转换为本视频的 frame.md 和字幕皮肤。

样式固定为代码编辑风格（温暖的编辑风格；专为差异对比打造的海军蓝代码界面）。运行：

node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .

脚本会将代码编辑风格预设的 FRAME.md 复制到 frame.md，并根据 capture/extracted/tokens.json 中的品牌令牌进行重新混合（PR 不含品牌令牌，因此 colors:[]/fonts:[] 会保留代码编辑风格自身的配色方案，形成完整的设计）；接着将预设的字幕皮肤复制到 .hyperframes/caption-skin.html，并自行验证（映射有误时以状态码 1 退出）。退出状态码为 0 后即可继续——不要手动编辑。

检查项：build-frame.mjs 以状态码 0 退出——frame.md 已从代码编辑风格预设生成，且 .hyperframes/caption-skin.html 已作为字幕皮肤源文件存在。

---

步骤 3：分镜脚本与旁白稿

目标：将 PR 转化为一份获批的、逐帧讲解计划。

阅读 ../hyperframes-creative/references/story-spine.md（钩子语言、先呈现价值再提供证据、将分镜作为提案、视觉内容可追溯至来源）、references/story-design.md、../hyperframes-animation/blueprints-index.md、../hyperframes/references/storyboard-format.md 和 ../hyperframes/references/script-format.md。根据简报中的 length 设置前置元数据 duration:——这只是粗略预期；组装报告会说明成片时长与其相比如何。

使用 story-design.md 确定 PR 类型（changelog / feature-reveal / fix-explainer / refactor-walkthrough）、适用于 PR 的帧类型、钩子、说服方式、节拍、每帧字数预算以及片尾署名。叙事顺序来自叙事设计，而非 diff 的文件顺序——要讲清楚变更，不要照着 diff 念。作为非强制参考，查阅 ../hyperframes-animation/blueprints-index.md 中的角色→蓝图菜单：对于每个节拍，按候选蓝图暗示的形式撰写旁白，并在适用时标注候选项的 blueprint: ID（故事实际内容决定哪些节拍存在——绝不要为了套用形式而强行添加节拍）。展示 2–4 个真实的 diff 代码块（来自 capture/diff.patch），每个都是简短易读的片段；在帧的 scene 中注明每个片段对应的 code-* 区块。除 credits 片尾外，帧中不得包含 asset_candidates（credits 片尾可包含 1–6 个 assets/<login>.png 头像）。使用分镜和旁白稿参考文档规定的准确必填字段。

草拟完成后，执行审阅循环的计划阶段——../hyperframes/references/review-loop.md § 1：将计划作为提案呈现，并提出两个问题——是批准还是修改，以及先看草图（推荐）还是跳过。反馈会以聊天回复的形式收到；持续循环，直到计划获批。这是一个检查点关卡（简报约定 § 1）：在自主模式下无需提问——发布相同的摘要作为提示，然后继续；草图并入构建流程，最终预览及其一个问题会在步骤 6 中给出。

关卡：STORYBOARD.md 已创建，每帧都包含必填的叙事字段，需要旁白时已创建 SCRIPT.md，并且用户已批准计划（自主模式下：已将摘要作为提示发布）。

---

步骤 3.1：音频

目标：根据已批准的脚本生成旁白、单词时间、音乐和音频元数据。

步骤 3 获批后开始处理音频。在后台运行，然后继续步骤 4。

调用前，根据用户的需求选择旁白音色。 如果用户指定了音色、性别或语气，请选择匹配的音色 ID，并通过 --voice <id> 传入。否则，流水线默认使用 HeyGen 上的 Marcia（女声），或 Kokoro 上的 am_michael，因此，如果用户要求“男声”却未传入该标记，这项要求会被忽略。音色 ID 因提供方而异；请根据步骤 0 的登录状态选择对应提供方并查找：已登录时使用 HeyGen，通过 node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list（或 GET /v3/voices?engine=starfish）查询；离线时使用 Kokoro，查阅 <MEDIA_DIR>/audio/references/tts.md 中的音色表（男性前缀为 am_/bm_，女性前缀为 af_/bf_）。如果用户未表达偏好，请优先使用已记住的音色（简要约定 § 2），再考虑流水线默认值，并说明使用了哪种音色；仅当两者都未指定时，才省略 --voice。如果用户本次明确选择了音色，请记录下来（prefs.mjs record --key voice）。

node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json --voice <voice-id> &

音频脚本负责处理旁白、单词时间、从 HeyGen 音乐库中查找背景音乐，以及生成时间元数据。背景音乐的情绪取自故事板的 music: 字段。此处使用 HeyGen 音频 API 检索音乐，而非生成音乐；TTS 使用相同的 ~/.heygen 凭据。有关提供方的详情，请阅读 ../media-use/audio/references/tts.md。如果宿主应用自己的工具生成音乐或音效，请将文件放在 assets/ 下，并在 audio_meta.json 文件中标记 "source": "host"：音乐使用 bgm，内容为 { "path": "assets/…", "source": "host" }，并在故事板中设置 music: none；音效使用 sfx 条目，内容为 { "frame": <n>, "file": "assets/…", "offset_s": 0, "duration_s": <其时长>, "source": "host" }。每次处理音频都要保留这些条目；含有宿主音效的帧不会添加查找得到的提示音。

如果没有旁白且不存在 SCRIPT.md，请跳过语音生成。若故事板中设置了音乐情绪，仍可生成背景音乐。

规范的全静音标记（适用于复用此音频模型的所有工作流）：STORYBOARD.md 顶部 YAML 块中设置 music: none，不存在 SCRIPT.md，并且没有 sfx: 提示或宿主音频。以上条件组合表示项目为静音状态——没有旁白、背景音乐或音效。audio.mjs 可识别此标记并且不会生成任何内容（它会移除过时的 audio_meta.json；assemble 将缺少 audio_meta.json 视为静音），因此可直接跳过此步骤。没有旁白但有 sfx: 提示或宿主音频时，影片并非静音：audio.mjs 会写入 audio_meta.json 文件，供 fetch-sfx 填充内容。存在旁白时，music: none 会保留 TTS，仅关闭背景音乐。请严格使用此拼写——不要自行变更标记。

**关卡条件：**音频任务已启动，或项目已标记为静音（music: none、不存在 SCRIPT.md，且没有 sfx: 提示或宿主音频）。

---

步骤 4：画面视觉设计

目标：为故事板中的每一帧添加视觉指导、布局意图和动态效果选择。 先绘制分镜表草图（仅协作模式）。 计划获批后，立即进行草图阶段——参见 ../hyperframes/references/review-loop.md § 2（不要等到 Step 3.1；静帧不使用时间设置）：自行构思每一帧的构图，将每帧放在 index.html 中的计划起始位置，一次运行截取所有静帧并编写分镜板 boards/storyboard.html（参见 ../hyperframes-creative/references/storyboard-recipe.md），将每帧标记为 built；等所有帧都标记为 built 后，暂停并提出唯一的布局问题；只修改指定的帧，直到分镜板得到确认。临时占位内容：对于代码段，使用简单的代码面板，显示文件名和几行真实差异文本——code-* 区块的接线工作由工作者负责。只有在此之后，才能将下方的视觉设计应用到已确认的布局上。自主模式下，或用户在 Step 3 选择跳过草图时，跳过此阶段——在 Step 5 中，帧会从 outline 直接进入 animated。

直接编辑 STORYBOARD.md。不要创建另一个分镜文件。以 frame.md 为颜色、字体、布局感受和风格的事实来源。

阅读 references/visual-design.md、../hyperframes-animation/blueprints-index.md、references/motion-language.md、references/code-vocabulary.md 和 ../hyperframes-animation/rules-index.md。使用 visual-design.md 中的方法（按时间编码的镜头序列、内联 Layout 词汇和代码段处理方式），并添加必需的 ## Video direction 区块。使用 ../hyperframes-animation/blueprints-index.md 为每帧选择镜头形态。使用 code-vocabulary.md 为每个代码段选择正确的 code-* 区块（diff = code-diff，重构 = code-morph，新代码 = code-typing，……）。使用 motion-language.md（动作词汇和动作规范）以及 ../hyperframes-animation/rules-index.md（有效规则名称）来设计动作——不要自行编造动作或区块／蓝图名称。

设计任何命名效果前，先搜索实时目录。 code-vocabulary.md 涵盖代码段，不涵盖其他内容。对于简报中提及的其他外观、效果、处理方式或转场——“CRT scanlines”、“glitch”、“film grain”、“shimmer sweep”、“confetti burst”——运行 npx hyperframes catalog --query "<the look, in plain English>" --json，并在将其写入 STORYBOARD.md 前阅读排名靠前的结果。搜索无需安装任何内容：不需要项目、不需要事先执行 add，也不需要账户。它会从任意目录对整个托管注册表（约 400 个区块和组件）进行排名。在此处写明找到的区块名称；Step 5 会预先安装分镜中提到的所有区块。只有在搜索后发现没有合适结果时，才能手动编写效果。

对于每一帧，按照 visual-design.md 中的方法，在 STORYBOARD.md 中编写按时间编码的镜头序列：为该帧选择蓝图（或组合蓝图），用此帧的内容具体化，并根据旁白安排每个 Scene 的揭示节奏，使帧在整个时长内逐步展开，而不是一开始就全部呈现然后静止。对于代码段，code-* 区块是该帧的 focal，Scene 负责编排周围的代码编辑呈现（文件／标题的出现、镜头移至代码块、落在目标行）——而不是代码动画本身，后者由区块负责。紧接每个代码帧的字段之后，添加一个 ### Source excerpt fenced diff 代码块，其中只包含工作者必须呈现的准确真实代码块（最多 12 行）。在此处从 capture/diff.patch 中选取；工作者不得重新打开完整 diff。按照每个 Scene 内联说明布局和动作（词汇见 visual-design.md 和 motion-language.md）。添加一个适用于整段视频的 ## Video direction 区块。

不要更改故事、脚本、transition_in、asset_candidates 或 PR 源文件。此步骤中除了草图阶段的构图，不要编写 HTML。没有素材暂存步骤——唯一的真实素材是 credits 头像，已在 assets/ 中。 **门槛：**每个画面都有按时间编码的镜头序列，揭示节奏与旁白同步（不得一开始就全部揭晓）；代码画面将某个 code-* 块指定为 focal；存在 ## Video direction。协作模式：草图表已确认。

---

第 5 步：构建画面

目标：将每个分镜画面构建为 HTML 组合，并组装可播放的视频。

如果已开始音频处理，请等待第 3.1 步的音频处理完成。然后同步时长并获取 SFX；如果是静音，则跳过这两项。

node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md

node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .

时长同步是机械操作：以实际语音时长为准；静音画面保留估算时长；绝不要手动编辑已同步的时长。

在派发前，预先安装 STORYBOARD.md 中指定的注册表块，一次性全部安装，避免并行工作者争抢注册表：

for b in <each registry block named in the storyboard>; do npx hyperframes add "$b"; done

派发前，阅读 ../hyperframes/references/subagent-dispatch.md。构建有界数据包和工作者角色载荷：

node <SKILL_DIR>/scripts/frame-packets.mjs --project "$PROJECT_DIR" --storyboard "$PROJECT_DIR/STORYBOARD.md"

如果代码画面缺少上游选定的 ### Source excerpt，数据包构建器会立即失败；同时会严格限制数据包字节数。它还会写入 _role.md（将 ../hyperframes/references/frame-worker-core.md 与本技能的 sub-agents/frame-worker.md 原样拼接而成——即完整的工作者角色说明）。最多派发三名工作者，并在各数据包路径间均衡分配；每名工作者的提示词都包含 _role.md 和分配给它的数据包路径——粘贴完整角色说明或提供其路径均可（两者等效；工作者只会根据这些文档开始工作）——每名工作者可以依次构建多个分配给它的画面，只需读取一次角色说明。工作者只读取其数据包和 frame.md。他们绝不能打开完整的 STORYBOARD.md、capture/diff.patch 或 capture/extracted/visible-text.txt。每名工作者只能写入分配给它的 compositions/frames/NN-*.html；工作者绝不编辑 STORYBOARD.md。如果画面已有磁盘上的已确认草图（协作运行——审阅循环 § 3），请在派发上下文中告知该工作者：草图就是现有的 compositions/frames/NN-*.html，工作者应在该布局上进行设计，而不是重新绘制（参见 frame-worker core § When a confirmed sketch exists）。

如果某个画面失败，只重新派发该画面，并附上现有数据包以及准确的验证器／lint 检查结果。最多重试一次。不要重新执行整个批次，也不要在没有具体问题时重试。

**铺满全画面的背景必须放在 class="clip" 图层上，绝不能放在 #root 上。**画面的底色（纯色／渐变／网格）应是持续整个画面时长的独立背景剪辑——设置在 #root／data-composition-id 元素上的 background 会受画面时间窗口限制，不能可靠地充当底色，因此深色内容可能落在黑色宿主 body 上并呈现为不可见。视频的基础底色由组装器从 frame.md 的 canvas 颜色绘制到索引页的 #root 上。（完整规则和自检：../hyperframes/references/frame-worker-core.md。）

每名工作者返回结果后，将该画面在 STORYBOARD.md 中标记为 animated。

音频时间信息就绪后，在后台构建字幕并组装索引：

node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &

node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .

captions.mjs 使用项目的 .hyperframes/caption-skin.html（属于 code-editorial，在第 2 步复制），并注入来自 frame.md 的品牌令牌；captions: skipped (<reason>) 属于有效结果。assemble-index.mjs 会将片尾鸣谢头像从 assets/ 暂存为幂等的后备措施。

**门槛：**每个画面都已标记为 animated（协作模式：草图表已在第 4 步确认），index.html 已存在，并且字幕已构建或明确跳过。

步骤 6：定稿

目标：检查已组装的视频，征求用户批准，并渲染最终 MP4。

插入转场，运行检查，暂停以供审阅，然后渲染。

node <SKILL_DIR>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .

node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html

npx hyperframes lint

npx hyperframes check

npx hyperframes snapshot --at <frame-midpoints>

snapshot 会将捕获的帧拼成一张联系表（.hyperframes/artifacts/snapshots/<id>/contact-sheet.jpg；命令会打印路径）。快速浏览一下；如果没有明显问题，就继续，不要在这里耽搁。

如果命令失败，显示 stderr 并停止，不要接连执行恢复命令。自行修复：对 compositions/frames/NN-*.html 做最小且安全的编辑，然后重新运行失败的检查。

已知的误报——不要追查。 check 可能会在 字幕 高亮词上报告少量约 1–4px 的 text_box_overflow 错误（选择器为 #caption-word-* / .caption-line）。字幕胶囊使用了刻意紧凑的 line-height（在 scripts/captions.mjs 中统一设置），并且没有 overflow:hidden，因此较粗的显示字体字形墨迹会溢出几 px，进入胶囊自身的内边距——实际上没有内容被裁切。将这些视为预期情况并继续。不要增大字幕的 line-height（这会使胶囊膨胀，效果更差）。只有当 text_box_overflow 指向帧元素（#el-NN-*）而非字幕词时，才进行处理。

检查通过后，暂停以供用户审阅——参照审阅循环的最后一轮检查（../hyperframes/references/review-loop.md § 4）：只提一个问题，让用户查看最终 Studio 预览——现在渲染，还是需要修改？（自主模式：同样只保留这一个问题——即使用户没有要求，也用下面的命令打开预览。）然后交付 MP4、联系表和帧 ID，以便修改时能针对单个帧。

预览：npx hyperframes preview "$PROJECT_DIR" --background

仅在用户批准后渲染（自主模式：在询问渲染还是修改之后）：

npx hyperframes render --skill=pr-to-video --quality high --output renders/video.mp4

渲染后，除非用户提出要求，否则不要重新运行 lint、check 或 snapshot。

用户完成审阅后（如果预计不会再进行实时编辑，则在渲染后），仅停止此项目的后台服务：npx hyperframes preview "$PROJECT_DIR" --stop。等待审阅期间绝不要关闭它。

**关卡：**渲染前已通过 lint 和 check，并检查了快照；用户在审阅暂停时已批准（自主模式：检查通过，交付内容包含联系表）；renders/video.mp4 已存在。最终回复需说明 MP4 路径和最终时长。

---

快速参考

**格式：**横屏 1920x1080；竖屏 1080x1920；正方形 1080x1080——根据目标位置确定（简述规范 § 2）。在分镜脚本的 frontmatter 中设置一次格式。

**与捕获素材工作流相比的 PR 差异：**无需步骤 1 捕获（gh CLI 会将 PR 导入合成的 capture/extracted/ 包——tokens.json + visible-text.txt + people.json）；唯一的真实素材是贡献者的 assets/<login>.png 头像（片尾鸣谢）；没有 asset-descriptions.md，也没有素材暂存步骤。代码段由 code-editorial 的藏青色 Code Surface 上的 code-* 注册块渲染；风格始终为 code-editorial。 **背景脚本：**此工作流在 scripts/ 下提供这些脚本：fetch-pr（通过 gh 将 PR → capture/pr.json + diff.patch；适用于大型 PR，无临时文件）、ingest（→ 合成的采集包；离线运行）和 fetch-people-avatars（将贡献者头像保存到 assets/）；此外还有共享引擎——build-frame（采用预设并进行品牌重混，生成 frame.md + 字幕皮肤）、audio（TTS、BGM、SFX、时长同步）、captions、transitions（注入 + 验证）和 assemble-index。其他所有操作都通过 hyperframes CLI 完成。代码块通过 npx hyperframes add <name> 安装。

可复用且与领域无关的镜头形状位于 ../hyperframes-animation/blueprints/（由 ../hyperframes-animation/blueprints-index.md 索引）；code-* 注册表区块是代码节拍词汇表（references/code-vocabulary.md）。

阅读	时机
[../hyperframes/references/brief-contract.md](../hyperframes/references/brief-contract.md)	门控类型、从 BRIEF.md 推导模式、字段语义。
[../hyperframes-creative/references/story-spine.md](../hyperframes-creative/references/story-spine.md)	第 3 步：故事准则——钩子语言、先价值后证据、提案形式、可追溯至来源的视觉内容。
[references/story-design.md](references/story-design.md)	第 3 步：规划 PR 说明。
[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)	第 3 步：角色→蓝图选单。第 4 步：选择镜头形式。
[../hyperframes/references/storyboard-format.md](../hyperframes/references/storyboard-format.md)	第 3 步：编写 STORYBOARD.md。
[../hyperframes/references/script-format.md](../hyperframes/references/script-format.md)	第 3 步：编写 SCRIPT.md。
[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)	第 3.1 步：选择或了解 TTS 提供方。
[references/visual-design.md](references/visual-design.md)	第 4 步：编写画面的镜头序列（以及布局词汇）。
[references/code-vocabulary.md](references/code-vocabulary.md)	第 4 + 5 步：为代码节奏选择并填充 code-* 区块。
[references/motion-language.md](references/motion-language.md)	第 4 步：动作词汇与动作准则。
[references/cut-catalog.md](references/cut-catalog.md)	第 4-5 步：剪辑目录（工作器在帧内构建衔接）。
[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md) + [../hyperframes-animation/rules/](../hyperframes-animation/rules/)	第 5 步：文中引用动作对应的本地规则配方正文。
[../hyperframes/references/frame-worker-core.md](../hyperframes/references/frame-worker-core.md)	第 5 步：共享工作器契约（数据包构建器会将其置于差异内容之前）。
[sub-agents/frame-worker.md](sub-agents/frame-worker.md)	第 5 步：工作流的帧工作器差异内容。
[../hyperframes/references/subagent-dispatch.md](../hyperframes/references/subagent-dispatch.md)	第 5 步：安全地调度子 Agent。
[../hyperframes-creative/frame-presets/code-editorial/FRAME.md](../hyperframes-creative/frame-presets/code-editorial/FRAME.md)	第 2 步：代码编辑风格预设（固定样式）。