旁白示範
一個代理、一個下午、一個 VP 能在手機上觀看的 .mov。配方（已在五個片段、69–188 秒的長度上驗證）：
- 訪談使用者 — 五個問題，不超過（下方）。從你已有的情境中草擬故事；使用者編輯，而非撰寫。
- 撰寫場景規格（
clips/<name>.yaml）：4–8 個場景，每個場景約 25–45 字的旁白（≈ 10–18 秒的口語時間）。每個場景都有一個重點 — 事物出現的時刻 — 影片的剪輯方式是讓重點提前出現，而不是最後。 - 渲染：
scripts/render_clip.py clips/<name>.yaml。每個場景：TTS → 擷取 → 將影片配對音訊 → 字幕 → 合成；然後串接。 - 審查渲染器產生的靜止畫面（
out/_<clip>_<scene>.png）使用read工具，然後再宣告完成。使用--only s2重新渲染單個場景。 - 發佈（可選）：
scripts/slack_post.py <channel_id> out/<clip>.mov "<宣傳文字>"。
所有操作皆可重複執行並有快取（TTS 依文字哈希，影片依場景），因此在一個句子上迭代僅需花費數秒。
1. 訪談（先詢問這些，再草擬）
在一個訊息中詢問全部五個問題；接受部分答案，並從情境中填補其餘部分，標註你假設的內容。
- 影片是給誰看的，他們有多少時間？（同儕工程師 3 分鐘 · 高階主管 90 秒 · Slack 快速瀏覽 60 秒）→ 設定場景數量和節奏。
- 他們看完後應該相信的一件事是什麼？ → 成為場景 1 的第一句話和最後一個場景的最後一句話。
- 螢幕上必須顯示什麼？（一個 UI、一個終端機、一份文件、一個圖表、一個檔案）→ 決定擷取類型。詢問 URL / 指令 / 路徑。
- 「即時」的時刻是什麼？ 一個視覺上會發生的事情（查詢返回結果、建置完成、數字出現）。每個片段至少一個。
- 語音和語氣？ 預設值：
onyx，「冷靜、清晰、自信的技術示範旁白，中等速度，數字稍微強調」。如果使用者想要更輕快的語氣，可以提供alloy/nova。
然後以表格形式提議故事板（場景 · 螢幕上顯示的內容 · 1 行旁白摘要 · 重點）並在獲得同意後才進行渲染。渲染一個 5 個場景的片段需要約 3–6 分鐘；在獲得同意之前不要渲染。
2. 場景規格
clip: 1-setup # 輸出名稱 → out/1-setup.mov
size: 1440x900 # 可選：所有場景的通用畫面（調整大小並填充）— 在混合螢幕和瀏覽器場景時設定
voice: onyx
instructions: "冷靜、清晰、自信的技術示範旁白。中等速度，在句點處自然停頓。數字稍微強調。"
scenes:
- id: s1 # 簡短、穩定的 ID → 快取金鑰
caption: "論點 · 一個圖表，四項證據" # 下方標題；保持 ≤ 60 字元
narration: "…25–45 字…" # 如果 TTS 處理不好，則將數字寫成文字（"一萬八千"）
# 每個場景剛好一個擷取來源：
url: "http://127.0.0.1:4300/#mode=purchase" # (a) 透過 Playwright 的瀏覽器 — 加上可選的操作：
actions: # 在載入後依序執行；`ready` 標記重點
- fill: ["#prompt", "Acne Studios"]
- press: ["#prompt", "Enter"]
- wait: ".layer-chip" # 選擇器（45 秒超時）→ 設定 ready
- click: "button:has-text('fit')"
- select: ["#graph-layout", "brand"]
- scroll_to: "#join" # scrollIntoView（用於長文件）→ 設定 ready
- hover: ".card"
# video: "cache/cr_s3" # (b) 預先錄製的目錄（page.mov + marks.json）或一個檔案 — 請參閱 record_screen.sh
# still: "docs/figure.png" # (c) 一個靜態圖片（圖表、投影片）— 無 Ken Burns 效果，在旁白期間保持顯示
hold: 2 # 最後一個動作後的額外秒數
speed: 1 # 預先加速來源（8 = 以 8 倍速顯示的慢速爬行）
scale: 2560 # 每個場景的縮小寬度（螢幕錄製）；font: 28 = 此場景的字幕像素大小
讓這些片段表現良好的規則：
- 重點優先。 渲染器在
ready之前約 2.5 秒開始每個場景，如果旁白較長則填補最後一個畫面，如果較短則修剪。 一個重點在 45 秒錄製的第 40 秒的場景，會變成一個在重點處開場的 12 秒場景。 - 旁白與螢幕一致。 旁白中的每個大寫名稱和每個數字都必須在螢幕上可見或即將可見。刪除不符合的句子。
- 每個場景一個想法。 如果一個句子以「此外」開頭，那就是一個新的場景，或者刪除它。
- 字幕是大綱。 僅閱讀字幕就應該能了解整個故事。
- 切勿為旁白捏造數字。 從你剛製作的結果檔案或即時回應中取得；如果四捨五入則說「大約」。
3. 擷取來源
- 瀏覽器（
url+actions） — Playwright Chromium，1440×900，無頭模式，錄製 webm。需要一個含有@playwright/test和 Chromium 的 Node 專案；設定PW_REPO=/path/to/that/project（預設：技能自己的pw/— 執行scripts/setup.sh一次來建立它）。 - 螢幕 / 終端機（
video） —scripts/record_screen.sh <scene> <seconds> [--rect x,y,w,h] -- <command…>：啟動screencapture -V，執行你的指令，當指令透過列印MARK來表示重點時，將started（毫秒）寫入marks.json。 注意：screencapture -V僅在像素變更時前進；靜態終端機面板會凍結錄製。保持某些東西在運作 （一個 1 Hz 的時鐘行）或使用show_file.sh，它會用時鐘分頁顯示檔案。使用DEMO_SCALE=2560縮小寬擷取。 隱私： 錄製一個矩形（--rect，以點為單位；screencapture -R），這樣只會捕捉到你指定的面板 — 沒有視窗標題、標籤列、 側邊欄、 Dock、通知或背景視窗。在發佈前，閱讀每個審查靜止畫面並問：螢幕上的任何東西是否識別出 雇主、主機、內部 URL、其他人？中性化你分頁顯示的文字（show_file.sh）— 這是示範，不是你的真實檔案。 - 靜態圖片（
still） — 一個在旁白期間保持顯示的 PNG/JPG；用於圖表、表格、投影片。 - 預先錄製（
video: file.mov） — 搭配場景中的ready: <seconds>。
4. 渲染、審查、發佈
export OPENAI_API_KEY=… # TTS（gpt-4o-mini-tts）；或者對於相容的代理，使用 TTS_URL=https://<proxy>/v1/audio/speech TTS_API_KEY=…
scripts/render_clip.py clips/1-setup.yaml # 完整片段 → out/1-setup.mov（+ out/_1-setup_<scene>.png 靜止畫面）
scripts/render_clip.py clips/1-setup.yaml --only s2 # 重新渲染一個場景，重新串接
DEMO_FONT=26 scripts/render_clip.py … # 字幕大小（1440 px 用 22，2560 px 來源用 26–30）
審查：使用 read 讀取兩三個 out/_*.png 靜止畫面。如果瀏覽器場景記錄了 wait failed: … Timeout，表示應用程式速度慢或選擇器已變更：場景仍然會從 t=0 渲染（沒有重點剪裁）— 修正選擇器，或在應用程式閒置時使用 --only <id> 重新執行該場景（每個場景的起始畫面）— 檢查字幕是否可讀、重點是否在畫面中、沒有敏感資訊可見（權杖、買家層級的行數、其他人的訊息）。如果可能，觀看 .mov 的前 5 秒和後 5 秒。
發佈到 Slack，宣傳文字不超過 3 行：顯示的內容 · 長度 · 一個數字。scripts/slack_post.py C0123… out/1-setup.mov "…" 使用
~/.config/slack-mcp/credentials.json 中的 slack-mcp 瀏覽器工作階段憑證；如果不存在，則將檔案和宣傳文字交給使用者。
5. 慣例（保持專案整潔）
clips/ 規格 · cache/ TTS + 每個場景的影片（gitignored） · out/ 最終檔案 + 靜止畫面 · blurbs/ Slack 文字。按照播放順序命名片段
（0-…、1-…、2a-…）。保留一個 storyboard.md，內含來自訪談的表格；這是人們在觀看影片後會要求的文件。
相依性：ffmpeg/ffprobe、node ≥ 18、Playwright Chromium（用於瀏覽器場景）、macOS screencapture（用於螢幕場景）、一個 TTS 金鑰。
scripts/setup.sh 會檢查並安裝它可以安裝的內容。