插件安装: 在执行设置或更新命令之前,如果此技能位于 HyperFrames 插件内部,请遵循插件执行规则。独立安装请保留下面的更新说明。
首先,保持此技能最新——运行前与用户确认:
npx hyperframes skills update pr-to-video。如果一切是最新的,则快速无操作;否则,在依赖它之前刷新此技能及其依赖的核心域技能。
媒体使用(media-use): 在获取音频/图片/徽标之前,请调用
/media-use从 HeyGen 目录和官方来源的品牌徽标中解析背景音乐/音效/图片。首先运行--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 关卡的 mode。除了步骤 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 项目,并使简报持久化。风格始终是 代码编辑型(code-editorial)(在步骤 2 固定,从不询问)。
简报由意图层确认,而非此处的问题。 开场规则,按顺序:(1) BRIEF.md 存在 → 读取它,不问任何问题——简报已确定,其 flow/storyboard 派生 mode(简报合同 § 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: $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 并逐字输出其结果。它报告语音/背景音乐将使用 HeyGen 还是本地引擎,以及当未登录时如何登录。应用一个分支:
- 协作: 等待用户登录或显式选择
offline/go。 - 自主: 显示状态并通过可用的本地引擎继续。
当没有离线提供商时,不要静默省略必需的能力;揭示阻塞因素。不要将此决定合并到另一个问题中或将密钥写入每个仓库的 .env 文件。认证所有权和离线回退:/media-use references/setup-providers.md § 提供商。
关卡: hyperframes.json 和 BRIEF.md 存在;PR 引用已捕获在简报中;由首选项支持的答案已记录(简报合同 § 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:[] → code-editorial 调色板), 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),报告其标准错误并停止——不要编造 PR 内容。如果 ingest.mjs 以 1 退出,读取其标准错误(通常是格式错误的 pr.json),修复后重新运行(确定性)。fetch-people-avatars.mjs 始终以 0 退出;缺少头像仅意味着没有给作者的信用结束卡片。
people.json 为 gh 已经命名的贡献者(PR 作者、提交作者、mergedBy)携带 name——其余为 null(审阅者/评论者/分配者,gh pr view 只提供裸 login)。在步骤 3 编写信用结束卡片之前,为你自己解析实际出现在该帧上的 1-6 人的任何 null name:gh api users/<login> --jq .name(你已经有了 gh——无需为此编写脚本)。如果 GitHub 也没有该用户的公共名称,则在屏幕上回退到 login,并从旁白中删除该人(参见 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:设计系统
目标:采用 code-editorial 帧预设;一个脚本将其转为此视频的 frame.md + 字幕皮肤。
风格是固定的——code-editorial(温暖编辑风格;为差异构建的海军蓝代码表面)。运行:
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。从前言设置 duration: 来自简报的 length——一个粗略的预期;组装报告最终剪辑与其对比的位置。
使用 story-design.md 来确定 PR 原型(changelog / feature-reveal / fix-explainer / refactor-walkthrough)、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:将计划作为提案呈现,并询问两个问题——批准或更改,以及先草图(推荐)或跳过。反馈以聊天回复形式到达;循环直到批准。这是一个检查点关卡(简报合同 § 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_ 女性)。当
…
[因翻译而截断]