已知錯誤
edit_item 更新原始形狀：
- 錯誤：
{ "id": "abc", "fromFrame": 30 } - 正確：
{ "json": "{\"updates\":[{\"id\":\"abc\",\"fromFrame\":30}]}" } - 對於常見的移動、修剪和軌道變更，使用相同的
updates形狀。
edit_item 新增原始形狀：
- 新項目位於
json交易的adds陣列中：{ "json": "{\"adds\":[{...}]}" }。 - 使用
edit_item進行簡單的影片放置，例如{ "json": "{\"adds\":[{\"type\":\"video\",\"assetId\":\"...\",\"fromFrame\":0}]}" }。
時間軸重疊：
- 錯誤文字：
Overlap: updated item at ... would overlap existing item at ... on this track. - 不要強制寫入或無聲地刪除衝突的項目。
- 使用明確可用的
trackId重試edit_item交易，例如包含"trackId":"V2"的更新，或詢問使用者哪個圖層應獲勝。
工作區路徑限制：
- 外部 MCP 上的
push_asset僅接受公開的 http(s) URL 作為filePath。它會拒絕本機路徑、工作區路徑和聊天附件路徑。 - 對於動態圖形資產，請透過
create_motion_graphic_from_code({ code:"...", name, width, height, durationInFrames })傳遞 JSX 原始碼。push_asset不再接受內聯的code參數。 - 將本機媒體複製到工作區並不是解決影片/音訊/圖片/GIF 匯入問題的方法；請改用
asset-import和import_media。 - 使用
import_media action=create_session，然後為客戶端持有的檔案，使用返回的權杖執行一次 OpenChatCut 媒體匯入輔助工具。
瀏覽器影片轉檔失敗：
- 錯誤文字通常包含
Unable to convert video without dropping audio/video tracks或unknown_source_codec。 - 重新執行 OpenChatCut 媒體匯入輔助工具；它負責前端對齊的轉換，如果轉換不可能，它會顯示使用者可操作的錯誤。
- 不要要求使用者透過編輯器 UI 重新匯入相同的檔案作為變通方法 — 轉換路徑相同，錯誤會重複出現。請修正來源（在本地使用
ffmpeg重新編碼）或選擇不同的檔案。 - 在替換的資產上傳/轉錄完成後，刪除失敗的原始資產（如果未使用）。乾淨的最終媒體池應看起來像成功的匯入，而不是失敗的匯入加上替換品。
動態圖形需求：
push_asset(type:"motion-graphic")需要width、height和duration或durationInFrames。- MG 程式碼必須通過 OpenChatCut 驗證器。
- 根層級的
AbsoluteFill對於產生的 MG 程式碼無效；請使用縮放的根層級div。 - 避免在 MG 程式碼內部宣告頂層區域變數名為
scale。驗證器/執行時期可能已保留該識別碼；請使用特定名稱，例如uiScale。
本地開發 Zero 注意事項：
- 當後端執行在非預設連接埠時，請使用匹配的 Zero 視圖同步器 (view-syncer) 配置。
- 在此概念驗證中，後端
3010、編輯器5177和視圖同步器4850有意與舊的3000/5173/4848堆疊隔離。
時間軸幀渲染器注意事項：
- 如果
view_timeline_frames對某一幀失敗，專案寫入路徑仍可能健康 — 在得出任何結論前，先以較少幀數或不同時間點重試。 - 仍處於
blob:佔位符（上傳進行中）的資產會渲染為空白；在將空白幀視為錯誤之前，請等待track_progress target=upload。 - 除非工具返回的圖片內容能明顯確認目標幀，否則不要報告視覺驗證成功。