nolan 是做什么的？
导演不会按下录制键然后碰运气。他们会提前画好分镜、设计每一个画面，并完整地完成每一个镜头。 nolan 为软件演示做到了这一点：它将一个功能转化为可视化分镜脚本，驱动屏幕上真实的应用，像产品经理向用户展示产品一样旁白每一步操作，并为每个场景捕获一个清晰的视频片段。
输出的是一个演示视频，而非烟雾测试——这是那种你会放在产品着陆页或发送给客户、让第一次看到的人既能理解发生了什么，也能明白为什么重要的视频片段。
何时使用该技能
当实际任务是“为从未见过该产品的人制作一段可观看的产品操作视频”时，请使用此技能。包括：产品发布视频、功能展示、着陆页宣传视频、入门引导演示以及版本更新日志动效。
不要用它来测试流程——那是端到端测试，应该简洁且无头运行。nolan 优化的是相反的方向：可读性、节奏感和针对人类观众的旁白。
工作流程——三个阶段
| 阶段 | 你问…… | nolan 输出 | 参考文档 |
|---|---|---|---|
| 🎬 分镜 | “为功能 X 规划一个演示” | 场景逐一分镜脚本 (JSON)：标题卡、字幕、精确的点击/输入操作及等待条件 | reference/storyboard.md |
| 🎥 录制 | “开始录制” | 每个场景一个 .webm 文件，在正在运行的应用上实时驱动，并叠加标题卡 + 字幕旁白 | reference/recording.md |
| ✨ 精修 | “让它更可观看” | 经过审查和重新拍摄的版本：调整了节奏、完整了操作、清晰了字幕、修正了画面 | reference/polish.md |
阶段串联：分镜 → 录制 → 回看检查 → 精修 → 重新录制。分镜脚本是唯一事实来源；录制过程由其决定。
四大原则（不可妥协，每段视频都必须遵守）
这些原则将演示视频与简单录屏区分开来。它们不是可选项。
-
产品经理的口吻，而非测试报告。 向用户阐述价值——该功能让用户能做什么、为什么好——绝不提测试的机械过程。每条字幕看起来都像 PM 在带客户使用产品。参考
reference/pm-voice.md。 -
屏幕上的日常、易懂内容。 只使用普通用户能理解的输入内容——常规问题、现实示例（如“购买燕麦奶”、“给同事写感谢信”）。绝不使用生僻术语、内部代号或观众需要解码的“外星”概念。可读性优先。
-
先展示，再说明。 每个场景以全屏标题卡（产品名称 + 场景名称）开始，并持续显示嵌入式字幕旁白（顶部横幅），在每一步发生时解说相应内容，使观众永远不会迷失。参考
reference/captions.md。 -
在真实应用上完成完整操作。 驱动真实的产品——可见、类人速度的输入和真实的点击——在继续下一步前确保每个操作都已完全完成，然后保持画面稍作停留以便阅读。切勿中途截断回答或过渡。片段长度服务于完整性。
标准流程
- 明确演示范围。 确定产品、功能、服务 URL 以及目标观众。确认应用正在运行且可访问（nolan 录制真实的应用，不模拟）。
- 分镜。 编写
storyboard.json——每个想法对应一个场景，包含标题卡、有序步骤（输入/点击/选择/等待）以及按 PM 口吻编写的字幕。使用assets/storyboard-template.json作为模板。保持提示通用化（参见原则 §2）。 - 试运行选择器。 在正式录制前确认分镜中目标元素的选择器（占位符/角色/文本）在 DOM 中实际存在（错误的选择器会浪费整个拍摄）。
reference/recording.md涵盖了稳健的选择方法。 - 录制。 运行
scripts/record.py storyboard.json [scene ...]。它会注入字幕/标题卡覆盖层，驱动每个场景，等待完成，并将每个场景的.webm文件保存到分镜脚本指定的out_dir目录。 - 回看并精修。 对照
reference/polish.md检查每个原则——是否有剪辑不当之处？字幕是否使用了术语？输入速度是否看起来自然？每个操作是否完整？修正分镜脚本，然后只重新拍摄受影响的场景。 - 交付。 报告文件存放位置、大小/时长，以及每个场景的一行描述。如果需要，可提供封面帧或 GIF。
nolan 期望的环境设置
- Python + Playwright（
pip install playwright && playwright install chromium）。scripts/record.py使用同步 API 和record_video_dir来捕获.webm文件。 - 一个正在运行的应用，其 URL 机器可访问（本地开发服务器或允许录制的已部署环境）。
- 在应用中加载真实、非敏感的演示数据——参见原则 §2 和
SECURITY.md中的数据说明。绝对不要录制真实的客户数据或机密信息。 - 可选——语音旁白。 默认情况下演示视频是无声的（由字幕承担）。要添加类人语音旁白，请在分镜脚本中添加
voice块，并在步骤中添加vo行；这需要 ffmpeg（brew install ffmpeg）以及一个 TTS 提供方——ElevenLabs / OpenAI / Deepgram（需要 API 密钥，效果最接近真人）、Piper（离线、开源）、macOSsay（免费但机械感强），或者任何通过command模板自定义的工具。参见reference/narration.md。
关于录制工具链细节、覆盖层技术以及分镜步骤的完整参考，请参阅 reference/recording.md。
添加旁白（可选）
除非分镜脚本包含 voice 块，否则旁白默认关闭。当有人要求添加音频/旁白/让它“听起来像真人”时：
- 询问使用哪个提供方。 如需真正的类人音频，请使用云端提供方，并确认用户已设置（或即将添加）相应的 API 密钥：
ELEVENLABS_API_KEY、OPENAI_API_KEY或DEEPGRAM_API_KEY。用户也可以将command指向自己的 TTS 工具。 - 如果用户没有密钥，提供免费/离线备选方案（Piper 质量尚可，macOS
say零设置但机械感强）——或使用"provider": "auto"自动选择最佳可用方案。 - 如果用户两者都不想要，则不设置
voice（或设置"provider": "none"）——视频会像之前一样无声录制。
然后以与字幕相同的 PM 口吻编写 vo 行，并按常规流程录制；record.py 会合成音频并将其与视频混流。详细信息参见 reference/narration.md。
输出原则
- 每个场景生成一个视频，命名格式为
NN-slug.webm，便于独立重新拍摄。 - 交接时先说明可观看的结果（每个片段展示的内容），再说明技术细节（路径、大小、如何重新录制）。
- 优先选择多个简短、完整的场景，而非一个长片段——便于重新拍摄和复用。
- 如果某个镜头必须提前结束或字幕是占位符，请如实说明——诚实的“场景 3 仍需重新拍摄”比交付一个剪辑过的演示要好。