技能:分析影片(父級簡報)
這是主執行緒在「分析影片」工作流程步驟中的劇本。在完成庫設定之後、進行任何剪輯工作之前執行。它涵蓋每個剪輯產生的三個成品:音訊 逐字稿、聯絡表 以及 Markdown 摘要。粗剪代理程式會透過對逐字稿 JSON 執行 script_extractor.rb 來按需讀取對話——不需要另外的腳本成品。
SKILL.md 是父級的分派簡報。子代理程式的工作提示位於 agent_prompt.md 中——在啟動 Task 代理程式時內嵌其內容。請勿傳遞 SKILL.md。
術語
- 對使用者呈現時: 稱之為「素材分析」或「分析素材」。
- 內部/檔案名稱: 「轉錄」(library.yaml 欄位
transcript等)。
先決條件
- 庫設定已完成(
library.yaml已存在,schema 為最新——如果不是,請從 AGENTS.md 執行遷移)。 - 直接讀取
libraries/settings.yaml以取得whisper_model。對於庫的欄位,請透過ruby lib/buttercut/library.rb <name> summary讀取快照,並從 JSON 中提取所需的值——請勿直接解析 library.yaml。
現在,建立一個對使用者可見的待辦事項清單,包含高層級、非技術性的步驟,以便他們可以了解處理資料庫的整體計畫。僅在使用者同意加入時才包含提神步驟。例如:
- [ ] 保持電腦清醒
- [ ] 建立逐字稿 (0/30)
- [ ] 分析素材 (0/30)
- [ ] 讓電腦再次休眠
- [ ] 一起檢閱素材
這些公開待辦事項對應到以下步驟:「保持電腦清醒」是步驟 1,「讓電腦再次休眠」是步驟 6;「建立逐字稿」涵蓋步驟 2 的機械執行以及步驟 3 的可選優化過程(根據步驟 2 的 [transcript …] 進度行更新其計數;當優化開啟時,在步驟 3 進行期間保持其為進行中狀態);「分析素材」追蹤步驟 4 的摘要(隨著剪輯被摘要而更新其計數,不是在聯絡表之後);「一起檢閱素材」是步驟 5。
在公開對話中,請參照這些非技術性步驟。將技術性工作(WhisperX、聯絡表生成、Sonnet 摘要)保留在幕後。
步驟 1 — 防止處理期間進入休眠
在開始分析之前,詢問使用者(透過 AskUserQuestion):「處理可能需要一段時間——要我讓你的電腦保持清醒直到完成嗎?」選項:「好(建議)」和「不要」。
如果選擇是,在背景啟動平台的保持清醒輔助程式並儲存 PID——你將在步驟 6 分析完成後終止它。(備份由調用技能——process-library——在此技能返回後處理。)
macOS:
caffeinate -i -w $$ &
KEEPAWAKE_PID=$!
Windows(Git Bash):
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/keep_awake.ps1 &
KEEPAWAKE_PID=$!
兩者都能在處理素材時防止閒置休眠(顯示器仍可能關閉,這沒問題)。
步驟 2 — 處理素材(逐字稿,然後聯絡表)
(如果你是直接到達此技能而非透過 process-library,請先告訴使用者:「找到 [N] 個影片([總大小])。正在開始素材分析...」)
這是兩個機械式指令,你需要一個接一個執行——首先執行逐字稿,然後執行聯絡表。請勿同時執行:WhisperX 很耗 RAM,避免兩者同時執行正是我們要做的。不要使用子代理程式手動處理;每個指令每次都以相同方式執行,一次處理約 2 個剪輯,並在每個剪輯完成時將其記錄到 library.yaml。兩者都是冪等的——它們只會處理仍缺少該成品的剪輯——因此重新執行只會完成剩餘的部分。它們會在一個小型的 Sidekiq 式任務服務中執行。你將執行指令,然後監控將返回的日誌檔案以查看進度。
步驟 2a — 逐字稿。 如果使用 Claude Code,請在 Bash 工具上使用 run_in_background: true 執行。否則使用正確的工具/參數在背景執行。
ruby lib/buttercut/process_footage.rb transcripts <library-name>
啟動後立即設定一個 Monitor 或等效工具在日誌檔案上,以便在每個剪輯完成或失敗時收到通知:
tail -f tmp/logs/processing/<library-name>/$(date +%Y-%m-%d).log | grep --line-buffered -E "TranscribeJob (done|error)|transcript: [0-9]+/[0-9]+|Error|error:|failed|Traceback"
ruby lib/buttercut/library.rb <name> pending transcript # JSON 列表;完成數 = N − 其長度
隨著剪輯完成,更新「建立逐字稿 5/20」,即 completed_clips/total_clips,以便使用者可以看到進度。當背景任務完成時,如果有任何剪輯失敗,它會以非零值退出。如果失敗,請重新執行一次。如果再次失敗,請進行調查,然後建立一個修復以優雅地處理,或者通知使用者有關該剪輯的問題並可能將其從庫中移除。
在開始 2b 之前等待 2a 完成。
步驟 2b — 聯絡表。 逐字稿完成後,建立聯絡表(一個快速的 ffmpeg 過程——前景執行即可):
ruby lib/buttercut/process_footage.rb contact-sheets <library-name>
聯絡表保持在幕後——不要將其作為公開計數呈現。一旦 2a 完成且任何優化(步驟 3)也完成後,將「建立逐字稿」標記為完成。
調整(可選):兩個步驟都從 libraries/settings.yaml 讀取 parallel_jobs(預設為 2);使用 --jobs N 可覆寫單次執行。每個步驟都會在 tmp/logs/processing/<library>/ 下寫入一個帶時間戳的日誌,以供事後檢閱。
重新處理。 每個步驟會跳過已擁有其成品的剪輯。要重做某個項目——例如一個聽錯名字的逐字稿——請使用 --force --clips NAME.mov 重新執行該步驟。單獨使用 --force 會重建所有剪輯。
步驟 3 — 優化逐字稿(判斷——僅在 transcript_refinement: true 時)
優化是轉錄中唯一需要判斷的部分——根據庫上下文修正聽錯的專有名詞——因此它保留為一個模型步驟,在機械式執行之後執行。如果庫的 transcript_refinement 為 false,請完全跳過此步驟。
當其為 true 時,派遣優化子代理程式(2-4 個平行,滾動式)處理步驟 2a 剛寫入的逐字稿。將 skills/transcribe-audio/refine_instructions.md 內嵌為每個子代理程式的提示,並內嵌傳遞:
transcript_path— 位於libraries/<library>/transcripts/下的剪輯逐字稿 JSON 的絕對路徑user_context和footage_summary— 來自ruby lib/buttercut/library.rb <name> summary的當前值(空字串也沒問題;優化仍然會修正無意義的 token 和自我見證問題)
子代理程式會原地編輯逐字稿 JSON 並返回一個簡短的修正清單。它們不會觸碰 library.yaml——步驟 2a 已經設定了 transcript 欄位。一旦優化完成,將公開的「建立逐字稿」待辦事項標記為完成。
步驟 4 — 摘要(Sonnet 子代理程式,批次處理,滾動式)
使用 Sonnet 模型派遣 analyze-video 子代理程式。Sonnet 讀取聯絡表時,在視覺特異性方面明顯比 Haiku 更勝一籌(能捕捉到服裝、建築物、鏡頭構圖)——這是值得的,因為摘要會影響後續每一個剪輯決策。
每個子代理程式批次處理 10 個剪輯,最多 10 個子代理程式平行執行,並採用滾動式分派。 每個子代理程式依序處理其 10 個剪輯;分批處理可以分攤每個代理程式約 5–10 秒的分派開銷。對於一個 93 個剪輯的庫,總共約需 10 個子代理程式,而不是 93 個。一旦某個子代理程式返回,立即啟動下一個——不要等待整個批次(10 個)都完成,否則你會因為等待批次中最慢的代理程式而損失大約 30% 的實際時間。
對於每個子代理程式,內嵌傳遞一個包含 10 個剪輯記錄的清單。每個剪輯記錄需要:
video_filename— 影片的 basename(用於摘要標題和回覆行)duration— 來自 library.yaml 的持續時間字串(例如00:01:19);代理程式會在摘要標題中呈現它contact_sheet_path—_full.jpg的絕對路徑(來自步驟 2)transcript_path— 音訊逐字稿 JSON 的絕對路徑(來自步驟 2);子代理程式透過script_extractor.rb按需提取對話summary_output_path— 子代理程式應寫入摘要 markdown 的絕對路徑。不要手動建構這個檔名;向庫查詢標準路徑:ruby lib/buttercut/library.rb <name> field_path summary <clip>(它會為你處理summaries/summary_<clip>.md約定,無論是否帶有副檔名)
當每個子代理程式返回其批次時,為該批次中的每個剪輯更新 library.yaml 中的 summary:
ruby lib/buttercut/library.rb <name> complete summary <filename> [<filename>...]
contact_sheet 欄位已在步驟 2 中填入,因此子代理程式返回時只貢獻摘要。
如果子代理程式內聯返回摘要而不是將其寫入磁碟(有時 Sonnet 會幻覺「Write 工具被封鎖」並將 markdown 傾印到其回覆中),請不要盲目重試——只需從代理程式的回應中提取每個摘要,並使用父執行緒中的 Write 將其寫入匹配的 summary_output_path。然後像往常一樣執行 complete summary 指令。這比重試更快,而且內容已經在那裡了。
(為長剪輯生成的逐段聯絡表與 _full 聯絡表一同存在於磁碟上,並可透過慣例發現——它們不會列在 library.yaml 中。)
在摘要完成之前不要繼續前進。隨著剪輯被摘要,更新「分析素材」的計數;完成後將其標記為完成。
靜態影像。 影像完全跳過步驟 2–3(沒有音訊需要轉錄,沒有聯絡表需要建立)——summary 是它們唯一需要的成品,而且它們會與影片一起出現在 ruby lib/buttercut/library.rb <name> pending summary 中。影像本身就是要查看的內容,因此直接對其進行摘要:從主執行緒或 Sonnet 子代理程式讀取影像檔案(它很小),並將一段 3–4 句的描述——主體、場景、構圖、任何影像上的文字——寫入從 ruby lib/buttercut/library.rb <name> field_path summary <image-filename> 獲得的標準路徑。注意,影像剪輯鍵值包含副檔名(title-card.png → summaries/summary_title-card_png.md),field_path 會為你處理。然後以相同方式記錄它:ruby lib/buttercut/library.rb <name> complete summary <image-filename>。
步驟 5 — 與使用者確認素材理解
(這是「一起檢閱素材」待辦事項。)一旦所有摘要都寫入,請與使用者討論素材實際顯示的內容——確認角色名稱、地點、敘事主線、任何偏離主題或不相關的剪輯,以及使用者對此庫的創意意圖。使用一般對話;只有在提供離散選項時才使用 AskUserQuestion。當你學到新資訊時,更新:
footage_summary和user_context,透過ruby lib/buttercut/library.rb <name> update_metadata footage_summary "..."(以及使用user_context進行相同操作)- 當摘要錯誤標記某人或遺漏關鍵細節時,更新個別的
summary_*.md檔案(例如,「一個穿米色夾克的男人」→ 使用者的名字)
這是進行這項徹底檢查的唯一地方。後續的每一次粗剪規劃執行都會繼承最終的上下文,而不是重新詢問庫。
步驟 6 — 停止保持清醒輔助程式
如果你在步驟 1 中啟動了一個,現在終止它(兩個平台):
kill $KEEPAWAKE_PID 2>/dev/null
平行子代理程式模式(參考)
用於步驟 3 和 4。
父代理程式職責:
- 讀取
library.yaml和settings.yaml一次,以收集子代理程式所需的所有值。 - 啟動 Task 代理程式,將所有需要的值內嵌在提示中傳遞。
- 在代理程式完成時(透過
LibraryAPI——請參閱 AGENTS.md)依序更新 library.yaml。 - 處理錯誤和重試。
子代理程式職責:
- 僅使用父代理程式內嵌傳遞的輸入來處理其分配的剪輯。
- 原地優化逐字稿 JSON(優化),或讀取預先生成的聯絡表,透過
script_extractor.rb從逐字稿中提取對話,並在一次 Write 呼叫中寫入摘要 markdown(analyze-video)。(WhisperX 不再是子代理程式——process_footage.rb transcripts在步驟 2a 中執行它。) - 返回一個包含檔案路徑的簡短結構化回應。
每個技能的 agent_prompt.md 都記錄其自己的 IO 合約——包括子代理程式是否讀取或寫入 library.yaml。(劇透:它永遠不會寫入 library.yaml。只有父代理程式透過 Library API 寫入。)
如果使用者在分析完成之前要求粗剪
警告:「我現在可以建立粗剪,但在分析完所有素材之後再做會更理想。仍然要繼續嗎?」如果使用者確認,則繼續。否則,等待分析完成。