heygen-com/hyperframes

插件安装： 在执行 setup 或 freshness 命令之前，当此技能位于 HyperFrames 插件内部时，请遵循 插件执行规则。独立安装请保留下面的更新说明。

首先，保持此技能更新——运行前请与用户确认： npx hyperframes skills update pr-to-video。如果一切都是最新的，这是一个快速的无操作指令；否则，它会在你依赖此技能及其依赖的核心领域技能之前，刷新它们。

media-use：在获取音频/图片/Logo 之前，请调用 /media-use 从 HeyGen 目录和官方来源获取 BGM/SFX/图片和品牌 Logo。先运行 --adopt 注册现有资产。详情请参阅 /media-use 技能。

PR 转 HyperFrames

使用此技能来获取一个 GitHub Pull Request，理解其变更，规划一个代码变更讲解，并在 HyperFrames 中逐帧构建它。输入是一个 代码变更（通过 gh 读取），而不是一个网站——没有捕获步骤，也没有除贡献者头像之外的“真实资产”。

总入口是 /hyperframes。 你是编排者。依次运行每个步骤，验证其门控，然后才能继续。此技能专用于 GitHub Pull Request（代码变更）。任何其他意图、单纯的“制作视频”请求，或任何不确定情况 → 先阅读 /hyperframes——意图层拥有所有路由决策权，一个没有 BRIEF.md 的新建请求最终也会通过它（参见 Setup 的初始规则）。

你是编排者。默认在解析后的外部 PROJECT_DIR 中工作，切勿在调用者仓库中工作。按顺序运行步骤，并在继续之前通过每个门控。用户参与的门控是步骤 0、步骤 3 和步骤 6。在步骤 0 之前阅读 ../hyperframes/references/brief-contract.md——它定义了门控类型以及 BRIEF.md 中的 flow/storyboard 如何导出控制步骤 3/4/6 门控的模式。除了步骤 5（你将分派一个有限的帧工作池）之外，所有步骤都由你亲自完成。不要在此处放置设计或动画规则；这些规则位于帧工作子代理、本技能的本地 ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ 以及 hyperframes-creative 中。

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

---

步骤 0：设置

目标：在确认了任务简报（包含 PR 引用：完整 URL、<owner>/<repo>#<N> 引用，或已检出仓库中的 "this PR"）后，创建 HyperFrames 项目，并使任务简报持久化。风格始终是 代码编辑风格（在步骤 2 中确定，无需询问）。

任务简报由意图层确认，而非在此处提问。 初始规则，按顺序：（1）如果 BRIEF.md 存在 → 读取它且不提问任何问题——任务简报已定，其 flow/storyboard 导出模式（参见 brief contract § 1）。（2）如果没有 BRIEF.md，但项目存在（磁盘上有 hyperframes.json / STORYBOARD.md）→ 从故事板的前置元数据和已记录的首选项恢复；永远不要重新审问一个半建成的项目。（3）两者都没有——一个直接到达此处的新建请求 → 读取 /hyperframes 并运行其意图层（references/intent-interview.md）：它会检查配方（recipes）和已记住的默认值，并询问此路由的问题——包括 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_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" && …)；切勿更改调用者仓库的工作树。

在 init 之后立即编写 BRIEF.md（绝不能在此之前——init 会拒绝非空目录）：意图层锁定的任务简报，其格式遵循 ../hyperframes/references/brief-format.md。将 <MEDIA_DIR> 解析为已安装的 /media-use 技能目录。然后使用 node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes .（brief-format.md 命名了其子集）记录每个偏好支持的答案。如果意图层采用了某个配方（recipe），运行 node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>；它会将配方中的 frame.md 复制到项目中（步骤 2 随后被跳过）并返回步骤 3 从中起草的骨架。补全答案，而非批准；审查门控仍然运行。

在继续执行通过 Setup 之前，显示登录状态——运行 npx hyperframes auth status 并原样输出其结果。它会报告语音/BGM 将使用 HeyGen 还是本地引擎，并在未登录时说明如何登录。应用以下分支之一：

• 协作模式： 等待用户登录或明确选择 offline / go。
• 自主模式： 说明状态，然后通过可用的本地引擎继续执行。

当没有离线提供商时，不要静默省略所需能力；将阻碍因素明确告诉用户。不要将此决策折叠到另一个问题中，也不要将密钥写入每个仓库的 .env 文件。关于认证所有权和离线备选方案：请参阅 /media-use 中的 references/setup-providers.md § 提供商。

门控： hyperframes.json 和 BRIEF.md 必须存在；PR 引用已捕获在任务简报中；偏好支持的答案已记录（参见 brief contract § 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>"

