Maestro Bug 视频
生成一个 MP4 文件，让即使从未见过该 Bug 的人也能无需帮助就能理解：一个命名 Bug 的标题卡片、每一步使用通俗语言描述、一个说明结果的字幕、以及一个停滞的最后一帧。视频只有在背后的运行能够证明其主张时才算是证据，因此 Maestro 的结果也是交付物的一部分。
两种模式共享一个工作流：
| 模式 | 展示内容 | 所需条件 |
|---|---|---|
explain | Bug 构建的单个运行 | 一个能复现 Bug 的流程 |
compare | 并排显示 Bug 构建和修复构建 | 相同的流程，以及一个包含修复的构建 |
前置条件
- 一个能复现 Bug 的 Maestro 流程：该流程在 Bug 构建上会在观察到 Bug 的步骤失败，在修复构建上通过。如果不存在这样的流程，请先编写；一个未观察到 Bug 的运行视频毫无意义。
maestro在PATH上（如果项目固定了版本，可通过mise exec --使用项目固定的版本），ffmpeg和ffprobe需支持drawtext过滤器。在 Android 上，还需要adb和 Python 3.10 或更新版本。- 能够运行 Bug 构建设备或模拟器，对于
compare模式还需要能运行修复构建的设备或模拟器。
工作流
路径如 scripts/compose-bug-video 是相对于该技能目录的；这些脚本不在 PATH 上。
-
使流程可读。 为每个命令添加一个通俗易懂的
label:，说明用户做了什么或看到了什么。在编辑流程之前，请阅读references/flow-tips.md；它涵盖了标签、录制变体和速度。 -
准备 Bug 运行的录制变体。 复制流程，将观察到 Bug 的步骤标记为
optional: true，并将其重新标记为Expected: <正确行为> – <实际发生的错误>。失败的步骤会在渲染器完成之前结束运行；可选的步骤仍然会在视频和日志中显示 ⚠。 -
安装构建。 从修复之前的提交构建 Bug 状态，而不是手动回退文件，除非修复是一行代码且您立即恢复它。在基准提交上使用
git worktree及其自己的构建输出，可以将两个构建分开。将每个构建放在各自的设备上，或者在录制之间重新安装。 -
一次录制一个运行。 每次录制之前，将设备留在主屏幕上或正在测试的应用程序上：直到流程的第一步更改屏幕，视频会显示设备之前显示的任何内容。 在 iOS 模拟器上，使用 Maestro 的渲染器：
maestro --device <bug-device> record --local <bug-variant.yaml> before.mp4 maestro --device <fix-device> record --local <flow.yaml> after.mp4始终传递
--local：没有它，Maestro 会将录制上传到其云端进行渲染。在 Android 设备或模拟器上，使用
scripts/record-maestro-run代替。maestro record会截断 Android 运行结束部分：screenrecord仅在屏幕变化时写入帧，而渲染器在最后一帧停止，即在运行的最终屏幕之前。该脚本直接录制屏幕，运行maestro test，保持最后一帧直到运行真正结束，并从 Maestro 的commands.json中绘制步骤：scripts/record-maestro-run --device <bug-device> --flow <bug-variant.yaml> --out before.mp4 scripts/record-maestro-run --device <fix-device> --flow <flow.yaml> --out after.mp4 --maestro "mise exec -- maestro"视频从流程的第一步开始，没有 Maestro 的启动画面。它退出时带有 Maestro 的退出码。只要设备的
screenrecord允许，录制就没有时间限制，例如 Android 17 上；旧版本在 180 秒后停止录制。对于输入密码等敏感信息的流程（例如从
${MAESTRO_PASSWORD}获取测试账户密码），需要在那个inputText上添加label:：maestro record会在其步骤列表中打印解析后的文本，因此未标记的步骤会在视频中显示密码。record-maestro-run从不显示解析后的值，它会在临时目录中保留 Maestro 的日志（其中记录了键入的文本），然后删除该目录。按顺序运行录制；两个分开启动的 Maestro 进程会竞争同一个驱动端口，导致两个运行都失败。在开始之前，检查没有先前的运行仍在活动（
pgrep -fl maestro），并停止您启动的残留进程。 -
确认运行能够证明主张。 Bug 录制必须显示所有设置步骤通过，并且 Bug 步骤出现警告（✅ 和 ⚠ 来自 Maestro 的渲染器；
record-maestro-run中的绿色和琥珀色标记），同时 Bug 在屏幕上可见；修复运行必须显示所有步骤通过。如果其中任何一个不同，视频会误导：请停止并修复流程或构建。 -
合成视频 使用
scripts/compose-bug-video：scripts/compose-bug-video explain --video before.mp4 \ --title "<应用> · <屏幕>" --subtitle "Bug: <用户会用一句话描述的问题>" \ --steps "<步骤，一行内描述>" --caption "<观众应该注意的事情>" --out bug.mp4 scripts/compose-bug-video compare --before before.mp4 --after after.mp4 \ --title "<应用> · <屏幕>" --subtitle "Bug: <一句话描述>" \ --steps "两侧步骤相同：<步骤>" \ --caption "左侧：<出什么问题>。 右侧：<修复做了什么>。" --out before-after.mp4为团队外的人员编写标题卡片和字幕：命名屏幕和可见的症状，而不是代码。横幅标签默认为 "BEFORE · current app" 和 "AFTER · with the fix"（可使用
--before-label、--after-label覆盖）；--hold设置最后一帧的停顿时间。 -
在移交之前检查结果。 提取标题帧和最后一帧（
ffmpeg -ss 1 -i out.mp4 -frames:v 1 title.png、ffmpeg -sseof -1 -i out.mp4 -frames:v 1 end.png）并查看：文本必须完整且清晰可辨，最后一帧必须显示 Bug，或 Bug 与修复的并排对比。
完成
报告视频路径、其长度、每侧显示的构建或提交、以及每次运行的 Maestro 结果。输出保持在本地；发布或附加它是用户的决定。