media-use:在获取音频/图像之前,先调用
/media-use从 HeyGen 目录解析 BGM/音效/图像。首先运行--adopt注册现有资源。详见/media-use技能。
PR 到 HyperFrames
使用此技能来摄取 GitHub 拉取请求、理解变更、规划代码变更解说视频,并在 HyperFrames 中逐帧构建。输入是一个代码变更(通过 gh 读取),而不是网站——除了贡献者的头像外,没有捕获步骤和真实资源。
在步骤0之前确认路由。 你是编排者。按顺序运行每个步骤,验证其关卡,然后才继续。此技能适用于GitHub 拉取请求(代码变更)。将其他意图路由到别处:产品发布/推广 →
/product-launch-video;通用网站导览 →/website-to-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> 引用,或已检出仓库中的“this PR”),并在一条消息中确认简介——为每个选项提供推荐的默认值,并预填 /hyperframes 已设定的任何内容:角度(变更日志/特性展示/修复说明/重构指导——默认值:从 PR 推断)、受众(默认值:开发者)、时长(默认值:根据 PR 的变更规模进行调整——见下文)、宽高比(默认值 16:9)、语言。风格始终是 claude。仅在用户回复后继续;一个“go”接受默认值。
根据 PR 的变更规模推荐时长,而非固定猜测。在确认简介之前,先快速查看 PR 一次——这是一个只读调用,同时也用于夯实角度(步骤1仍会执行完整的确定性获取):
gh 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 的 kebab-case 格式命名 <project>,例如 acme-sdk-pr-1842;切勿使用工作区名称或时间戳。
npx hyperframes init "videos/<project>" --non-interactive --example=blank — init 检查已安装的技能是否与 GitHub 上的最新版本一致,并在任何技能过时时更新全局集合。
在简介前显示登录状态——运行 npx hyperframes auth status 并逐字转发其输出(不要改写或重写)。 它会报告语音/BGM 将使用 HeyGen 还是本地引擎,以及未登录时如何登录。如果未登录,停止并等待用户选择——登录,或说“go”/“offline”以使用本地引擎继续——然后再询问简介或其他任何事情。 将其视为一个真正的决策点,而非附带说明;不要将选择折叠到简介问题中,也不要将密钥写入每个仓库的 .env 文件。(在自主模式下,记录状态并以离线模式继续。)参见 ../hyperframes-media → Preflight 获取规范指导。
关卡: 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 / 未找到 / 私有),报告其 stderr 并停止——不要编造 PR 内容。如果 ingest.mjs 退出并返回 1,读取其 stderr(通常是格式错误的 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(温暖编辑风格;为 diff 构建的深蓝代码表面)。运行:
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 原生帧类型、钩子、说服、节拍、每帧字数预算以及可选的致谢结尾。顺序来自叙事设计,而非 diff 的文件顺序——解释变更,而非逐行朗读 diff。展示 2–4 个真实的 diff 片段(来自 capture/diff.patch),每个都是小而可读的代码片段;为每个片段在帧的 scene 中命名所需的 code-* 块。帧不携带 asset_candidates,除了可选的 credits 结尾(2–6 个 assets/<login>.png 头像)。使用故事板和脚本参考中的确切必填字段。
起草后,显示逐帧摘要。在同一条消息中询问用户 (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 音频 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 为每个节拍选择正确的块(diff = code-diff、refactor = code-morph、new code = 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的音频完成。然后同步时长并获取音效;如果项目为无声,则跳过两者。
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 中将该帧标记为 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(claude 的,在步骤2中复制),注入来自 frame.md 的品牌令牌;captions: skipped (<reason>) 如果返回,只需继续。
...
[truncated for translation]