Agentic Video Editing

核心基元優先的邊界 (Primitive-First Boundary)

ScreenKite 讓 agent 編輯保持簡單：應用程式暴露確定的編輯基元 (primitives)，而 agent 負責處理計畫、逐字稿推理和編輯策略。

這樣的邊界劃分很重要。ScreenKite 應該回答像「目前的版面配置為何？」、「剪下這段範圍」，或是「在 12.5s 到 17.0s 之間應用這個場景版面配置」等問題。而 agent 應該決定哪些段落比較關鍵、要在哪裡進行剪輯、是否要插入視覺素材，以及何時停止迭代。

從事實狀態開始 (Start With Facts)

使用這些讀取出的資料作為你的基準：

• 將 getProjectState(scope: "summary") 視為取得時間、軌道和整體專案狀態的輕量級索引
• 將 getProjectState(scope: "layout") 視為場景組成的來源依據 (source of truth)
• 使用 getProjectResources() 以確認哪些媒體實際上存在
• 當說話時間點和詞彙邊界的剪輯很重要時，使用 exportTranscript(...)

如果逐字稿中包含了英文產品名稱、API 或其他專有名詞，在建立視覺素材或字幕前請務必進行校對。一旦產品名稱錯誤，這份錯誤將會蔓延至每一個下游素材中。

建議的工作迴圈 (Recommended Loop)

1. 在計畫任何事之前，先讀取 summary、layout 以及資源 (resources)。
2. 如果時間或旁白內容很重要，匯出並審查逐字稿。
3. 先計畫節奏點，再決定哪些範圍需要剪輯、調整版面配置、添加字幕或視覺素材。
4. 在變更畫面比例前執行 setCanvas(..., dryRun: true)；在進行較複雜的佈局工作前，執行 setSceneLayout(..., dryRun: true)。
5. 使用 editTimeline、setSceneLayout 和 manageEffects 來應用改變。
6. 在每一批次處理後，透過 getProjectState(scope: "visual") 或輸出的快照 (snapshots) 來進行驗證。
7. 如果變更調用 (mutating call) 發生超時，重試前請先重新讀取一次專案狀態。

何時使用各種基元 (When to Use Each Primitive)

• editTimeline 用於剪下、裁剪和清理詞彙邊界
• setSceneLayout 用於有時間範圍的畫面組成變更，包含進階的佈局 DSL
• manageEffects 用於字幕、縮放及其他特效處理
• 在外部算圖往返的工作流程中，使用 vfxExportVideoSegment 搭配 vfxOverlayProcessedClip
• exportArtifact 用於交付檔案、快照、SRT 以及範圍輸出

進階版面配置與 B-Roll (Advanced Layout and B-Roll)

在 ScreenKite 的視覺呈現中，螢幕錄影依然是主角。進階佈局與 B-roll 通常應為簡短的輔助段落，而非全面覆蓋畫面的內容。

如果你打算算繪出一個外部的視覺素材，並透過 <ScreenKite.Visual /> 來放置它，請遵守以下原則：

• 算圖時請將素材完全對齊目標寬度、長度、fps 和幀時長
• 請將算出來的檔案當成一個完整的子母畫面（PiP frame）來處理，而不是當作漂浮在大部分為空背景的影音中的小卡片
• 視覺動畫的設計應符合 進入 (entry) -> 穩定靜止 (settled hold) -> 無內部淡出效果 (no internal exit) 模式
• 將不同片段間的退場轉場處理直接交給 ScreenKite 的 magicMove 來處理

如果你將較短的進階版面配置時間區間，重新覆蓋到前面較長的時間區間上，請確保把多餘的地方清除並復原為 pictureInPicture 模式。否則前面殘留的進階版面片段，可能會在超過你預期的範圍內繼續播放。

安全護欄 (Guardrails)

• 絕對不要從單字中途進行剪輯。當說話時間的精確度很重要時，請務必切在逐字稿提供的詞彙間距上。
• 在超時後要重試寫入動作前，一定要再讀取一次專案狀態。
• 在把自訂覆蓋畫面放進時間軸前，務必確認算繪輸出的寬度、長度和幀時長與目標吻合。
• 確保所有生成的輸出檔案，都放置在 .skbundle 目錄之外。
• 為自我驗證的迴圈設置上限。當歷經幾回後視覺驗證如果依然失敗，請立即停止，並轉為直接調查版面設計或原始媒體。