已知错误
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 配置。
- 在此 POC 中，后端
3010、编辑器5177和 view-syncer4850已与较旧的3000/5173/4848堆栈有意隔离。
时间线帧渲染器注意事项：
- 如果
view_timeline_frames对某一帧失败，项目写入路径仍可能正常——在得出结论之前，使用较少帧或不同时间重试。 - 仍在
blob:占位符（上传进行中）上的素材渲染为空；在将空白帧视为错误之前，请等待track_progresstarget=upload。 - 除非工具返回的图像内容能明显确认目标帧，否则不要报告视觉证据成功。