Communitygithub.com

tldraw/tldraw

为拉取请求创建一个带代码幻灯片和音频旁白的解说视频。在要求创建PR解说、PR视频或解说视频时使用。

tldraw 是什么?

该技能用于自动为GitHub拉取请求生成带有音频旁白的解说视频。它旨在作为内部制品,模仿PR作者通过Loom视频讲解代码变更的效果,让观看者快速理解PR的来龙去脉。该技能通过一系列步骤工作:首先理解PR的提交、差异和描述;然后以作者视角编写旁白脚本;接着调用Gemini TTS API生成分段音频;最后使用Hyperframes渲染引擎合成包含代码差异、幻灯片和同步字幕的MP4视频。该技能主要针对tldraw/tldraw仓库设计,可处理该仓库中任意PR,支持CLI工具和本地执行,输出1280×720分辨率、30帧/秒的MP4文件,并包含whisper转录生成的黄色字幕。

兼容平台✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/tldraw/tldraw/tree/HEAD/skills/pr-walkthrough

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

PR 解说视频

为拉取请求创建一个带音频旁白的解说视频。这被设计为一个内部制品,其目的类似于PR作者创建的一个Loom视频——逐行讲解代码变更,解释做了什么以及为什么这样做,以便任何观看者能快速理解PR。

