media-use:在获取音频/图片之前,先调用
/media-use从 HeyGen 目录中解析 BGM/SFX/图片。先运行--adopt注册现有资产。参见/media-use技能。
PR 到 HyperFrames
使用此技能来摄入一个 GitHub Pull Request,理解变更,规划代码变更解说视频,并在 HyperFrames 中逐帧构建。输入是代码变更(通过 gh 读取),而非网站——没有捕获步骤,也没有真实资产(除了贡献者的头像)。
在步骤 0 之前确认路由。 你是协调者。运行每个步骤,检查关卡,然后才继续。此技能用于 GitHub Pull Request(代码变更)。将其他意图路由到别处:产品发布/推广 →
/product-launch-video;通用网站导览 →/general-video;无 PR 的专题讲解 →/faceless-explainer;在现有素材上添加字幕 →/embedded-captions;短篇无旁白动态图形 →/motion-graphics;整个仓库或多 PR 的发布讲解 →/general-video。超出范围: 实时/渲染时的数据——PR 事实仅在创作时读取一次并固化。如果用户只说“制作一个视频”或路由不明确,请先阅读/hyperframes。
你是协调者。在 videos/<project>/ 中工作。按顺序运行步骤,在继续前通过每个关卡。用户关卡的步骤是步骤 0、步骤 3 和步骤 6。除步骤 5(你需要为每帧分发一个子代理)外,亲自执行所有步骤。不要在此处放置设计或动画规则;这些规则存在于帧工作者子代理 hyperframes-creative 和 hyperframes-animation 中。
工作流程:步骤 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 引用和核心视频简报,并在需要时创建 HyperFrames 项目。
获取 PR 引用(完整 URL、<owner>/<repo>#<N> 引用或已检出仓库中的“此 PR”),并在一条消息中确认简报——为每项提供一个推荐默认值并预填 /hyperframes 已设置的任何内容:角度(变更日志/功能展示/修复讲解/重构讲解——默认值:从 PR 推断)、受众(默认值:开发者)、长度(默认值:根据 PR 变更规模缩放——见下方)、宽高比(默认值 16:9)、语言。风格始终是 claude。仅在用户回复后才继续;“继续”接受默认值。
根据 PR 的变更规模推荐长度,而非固定猜测。在确认简报前,先只读地查看一次 PR——该调用也用于确立角度(步骤 1 仍会执行完整的确定性获取):
github pr view <PR_REF> --json title,additions,deletions,changedFiles
从 additions + deletions 中选择层级(由 changedFiles 微调),并以该值作为默认值推荐(用户可以覆盖;硬上限约 3 分钟):
| PR 变更规模 | 推荐长度 |
|---|---|
| 微小(≲ 50 行变更) | ~20–40 秒 |
| 集中(~50–200 行) | ~40–70 秒 |
| 较大(~200–600 行) | ~70–110 秒 |
| 大型(≳ 600 行,或 25+ 文件) | ~110–180 秒 |
在推荐时用一句话说明依据(例如,“~40 秒 —— 小变更,+44/−13 跨 12 个文件”)。大型 PR 不意味着长视频——如果故事是一个亮点变更,就保持简短并说明原因。
仅在 hyperframes.json 缺失时初始化。以烤串命名法从 PR 命名 <project>,例如 acme-sdk-pr-1842;绝不使用工作区名称或时间戳。
npx hyperframes init "videos/<project>" --non-interactive --example=blank——init 会检查已安装的技能是否与 GitHub 上的最新版本一致,并在有技能过时时更新全局技能集。
在简报前显示登录状态——运行 npx hyperframes auth status 并逐字输出其结果(不要改写或重写)。 它会报告语音/BGM 将使用 HeyGen 还是本地引擎,以及当未登录时如何登录。如果未登录,则停止并等待用户选择——登录,或说“继续”/“离线”以使用本地引擎继续推进——之后再询问简报或其他任何内容。 将其视为一个真正的决策点,而非无关紧要的备注;不要将选择权与简报问题合并,也不要在每个仓库的 .env 中写入密钥。(在自主模式下,记录状态并以离线模式继续。)参见 ../hyperframes-media → 预检事项以获取权威指导。
关卡: hyperframes.json 存在;PR 引用已捕获;角度、长度、宽高比和语言已锁定;登录状态已显示(已登录,或继续以离线模式进行)。
步骤 1:摄入 PR(无捕获)
目标:获取 PR 的事实并将其合并到项目中以作为信息来源。没有网站捕获。fetch-pr.mjs 仅运行 gh 并执行确定性操作——通过分页 gh api 完成文件列表,因此大型 PR 不会在约 100 个文件处截断,并且仅写入 capture/pr.json + capture/diff.patch(无临时目录)。然后 ingest.mjs 离线地将这些数据纳入合成的捕获包中。
PR="<url | owner/repo#N | N>"
# 确定性获取 PR:运行 gh,通过分页的 gh api 完成文件列表(因此大型 PR 不会
# 在约 100 个文件处截断),仅写入 capture/pr.json + capture/diff.patch——
# 无临时目录。gh auth/未找到/私有错误会以退出码 1 退出。
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# 离线转换 → capture/extracted/{tokens.json (colors:[] → claude 调色板),
# visible-text.txt (简报), people.json (贡献者,过滤机器人,avatarFile=assets/<login>.png)}。
(cd "videos/<project>" && 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 "videos/<project>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
如果 fetch-pr.mjs 以退出码 1 退出(gh auth/未找到/私有错误),报告其标准错误并停止——不要虚构 PR 内容。如果 ingest.mjs 以退出码 1 退出,读取其标准错误(通常是格式错误的 pr.json),修复后重新运行(确定性)。fetch-people-avatars.mjs 始终以退出码 0 退出;缺失头像仅表示没有鸣谢结尾的作者部分。
关卡: capture/pr.json、capture/diff.patch、capture/extracted/tokens.json、capture/extracted/visible-text.txt 和 capture/extracted/people.json 存在;你可以用一句清晰的话说明 PR 的变更。assets/<login>.png 是尽力而为——其缺失不视为失败。
步骤 2:设计系统
目标:采用 claude 帧预设;脚本将其转换为本视频的 frame.md + 字幕样式。
风格是固定的——claude(温暖编辑风格;海军蓝代码表面,专为差异比较设计)。运行:
node <SKILL_DIR>/scripts/build-frame.mjs --preset claude --hyperframes .
该脚本将 claude 预设的 FRAME.md 复制为 frame.md,将其与 capture/extracted/tokens.json 中的任何品牌令牌重新混合(PR 没有令牌 → colors:[]/fonts:[] 保持 claude 自己的调色板,形成完整设计),将预设的字幕样式复制到 .hyperframes/caption-skin.html,并自我验证(在映射损坏时以退出码 1 退出)。一旦它以退出码 0 退出就继续——无需手动编辑。
关卡: build-frame.mjs 以退出码 0 退出——frame.md 已从 claude 预设存在,且 .hyperframes/caption-skin.html 已作为字幕样式源存在。
步骤 3:故事板与脚本
目标:将 PR 转化为经批准的逐帧解说计划。
阅读 references/story-design.md、../hyperframes-core/references/storyboard-format.md 和 ../hyperframes-core/references/script-format.md。使用它们编写 STORYBOARD.md,并在需要旁白时编写 SCRIPT.md。
使用 story-design.md 获取 PR 原型(变更日志/功能展示/修复讲解/重构讲解)、PR 原生帧类型、开场钩子、说服点、节奏、每帧字数预算以及可选的鸣谢结尾。顺序来自叙事设计,而非差异比较的文件顺序——解释变更,而非逐行朗读差异比较。展示 2–4 个真实差异比较片段(来自 capture/diff.patch),每个片段为一个短小易读的代码段;为每个片段在帧的 scene 中指定所需的 code-* 块。帧除了可选的 credits 结尾(2–6 个 assets/<login>.png 头像)外,不携带 asset_candidates。使用故事板和脚本参考中指定的确切必填字段。
起草后,展示一个逐帧摘要。在同一消息中询问用户 (a) 是否批准或请求修改,以及 (b) 是否希望进行故事板框架的实时预览(npx hyperframes preview)——仅当用户同意时才打开。迭代直到获得批准;将预览选择带到步骤 6。
关卡: STORYBOARD.md 存在,每帧都有必需的叙事字段,SCRIPT.md 在需要旁白时存在,且用户已批准计划。
步骤 3.1:音频
目标:根据批准的脚本生成旁白、单词时间戳、音乐和音频元数据。
在步骤 3 批准后开始音频处理。在后台运行它,然后继续到步骤 4。
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
音频脚本处理旁白、单词时间戳、从 HeyGen 音乐库查找 BGM 以及时间元数据。BGM 风格来自故事板的 music: 字段。此脚本使用 HeyGen Audio API 进行检索而非生成,并且使用与 TTS 相同的 ~/.heygen 凭据。有关提供商详细信息,请阅读 ../hyperframes-media/references/tts.md。
如果没有旁白且没有 SCRIPT.md,则跳过语音生成。如果故事板有音乐风格,BGM 仍可能运行。
关卡: 音频任务已启动,或项目标记为静音。
步骤 4:帧视觉设计
目标:为每个故事板帧添加视觉方向、布局意图和运动选择。
就地编辑 STORYBOARD.md。不要创建另一个故事板。使用 frame.md 作为颜色、字体、布局感觉和风格的唯一真实来源。
阅读 references/visual-design.md、references/composition.md、references/motion-language.md、references/code-vocabulary.md 和 ../hyperframes-animation/。使用 visual-design.md 获取所需的帧字段和必需的 ## Video direction 块,以及代码节奏如何将 code-* 块命名为其 focal。使用 code-vocabulary.md 为每个节奏选择正确的块(差异比较 = code-diff,重构 = code-morph,新代码 = code-typing,……)。使用 composition.md 获取布局/层级/焦点,使用 motion-language.md + ../hyperframes-animation/ 获取有效的效果和蓝图 ID。不要发明效果名称或块/蓝图 ID。
为每帧添加必需的视觉和运动字段,包括 effects 和 focal 和/或 roles。对于代码节奏,将 code-* 块命名为 focal,并让 effects 编排周围 claude 代码表面的动画(而非块本身拥有的代码动画)。添加一个视频范围的 ## Video direction 块。
不要更改故事、脚本、transition_in、asset_candidates 或 PR 来源。不要在此步骤编写 HTML。没有资产分阶段步骤——唯一的真实资产是鸣谢头像,它们已经位于 assets/ 中。
关卡: 每帧都有 effects 加上 focal 和/或 roles;代码帧命名了一个 code-* 块;## 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 <每个故事板中命名的注册表块>; do npx hyperframes add "$b"; done
在分发前,阅读 sub-agents/frame-worker.md 和 ../hyperframes-core/references/subagent-dispatch.md。为每帧分发一个子代理,尽可能并行;否则按波次运行工作者。每个工作者恰好得到一个帧。每个工作者的上下文必须包含 PROJECT_DIR、frame_id、画布大小、字幕状态和启用字幕时的保留条区域、ANIM_DIR(../hyperframes-animation/ 的绝对路径)以及 references/code-vocabulary.md 的绝对路径。每个工作者读取 frame.md、自己的 ## Frame N 块、每个引用的效果/蓝图 ID 的配方正文,以及——对于代码节奏——code-vocabulary.md 以获取命名块的输入。每个工作者仅写入 compositions/frames/NN-*.html;工作者绝不编辑 STORYBOARD.md。
每当一个工作者返回时,在 STORYBOARD.md 中标记该帧为 动画完成。
在音频时间戳存在后,在后台构建字幕并组装索引:
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(claude 的,在步骤 2 中复制),注入来自 frame.md 的品牌令牌;captions: skipped (<reason>) 是有效输出。assemble-index.mjs 只写入 compositions/index.html。
步骤 6:最终渲染
目标:将所有帧组件编译为最终视频文件。
等待步骤 5 的所有并发任务(字幕、索引和所有帧工作者)完成。然后在获得用户审批后,运行渲染:
npx hyperframes render videos/<project>\
--output renders/video.mp4\
--fps 30\
[--preview] # 如果用户在步骤 3 要求预览
渲染是服务器端视频合成,由 HyperFrames 引擎处理。render 命令将视频写入renders/video.mp4`。
关卡: renders/video.mp4 存在且可播放,包括音频(如果项目不是静音的话)。
附录 A:使用特定 PR 引用类型
- 完整 URL:
https://github.com/owner/repo/pull/123→ 提取为owner/repo#123 - 简写引用:
owner/repo#123→ 直接使用 - “此 PR”: 从已检出仓库的
git rev-parse --show-toplevel推断远程源
故障排除
| 症状 | 可能的原因 | 操作 |
|---|---|---|
fetch-pr.mjs 以退出码 1 退出 | gh 认证/PR 未找到/私有仓库 | 检查 gh auth status;验证 PR 可见 |
ingest.mjs 失败 | pr.json 格式错误 | 验证 pr.json 结构;消息记录后重新运行 |
| 头像缺失 | 仅限最佳努力 | 无操作;省略鸣谢结尾 |
| 渲染失败 | HyperFrames 引擎问题 | 检查引擎版本;消息记录后重新运行 |