用途
known-errors 是一份面向 OpenChatCut 工具的已知错误与调用规范文档。当 OpenChatCut 的某个工具调用失败，或返回非预期（unexpected）的数据结构时，可参考此文档排查。它记录的是工具调用的正确参数写法、已知报错文案及对应的处理方式，而非产品功能说明。
主要能力与规则
edit_item 更新（update）的正确结构
错误写法：{ "id": "abc", "fromFrame": 30 } 正确写法：{ "json": "{"updates":[{"id":"abc","fromFrame":30}]}" } 常见的移动、裁剪和轨道变更都使用同样的 updates 结构。
edit_item 新增（add）的正确结构
新增项需放入 json 事务的 adds 数组中：{ "json": "{"adds":[{...}]}" }。 简单视频放置示例：{ "json": "{"adds":[{"type":"video","assetId":"...","fromFrame":0}]}" }。
时间线重叠（Timeline overlap）
错误文案示例：Overlap: updated item at ... would overlap existing item at ... on this track. 处理要求：不要强行写入，也不要静默删除冲突项。应使用明确的可用 trackId 重试 edit_item 事务，例如更新中包含 "trackId":"V2"，或询问用户哪一层应保留。
工作区路径限制（Workspace path restrictions）
外部 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，再用返回的 token 运行一次 OpenChatCut 媒体导入辅助工具。
浏览器视频转换失败
错误文案常包含：Unable to convert video without dropping audio/video tracks 或 unknown_source_codec。 处理方式：重新运行 OpenChatCut 媒体导入辅助工具，它负责与前端对齐的转换；若无法转换，会给出用户可操作的错误提示。 不要让用户通过编辑器 UI 重新导入同一文件作为变通——转换路径相同，错误会重复。应修复源文件（本地用 ffmpeg 重新编码）或更换文件。 替换资源上传/转写完成后，若原失败资源未被使用应删除。干净的最终媒体池应像一次成功导入，而不是失败导入加替换项。
动效图形（Motion Graphic）要求
push_asset(type:"motion-graphic") 需要 width、height 以及 duration 或 durationInFrames。 MG 代码必须通过 OpenChatCut 校验器。 生成的 MG 代码中根节点使用 AbsoluteFill 无效，应使用带缩放的根 div。 避免在 MG 代码中声明顶层局部变量 scale，校验器/运行时可能已保留该标识符，应使用如 uiScale 这类具体名称。
本地开发 Zero 注意事项
当后端运行在非默认端口时，使用匹配的 Zero view-syncer 配置。 在此 POC 中，后端 3010、编辑器 5177、view-syncer 4850 有意与旧的 3000/5173/4848 栈隔离。
时间线帧渲染（Timeline frame renderer）注意事项
若 view_timeline_frames 对某一帧失败，项目写入路径仍可能正常；应先以更少帧数或不同时间重试，再下结论。 仍处于 blob: 占位（上传进行中）的资源会渲染为空；在 track_progress target=upload 完成前，不要把空白帧当作 bug。 除非工具返回的图像内容能明显确认目标帧，否则不要报告视觉验证成功。
适用场景
适用于调试 OpenChatCut 工具调用返回异常、edit_item 参数结构错误、时间线轨道冲突、媒体导入与视频转换失败、动效图形代码校验不通过，以及本地开发环境端口与帧渲染排查等场景。
限制
本资料为已知错误参考文档，未提供独立产品的功能列表、收费、价格、支持平台或效果数据。除上述内容外，其他信息暂未提供。