Walkthrough Video（导览视频生成） 是做什么的？
将正在运行的 Web 应用转化为带有旁白、字幕和开场幻灯片的高清演示视频（MP4 + .srt），且当应用更新后可重新生成。整个过程全部在本地运行：无需视频编辑器，无需付费服务。
narration text -> local voice -> one WAV per scene + caption timings
real app -> Playwright scenes -> clips + marker times -> assemble.py -> walkthrough.mp4 + .srt
工作原理：录制的画面来自真实应用，因此始终真实可信；录制时会自动剪掉慢速步骤（如 AI 响应、页面加载）；每个场景记录的“标记”让合成器能将关键画面与对应的语音文字精确对齐。
准备工作
- 仅询问缺失的信息：应用是什么、视频必须展示什么、谁观看、目标时长（2 至 4 分钟效果最佳）、基调。
- 检查工具（详情见
references/setup.md）：Node 20+、带 Chromium 的 Playwright、FFmpeg（支持xfade、zoompan、loudnorm、libx264）、Python 3.11 或 3.12（带kokoro-onnx）。将语音模型（约 350 MB）安装到仓库外部，例如~/video-tools。 - 将工作文件复制到用户项目中，并确保生成的文件不被 Git 追踪：
mkdir -p e2e/video-kit && cp -R <this skill>/scripts/. e2e/video-kit/ && cp <this skill>/templates/*.mjs e2e/video-kit/ printf '\ne2e/video-kit/clips/\ne2e/video-kit/vo/\ne2e/video-kit/build/\ne2e/video-kit/*.mp4\ne2e/video-kit/*.srt\ne2e/video-kit/spec.json\ne2e/video-kit/.*.json\n' >> .gitignore - 阅读
references/toolkit-api.md一次。它记录了录制辅助函数和PLAN语法。不要修改rec.mjs、speak.py、overlays.mjs或assemble.py；只编辑指南中指定的部分。
工作流程：三道门
在每个门控处停下来等待用户确认。在录制之前修改措辞和结构成本很低，录制之后则代价高昂。
门控 1：故事板。 查看项目（文档、路由、现有的 Playwright 测试），建议 8 到 12 个场景。每个场景说明：屏幕上显示什么、旁白文本（20 到 35 个词，平实语言）、以及如何录制。如果用户需要背景上下文，可以包含开场幻灯片：问题、已完成或审计的内容、解决方案和技术栈。不要描述应用实际未做的事情；不确定时要询问。
门控 2：措辞与语音。 编写 chunks.txt，格式为 scene|text 行，每行约 12 个单词以内（每行将成为一条字幕）。在 speak.py 的 PRONOUNCE 中添加产品名称和缩写。运行 python speak.py 并报告每个场景的时长。用户需要试听并在录制前批准。
门控 3：录制、合成并检查。
- 基于
scenes.template.mjs编写scenes.mjs，每个场景一个片段，命名为scene-N以匹配默认计划。在后台逐个录制场景：node scenes.mjs <name>。仅重新录制失败的场景。 - 如果使用了幻灯片，渲染幻灯片（使用
slides.template.mjs），然后在assemble.py中填写PLAN和LABEL：哪个片段对应哪个场景，以及哪个标记落在哪一行旁白上。 - 运行
python assemble.py all。它将生成walkthrough.mp4和walkthrough.srt。 - 通过一个联系表（每个场景一到两帧，以平铺方式展示）而不是多个独立图片来检查结果：名称、日期、字幕、无截断、无隐私信息。修正后重新合成并交付。
重要规则
- 隐私。 使用演示或测试账号。模糊或遮挡任何显示真实人物、电子邮件、电话号码、账户名、密钥、ID、令牌或账单信息的内容（使用
opts.cover、opts.init）。绝不要处理密码：当某个场景需要登录时，让用户在可见浏览器中手动登录一次（使用templates/auth.template.mjs），然后复用保存的会话。绝不要在摄像头前输入或显示密码或双因素认证码。保持.env、保存的登录信息和浏览器配置文件不被 Git 追踪。 - 不要操作真实账号。 永远不要点击任何会发送、发布、安排或删除真实账号中内容的操作。将鼠标悬停在按钮上，说明它的功能。
- 不要虚构功能。 只描述代码和运行中的应用实际实现的功能。
- 语音和麦克风音频不能通过浏览器捕获。 展示界面并说明发生了什么。
- 在启动服务器前检查端口；停止你启动的所有服务。 对于超过一分钟的任务（录制、语音合成、合成），在后台运行并等待完成，而不是通过循环轮询。
- 回复保持简短。 报告你做了什么、文件路径以及你无法验证的任何内容。
实际使用经验
在编写场景前阅读 references/lessons.md。简要总结：验证种子数据确实存在（随机测试数据可能与旧数据冲突）；等待证明慢速页面已完成的定位器；清除搜索记忆的过滤器后再输入；关闭弹窗；直接链接到记录；将非必要的修饰逻辑包装起来，以免单个失败导致整个场景失败；保持幻灯片底部 200px 区域空白以显示字幕。
文件
scripts/rec.mjs录制器：平滑光标移动、点击波纹、缩放、标记、think()用于剪除等待时间。scripts/speak.py将旁白文本转为 WAV 和字幕计时。scripts/overlays.mjs将字幕、标签和标题卡片渲染为图片。scripts/assemble.py根据语音重新调整片段时长、拼接、叠加、混合音频、生成 MP4 和 SRT。templates/场景、登录保存、幻灯片和旁白文件的起始模板。references/工具包指南、设置和经验教训。
当出现故障时
- 语音失败并出现
espeakng_loader/phontab: No such file：请参阅references/setup.md。 - 场景因等待文本超时：页面可能尚未完成绘制，或者记忆的过滤器隐藏了目标元素。在失败时截取屏幕截图并查看。
- 视频中出现等待时间：将慢速步骤包装在
think()中。 - 画面和声音不同步：重新录制场景，因为标记时间会随着脚本变化而改变。