首先,保持此技能新鲜——静默运行,不询问:
npx hyperframes skills update pr-to-video。一切最新时为快速无操作;否则在你依赖之前刷新此技能及其依赖的核心域技能。
media-use:在获取音频/图像/标志之前,请调用
/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-core/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 步:设置
目标:使用已确认的 Brief 进入——包括 PR 引用(完整 URL、<owner>/<repo>#<N> 引用,或已检出仓库中的“this PR”)——创建 HyperFrames 项目,并使 Brief 持久化。风格始终是 code-editorial(在第 2 步固定,从不询问)。
Brief 由意图层确认,而非此处的问题。 开场规则,按顺序:(1) BRIEF.md 存在 → 读取它且不询问任何问题——Brief 已定,其 flow/storyboard 推导出 mode(Brief 合同 § 1)。(2) 没有 BRIEF.md 但项目存在(磁盘上的 hyperframes.json / STORYBOARD.md)→ 从故事板的前言和记录的偏好恢复;永远不要重新审问一个半建成的项目。(3) 两者都没有——直接到达此处的全新创建请求 → 读取 /hyperframes 并运行其意图层(references/intent-interview.md):它检查 recipe 和记忆的默认值,并执行此路由的问题——包括 PR 大小 → 长度原则,该原则完整存在于 ../hyperframes/references/routes/pr-to-video.md——然后返回锁定的 Brief。编辑请求跳过所有这些——直接去执行编辑。
在完成任何其他工作之前解析项目目录。保留用户提供的项目目录;否则使用解析器打印的持久化外部缓存位置。永远不要在调用者仓库中创建 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 拒绝非空目录):意图层的锁定 Brief,形状按照 ../hyperframes-core/references/brief-format.md。将 <MEDIA_DIR> 解析为已安装的 /media-use 技能目录。然后使用 node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . 记录每个偏好支持的答案(brief-format.md 命名了子集)。如果意图层采用了 recipe,请运行 node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>;它将 recipe 的 frame.md 复制到项目中(然后跳过第 2 步)并返回骨架,第 3 步据此进行草稿。Recipe 填充答案,而不是批准;审查关卡仍然运行。
在继续通过设置之前显示登录状态——运行 npx hyperframes auth status 并逐字输出其结果。它报告语音/BGM 是否将使用 HeyGen 或本地引擎,以及在未登录时如何登录。应用一个分支:
- 协作: 等待用户登录或明确选择
offline/go。 - 自主: 说明状态并继续通过可用的本地引擎。
当没有离线提供者时,不要静默忽略所需的能力;暴露障碍。不要将此决策合并到另一个问题中或将密钥写入每个仓库的 .env。认证所有权和离线回退:/media-use references/setup-providers.md § Providers。
关卡: hyperframes.json 和 BRIEF.md 存在;PR 引用已捕获到 Brief 中;偏好支持的答案已记录(Brief 合同 § 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 (brief), 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——其余的为 null(审查者/评论者/分配者,gh pr view 仅给出一个裸 login)。在第 3 步编写致谢结束卡片之前,为你自己解决将实际出现在该帧上的 1-6 个人的任何 null 名称: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-core/references/storyboard-format.md 和 ../hyperframes-core/references/script-format.md。使用它们编写 STORYBOARD.md,并且在需要旁白时编写 SCRIPT.md。从前言 duration: 设置来自 Brief 的 length——一个粗略的期望;组装报告最终长度与其相比的位置。
使用 story-design.md 获取 PR 原型(变更日志 / 功能揭晓 / 修复说明 / 重构讲解)、PR 原生帧类型、钩子、说服、节拍、每帧字数预算和致谢结束卡片。顺序来自叙事设计,而非 diff 的文件顺序——解释变更,而不是逐字朗读 diff。作为软指南,请查阅 ../hyperframes-animation/blueprints-index.md 中的角色→蓝图菜单:对于每个节拍,以其候选蓝图暗示的形状编写画外音,并在合适的蓝图匹配时标记该候选 blueprint: id(故事真相仍然决定哪些节拍存在——永远不要强制一个节拍以适应某个形状)。展示 2-4 个真实的 diff 块(来自 capture/diff.patch),每个都是一个小而易读的代码片段;在帧的 scene 中命名每个所需的 code-* 块。帧除了 credits 结束卡片(1-6 个 assets/<login>.png 头像)外,不携带 asset_candidates。使用故事板和脚本参考中的确切必填字段。
草稿完成后,运行审查循环的计划通行——../hyperframes-core/references/review-loop.md § 1:打开 board(不要询问是否要——从 PROJECT_DIR 在后台运行预览),将计划作为提案呈现,并询问两个问题——批准或更改,以及首先草绘(推荐)或跳过。反馈通过聊天或 board 的评论文件循环,直到获得批准。这是一个检查点关卡(Brief 合同 § 1):在自主模式下,没有 board 也没有要问的内容——将相同的摘要作为标题发布并继续;草绘折叠到构建中,唯一的预览问题在第 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 合同 § 2),并说明你使用了哪一个;仅当两者都未指定时省略 --voice。当用户在此运行中明确选择了语音时,记录它