pr-to-video - 调度入口
输入是一个 GitHub 拉取请求(代码变更),以 PR URL、<owner>/<repo>#<N> 引用或当仓库检出且存在开放 PR 时的“this PR”形式提供。输出是一个 代码变更讲解视频:说明了什么内容、变更原因以及工作原理——通过差异/提交渲染为前后对比、差异高亮、文件树和影响场景。默认长度 最长约 3 分钟(最佳时长约 30-90 秒);真正的长篇或详尽的逐个文件讲解(5 分钟以上)属于不同范畴 → 转到 /general-video。没有网站抓取,也没有用于摄取的无头 Chrome —— 摄取是通过 gh CLI 完成的。内置样式预设始终为 claude(温暖的编辑风格;标志性的海军蓝代码窗口)。
在第 0 步之前确认路线。 此技能讲解一个 GitHub 拉取请求(通过
gh读取的代码变更)。如果输入是 营销/产品网站 → 转到/product-launch-video;通用网站 → 转到/website-to-video;不含 PR 的主题/文章 → 转到/faceless-explainer;整个仓库巡览或多 PR 发布 → 转到/general-video。超出范围:实时/渲染时数据——PR 事实在作者创作时读取一次并固定下来。如果提供了非 PR 输入,或不确定?请先阅读/hyperframes。
此工作流仅拥有 PR 特定的前端(摄取 + 故事设计);标记为 共享 的每个阶段都重用从 faceless-explainer 复制而来的引擎(它位于此技能自身的 scripts/ + agents/ + phases/ 下,因此 <SKILL_DIR> 解析为 pr-to-video)。
所有产物都放到 PROJECT_DIR = videos/<project-name>/ 下(在第 0 步创建);以下所有路径都相对于它。调度是适配器可移植的:在第一次分发子 Agent 之前,阅读 <SKILL_DIR>/../hyperframes-core/references/subagent-dispatch.md —— 它将调度动词(并行扇出 / 后台 / 等待)映射到您适配器的原语;低于 N 的并发限制意味着 N 个大小的批次,从不使用更少的工作者。此文件是一个具有约束力的运行手册,而非背景阅读:按顺序执行步骤,并使用指定的脚本或 Agent 角色生成每个阶段的产物——请勿替换为自由式管道,也不要因为请求看起来明确而跳过暂停步骤。如果某个步骤您无法执行 → 停止并报告。
| 阶段 | 执行方式 | 主要产物 | 详细流程 |
|---|---|---|---|
| init | Bash | hyperframes.json | 第 0 步 |
| ingest (自有) | Bash(gh CLI + ingest.mjs + fetch-people-avatars.mjs,无 Agent,无抓取) | capture/pr.json + diff.patch + extracted/{tokens.json,visible-text.txt,people.json} + public/avatars/ | 第 1 步 |
| design-system (共享) | Bash(无 Agent,确定性 claude) | design-system/design.html + chunks/ | 第 1b 步 |
| story-design (自有) | subagent | narrator_scripts.json | agents/story-design.md |
| audio (共享) | Bash 中的 audio.mjs | audio_meta.json | phases/audio/guide.md |
| visual-design (共享) | subagent | section_plan.md | agents/visual-design.md |
| prep (共享) | Bash 中的 prep.mjs | group_spec.json | scripts/prep.mjs |
| captions (共享, 详细) | Bash 中的 captions.mjs group -> captions.mjs html(无 subagent) | caption_groups.json + compositions/captions.html | scripts/captions.mjs |
| scenes (共享) | N x subagent(并行) | compositions/scene_*.html 或 compositions/group_w*.html | agents/hyperframes-scene.md |
| finalize (共享) | Bash 前奏(等待 BGM + 组装 + 注入/验证转场 + 提升视频 + SFX 验证 + 预检)-> finalize subagent(就地修复短暂发现 + 一次简洁的联系表查看 + 渲染) | renders/video.mp4 | 第 7 步 / agents/hyperframes-finalize.md |
前提条件
macOS Apple Silicon 或 Linux x64。系统工具:brew install [email protected] node ffmpeg(使用 Homebrew Python,不要用 /usr/bin/python3,否则 pip install 会被 PEP 668 阻止);然后执行 npx hyperframes doctor(下载 Chrome——用于快照/渲染,不用于摄取)。渲染的重叠检查门(scripts/check-overlap.mjs,在工作者的自检和预检中运行)重用相同的缓存 Chrome——它从不下载浏览器;其唯一依赖是 puppeteer-core npm 模块,在场景扇出之前确保一次(第 5.5 步,--ensure-deps,约 5 秒,无需完整安装 puppeteer)。CLI:gh(GitHub CLI,需认证——gh auth status 必须通过)和 hyperframes。可选的云密钥(否则使用本地回退)——在第 0.5 步注入:
| 密钥 / 要求 | 用途 | 默认 / 回退 |
|---|---|---|
gh auth status OK | 读取 PR(公开或私有) | 必填 —— 失败时显示认证提示信息 |
HEYGEN_API_KEY(或 hyperframes auth login) | TTS(云端,单词级别时间戳) | 语音:自动(第一个英语海星语音;可通过 --voice 覆盖) |
ELEVENLABS_API_KEY | TTS(云端;需要 pip install elevenlabs) | 语音 21m00Tcm4TlvDq8ikWAM (Rachel) |
| 两者都未设置,也未登录 | TTS | 本地 Kokoro,语音 am_michael(非英语:传递 --voice) |
GEMINI_API_KEY / GOOGLE_API_KEY(别名) | Lyria BGM | 未设置 -> 本地 MusicGen(首次运行下载约 300 MB) |
流程
第 0.0 步 - 确认简报(始终询问一轮,然后构建)
在第 0 步之前,始终暂停并以一条消息询问简报,然后等待用户——永远不要跳过这一步,即使请求看起来很完整。为每个字段推荐一个默认值,并预先填充用户已给出的信息(确认它,而不是盲目地重新询问):角度(更新日志 / 功能揭晓 / 修复 / 重构——默认:从 PR 推断),受众(开发者 vs 普通用户——默认:开发者),长度(默认约 60-90 秒),以及——如果 /hyperframes 没有设置它们——宽高比(默认 16:9)和语言。样式始终为 claude。只有在用户回复后才进入第 0 步;一个“开始”/“使用默认值”是有效的回复,表示接受所有默认值。
第 0 步 - 初始化视频项目
cwd 是 Agent 工作区的根目录(例如 /tmp/pr-video-...)。将所有视频产物写入 PROJECT_DIR = videos/<project-name>/。
<project-name>:使用用户给定的目录(例如 Use ./videos/retry-pr),否则从 PR 派生一个短横线连接的短名称(<repo>-pr-<N>,例如 widgets-pr-1187)。不要使用工作区的基础名称或时间戳。
仅当 $PROJECT_DIR/hyperframes.json 不存在时:
PROJECT_DIR="${PR_VIDEO_DIR:-videos/<project-name>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes init会向$PROJECT_DIR中投放通用的AGENTS.md/CLAUDE.md;将其保留在原处——它们是 Agent 脚手架,供以后打开已完成项目的人使用。
**约束条件:**切勿在工作区根目录下运行 hyperframes init / 生成 AGENTS.md / CLAUDE.md;切勿在 PROJECT_DIR 内嵌套另一个 hyperframes/;每个 Bash 命令(主控 + 子 Agent)都是一个 (cd "$PROJECT_DIR" && ...) 子 shell——切勿使用裸 cd。
第 0.5 步 - API 密钥指导
如果 $PROJECT_DIR/.env 存在或 context.log 非空(= 不是首次运行),则跳过。否则首先检测可用的内容(如果设置了 $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY 或 ~/.heygen/credentials 存在(来自 hyperframes auth login),则 HeyGen TTS 开启;仅当设置了其环境密钥时,ElevenLabs / Gemini 才可用),然后始终暂停并提供菜单——等待用户;即使检测到可行的配置,也不要自行继续(用户可能想要添加一个密钥,如 Gemini)。说明检测到的内容,然后:粘贴密钥(→ 写入 $PROJECT_DIR/.env,每行一个 KEY=value,覆盖同名密钥)/“开始”(使用已配置的内容——环境变量、.env 或 hyperframes auth login)/“跳过”(对任何未配置的内容使用本地回退继续)。然后进入第 1 步。
第 1 步 - 摄取(Bash,无 Agent,无抓取)
解析 PR 引用并使用 gh 提取结构化事实,然后将它们整合到共享后端期望的合成捕获包中(镜像 faceless-explainer 的无抓取脚手架)。gh 在此处,在编排器中运行,因此认证/未找到/私有仓库错误会通过 gh 自身的 stderr 显示;ingest.mjs 是一个纯离线转换工具。
# PR 引用:完整 URL、"<owner>/<repo>#<N>"、或检出仓库内的 "<N>"。
PR="<url | owner/repo#N | N>"
# 如果 gh 未认证,快速失败。
gh auth status || { echo "gh 未认证 — 运行: gh auth login"; exit 1; }
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && gh pr view "$PR" \
--json number,title,body,author,url,baseRefName,headRefName,commits,files,additions,deletions,changedFiles,labels,reviews,latestReviews,comments,assignees,reviewDecision,mergedBy \
> capture/pr.json)
(cd "$PROJECT_DIR" && gh pr diff "$PR" > capture/diff.patch)
# 将 pr.json + diff.patch 整合为 tokens.json(colors:[] → claude 原生调色板)+
# visible-text.txt(叙述性简报)+ people.json(PR 作者 + 提交作者及其计数 +
# 审阅者/评论者/受让人,经过机器人过滤和去重,每个都带有 GitHub 头像 URL)。
# (PR `author` 仅是开启者;提交作者来自 commits[].authors[] 也会被追踪。)
# ingest 是离线的。
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# 网络步骤(人员前端的唯一一个——ingest 保持离线):将每个贡献者的
# GitHub 头像下载到 public/avatars/<login>.png,用于可选的鸣谢 /
# 由谁发布特写。尽力而为——缺少头像或离线运行永远不会阻塞(exit 0)。
# 头像 + 那个特写是 pr-to-video 放宽无面孔默认值的唯一地方。
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
验证:
[ -s "$PROJECT_DIR/capture/pr.json" ] && \
[ -s "$PROJECT_DIR/capture/diff.patch" ] && \
[ -s "$PROJECT_DIR/capture/extracted/tokens.json" ] && \
[ -s "$PROJECT_DIR/capture/extracted/visible-text.txt" ] && \
[ -s "$PROJECT_DIR/capture/extracted/people.json" ] && \
[ -d "$PROJECT_DIR/capture/assets" ] && echo ok || echo missing
# public/avatars/ 是尽力而为的——其缺失并不是失败(未解析出头像 / 离线)。
如果 gh 出错(认证/未找到/私有),报告确切的 stderr 并停止——不要编造 PR 内容。如果 ingest.mjs 退出