产品演示录制

产品演示录制 是做什么的？

将构图、隐私、叙事和解码输出视为独立的发布关卡。 成功的产品运行并不能证明录制是安全的、可读的或构图干净的。

有关原生 macOS 或浏览器捕获机制，请阅读 references/capture-macos.md。 有关包含轮询或重试循环的浏览器工作流，请阅读 references/browser-workflows.md。 有关标题卡、下方三分之一、图表、标注和结尾卡，请阅读 references/infographic-style.md。

首先确定交付帧

录制之前：

1. 在编写镜头列表之前选择叙事类型：
   • 概述 介绍产品形态：展示最具代表性的最小节点或屏幕序列，使用通用文案，并省略特定场景的解释。
   • 场景演示 回答一个具体问题：说明情况，展示实际执行阶段，并以验证结果结束。
   • 当两者都有用时，优先选择分开的短视频。除非用户明确要求组合演练，否则不要混合通用产品解释和特定领域案例。
2. 建立视觉参考：
   • 如果存在之前的录制，从头到尾检查它。如有用，提取联系表，并注意其节奏、构图、标注和最有力的解释时刻。
   • 如果没有之前的录制，则按照以下顺序使用 @themoltnet/design-system 库、相邻文档媒体和集成产品的原生 UI，在录制之前创建一张标题卡静态图、一张最密集的带注释 UI 静态图和一张结尾卡静态图。这些经过批准的静态图将成为系列中后续视频的基准。
3. 阅读视频将出现的页面。编写一个简短的镜头列表，指明用户成果、所需设置、主要交互、等待或重试行为以及成功结果。
4. 在安排应用之前选择最终宽高比和分辨率。首选传统的 16:9 帧，例如 1440x810 或 1920x1080。
5. 安排应用程序，使完整的目标内容区域适合该帧。必要时隐藏应用内的可选侧边栏；不要通过任意的后期制作裁剪来移除一半的侧边栏或控件。
6. 决定浏览器外壳是否是构图的一部分。首选干净的浏览器视口捕获。如果无法做到，则保留完整的浏览器窗口或将其放置在特定的框架内。完整的窗口比剪切的标签页、边缘或应用内容更干净。
7. 以实际显示尺寸查看三个代表性样式帧。在叠加系统、安全区域或信息层次仍在设计中的时候，不要录制完整的演练。

使用安全的捕获边界

• 捕获一个应用程序窗口或一个浏览器视口，切勿捕获另一个应用程序可以进入的桌面矩形。
• 在录制之前确定并锁定确切的窗口标识符。导航、弹出或应用程序重启后重新检查。
• 禁用通知并使用专用的演示数据，但不要依赖这些预防措施作为隐私边界。
• 将凭据、令牌、个人标识符、私人 URL 和不相关的账户数据保持在捕获表面之外。密码屏蔽是必要的，但并不能使凭据输入镜头变得可取。
• 使指针有目的地移动。在阅读静态结果时，将指针移离文本。

为便于理解而录制

• 每个镜头使用一个想法。在正常播放速度下，保持重要配置和结果的显示时间足以让人阅读。
• 仅在有助于观看者重现结果时才显示设置。对于集成演示，这通常意味着安装、认证而不泄露秘密、导入工作流、运行它并检查终端结果。
• 首选原生应用程序缩放和布局更改，而不是稍后放大裁剪的光栅图。
• 捕获真实的成功执行。重构的标题卡和标注可以解释它，但绝不能暗示未观察到操作或结果。
• 当动作本身不具有指导性时，以状态为主导的编辑可以使用来自一次真实运行的干净静态图。按观察到的顺序保留状态，保留可见的任务证据，仅使用过渡来传达进展。
• 在录制的拍摄之外完成凭据创建和连接测试。从安全的认证状态开始叙述，除非凭据设置本身就是文档主题。
• 当流程具有稳定阶段时，录制短小的、可独立使用的片段。这限制了重新录制，并使隐私审查更精确。
• 对于长轮询或重试循环，保留真实的顺序状态，但加速或修剪重复的空闲部分。以可读速度保持初始操作、终端工作流状态和可接受的结果。

编辑而不隐藏产品

