插件安装: 在执行设置或更新命令之前,当此技能位于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之外,你自己执行每个步骤,在步骤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项目,并使简报持久化。样式始终是代码编辑(在步骤2中固定,无需询问)。
简报由意图层确认,而非在此处通过提问确认。 开启规则,按顺序:(1) BRIEF.md存在 → 读取它,不询问任何内容——简报已定案,其flow/storyboard派生模式(简报合同§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引用已捕获在简报中;偏好支持的答案已记录(简报合同§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),报告其stderr并停止——不要编造PR内容。如果ingest.mjs以1退出,读取其stderr(通常是格式错误的pr.json),修复并重新运行(确定性)。fetch-people-avatars.mjs总是以0退出;缺少头像仅意味着没有作者演职员表结尾。
people.json携带一个name,用于gh已经命名的贡献者(PR作者、提交作者、mergedBy)——其余的为null(审阅者/评论者/分配者,gh pr view只给出一个裸露的login)。在步骤3中写入演职员表结尾之前,为你自己解析任何将实际出现在该帧上的1-6个人的null名称: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 .
该脚本将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原型(变更日志/功能展示/修复解释器/重构演练)、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_女性)。当用户没有表达偏好时,在流水线默认值之前回退到记住的语音(简报合同§2)。
运行音频生成:
(cd "$PROJECT_DIR" && node <MEDIA_DIR>/audio/scripts/generate-audio.mjs \
--script ./SCRIPT.md --storyboard ./STORYBOARD.md \
--output ./audio_meta.json [--voice <id>])
generate-audio.mjs会生成一个音频文件(assets/voiceover.wav)并填充audio_meta.json,其中包含单词时间戳(words:{word, start, end}数组)和用于背景音乐(BGM)的tracks条目。BGM的选择基于tokens.json中的mood(例如“uplifting”、“technical”、“dramatic”),如果存在的话;否则回退到../hyperframes-creative/music/default.json。该脚本还会验证总时长与STORYBOARD.md中的估计值是否大致匹配,如果偏差超过20%,则发出警告。
门槛: audio_meta.json存在,并且assets/voiceover.wav已生成(或为无解说模式提供占位符)。
步骤4:视觉设计
目标:通过添加场景描述、示意图和动画指令来丰富故事板。
阅读../hyperframes-animation/rules/visual-composition.md和../hyperframes-creative/references/visual-design.md。然后运行视觉设计脚本:
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/enrich-storyboard.mjs \
--storyboard ./STORYBOARD.md --frame ./frame.md \
--tokens ./capture/extracted/tokens.json --audio ./audio_meta.json \
--output ./STORYBOARD.md)
enrich-storyboard.mjs会用以下内容丰富STORYBOARD.md:
- 场景描述: 每个帧的视觉布局的详细文本描述(例如,“左上角:差异块高亮显示添加的行;右下角:函数签名的缩放镜头”)。
- 示意图: 用于帧结构的轻量级ASCII艺术或伪代码布局(例如,
[代码 | 覆盖层 | 字幕])。 - 动画指令: 对帧工作者子代理的引用,用于过渡(例如,“
anim:fade-in code-block with delay 0.5s”)。
该脚本还会验证音频时间戳与帧时长的一致性,如果检测到不匹配则标记。输出是就地更新STORYBOARD.md,添加一个Visual Design部分到每个帧条目。
门槛: 丰富后的STORYBOARD.md为每个帧包含场景描述、示意图和动画指令,并且没有音频/视觉时间不一致。
步骤5:帧装配 (Frame Assembly)
Goal: Dispatch frame workers to build individual HTML frames and an index.html player. You are the orchestrator — delegate to a bounded pool of sub-agents.
You are the orchestrator — delegate to a bounded pool of sub-agents. Read ../hyperframes/references/frame-worker-dispatch.md for the exact pool bounds (max 4 concurrent workers for PR-based projects) and the frame-assignment protocol: each worker receives a slice of frames (e.g., frames 1–4, 5–8, …), writes them to compositions/frames/NN-*.html using the enriched STORYBOARD.md, frame.md, audio_meta.json, and capture/extracted/ assets, and returns once its batch is complete. Workers must not block on each other or on network calls beyond those already cached.
Workers build each frame as a self-contained HTML file that references shared resources (fonts, CSS, JS) from a compositions/assets/ symlink tree created by a setup script:
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/setup-compositions.mjs \
--storyboard ./STORYBOARD.md --frame ./frame.md \
--audio ./audio_meta.json --assets ./assets --out ./compositions)
This script validates that all referenced assets exist and creates the symlink structure. If it fails, surface the missing assets and stop — do not proceed with broken frames.
Workers then run independently. After all workers finish, build the index.html player that sequences the frames with synchronized audio:
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/build-player.mjs \
--frames-dir ./compositions/frames --audio ./assets/voiceover.wav \
--audio-meta ./audio_meta.json --output ./compositions/index.html)
Gate: All frame HTML files in compositions/frames/ exist (one per storyboard frame), index.html exists as a working player, and the setup script exited 0.
Step 6: Final Render
Goal: Render the assembled frames into a video file with audio, apply final quality checks, and present the result.
Run the render command:
(cd "$PROJECT_DIR" && npx hyperframes render \
--input ./compositions/index.html \
--output ./renders/video.mp4 \
--width 1080 --height 1920 \
--fps 30 --quality high)
After rendering, run the quality assurance script:
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/qa.mjs \
--video ./renders/video.mp4 \
--storyboard ./STORYBOARD.md --audio ./audio_meta.json)
qa.mjs checks: video duration matches storyboard estimate (±10%), audio synced, no missing assets, and frame transitions are smooth. It outputs a JSON report with pass/fail for each check.
This is a user-gated step (brief contract § 1) — present the rendered video and the QA report to the user. In collaborative mode: ask the one question: "Does this video meet your expectations?" — accept feedback as a chat reply and loop (re-edit → re-render → re-QA) until approved. In autonomous mode: post the QA report as a heads-up; the video is considered approved by default unless the user explicitly objects within the context window.
Gate: renders/video.mp4 exists, QA report shows all checks passed or known exceptions documented, and the user has approved (autonomous: no objection received).
Post-Step: Usage Report
After Step 6 approval, summarize the run for the user: PR reference, video duration, frame count, any skipped frames, and the render quality. Store usage metadata to $PROJECT_DIR/render-log.json for future reference.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/log-usage.mjs \
--pr "$PR" --duration <video_duration> --frames <frame_count> \
--status success --output ./render-log.json)
Error Handling & Rollback
- Any script exits non-zero: Read stderr, attempt a fix (re-run with corrected params), and if that fails, stop with a clear error message. Do not silently proceed.
- PR fetch fails (exit 1 from fetch-pr.mjs): Stop immediately — do not fabricate data. Report the
gherror to the user. - Missing assets: If
fetch-people-avatars.mjsfails silently (it always exits 0), note it in the credits but do not block. If other mandatory assets are missing (e.g.,capture/diff.patch), surface the blocker. - Partial renders: If Step 5 or 6 fails, preserve
compositions/andcapture/for debugging; roll back only temporary files. - User cancels mid-step: Clean up by removing incomplete renders but keep the project directory.
References
The following references are read by various steps. They live relative to this skill's directory (<SKILL_DIR>):
../hyperframes/references/brief-contract.md— gate types, brief structure, mode derivation.../hyperframes/references/brief-format.md— BRIEF.md file format.../hyperframes/references/storyboard-format.md— STORYBOARD.md required fields.../hyperframes/references/script-format.md— SCRIPT.md required fields.../hyperframes/references/review-loop.md— collaborative/autonomous approval gates.../hyperframes/references/frame-worker-dispatch.md— worker pool bounds and assignment.../hyperframes-creative/references/story-spine.md— narrative structure principles.references/story-design.md— PR archetype and frame type guidance.../hyperframes-animation/blueprints-index.md— role→blueprint mapping.../hyperframes-animation/rules/visual-composition.md— layout and animation rules.../hyperframes-creative/references/visual-design.md— visual design enrichment guidance.../hyperframes-creative/music/default.json— default BGM track.../hyperframes/references/routes/pr-to-video.md— PR-size→length doctrine.../hyperframes/references/plugin-installation.md— plugin setup rules./media-useskill directory (resolved via<MEDIA_DIR>) for audio/asset scripts.