给视频编辑器接入 AI，一个关键问题是：怎样把用户的一句话，变成准确、可检查、还能继续修改的编辑操作？
例如：
把第二段素材放到开头，第一段只保留第 2 秒到第 6 秒，其他顺序不变。
对于用户，这是一个很直接的需求。对于编辑器，它至少涉及片段定位、素材裁切、时间线重新排列，以及修改后工程状态的一致性。如果用户在 AI 思考期间又手动剪了一刀，之前生成的计划还能不能执行，也需要明确处理。
我们在开发开源浏览器视频编辑器 Timeline Studio 的过程中，把这条链路逐步拆成了几个部分：读取工程、生成结构化计划、预览变化、应用编辑，以及最终的视频导出。
最近，项目也完成了 Anna 中的视频制作能力接入，ChatCut 已经可以使用。这篇文章主要分享背后的编辑执行机制，以及浏览器视频处理中的一些工程取舍。
一、先让 AI 面对明确的工程状态
视频编辑器中的一个片段，并不等于一个视频文件。
同一个素材可以被切成多个片段，每个片段拥有不同的裁切区间、播放速度、画面变换和效果。素材本身没有变化，变化的是时间线如何引用它。
因此，需要先区分三个概念：
- 素材：原始视频、图片或音频。
- 片段：素材在工程中的一次使用，包含裁切和编辑属性。
- 时间线：这些片段在最终作品中的排列与时间关系。
这也是为什么编辑命令需要使用稳定的片段 ID，而不能只依赖“第二个视频”这样的描述。用户说的“第二段”需要先根据当前工程解析成具体对象，之后的执行都围绕这个对象进行。
Timeline Studio 提供了工程、轨道和片段的分层读取能力。Agent 可以先查看工程的画幅、时长、轨道与媒体清单，再读取目标片段的源时间映射、效果和关联信息。
这种方式也能减少无关上下文。调整一个片段的裁切区间，通常不需要把所有素材和全部工程细节一次性交给模型。
还需要明确一个边界：读取素材元数据，并不等于理解视频内容。 元数据可以告诉系统视频有多长，却不能证明哪个镜头更精彩。画面理解、语音识别与编辑执行需要分别接入，不能用一个模糊的“AI 已分析”代替。
二、把自然语言转成结构化编辑计划
在执行层，我们使用 JSON 表达编辑计划。
下面是一个本地命令计划示例。假设工程检查结果为 revision 12，目标片段是 visual-123，其源素材范围允许保留第 2 秒到第 6 秒：
{
"schemaVersion": 1,
"project": "/projects/input.timeline",
"baseRevision": 12,
"dryRun": false,
"operations": [
{
"id": "trim-001",
"type": "visual.trim",
"clipId": "visual-123",
"sourceIn": 2,
"sourceOut": 6
}
],
"output": {
"project": "/projects/output.timeline"
}
}
这个计划包含几个有实际作用的字段：
schemaVersion 用来明确协议版本；baseRevision 表示计划基于哪个工程版本生成；clipId 定位具体片段；操作 id 用于识别重复请求；输出路径则明确指定一个新的工程文件。
自然语言存在解释空间，而结构化操作必须落到明确字段上。执行器只接受已实现的操作类型和合法参数，例如裁切、切分、排序、修改速度或调整属性。
这样，模型负责提出编辑意图，编辑引擎负责落实规则。新增一种操作时，也需要同步定义它的参数、校验规则和状态变化，而不是仅仅在提示词中增加一句“支持某功能”。
三、JSON 合法之后，还要做工程语义检查
一个计划能够被 JSON 解析，不代表它能够正确执行。
例如：
- 片段 ID 可能已经不存在。
- 裁切区间可能超过源素材范围。
- 目标轨道可能被锁定。
- 用户可能已经修改了工程。
- 单个操作合法，组合后却可能产生不合法的字幕时间范围。
所以我们把校验分成两层。
第一层检查传输结构，包括字段类型、有限数值和重复操作 ID 等。
第二层检查工程语义：在当前工程上模拟执行计划，确认它具体会产生什么变化。
本地命令入口提供了这样的流程：
npm run agent -- project.inspect /projects/input.timeline
npm run agent -- project.diff /projects/plan.json
npm run agent -- project.run /projects/plan.json
其中，project.diff 是关键步骤。它复用正式执行时的命令注册表、版本检查和状态变换逻辑，但不写出工程包，并返回预计发生的工程、轨道和片段变化。
这比只展示模型生成的一段说明更可靠。用户审阅的是执行器计算出的结果，例如片段的前后顺序、裁切范围和总时长变化。
本地执行也要求写到新的输出路径，保留输入工程，方便比较和恢复。
四、用状态令牌处理“AI 思考期间，用户继续编辑”
浏览器编辑器有一个很常见的并发场景：
- Agent 读取当前工程。
- Agent 开始生成计划。
- 用户手动修改时间线。
- Agent 返回之前生成的计划。
这时，计划所依据的工程已经发生变化。
Timeline Studio 的浏览器接口使用 stateToken 标识读取到的编辑状态。生成编辑预览时，需要提交当前令牌；预览成功后，系统返回 previewId。
应用时再检查当前状态是否仍然与预览对应。如果期间发生了编辑，就拒绝应用过期计划，让 Agent 重新读取和规划。
流程可以表示为：
读取工程，取得 stateToken
↓
提交计划，生成语义预览
↓
取得 previewId，审阅变化
↓
检查状态仍然匹配
↓
通过编辑器正常历史机制应用
这件事直接影响用户对工具的信任：AI 不应拿着旧工程的理解，覆盖用户刚完成的修改。
对于重复提交，执行层也需要识别已经应用过的请求，避免网络重试导致同一次编辑被执行两遍。
五、时间处理必须区分素材时钟与时间线时钟
视频编辑中容易被低估的问题，是“时间”并不只有一种。
假设一个视频片段截取源素材的第 10～18 秒，以 2 倍速播放，并从时间线第 5 秒开始出现。那么它在时间线中的持续时间是 4 秒。
在恒定速度下，映射关系是：
源时间 = 源素材起点 + 片段局部时间 × 播放速度
因此，播放头到达时间线第 7 秒时：
片段局部时间 = 7 - 5 = 2 秒
源时间 = 10 + 2 × 2 = 14 秒
裁切、切分、预览取帧和导出都需要遵守同一套映射。存在速度曲线时，还需要根据速度随时间的变化累计计算。
Timeline Studio 已经包含源时间速度曲线相关处理。对 Agent 接口而言，也必须明确每个操作接收的是源时间、片段局部时间，还是工程绝对时间。
否则，一个数值即使通过了类型校验，也可能被用在错误的时钟上。
六、不同接入入口复用同一个编辑引擎
项目提供了本地 CLI、STDIO MCP 以及浏览器 WebMCP 等接入方式。
这些入口处理的上下文有所不同：本地命令读取工程文件，浏览器接口面对的是正在编辑的实时工程。但核心编辑规则需要保持一致。
我们把命令注册、参数校验和工程状态变换集中在共享引擎中。本地 CLI 与 MCP 调用同一套服务；浏览器适配层把经过审阅的操作计划转换到共享引擎，再通过编辑器正常历史机制提交。
这样可以减少一种维护问题：同一个裁切操作，在不同入口中使用不同的边界规则，或者某个入口忘记处理字幕与音频的关联。
同时，共享命令并不意味着所有入口拥有相同能力。
浏览器能够访问实时媒体、模型推理和完整编辑器导出流程；本地命令的渲染路径目前支持明确限定的组合范围。调用方需要检查能力边界，遇到不支持的组合时给出明确结果。
七、预览与导出使用不同的执行节奏
浏览器播放预览需要及时响应暂停、定位和拖动；离线导出则需要按确定的时间采样，生成完整视频。
Timeline Studio 的播放预览使用原生媒体路径，导出则使用独立的确定性离线渲染路径，通过 WebCodecs 等能力完成画面编码与音频处理，并提供兼容回退。
离线导出不能简单地假设“播放一遍并录下来”就足够。它需要控制输出帧时刻、源素材取帧、效果计算、字幕绘制和音频混合。
这里还有资源约束。解码、合成和编码都可能占用较多内存，不能无限堆积待处理帧。因此需要保持有界队列，在吞吐量与内存占用之间取得平衡。
预览和导出可以使用不同的执行节奏，但应共享时间映射与效果参数的含义，让用户看到的编辑结果能够准确进入最终视频。
八、缩略图也是编辑正确性的一部分
时间线缩略图看起来是界面细节，实际上会影响用户判断剪切位置。
在镜头切换附近，如果使用最近帧或单元格中心采样，可能提前展示下一个镜头。此时预览还在上一个镜头，时间线却已经显示下一幕，用户就容易误判切点。
我们的处理思路是保留普通胶片条的可读密度，同时对播放头所在单元格使用更精确的源时间帧。
长视频则渐进准备：先发布有界的种子帧，再优先补充可见区域，并通过递归细分让覆盖均匀出现。用户拖动播放头时，暂停后台缩略图定位与提交，把资源优先交给实时预览，松手后再恢复细化。
这类工作没有模型参数那么显眼，却决定了 AI 完成初稿之后，用户能否顺畅地继续精修。
结语
这次实现让我们更明确了一点：对话式视频制作需要一套完整的编辑执行机制。
工程数据模型让 AI 知道自己正在操作什么；结构化计划让意图可以检查；语义预览让变化可以审阅；状态检查避免旧计划覆盖新编辑；共享命令引擎让不同接入入口遵守一致规则。
最终，用户得到的是一个能够继续编辑的工程，以及由这个工程导出的视频。
Timeline Studio 的源码、运行方式和体验入口都整理在仓库中。欢迎对浏览器媒体处理、AI Agent 和视频编辑工具感兴趣的开发者交流。