# 确定性地获取 PR：运行 gh，通过分页的 gh api 补全文件列表
# （这样大 PR 的文件列表不会被截断在大约 100 个文件），只写入 capture/pr.json +
# capture/diff.patch —— 无临时目录。gh auth / 未找到 / 私有仓库错误会导致此处退出码为 1。
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)

# 离线转换 → capture/extracted/{tokens.json (colors:[] → 代码编辑调色板),
# visible-text.txt (任务简报), people.json (贡献者, 已过滤机器人, 包含 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)

# 人员相关的唯一一次网络步骤——将每位贡献者的 GitHub 头像下载到
# assets/<login>.png，用于制作人员名单结束画面。尽力而为；始终以退出码 0 结束。
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
  --people ./capture/extracted/people.json)

如果 fetch-pr.mjs 退出码为 1（gh auth / 未找到 / 私有仓库），报告其 stderr 并停止——不要编造 PR 内容。如果 ingest.mjs 退出码为 1，读取其 stderr（通常是格式错误的 pr.json），修复后重新运行（这是确定性的）。fetch-people-avatars.mjs 始终以退出码 0 结束；缺少头像仅意味着没有作者的人员名单结束画面。

people.json 为 gh 已命名的贡献者（PR 作者、提交作者、mergedBy）携带一个 name 字段——其余人员（审查者、评论者、分配者，gh pr view 对此仅提供裸 login）的 name 为 null。在步骤 3 中编写人员列表结束画面之前，请自行解析将实际出现在该帧上的 1-6 个人的任何 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 .

该脚本将 code-editorial 预设的 FRAME.md 复制为 frame.md，将其与 capture/extracted/tokens.json 中的任何品牌标记重新组合（PR 没有这个 → colors:[]/fonts:[] 保留 code-editorial 自己的调色板，一个完整的设计），将预设的字幕皮肤复制到 .hyperframes/caption-skin.html，并进行自我验证（如果映射错误则退出码为 1）。一旦退出码为 0，即可继续——无需手动编辑。

门控： build-frame.mjs 退出码为 0——frame.md 已从 code-editorial 预设中生成，且 .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。利用它们编写 STORYBOARD.md，并在需要旁白时编写 SCRIPT.md。根据任务简报中的 length 设置前置元数据的 duration:——这是一个粗略预期；最终组装报告将显示实际剪辑时长与之的对比。

使用 story-design.md 来确定 PR 的原型（更新日志 / 功能展示 / 修复讲解 / 重构讲解）、PR 原生帧类型、钩子、说服、节奏、每帧字数预算以及人员列表结束画面。其顺序由叙事设计决定，而非 diff 的文件顺序——解释变更，而非逐字朗读 diff。作为软性指导，可查阅 ../hyperframes-animation/blueprints-index.md 中的角色→蓝图菜单：对于每个节拍，按照其候选蓝图所暗示的形式编写画外音，并在合适时标记该候选蓝图的 blueprint: id（故事的真实性仍决定存在哪些节拍——永远不要为了适合某个形式而强行加入一个节拍）。展示 2-4 个真实的 diff 块（来自 capture/diff.patch），每个块是一个小的易读片段；在帧的 scene 中命名其所需的 code-* 块。帧上不携带 asset_candidates，除了 credits 结束画面（1-6 个 assets/<login>.png 头像）。使用来自分镜和脚本参考文档中的精确必需字段。

起草后，运行审查循环的计划阶段——../hyperframes/references/review-loop.md § 1：将计划作为提案展示，并提出两个问题——批准或修改，以及 是否先看草图（推荐）或跳过。反馈以聊天回复的形式到达；循环直到被批准。这是一个检查点门控（参见 brief contract § 1）：在自主模式下无需询问任何问题——以预告形式发布相同的摘要并继续；草图合并到构建中，唯一的预览问题在步骤 6 中提出。

门控： STORYBOARD.md 必须存在，每一帧都具有必需的叙事字段，当需要旁白时 SCRIPT.md 必须存在，并且用户已批准该计划（自主模式：摘要已作为预告发布）。

---

步骤 3.1：音频

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

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

在调用之前，根据用户的请求选择旁白语音。 如果请求指定了语音、性别或语调，选择一个匹配的语音 ID 并通过 --voice <id> 传递。管道默认值是 Marcia（女声）（HeyGen 平台）/ am_michael（Kokoro 库）——因此，像“男声”这样的请求除非你传递了该标志，否则会被静默忽略。语音 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_ 为女声）。当用户未表达任何偏好时，在管道默认值之前回退到已记住的语音（参见 brief contract § 2），

...（原文已被截断）

---