Maestro Bug 影片
產出一個從未見過該錯誤的人也能無需協助理解的 MP4 檔案：一個標題卡標示錯誤名稱、每個步驟以白話文說明、一個字幕指出結果，以及一個停滯的最後畫面。該影片僅在背後執行的流程能證明主張時才具備證據力，因此 Maestro 的執行結果也是交付物的一部分。
兩種模式共用同一個工作流程：
| 模式 | 顯示內容 | 需求 |
|---|---|---|
explain | 僅執行一次錯誤版本 | 一個能重現錯誤的流程 |
compare | 錯誤版本與修復版本並排顯示 | 相同流程，外加包含修復的版本 |
前置條件
- 一個能重現錯誤的 Maestro 流程：它在錯誤版本上會於觀察到錯誤的步驟失敗，而在修復版本上則通過。若無此流程，請先撰寫；一個未觀察到錯誤的執行影片無法證明任何事。
maestro在 PATH 上（若專案鎖定了特定版本，則透過mise exec --使用專案鎖定的版本）、ffmpeg和ffprobe需具備drawtext濾鏡。在 Android 上，還需要adb以及 Python 3.10 或更新版本。- 能夠執行錯誤版本的裝置或模擬器，對於
compare模式尚需能夠執行修復版本的裝置或模擬器。
工作流程
路徑如 scripts/compose-bug-video 是相對於此技能的目錄；這些腳本不在 PATH 上。
-
讓流程易於閱讀。 為每個指令添加一個白話文的
label:，說明使用者做什麼或看到什麼。在編輯流程之前，請閱讀references/flow-tips.md；內容涵蓋標籤、錄製變體和速度。 -
準備錯誤執行的錄製變體。 複製流程，將觀察到錯誤的步驟標記為
optional: true，並將其重新標籤為Expected: <正確行為> – <實際發生的情況>。失敗的步驟會在渲染器完成之前結束執行；選擇性步驟仍會在影片和日誌中顯示 ⚠ 標記。 -
安裝版本。 從修正前的提交建構錯誤版本，而非手動還原檔案，除非修復僅為單行且立即恢復。在基礎提交上使用
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），並停止您啟動的殘留行程。 -
確認執行能證明主張。 錯誤錄製必須顯示所有設置步驟通過，而錯誤步驟顯示警告（Maestro 渲染器的 ✅ 和 ⚠；
record-maestro-run的綠色和琥珀色標記），且錯誤在螢幕上可見；修復錄製則必須顯示所有步驟通過。若任一項不符合，影片會產生誤導：請停止並修正流程或版本。 -
合成影片 使用
scripts/compose-bug-video：scripts/compose-bug-video explain --video before.mp4 \ --title "<App> · <Screen>" --subtitle "Bug: <使用者會說的一句話>" \ --steps "<一行內的步驟>" --caption "<觀眾應注意的內容>" --out bug.mp4 scripts/compose-bug-video compare --before before.mp4 --after after.mp4 \ --title "<App> · <Screen>" --subtitle "Bug: <一句話>" \ --steps "兩側步驟相同：<步驟>" \ --caption "左：<錯誤情況>。 右：<修復作用>。" --out before-after.mp4為團隊以外的人撰寫標題卡和說明：命名螢幕和可見的症狀，而非程式碼。橫幅標籤預設為「BEFORE · 目前應用程式」和「AFTER · 包含修復」（
--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），然後查看：文字必須完整且可讀，最後一個影格必須顯示錯誤，或錯誤與修復並排。
完成
回報影片路徑、其長度、兩側分別顯示的版本或提交，以及每個執行的 Maestro 結果。輸出保留在本機；發布或附加為附件由使用者決定。