插件安装: 在执行设置或更新命令前,当该技能位于 HyperFrames 插件内时,请遵循插件执行规则。独立安装则保留下面的更新说明。
首先,保持技能最新——在运行前向用户确认:
npx hyperframes skills update pr-to-video。如果一切为最新版本,则为快速无操作;否则在依赖之前会刷新此技能及其依赖的核心领域技能。
媒体使用: 在获取音频/图片/徽标前,先调用
/media-use从 HeyGen 目录解析 BGM/SFX/图片,并从官方来源解析品牌徽标。先运行--adopt注册现有资产。参见/media-use技能。
PR 到 HyperFrames
使用此技能来摄取 GitHub 拉取请求,理解更改,规划代码变更解说,然后在 HyperFrames 中逐帧构建。输入是代码变更(通过 gh 读取),而非网站——没有捕捉步骤,也没有真正的资产,除贡献者的头像外。
入口是
/hyperframes。 你是编排者。运行每一步,验证其关卡,然后再继续。此技能用于 GitHub 拉取请求(代码变更)。任何其他意图,仅“制作视频”需求,或任何不确定性→先阅读/hyperframes——意图层拥有所有路由决策,一个没有BRIEF.md的新请求无论如何都会经过它(设置的初始规则)。
你是编排者。在解析的外部 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> 引用或已检出仓库中的“此 PR”)——创建 HyperFrames 项目,并使简报持久化。风格始终为代码编辑型(在第 2 步中固定,绝不询问)。
简报由意图层确认,而非此处的提问。 初始规则,按顺序:(1) BRIEF.md 存在→读取它并不提问——简报已确定,其 flow/storyboard 派生“模式”(brief contract § 1)。(2) 没有 BRIEF.md 但项目存在(磁盘上的 hyperframes.json / STORYBOARD.md)→从故事板的前置数据和记录的首选项恢复;永不重新盘问半成品项目。(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" && …);切勿更改调用者仓库的工作树。
在 init 后立即写入 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 并逐字输出其结果。它报告语音/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 携带 name 用于 gh 已命名的贡献者(PR 作者、提交作者、mergedBy)——对于其余部分(审查者、评论者、指派者,gh pr view 只提供裸 login)为 null。在第 3 步写入制作者名单结束画面之前,为你自己解析任何 null name,用于实际出现在该帧上的 1-6 人: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。使用它们来编写 STORYBOARD.md,并在需要旁白时编写 SCRIPT.md。从简报的 length 设置前置数据 duration:——一个粗略期望;组装会报告最终成片相对于它的位置。
使用 story-design.md 获取 PR 原型(变更日志/功能展示/修复讲解/重构讲解)、PR 原生帧类型、钩子、说服力、节拍、每帧字数预算和制作者名单结束画面。顺序来自叙事设计,而非差异的文件顺序——解释更改,而非逐字朗读差异。作为软指南,咨询 ../hyperframes-animation/blueprints-index.md 中的角色→蓝图菜单:对于每个节拍,编写画外音,使其形状符合候选蓝图隐含的形状,并在合适时标记候选 blueprint: id(故事真相仍然决定哪些节拍存在——绝不强制节拍去适应形状)。展示 2-4 个真实差异块(来自 capture/diff.patch),每个为小的易读片段;在帧的 scene 中命名每个所需的 code-* 块。帧除了 credits 结束画面(1-6 个 assets/<login>.png 头像)外,不携带 asset_candidates。使用来自故事板和脚本参考资料的确切必填字段。
起草后,运行审查循环的计划通道——../hyperframes/references/review-loop.md § 1:将计划作为提案呈现,并询问两个问题——批准或更改,以及先草图(推荐)或跳过。反馈以聊天回复形式到达;循环直到批准。这是一个检查点关卡(brief contract § 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_ 为女性)。当用户未表达偏好时,在回退到管道默认值之前先回退到记住的语音(brief contract § 2)。