视频培训:先有故事板,再展示真实应用
这里的培训视频由一组手机形状的卡片组成。每张卡片包含一个标题、一行帮助文本、一张带有标注的真实应用关键帧,以及一行旁白。部分卡片会播放应用的一段短视频片段代替静态截图。这些卡片也会以幻灯片和 PDF 的形式交付。
一切由同一个文件驱动:storyboard.json。Dave 通过设计画布编辑它;所有构建脚本都读取这个文件。
何时使用
适用于:
- 展示应用的培训、入门、快速开始或操作视频
- 面向技术员、顾问或配件人员的带注释截图或幻灯片指南
- 对使用此技能制作的现有视频进行修订(新措辞、新卡片、新片段)
不适用于:
- 营销或推广视频(风格和规则不同;请咨询 Dave)
- 产品内部录制的客户检验视频
- 尚未存在的屏幕模型(请使用
/visual)
原则
- 先故事板,后制作。 在 Dave 编辑完故事板画布并确认完成之前,不进行旁白或组装。
- 展示真实应用,执行真实操作。 真实的扫描、真实的听写、真实生成的故事。绝不使用模拟屏幕,绝不输入伪造的结果。
- Dave 在画布上做决策,而非在聊天中。 读取画布内容并进行比较。不要从对话中重构他的指示。
- 已认可的版本予以保留。 仅当文本发生更改时重新生成旁白。绝不覆盖 Dave 已审核过的版本;交付
-v2、-v3。 - Claude 无法听到或看到。 在每次交回控制权时明确说明。通过转录文本验证文字,通过示例帧验证图片,并指出哪些内容未经检查。
- 恢复原状。 恢复并确认模式,关闭重拍工单。
首先阅读
/Users/davidsonders/ro-bot/shared/product-facts.md和shared/brand.md:名称、计数、禁用词。不要使用长破折号,不要使用表情符号,“TenthGear”作为一个词。在观众看到或听到的任何内容中,绝对不说“single player”或“multi-player”。- 此文件夹中的
reference.md:技术陷阱,每个都已经付出过代价。 - 设计画布上的记忆笔记:
reference_design_canvas_mechanics、reference_design_canvas_roundtrip、reference_design_canvas_entity_crash。
存放位置
| 项目 | 位置 |
|---|---|
| 视频项目文件夹 | /Users/davidsonders/ro-bot/training-videos/<slug>/(绝不放在会随会话消失的会话临时文件夹中) |
| 唯一真实来源 | <project>/storyboard.json |
| 关键帧、片段、旁白 | <project>/frames/、footage/、narration/ |
| 构建输出 | <project>/out/ |
| Dave 接收的位置 | ~/Desktop/<Title>/ |
| 工作示例 | training-videos/story-writer-getting-started/ 和此目录下的 examples/story-writer/ |
脚本位于此目录下的 scripts/ 中。它们将项目文件夹作为第一个参数。
工作流程
为这些步骤创建一个待办列表,并按顺序执行。
第 0 步:确定需求
从请求中找出以下信息。仅询问缺失的部分,一次只问一个问题,并优先给出推荐方案。
| 决策项 | 默认值 |
|---|---|
| 观众是谁,以及担任的角色 | 技师 |
| 手机还是桌面 | 手机,390 x 844 |
| 哪个流程,从头到尾 | Dave 的大纲 |
| 商店和工作流模式 | 询问 Dave。见第 2 步。 |
| 仅静态截图,还是截图加片段 | 凡是有屏幕移动的地方都使用片段:录制、加载、打开和关闭 |
| 时长 | 2 分 30 秒以内 |
第 1 步:在设计画布上创作故事板
这是 Dave 首先看到的内容,也是他编辑脚本和标注的地方。
-
创建项目文件夹 并渲染任何道具(
props/render-paper.mjs用于生成纸版工单样本)。 -
探查流程以确定关键帧。 关键帧来自真实应用,因此此步骤需要一次捕获运行(第 2 步和第 3 步,仅截图)。将
examples/story-writer/capture-stills.mjs复制到项目中并重写流程。在继续之前查看每一帧。 -
起草
storyboard.json。 对于观众执行的每个操作,使用一张卡片。格式如下:{ "id": "write-story", "part": 2, "img": "10-write-story", "title": "点击 [[撰写故事]]", "body": "AI 助手将审查您的笔记并为您编写 3Cs。", "boxes": [[183, 400, 191, 44]], "arrow": [162, 768], "footage": { "clip": "C-write", "runs": [[15, 336]], "note": "片段显示的内容" }, "narration": "准备好了,就点击撰写故事。" }boxes和arrow使用手机像素单位;捕获程序会将其控制框信息写入帧旁。[[Label]]用于绘制按钮芯片。从第一版草稿起就遵循下面的样式规则。 -
创建画布。 使用工件工具:
quickstart,意图为design,然后使用返回的type_url和标题发布它。将 URL 保存在<project>/storyboard/artifact.json中。 -
将关键帧作为资源上传到画布(JPEG 格式,高 1688 像素,先暂存在临时文件夹中以便一次性发送)。记录每个返回的
/_blob/...URL,按帧名作为键存储在artifact.json的assets下。 -
生成并发布。
node scripts/storyboard-canvas.mjs <project>写入storyboard/project/。将该文件夹复制到临时文件夹并发布:canvas.json作为file_path,files中的每个.dc.html文件作为单独文件。 -
将链接交给 Dave 并停止。 告诉他:可以修改任何卡片上的文字,每张卡片下方的蓝色备注代表语音轨道,可以拖动黄色标注,在便签上写其他内容。不要开始制作。
-
收集他的编辑。 使用工件
read,并提供paths(索引和每个画板)和out_dir,然后运行node scripts/storyboard-harvest.mjs <project> <out_dir>。用通俗的语言向他报告结果,处理他添加的任何备注,然后使用--write参数重新运行。 -
再来一轮? 重新读取
project/canvas.json,使用--live <那个文件>参数重新生成,然后重新发布。不从当前实时索引开始的发布将被拒绝。
第 2 步:借用测试商店
应用必须处于视频要展示的模式。只能使用测试商店。
| 商店 | ID | 正常模式 | 备注 |
|---|---|---|---|
| Summit Auto Group (demo) | demo-dealership | 团队工作流 | Dave 用于向潜在客户演示。登录账号 [email protected] (技师)、marcus@ (顾问)、priya@ (配件)。仅用于第一个视频。 |
| Test Dealership 1 | mlTaPo12wbpUtJB9GXJM | 团队工作流 | 与构建会话共享。经常被占用。 |
- 执行
ListAgents,然后向每个同伴发送SendMessage询问:是否正在使用该商店,以及是否需要设置模式?等待回复。如果有同伴需要使用,则改用另一个商店或询问 Dave。 - 首先读取模式:在应用文件夹中运行
NODE_OPTIONS='-r dotenv/config' npm run --silent manage-org -- info <id>。 - 仅在捕获运行的几分钟内更改模式,并在与捕获和恢复相同的命令链中完成。然后再次读取并确认。
- 永远不要接触客户商店。永远不要更改测试账户的首选项。
第 3 步:捕获
- 静态截图:
dpr: 3。每张卡片对应一帧,在屏幕稳定后捕获。 - 视频片段:
dpr: 2,使用vt.recorder。每个片段以短暂的静止开始,显示手指标记,然后进行操作。读取marks.json文件来选择footage.runs。 - 听写是真实的。
vt.dictation播放一段音频片段到模拟麦克风中;应用会录制并转录它。打印每份转录文本并阅读:转录器会重写数字和品牌名称。 - 重拍需要使用新的维修工单。依次编号,并将每个 ID 列入
created-ros.txt文件中。
第 4 步:幻灯片
运行 node scripts/build-slides.mjs <project>,它会在 out/slides/*.png 生成幻灯片图片、PDF 文件以及视频需要的图层。查看每张卡片的缩略图列表。检查是否没有标注覆盖了它所指向的元素。
第 5 步:旁白
cd /Users/davidsonders/ro-bot/app
NODE_OPTIONS='-r dotenv/config' node ~/.claude/skills/video-training/scripts/narrate.mjs <project>
语音 ash,模型 gpt-audio-1.5(从 gpt-4o-mini-tts 迁移而来,OpenAI 将于 2027-01-06 关闭该模型)。如果某个音频录制的转录文本与卡片文本不匹配,则重试,然后拒绝。Dave 已批准此语音,并拒绝了 Mac 内置语音(认为太机械)。它使用应用的 OpenAI 密钥,每次构建成本仅几美分:在每个新视频的需求说明中说明这一点,以便费用不会令人意外。设置 DRY=1 可以列出将要重新生成的内容。
为听觉编写旁白:“R O”、“three Cs”、“tenthgear 点 A I”。在每个部分的第一张卡片上播报该部分名称。
第 6 步:视频
运行 node scripts/build-video.mjs <project>。速度设为 1.25 倍(QuickTime 的“Fast”),这是 Dave 认可的节奏。如果有片段的卡片,其时长以旁白和片段中较长者为准。
第 7 步:验证,并说明哪些未经验证
- 运行
check-audio.mjs转录音频并评估每张卡片。阅读每一条LOOK行。 - 从每张包含片段或箭头的卡片中抽取一帧并查看。
- 在交回控制权时,明确说明:未逐一收听,未从头到尾观看。
第 8 步:交付
将视频、PDF 和 out/slides/ 复制到 ~/Desktop/<Title>/。保留早期版本。提供时长、更改内容以及 Dave 可能注意到的任何事项(如片段中不同的工单号、标注覆盖在片段上等)。
第 9 步:清理
- 恢复商店模式,然后重新读取并确认。
- 运行
node scripts/close-ros.mjs <project> <email> <org-id>关闭重拍工单。删除工单由 Dave 决定。 - 通知您联系过的任何同伴商店已空闲。
样式规则(Dave,2026-09-29)
| 规则 | 示例 |
|---|---|
| 观众点击的按钮绘制为按钮 | 点击 [[新建工单]] |
| 部分标题要简短,不含“之三” | 第二部分:保修故事 |
| 封面不含步骤编号 | |
| 每个操作对应一张卡片。合并演示一个决策点的卡片。 | 审查和保存合并为一张卡片 |
| 删除观点不言自明的卡片 | 阅读“原因和修正” |
| 说明谁操作以及使用什么 | “添加语音备注”,而非“添加备注” |
| 当屏幕上两个元素都可能被误解时,指向其中一个 | 箭头指向绿色按钮 |
| 应用中任何移动的元素,视频中也应移动 | 波形、加载动画、卡片展开 |
| 车间用语 | 工单、行、故事、3Cs、CP |
Dave 通过 PDF 页码提供幻灯片编辑。第 1 页是封面,所以“第 7 页”指的是步骤 6。在应用每个编辑之前,先用步骤名称重述。
成功标准
- Dave 编辑了故事板画布,且其编辑内容已被准确收集,而非猜测
- 每一帧和片段都来自真实应用,且处于视频所要展示的模式
- 幻灯片、PDF 和视频均源自同一个
storyboard.json - 通过转录文本检查旁白;指出不清晰的句子
- 交回控制权时说明哪些内容未经听取或观看
- 商店模式已恢复并确认;重拍工单已关闭
- 项目文件夹保留在临时会话文件夹之外
相关技能
/visual:用于制作尚未存在的屏幕的模型/app-testing:用于此技能借用的测试账户和实时通行测试框架/compound:如果捕获过程暴露了产品缺陷或新的陷阱,可随后使用