agent-demo-film 是做什麼的？
一部示範影片只有在螢幕上的內容是真實的、且與人物當下所說的話完全一致時，才值得傳送。這個技能讓人只需要做一件事：一次坐下來對著鏡頭唸完腳本。其他工作——研究、擷取畫面、撰寫腳本、剪輯與後製——全部由代理程式完成。
1 準備 ─> 2 擷取 ─> 3 腳本 ─(審核)─> 4 錄製（真人） ─> 5 剪輯 ─> 6 提示表規劃 ─(審核)─> 7 建置 ─> 8 驗證 ─> MP4
每個專案需要不同的畫面與不同的故事；這些要從專案本身來決定。examples/ 目錄展示了兩個實際執行的案例：一個是旁白產品解說，另一個是代理技能的有/無對照影片。在規劃之前，請先閱讀與需求最接近的範例。
原則
- 僅使用真實畫面。 所有應用程式畫面、代理回覆、螢幕上的數字與記錄，都來自於擷取的畫面或檔案，由腳本複製，絕不重新輸入。如果你想加入的一句台詞不在任何擷取畫面中，影片就無法顯示它。
- 畫面跟隨語音。 每個視覺元素會精準落在提到它的那個字詞上。建置中的所有時間點都來自剪輯中的字詞 ID，因此重新剪輯時，視覺元素會跟著語音移動。
- 不誇大聲明。 不宣稱任何超出文字與來源範圍的內容。保留事實清單（附帶每個事實的來源檔案）與「未宣稱」清單。任何研究引用都需對照原始論文（Crossref：
https://api.crossref.org/works/<doi>）。 - 合成輸入資料。 虛構的使用者、對話與資料。不使用真實姓名或對話記錄。在畫面中遮蓋機密資訊與電話號碼，絕不印出金鑰：登入步驟在未錄製的環境中從環境變數檔案讀取。
- 保留所有原始素材。 腳本不會覆寫已擷取的畫面或剪輯來源。原始錄製檔案會保留在人物放置的位置，刪除與否由人物自行決定。
- 人物需審核兩次： 大綱與腳本（錄製前），以及提示表規劃（建置前）。腳本用詞可能需來回修改數次，這是該階段的重點。
模型路由
將大部分工作交由子代理執行，主工作階段則保留決策權。當人物為某個步驟指定模型時，使用指定的模型。
| 工作 | 模型 |
|---|---|
| 大量文字閱讀與研究：儲存庫事實表、主題研究、將錄製內容分割成編輯清單、審查腳本中的人工智慧痕跡 | Sonnet |
| 任何讀取影片或畫格的工作：裁切取景、渲染後的畫格檢查、檢查畫面中的機密資訊，以及逐段提示表群組（每個段落一個代理） | Haiku |
| 建立管線中缺少的新工具，例如自訂錄製器 | Opus |
| 大綱、腳本、提示表規劃，以及所有需要人物審核的呼叫 | 主工作階段 |
Haiku 與 Sonnet 無法聽取音訊。字詞時間戳記僅來自語音轉錄（步驟 5）。
1. 準備
閱讀 references/prep.md。同時進行以下工作：一個 Sonnet 代理從儲存庫撰寫事實表（專案的功能、帶有來源檔案的實際數字、需避免在螢幕上顯示的已知特性），以及 Sonnet 代理研究故事所依據的主題。然後撰寫大綱：包括段落、目標秒數、每個段落螢幕上顯示的內容、每個段落所需畫面、事實清單與未宣稱清單。
2. 擷取
閱讀 references/capture.md。從專案中選擇擷取方式：網頁應用程式使用 Playwright、代理行為使用 scripts/run_take.sh 透過 claude -p、CLI 使用終端機錄製器、即時網頁使用捲動擷取。每次擷取會記錄其標記（傳送、回覆、捲動停止）與時間戳記，以便建置時能將畫面剪輯至語音。Haiku 代理檢查每次擷取的畫格。
3. 腳本
閱讀 references/script.md。僅撰寫人物的對話，格式為 ## N. 標題 的段落，與大綱對應，以約每分鐘 150 字的速度一氣呵成。使用人物自然的說話語氣：不加行銷用語，不帶人工智慧痕跡。展示腳本與錄製指南，等待審核。
4. 錄製
人物使用網頁攝影機與麥克風同時錄製一個檔案（OBS、相機應用程式或手機）。錯誤與重新開始的台詞都沒有問題，因為剪輯會取用最後一個完整的版本。也可以使用多個檔案（每個段落一個，或後續補錄的台詞）。
5. 剪輯
閱讀 references/cut.md。
- 在本地對每個錄製檔案進行轉錄：
npx hyperframes transcribe <take> --engine parakeet。 - 對字詞進行編號並修剪至真實的靜音處：
python scripts/words.py transcript.json <take> vo --media <take>。 - 將短語清單與腳本提供給 Sonnet 代理（
assets/SPLIT-BRIEF.md）。它會產出edl.json：每個段落保留哪些字詞範圍、丟棄哪些填充詞與錯誤開頭，以及哪些台詞所表達的內容不受事實支援。 - 在剪輯前，向人物確認任何重複的台詞或標記的聲明。
- 裁切網頁攝影機畫面：Haiku 代理從取樣畫格中選擇一個能跨所有錄製檔案保持頭肩構圖的裁切範圍，或改用背景模糊（
scripts/blur_bg.py）。 - 剪輯：
python scripts/cut.py edl.json會產出vo.wav、cam.mp4、timeline.json以及每個段落的字詞檔案。由於音訊與視訊在同一畫格網格上進行修剪，唇形同步得以維持。
6. 提示表規劃
每個段落由一個 Haiku 代理（assets/CUE-BRIEF.md）負責，將該段落的時間標記字詞轉換為字幕、提示（哪個視覺元素落在哪個字詞上，及其來源）與閃現提示。然後：
python scripts/cues.py cut檢查每個段落檔案是否與剪輯結果相符，並將其合併為film.json。將任何錯誤回報給撰寫該段落的代理。- 為人物撰寫提示表規劃（
examples/samatva-support/CUE-plan.md展示了格式）：段落佈局、逐行視覺元素、音訊剪輯，以及只有人物才能決定的部分。等待審核。
字幕規則：顯示正確的字詞。靜默修正轉錄器的誤聽。對於真正的口誤，以正確字詞標記為 *(字詞) 取代原話。對難以聽清的姓名、數字與術語，在字幕上方以大尺寸閃現提示顯示。
7. 建置
閱讀 references/hyperframes.md。將 assets/build_film.py 複製到影片資料夾中。依照現狀，它會從 film.json 建置一個動畫腳本：每個提示的文字出現在對應字詞上、每個段落的網頁攝影機嵌入畫面、字幕與閃現提示。如果對時間點有疑慮，請先渲染這個版本。然後將每個段落的內容替換為真實畫面：根據提示時間剪輯的畫面、隨著每個部分被提及而逐步建構的圖表，以及顯示來源的卡片。
8. 驗證
閱讀 references/verify.md。按順序執行：
- 執行
npx hyperframes check --json直到顯示 0 個錯誤。 - 在每個提示時間點擷取快照（建置器會寫入
cues.json），並讓 Haiku 代理檢查這些畫格是否符合提示表規劃，以及是否有洩漏機密資訊。 - 透過腳本比對螢幕上的文字與其來源。
- 渲染 1080p 主要版本與 720p 審閱版本。
然後傳送審閱版本。當人物指出某個時間點（「在 1:23 我說……」），透過補錄或提示變更來修正，並僅重新驗證有變更的畫格。
檔案
scripts/words.py：將轉錄結果轉換為編號字詞與短語清單，並修剪至真實的靜音處。scripts/cut.py：將編輯清單轉換為vo.wav、cam.mp4與timeline.json，在畫格網格上同步。scripts/cues.py：檢查提示代理的段落檔案並合併為film.json。scripts/blur_bg.py：為網頁攝影機提供本地背景模糊（RobustVideoMatting，CPU）。scripts/run_take.sh、scripts/grade.py：用於實際claude -p擷取代理行為，並對其評分。assets/build_film.py：初始建置器（動畫腳本、網頁攝影機、字幕、閃現提示）。assets/edl.example.json、assets/SPLIT-BRIEF.md、assets/CUE-BRIEF.md：編輯清單格式與兩個代理任務說明。references/：包含準備、擷取、腳本、剪輯、hyperframes、驗證等參考文件。examples/samatva-support/：一個 2 分 19 秒的旁白產品解說影片，由三段錄製素材製成。examples/samatva-vent/：一個簡短的無聲有/無對照影片，展示代理技能，基於實際的claude -p擷取結果建置。