nolan

nolan 是做什麼的？

導演不會按下錄製鍵然後祈禱。他們會先繪製分鏡腳本、構思每個鏡頭，然後拍攝完整的片段。nolan 正是為軟體展示影片而設計：它將功能轉化為故事板，驅動你真正的應用程式在螢幕上操作，像產品經理向用戶展示產品一樣敘述每個步驟，並為每個場景捕捉清晰的影片。

產出的是展示影片，而不是冒煙測試——那種你會放在登陸頁面或寄給客戶的片段，讓初次觀看者能同時理解發生什麼事以及為什麼重要。

何時使用此技能

每當真正的工作是「為從未見過此產品的人製作一段可觀看的影片，展示產品操作」時，就使用它。這包括產品發表短片、功能展示、登陸頁面主視覺影片、入門引導教學，以及版本更新說明的 GIF。

請不要用它來測試流程——那是端對端測試，應該簡潔且無頭執行。nolan 專注於相反的方向：清晰易讀、節奏得宜，以及為人類觀眾提供的敘述。

工作流程——三個階段

階段	你問…	nolan 產出	參考文件
🎬 故事板	「規劃功能 X 的展示影片」	逐場景的故事板 (JSON)：標題卡、字幕、確切的點擊/輸入動作，以及等待條件	reference/storyboard.md
🎥 錄製	「開始錄製」	每個場景一個 .webm 檔案，對正在執行的應用程式進行即時驅動，並疊加標題卡與字幕	reference/recording.md
✨ 潤飾	「讓它更好看」	經過審查並重新拍攝的片段：修正節奏、完成所有動作、可讀的字幕、正確的畫面構圖	reference/polish.md

階段是連鎖的：故事板 → 錄製 → 回放觀看 → 潤飾 → 重新錄製。故事板是唯一的真相來源；錄製結果由故事板決定。

四項核心規範（不可妥協，每支影片必備）

這些是區分展示影片和螢幕截圖的關鍵。它們不是選項。

1. 產品經理的口吻，而非冒煙測試。 敘述對用戶的價值——這項功能讓用戶能做什麼以及為什麼好——絕不提及測試的機制。每句字幕讀起來都像是產品經理在引導客戶使用產品。請參閱 reference/pm-voice.md。

2. 螢幕上呈現日常、 relatable 的內容。 僅使用一般觀眾已經理解的輸入內容——常見問題、真實世界的範例（例如「購買燕麥奶」、「寫一封感謝信給同事」）。絕對不要使用生僻的行話、內部代號，或觀看者需要解讀的「外星」概念。親和力優先。

3. 先顯示，再說明。 每個場景都以全螢幕標題卡（產品名稱 + 場景名稱）開場，並包含內嵌字幕（頂部橫幅），在每個步驟發生時同步敘述，確保觀看者不會迷失。請參閱 reference/captions.md。

4. 在真實應用程式上完成完整操作。 即時驅動實際產品——可見、人類速度的輸入與真實的點擊——並且等待每個動作完全完成後再繼續，然後停頓使其可讀。永遠不要在回答或轉場中途截斷。長度服務於完整性。

標準程序

1. 界定展示範圍。 是什麼產品、哪些功能、在哪個 URL 提供服務，以及觀眾是誰？確認應用程式正在執行且可連線（nolan 拍攝的是即時應用程式；它不會模擬一個）。
2. 製作故事板。 草擬 storyboard.json——每個想法一個場景，每個場景包含標題卡、有序步驟（輸入 / 點擊 / 選取 / 等待），以及使用產品經理口吻撰寫的字幕。使用 assets/storyboard-template.json 作為格式模板。保持提示詞通用（§2）。
3. 執行選擇器測試。 確認故事板中目標的佔位符、角色或文字確實存在於 DOM 中，然後再進行完整拍攝（錯誤的選擇器會浪費整個片段）。reference/recording.md 涵蓋了穩健的選取策略。
4. 開始錄製。 執行 scripts/record.py storyboard.json [scene ...]。它會注入字幕/標題卡疊加層、驅動每個場景、等待完成，並將每個場景儲存為一個 .webm 檔案到故事板指定的 out_dir 目錄。
5. 回放觀看並潤飾。 根據 reference/polish.md 檢查每項規範——是否有任何部分被截斷、字幕是否包含行話、輸入速度是否像人類、每個動作是否完整？修正故事板，然後只重新拍攝受影響的場景。
6. 交付。 回報檔案存放位置、大小/時長，以及每個場景的一行描述。如有需要，可提供海報幀或 GIF。

nolan 預期的設定

• Python + Playwright (pip install playwright && playwright install chromium)。scripts/record.py 使用同步 API 與 record_video_dir 來捕捉 .webm。
• 一個正在執行的應用程式，位於機器可連線的 URL（本地開發伺服器或你被允許拍攝的已部署環境）。
• 應用程式中載入了逼真、不敏感的展示資料——請參閱規範 §2 以及 SECURITY.md 中的資料說明。切勿拍攝真實客戶資料或機密。
• 可選——語音旁白。 預設情況下，展示影片是無聲的（由字幕承擔）。若要加入人類語調的旁白，請在故事板中加入 voice 區塊，並在步驟中加入 vo 行；這需要 ffmpeg (brew install ffmpeg) 以及一個文字轉語音（TTS）提供者——ElevenLabs / OpenAI / Deepgram（需要 API 金鑰，最逼真）、Piper（離線、開源）、macOS say（免費、機械音），或透過 command 範本使用任何工具。請參閱 reference/narration.md。

請參閱 reference/recording.md 以了解驅動工具的細節、疊加層技術，以及故事板步驟參考。

加入旁白（可選）

除非故事板中有 voice 區塊，否則旁白功能是關閉的。當有人要求加入音訊/旁白/讓它「聽起來像真人」時：

1. 詢問使用哪個提供者。 要獲得真正自然的音訊，請使用雲端提供者並確認使用者已擁有（或將加入）API 金鑰：ELEVENLABS_API_KEY、OPENAI_API_KEY 或 DEEPGRAM_API_KEY。他們也可以將 command 指向自己的 TTS 工具。
2. 如果他們沒有金鑰，提供免費/離線的替代方案（Piper 品質不錯，macOS say 不需設定但語調機械）——或使用 "provider": "auto" 來自動選擇最佳可用方案。
3. 如果他們兩者都不想用，則不加入 voice（或設為 "provider": "none"）——影片會照常靜音錄製。

然後使用與字幕相同的產品經理口吻撰寫 vo 行，並照常錄製；record.py 會合成音訊並將其混入每個場景的影片中。詳細說明：reference/narration.md。

產出原則

• 每個場景一個影片，命名為 NN-slug.webm，以便獨立重新拍攝場景。
• 先提供可觀看的結果（每個片段展示的內容），再說明技術細節（路徑、大小、如何重新錄製）。
• 寧可選擇幾個較短且完整的場景，也不要一個冗長的片段——更容易重新拍攝和重複使用。
• 如果某個片段不得不提前結束，或某句字幕是佔位符，請誠實說明——「場景 3 仍需要重拍」遠比送出一個被截斷的展示影片好。