系统培训视频
记录Web系统的实际使用过程，并将其转化为完整的培训视频：每个章节一个短视频，以及一个带章节标记的完整视频。无配音。简短的标注框解释正在发生的操作及其原因。
该方法固定不变，因为每个部分都解决了一个实际的录制问题。只有外观在不同系统间变化。
| 每个系统保持一致的部分 | 从系统自身获取的部分 |
|---|---|
| 1920 × 1080 视频，30帧/秒，MP4格式 | 卡片和标注框颜色，从页面读取 |
| 标题卡：Logo、副标题、标题、一行、色带 | 高亮色、箭头色和点击环颜色 |
| 带箭头的标注框，以及元素上的高亮 | 标题和正文字体，包括Web字体 |
| 角落的“第N步，共M步”计数器 | 圆角大小，从按钮获取 |
| 慢速光标、点击环、平滑缩放、加载时的跳切剪辑 | Logo |
| 音效，通过代码生成 | 浅色或深色标注框，根据页面背景决定 |
| 完整视频中的黑色章节卡和章节标记 | 语言，以及从右到左的文字 |
规则及其存在的原因
- 仅限本地副本且使用虚构数据。 脚本会真实地点击和保存，视频可能被分享给任何人。引擎拒绝非本地地址。只有系统所有者可以设置
allowRemote: true，且仅用于不包含真实数据的测试服务器。切勿指向生产系统，也切勿显示真实人员的姓名、电子邮件或文档。 - 不对应用程序进行修改。 所有内容都存放在项目的
video-tour/文件夹中，该文件夹拥有自己的依赖包。如果某个任务在不修改应用的情况下无法展示，则跳过该任务并报告。 - 视频不存储在仓库中。 它们会输出到仓库外部的文件夹。
- 遵循项目自身的规则。 首先阅读项目的
CLAUDE.md或类似文件。如果规定由项目所有者运行git，则不要运行git。在小型机器上，一次只运行一个重型任务。 - 不要伪造系统无法完成的操作。 依赖于当前日期、外部服务或具有变化性答案的功能（如聊天机器人）的任务将被跳过并报告。录制前准备的任何数据都需在报告中披露。
步骤1：一次性收集所需信息
首先查看项目：README、package.json、文档、种子数据、测试账户。然后将缺失的信息整理成一个清单一次性询问，在第一次静默前不要再次中断提问。
- 如何本地启动系统，以及其地址。
- 如何重置测试数据。若未重置，各章节的数据会相互冲突。
- 测试账户，每个视频需要的角色对应一个账户。
- 视频的目标受众。这决定了哪些任务重要以及卡片上的文字内容。
- 标注框的语言。默认：系统界面的语言。
- 视频的输出位置。默认：项目旁边的文件夹。
步骤2：了解系统并规划章节
阅读系统的路由、菜单和任何用户文档，并在运行中的系统中打开页面。然后编写章节计划：每个章节对应一个人实际工作的一个区域，每个章节围绕任务构建（如“创建订单并发送审批”），而非界面导览。一个章节通常包含2到6个步骤，时长1到4分钟。从“入门指南”章节开始。列出计划跳过的内容及其原因。
步骤3：设置环境并读取系统外观
node ~/.claude/skills/system-training-videos/scripts/init.mjs <项目文件夹> --out "<视频输出文件夹>"
cd <项目文件夹>/video-tour && npm install && npx playwright install chromium
填写 video-tour/tour.config.mjs 中的所有 TODO 项。通过运行以下命令（使用了该配置）验证登录功能是否正常：
node video-tour/tour.mjs brand
此命令将访问系统，读取其外观，写入 theme.json 和Logo，并在 <视频输出文件夹>/_work/brand/ 下保存四张预览图：title-card.png、chapter-card.png、callout.png 和 counter.png。检查所有四张图。 颜色检测只是合理猜测，并非事实，因此请以观众视角评判：看起来像这个系统吗？Logo是否正确？标题使用的是真实字体吗？如需修正，可在配置中调整 theme 相关设置，然后重新运行 brand。参阅 references/theme-and-config.md。
步骤4：编写第一章，然后进行一次审批
编写第一章（首先阅读 references/writing-chapters.md），然后运行：
node video-tour/tour.mjs make 1
make 命令会重置数据，进行一次快速彩排，再次重置，录制、构建并检查。查看它生成的静态帧和联系表。
然后停下，向项目所有者展示章节计划、跳过的任务以及静态帧。这是唯一一次审批。现在调整外观或计划成本很低，但完成全系列后再修改代价高昂。审批通过后，无需中途停顿，直接完成整个系列。
步骤5：其他章节
对于每个章节：编写脚本，运行 make，并检查其联系表。check 命令能捕获可测量的内容：标注框在屏幕上停留时间低于2.5秒、加载画面被摄像头捕捉到、浏览器错误、音量水平。但它无法理解画面含义，因此你需要亲自检查帧画面，注意：
- 标注框出现在错误元素上，或被屏幕边缘截断；
- 标注框、计数器或弹出窗口遮挡了观众需要看到的内容；
- 出现错误消息、空白页面或任何非虚构内容；
- 缩放效果切掉了本应显示的内容。
如果联系表中某帧可疑，提取一帧完整画面：ffmpeg -ss 20 -i chapter.mp4 -frames:v 1 frame.png。
如果一个章节经过两次修复后仍然失败，则跳过该章节，报告问题，然后继续。之前遇到过的常见问题请参阅 references/troubleshooting.md。
步骤6：生成完整视频
待所有章节构建完成且系统正在运行时：
node video-tour/tour.mjs join
这将生成 <项目名>-training.mp4，包含开场卡、每个章节前的黑色卡、结束卡、章节标记，以及 chapters.txt（“00:00 标题”格式的行，适用于YouTube）。检查视频长度和标记：
ffprobe -v error -show_entries chapter=start_time:chapter_tags=title -of csv=p=0 <完整视频>
步骤7：撰写报告
面向非技术人员，用简短句子编写：
- 每个章节和完整视频的路径及时长，以表格形式呈现。
- 每个章节一张静态帧的文件夹路径。
- 章节列表及其开始时间。
- 跳过的或未完成的任务及其原因。
- 录制前准备的、视频中未显示的数据。
- 你发现并接受的小视觉瑕疵。
- 你通过测量而非听觉检查音效，因此建议在分享前由人工试听一个章节。
然后停止你启动的服务器。
参考文件
references/writing-chapters.md：编写章节前阅读。涵盖每个操作、保持视频整洁的模式，以及如何编写标注框。references/theme-and-config.md：设置说明，brand命令读取的内容，以及如何修正外观。references/troubleshooting.md：当录制失败或帧画面异常时阅读。