• 保留每一个预期的应用边缘。缩小并填充到交付帧，而不是裁剪内容以强制宽高比。
• 仅当标题和结尾卡能改善定位或后续步骤时才使用它们。
• 将下方三分之一保持在预先规划的安全区域内。它们不得覆盖理解流程所需的控件、状态、输出、错误或标识符。
• 对于场景演示，让标注随执行推进。用一句话简短说明当前阶段及其后果，例如 INTENT — 提取地点和时间范围 后接 INTENT COMPLETE — 获取预报。使用产品的实际阶段名称和可观察状态；不要叙述隐藏的推理。
• 保持概述视频在视觉上比其伴随的场景演示更简洁。当节点标签和原生状态指示器已经足够时，它们应承担解释任务。
• 替换现有视频时，匹配已建立的文档视觉语言。不要让人觉得替换品比其取代的资产更随意。
• 为获得广泛的浏览器兼容性，默认使用 H.264 High、yuv420p、恒定 30 fps、无音频（除非有意添加旁白）和 MP4 fast-start。
• 在此 macOS 工具链上，实际可行时，首选单线程 libx264 进行最终渲染。提取精确时间戳的 QA 帧时，使用捆绑的辅助程序，而不是快速输入搜索。
• 如果某个帧在成品预览中显得损坏，请重新打开校验和稳定的成品并在原生播放器中检查视频。预览路径偶尔会以不同方式渲染相同的图像字节；除非缺陷可独立重现，否则不要更改视频。
• 如果某个帧在正常播放和重复提取中仍然损坏，则从干净源替换受影响的片段，并使用 -threads 1 重新编码最终母版。

仅在音频有价值时添加

• 将无声播放作为嵌入式文档视频的默认设置。当音频能实质性解释简洁视觉标注无法传达的时间、因果关系或上下文时，才添加旁白。
• 根据锁定画面编写和计时旁白。字幕或文本转录必须保留相同的信息，并且视频在静音时必须仍然可理解。
• 仅在该人明确授权的情况下，使用基于可识别人物建模的克隆或合成语音。在周围页面或致谢中披露该语音是合成的；不要将其呈现为真实的现场录制。
• 除非用户明确选择发布，否则请将语音样本、模型文件和生成的中间文件保留在仓库之外。将创建一次带旁白演示的授权视为限于该可交付成果，而不是对未来语音生成的持续同意。
• 在复用音频后重新运行交付质量检查。验证可理解性、电平、同步、字幕、声道布局，以及最终容器是否仍然满足视频交付规范。

审查解码后的可交付成果

对最终文件（而不是中间文件）运行捆绑的辅助程序：

.agents/skills/product-demo-recording/scripts/qa-video.sh \
  path/to/final.mp4 /private/tmp/demo-video-qa --interval 2 4 5 6

辅助程序将流元数据、一个顺序解码的联系表以及开始/中间/结束加上请求的时间戳帧写入为 JPEG。使用一个新的输出目录。

然后执行所有这些检查：

1. 以正常速度观看整个最终视频。
2. 检查联系表中的每一次应用程序、模态框、镜头、标注和结果状态变化。
3. 检查每个编辑边界前后和边界上的精确帧。始终添加审查反馈中指定的时间戳；不要推断相邻帧具有代表性。
4. 确认没有其他应用程序、桌面区域、通知、凭据、私人数据、裁剪的边缘、部分浏览器外壳、奇怪的黑色边框或遮挡的控件。
5. 确认文本可读、指针放置平稳、过渡干净、可见结果与周围文档匹配。
6. 对照交付规范验证编解码器、像素格式、尺寸、帧率、时长、音频选择和 fast-start 要求。

在这些检查针对将要提交的确切文件执行之前，不要将录制描述为已审查。

有目的地交付和保留

• 仅暂存最终资产和有意的文档更改。不要添加原始拍摄、凭据、浏览器配置文件或 QA 导出。
• 保留原始拍摄，直到最终文件经过审查并安全提交或上传。然后遵循操作员的保留选择；显式删除敏感临时捕获，而不是使用广泛的删除模式。
• 在交接时，说明展示了什么、最终技术属性、检查了哪些时间戳以及最终资产的位置。