首先,保持技能更新——运行前请先向用户确认:
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)→ 从故事板的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_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
能力预检在抓取、故事工作、音频或帧分发之前运行。如果安装的CLI无法运行此技能所需的验证命令,则以它的升级指令停止,而不是消耗本次运行的上下文。
仅在 $PROJECT_DIR/hyperframes.json 缺失时初始化。其basename来自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 并逐字中继其输出。它报告语音/BGM将使用HeyGen还是本地引擎,以及在登出时如何登录。应用一个分支:
- 协作模式: 等待用户登录或显式选择
offline/go。 - 自主模式: 说明状态并通过可用的本地引擎继续。
当没有离线提供商时,不要静默省略必需的能力;明确提出障碍。不要将此决策合并到另一个问题中,或将密钥写入每个仓库的 .env。认证所有权和离线回退:/media-use references/setup-providers.md § Providers。
关卡: 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 / not-found / private 错误在此处退出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 / not-found / private),报告其stderr并停止——不要编造PR内容。如果 ingest.mjs 退出1,读取其stderr(通常是格式错误的 pr.json),修复并重新运行(确定性)。fetch-people-avatars.mjs 始终退出0;缺失的头像仅意味着没有给作者的演职员名单结束画面。
people.json 为 gh 已命名的贡献者(PR作者、提交作者、mergedBy)携带一个 name——其余贡献者(审核者/评论者/指派者,gh pr view 只提供纯 login)为 null。在步骤3写入演职员名单结束画面之前,为你将实际出现在该帧上的1-6人自行解析任何 null 名字:gh api users/<login> --jq .name(你已经有了 gh——无需编写脚本)。如果GitHub也没有该用户的公开名字,则在画面上回退为登录名,并从旁白行中移除该人(请参阅故事设计.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 设置frontmatter的 duration:——一个粗略的期望;组装会报告最终时长与其的偏差。
使用 story-design.md 确定PR原型(变更日志/功能展示/修复说明/重构步骤演示)、PR原生帧类型、钩子、说服力、节拍、每帧单词预算和演职员名单结束画面。序列来自叙事设计,而非差异对比的文件顺序——解释变更,而不是朗读差异对比。作为软指南,查阅 ../hyperframes-animation/blueprints-index.md 中的角色→蓝图菜单:对于每个节拍,按照其候选蓝图暗示的形状编写旁白,并在匹配时标记该候选 blueprint: id(故事真相仍然决定哪些节拍存在——绝不要强行让节拍适合某种形状)。特色展示2-4个真实的差异块(来自 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),并说明你使用了哪个;仅当两者都没有指定时才省略 --voice。当用户本次运行显式选择了语音时,记录它(prefs.mjs record --key voice)。
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STOR
…
[已截断以进行翻译]