输入: 一个GitHub拉取请求URL(例如,https://github.com/tldraw/tldraw/pull/7924)。如果只给了一个PR编号或其他描述,则假定该PR位于tldraw/tldraw仓库中。

输出: 一个1280×720(30帧/秒)的MP4视频,带音频旁白、whisper定时的黄底黑字字幕,以及标准化的开场/结束幻灯片,保存为 out/pr-<number>-walkthrough.mp4。

所有中间文件(音频、清单、脚本)都放在相对于此技能目录的 tmp/pr-<number>/ 目录下。此目录已被git忽略。只有最终的 .mp4 文件位于 out/ 目录下。

从本技能目录运行引用 ./scripts 或 ./video 的命令。

理念

这是从作者视角进行的一次解说。 目标与PR作者坐下来向某人逐行讲解变更一样——展示具体代码,解释改变了什么以及为什么,并按照增进理解的顺序进行。观看者应该能够理解代码的功能以及如何看待这些变更。

这意味着:

  • 旁白驱动一切。 首先编写旁白,作为对PR的连续解释。然后再决定每一时刻屏幕上应该显示什么来支持讲述的内容。
  • 展示代码。 默认的可视化内容是代码差异或源文件。文字幻灯片是例外(开场、简短过渡、结尾),而不是常规。当旁白提到一个函数时,观看者应该正在看着那个函数。
  • 按逻辑顺序讲解变更,不一定是文件顺序或提交顺序——但始终锚定在具体的代码上,而不是抽象的描述。
  • 解释“为什么”,而不仅仅是“是什么”。 屏幕上的代码展示了什么改变了。旁白补充了推理——为什么选择这种方法,它解决了什么问题,它处理了什么边缘情况。

工作流程

步骤1:理解PR

阅读PR的提交、差异和描述。理解叙事弧:

  • 这解决了什么问题?
  • 方法是什么?
  • 关键机制是什么?
gh pr view <number> --json title,body,commits
git log main..HEAD --oneline
git diff main..HEAD --stat

跳过自动生成的文件。 在阅读差异时,忽略自动生成而非手动编辑的文件。这些只会增加噪音而无助于解说。此仓库中的常见示例:

  • **/api-report.md, **/api-report.api.md — 生成的API表面报告
  • **/*.api.json, **/temp/*.api.json — API提取器输出
  • apps/docs/content/reference/** — 生成的参考文档
  • pnpm-lock.yaml, package-lock.json — 锁定文件
  • **/CHANGELOG.md — 自动生成的变更日志
  • 仓库工具重新生成的任何文件(快照、模式转储、打包资源)

如果不确定一个文件是否自动生成,请检查是否有类似“DO NOT EDIT”的头部注释,或者检查仓库是否有生成该文件的生成器命令。在选择要在 diff / code 幻灯片中展示哪些文件时,过滤掉这些文件。

步骤2:编写旁白

将旁白写成连续文本,分成逻辑段落。每个段落都是解说的一个节拍——一个概念、一个变更或一组相关的变更。将其保存为 tmp/pr-<number>/SCRIPT.md。

旁白应该像作者向同事解释PR一样:“那么,这是我们所做的...核心问题是X...我采用的方法是Y...如果你看看这个函数...”

结构:开场 → 背景/问题 → 代码讲解 → 总结。参见下面的脚本结构。

如果提交简单且组织良好(通常位于名称带有 -clean 的分支上),你可以按照它们的提交消息和描述来指导你的旁白。否则,检查代码并创建自己的叙事。按照能建立在先前概念之上的顺序引入概念。

避免冗余,尤其是在开场和第一个内容段落之间。

步骤3:生成音频和时间戳

每段调用一次TTS生成每段音频片段。这完全避免了分块、对齐和分割——每个段都足够短,以便单次可靠的TTS调用。

编写一个 narration.json 文件,然后运行 generate-audio.sh CLI工具:

./scripts/generate-audio.sh narration.json tmp/pr-<number>/

API密钥: 从仓库 .env 文件(GEMINI_API_KEY)自动获取。

旁白JSON格式

{
	"style": "以平静、稳定、专业的语气朗读以下解说旁白。以适中的速度说话,就像拉取请求的作者在向同事讲解代码变更一样。",
	"voice": "Iapetus",
	"slides": [
		"此拉取请求为箭头工具添加了组感知绑定解析...",
		"核心问题是当目标形状被分组时箭头绑定会失效...",
		"如果你看看ArrowBindingUtil.ts中的getBindingTarget方法..."
	]
}
  • style — 语音角色和语速说明。保持简短具体。
  • voice — Gemini语音名称(默认:Iapetus)。
  • slides — 旁白文本数组,每段一个条目。

工作原理

  1. 对于每个段落,脚本构建一个提示:风格前言 + 段落文本。
  2. 每个段落调用一次 gemini-3.1-flash-tts-preview API,直接生成一个WAV片段。
  3. 每个片段都经过验证(基于字数的时长合理性检查),如果输出不佳则自动重试。
  4. 每个片段的前导/尾部静音被修剪。

输出: 每段音频片段 (audio-00.wav, ...) 和一个 durations.json 文件,将每个音频文件名映射到其时长(秒)。

依赖项: ffmpeg / ffprobe。除了标准库外,不需要Python包。

不要在旁白文本中使用 [pause long] 或 [pause medium] 标记标签——模型可能会字面地读出来。

步骤4:编写清单

读取步骤3中 durations.json 中的每个片段时长,然后在音频文件旁边编写 manifest.json。它按顺序列出每个幻灯片的条目,每个条目包含 type、audio 和 durationInSeconds。

参见 references/manifest.md 了解幻灯片类型及其字段。

步骤5:渲染视频

运行 render.sh 脚本:

./video/render.sh \
  tmp/pr-<number>/manifest.json \
  out/pr-<number>-walkthrough.mp4

该脚本:

  1. 将引用的音频/图像文件复制到 video/assets/。
  2. 对每个音频文件运行whisper转录 → video/transcripts/audio-NN.json(幂等——仅当音频比现有转录更新时才重新转录)。
  3. 运行 build.mjs <manifest> 生成 video/index.html——一个带有每个幻灯片定时片段的hyperframes合成,包含GSAP时间线用于过渡和代码聚焦平移,以及基于whisper转录的开始/结束时间推导出的黄底黑字字幕片段。
  4. 检查合成正确性并通过 npx hyperframes render 渲染1920×1080帧。
  5. 通过ffmpeg降采样到1280×720 / 30帧/秒并重新压缩(CRF 26 + AAC 96k),生成最终小而清晰的MP4。

依赖项: Node.js 22+、ffmpeg、Python 3(由 render.sh 用于解析清单)。hyperframes 通过 npx --yes 调用,因此无需安装步骤。Whisper在本地运行(small.en模型,首次下载约150MB)。

通过whisper同步字幕

字幕以黄色文本显示在纯黑色药丸形状背景上,锚定在帧底部。它们的开始/结束时间来自whisper词级转录,按5-7个词分组,在自然停顿处提前断开(>450ms间隙 = 句子边界)。一个含义是:whisper会音译品牌/代码名称——例如,“tldraw” → “TL Draw”,“OverlayUtil” → “overlay util”。这对于字幕是可以接受的,但以后可以通过 build.mjs 中的替换表进行规范化。

文件大小调节

默认渲染目标为8分钟视频大约30-60 MB。要调整:

  • render.sh 内ffmpeg降采样步骤中的 --crf <n>——22接近无损,26是默认值,30+则更小。CRF 28-30是获得文档质量结果的良好范围。
  • 1080p hyperframes渲染使用 -q draft --crf 30 来保持中间文件较小(无论如何降采样主导最终大小)。

文件组织

最终输出位于此技能目录中。所有中间文件都放在 tmp/ 目录(已git忽略):

pr-walkthrough/
├── SKILL.md                    # 本文档
├── scripts/                    # CLI工具(已检查)
│   └── generate-audio.sh       # narration.json → 每幻灯片WAV + durations.json
├── video/                      # Hyperframes项目(已检查)
│   ├── hyperframes.json        # hyperframes配置
│   ├── meta.json               # 项目元数据
│   ├── build.mjs               # manifest.json → index.html 合成
│   ├── render.sh               # manifest.json → 720p MP4(完整流水线)
│   ├── assets/                 # 渲染时自动填充(已git忽略)
│   ├── transcripts/            # Whisper词级JSON(已git忽略,缓存)
│   └── renders/                # 中间1080p渲染(已git忽略)
├── out/                        # 最终输出(已git忽略)
│   └── pr-XXXX-walkthrough.mp4
└── tmp/                        # 中间文件(已git忽略)
    └── pr-XXXX/
        ├── SCRIPT.md           # 旁白脚本
        ├── narration.json      # 输入给generate-audio.sh
        ├── durations.json      # 音频文件名 → 时长(秒)
        ├── manifest.json       # 输入给render.sh
        └── audio-XX.wav        # 每段音频片段

API配置

  • Gemini API密钥: 存储为项目根目录下 .env 文件中的 GEMINI_API_KEY。用于TTS和音频对齐。
  • TTS模型: gemini-3.1-flash-tts-preview
  • TTS语音: Iapetus(始终)

脚本结构

解说遵循一致的叙事弧。并非每个部分都需要自己的段落——根据PR的复杂度合并或跳过部分。目标是总共8-12个段落,其中绝大多数显示代码。

开场(1个段落)

开场卡片:tldraw标志 + PR标题 + 日期。旁白应该是一个句子,在高层次上概述此PR的功能。暂时不要深入细节。

清单幻灯片类型:intro。

背景(0-1个段落)

在深入代码之前进行简要介绍。在此PR之前的情况是什么?什么问题或需求推动了这项工作?保持简短——只需足够的框架使代码讲解有意义。

  • 要具体:“当目标形状在组内时箭头绑定失效”而不是“绑定系统存在问题”
  • 指出受影响的代码库区域

如果在展示第一段相关代码的同时可以解释背景,则跳过独立的背景段落,将其合并到第一个代码段落中。

清单幻灯片类型:text 或 diff(如果展示有问题的代码)。

代码讲解(6-10个段落)

视频的主体部分。逐行讲解实际的代码变更,展示具体的差异和文件,同时解释做了什么以及为什么。

每个段落都应该显示代码。 使用 diff 幻灯片展示变更,使用 code 幻灯片展示未变更的参考代码。

指南:

  • 命名文件和函数。 每个旁白段落至少应引用一个特定的文件或函数。
  • 显示差异。 每个段落的可视化内容应该是正在讨论的实际差异。使用 git diff main..HEAD -- path/to/file 获取差异,然后提取相关的hunk。
  • 按理解顺序排列,而不是按文件排列。 按照构建理解所需的顺序展示变更。如果一个新类型在一个文件中定义并在另一个文件中使用,则先展示定义。
  • 解释“为什么”,而不仅仅是“是什么”。 差异显示了什么改变了——旁白补充了推理、它处理的边缘情况、考虑过的替代方案。
  • 跳过样板代码,但提一下。 不要为每个导入变更或类型导出都专门做一个段落,但可以在旁白中顺便提一句:“还有一些在 index.ts 中添加的类型导出——它们只是我们接下来将看到的新类型的重新导出。”
  • 将相关的小变更分组。 如果三个文件都得到了相同的一行修复,一个段落可以覆盖所有三个。通过名称提及每个文件。

总结(1个段落)

简要回顾PR完成了什么。这是一个简短的收尾部分——一两句总结整体变更,如果相关,提及任何已知的限制或后续工作。

清单幻灯片类型:text。

结尾(1个段落,静默)

tldraw标志,3秒静默。始终将此作为最后一张幻灯片。

清单幻灯片类型:outro,durationInSeconds: 3。

旁白编写技巧

  • 对代码要具体。 说“在 BindingUtil.ts 中,onAfterChange 处理程序现在检查组祖先”——而不是“绑定系统已更新。”命名文件和函数,以便观看者将旁白与屏幕上的内容联系起来。
  • 每个段落 = 一个变更或紧密相关的变更组。 如果你无法为段落指出一个具体的差异,它可能太抽象了。
  • 以作者身份写作。 语气应该是解释性和自然的——就像在带人查看你的工作。“所以主要的事情是...”或“棘手的部分是...”都是可以的。
  • 避免开场和第一个内容段落之间的冗余。
  • 提及未显示的文件。 如果一个PR涉及15个文件但只有6个有趣,简要提及其余的:“其余更改为类型导出和测试夹具。”
  • 目标是总共5-7分钟的旁白。

检查列表

  • 阅读所有PR提交并理解完整的差异
  • 在SCRIPT.md中编写旁白(8-12个段落)
  • 生成每段音频(Iapetus语音)
  • 读取durations.json获取每段时长
  • 编写manifest.json(基于references/manifest.md中的幻灯片类型)
  • 运行render.sh
  • 验证输出:音频同步、字幕、时长、文件大小
  • 删除tmp/pr-XXXX/(但将最终MP4保留在out/中)

提示

处理tldraw/tldraw仓库中的PR。请勿翻译此消息。

相关技能