showrunner 是做什麼的？
將「為我製作這個應用程式的展示影片」轉化為可重複執行、可審閱的檔案。CLI：node ~/.showrunner/bin/showrunner.mjs（或已連結的 showrunner）。從儲存庫執行 ./install-skill.sh 即可一次安裝。
使用時機
使用者想要一個你能在瀏覽器中開啟的網頁 UI 影片：產品展示、功能導覽、「顯示變更內容」的錄影、教學影片。不適用於原生桌面應用程式或任何需要語音旁白的內容。
操作流程：先思考，再執行
- 確認錄製安全。 僅限於本機、暫存或可丟棄的資料。絕不錄製含有真實客戶資料的正式環境。嚴禁將令牌放入腳本中；請使用
${env:NAME}。 - 啟動應用程式並植入真實資料。 空白狀態會讓展示效果很差。建立故事所需的記錄（成功案例、失敗案例、進行中的案例）。
- 先寫故事板，再寫 JSON。 展示影片控制在 4 分鐘內：一個標題卡、8-12 個場景（每個 8-20 秒）、一個結尾總結卡。每個場景一個重點。字幕應寫明 觀看者應注意什麼，而非滑鼠在執行什麼動作。
- 使用
probe尋找目標。 對每個頁面執行showrunner probe <url>；貼上它輸出的{role,name}物件。優先使用角色和可見名稱，而非 CSS。 - 驗證後再乾執行。
showrunner check s.json，然後showrunner run s.json --fast --strict。乾執行的長度約為實際執行的四分之一。在正式錄製前修正所有回報的步驟。 - 錄製正式版本（
showrunner run s.json --out out）。它會以實際時間執行，因此在背景啟動它並等待完成；不要讓工具呼叫停滯數分鐘。 - 審查畫面。
showrunner sheet out/<name>.mp4 --every 5，然後開啟產生的 PNG 檔案。檢查：字幕是否遮蓋主體（使用"position": "left"）、場景是否發生錯誤、彈視窗或導覽提示是否外洩、主題是否錯誤。 - 回報路徑、持續時間、解析度、場景列表，以及任何未正常運作的部分。除非使用者要求，否則不要提交或推送影片。
會浪費實際時間的陷阱
| 症狀 | 原因 | 修正方法 |
|---|---|---|
| 執行停滯數分鐘 | 一個錯誤的選擇器配上預設的 30 秒逾時，且重複發生 | Showrunner 預設為 8 秒並放棄該場景；先執行 --fast --strict |
| 連結或按鈕「不可見」 | 側邊欄在該狀態下收起，或選單關閉 | 先 goto 到已知頁面，或直接以頁面 URL 為目標 |
| 首次執行導覽在影片中途彈出 | 應用程式對新使用者顯示引導 | 在應用程式的 storage 中設定「導覽已看過」的金鑰，或在 dismiss 中列出「跳過」按鈕 |
getByText 匹配到隱藏的副本 | 文字也出現在隱藏節點中 | 使用 { "role": "button", "name": "/^ITEM-1\\b/" } |
| 文件側邊欄項目無作用 | 它們是 <button> 元素，而非連結 | 以 { "role": "button", ... } 為目標 |
| 字幕遮蓋抽屜或表單 | 底部中央的字幕與側面板重疊 | 使用 "position": "left" 或 "right" |
| 終端機退出時錄製中斷 | 背景工作與終端機綁定 | 以適當的背景任務執行並輪詢其完成 |
| 影片為空白或破碎 | 捕捉了 IDE 內嵌的瀏覽器 | 使用 Showrunner 自己的無頭 Chrome，而非網頁檢視 |
| 字幕些微偏移 | 提示時間從頁面建立時開始計算 | 用於審閱尚可；並非精確到影格 |
腳本速查表
{
"name": "demo", "baseUrl": "http://127.0.0.1:3000", "viewport": {"width":1440,"height":900},
"storage": { "token": "${env:DEMO_TOKEN}" },
"dismiss": ["text=Skip"],
"scenes": [
{ "name": "Title", "steps": [ {"goto":"/"}, {"card":{"title":"Acme","text":"Demo","hold":3000}} ] },
{ "name": "Create", "steps": [
{"caption":{"title":"1 · Create","text":"One click.","position":"left","hold":1500}},
{"click":{"role":"button","name":"New"}},
{"type":{"into":{"label":"Name"},"text":"Launch plan"}},
{"press":"Enter"}, {"wait":1500}
]},
{ "name": "Summary", "steps": [ {"caption":null}, {"card":{"title":"Summary","items":["A","B"],"hold":4000,"keep":true}} ] }
]
}
動作：goto click hover type press scroll wait waitFor caption card storage（以及在任何步驟加上 "optional": true）。
完整參考：儲存庫的 README。
安全性
- 腳本是資料：無程式碼執行，無 shell。字幕文字已跳脫。
- 失敗的步驟只會放棄其場景；
--strict會讓結束碼變為 1。 - 除非使用者要求，否則絕不提交、推送或分享影片。