我们最近给开源视频编辑器 Timeline Studio 增加了一项新能力：通过 WebMCP，让浏览器中的 AI Agent 读取项目状态、提出剪辑方案，并调用编辑器提供的工具完成操作。
这次改造已经随 v1.0.8 发布。第一阶段支持项目与轨道检查、已有字幕读取、主视频轨道排序与有限裁剪，以及编辑预览、应用、撤销和项目保存。
做完之后，我觉得最值得分享的，是一个具体的工程问题：当 AI Agent 成为应用的操作者之一，前端应该怎样提供清晰、可靠、可撤销的操作接口？
项目已经开源，欢迎体验和交流：
为什么尝试 WebMCP？
目前，浏览器 Agent 常见的操作方式是读取页面、识别控件，再模拟点击、输入和拖动。简单表单通常比较容易处理，但视频编辑器的情况复杂得多。
时间线里的一个位置，可能同时对应视频、画中画、音频和字幕。拖动片段边缘可能改变片段长度，也可能触发其他轨道跟随移动。界面的缩放、滚动和选中状态，还会影响操作结果。
应用本身已经知道这些业务规则。如果能把明确的编辑能力提供给 Agent，就可以减少它从界面外观推断业务含义的过程。
WebMCP 为此提供了一条路径：网站在页面中注册结构化工具，描述工具用途、输入参数和执行逻辑，由支持该能力的浏览器或 Agent 宿主调用。
需要说明的是，WebMCP 目前仍处于实验性发展阶段，不能假设所有浏览器和 Agent 都已经支持。它适合以渐进增强的方式接入，常规编辑功能仍然应当独立可用。WebMCP 规范草案、Chrome 官方文档
第一版先完成一个可验证的编辑闭环
我们的实现围绕九个工具展开：
| 工具 | 作用 |
|---|---|
timeline_project_inspect |
读取项目概况和当前状态标识 |
timeline_track_inspect |
分页读取指定轨道 |
timeline_clip_inspect |
检查单个片段 |
timeline_transcript_inspect |
读取项目中已有的字幕 |
timeline_edit_preview |
校验编辑计划并展示预览 |
timeline_edit_apply |
应用已生成的预览计划 |
timeline_preview_seek |
将播放头移动到指定时间 |
timeline_edit_undo |
撤销符合条件的 Agent 编辑 |
timeline_project_save |
下载可继续编辑的项目文件 |
其中，字幕读取使用的是项目中已经存在的字幕数据，不会自动执行语音识别；项目保存下载的是 .timeline 工程文件，也不等于导出成品视频。
编辑能力同样有明确范围：第一版主要处理现有主视觉片段的排序，以及符合条件的普通视频片段裁剪。涉及复杂变速、倒放或其他暂未支持的处理时，工具会拒绝不符合约束的计划。
这样做的好处是，每个工具的输入、结果和限制都能被解释和验证。
编辑流程为什么分成检查、预览和应用？
我们采用了这样一条调用链：
读取项目状态
↓
提交结构化编辑计划
↓
校验并展示预览
↓
应用计划
↓
检查结果，按需撤销或保存
假设时间线上有两个片段：
- A 片段长 4 秒。
- B 片段长 6 秒。
用户希望把 B 放到前面，只保留它的第 1 秒到第 5 秒，然后接上 A。
Agent 首先读取项目，获得片段身份、时长和当前状态标识。接着提交计划，表达“B 在前、保留指定源时间范围，A 在后”。
编辑器负责检查片段是否存在、裁剪范围是否合法、相关轨道是否允许编辑，以及项目是否仍然处于检查时的状态。校验通过后，页面展示计划预览，此时还没有修改时间线。
用户可以通过界面应用方案，Agent 也可以在用户授权范围内调用应用工具。
这个流程中，Agent 负责组织剪辑意图，编辑器负责执行业务规则。预览让两者之间的约定变得可见。
比注册工具更重要的，是处理状态变化
接入过程中，最容易低估的是状态一致性。
Agent 读取项目之后，用户可能手动调整片段、锁定轨道，或者执行一次撤销。如果 Agent 继续应用旧计划，即使参数格式正确，也可能修改错误的项目状态。
因此，我们为检查结果提供了 stateToken。生成编辑预览时需要携带这个标识；项目发生实质性变化后，旧计划就需要重新检查。
同时，编辑器里还有很多持续变化的数据，例如后台生成的缩略图、时间线缩放和播放预览状态。如果把这些变化也视为项目内容变化，Agent 的计划就会频繁失效。
我们将判断重点放在实际影响编辑结果的状态上，让后台缩略图更新和普通预览操作不至于无故打断编辑流程。
撤销也需要类似约束。一次 Agent 编辑完成后，如果用户又做了新的手动修改，旧的撤销请求不应该覆盖这些后续工作。为此，应用操作会返回事务标识，撤销时再检查当前状态是否仍允许回退该次编辑。
此外，对同一个已应用计划的重复请求需要避免重复执行，防止重试导致再次裁剪或再次移动片段。
让 WebMCP 复用编辑器已有能力
另一个关键决定，是让 WebMCP 接入现有编辑逻辑。
视频编辑器已经有自己的时间线模型、裁剪规则、轨道锁定、字幕音频关联和撤销历史。工具层应当把结构化参数交给这些能力处理。
如果另外实现一套“专供 Agent 使用”的编辑逻辑，两条路径很容易逐渐出现差异：鼠标操作遵守的约束，Agent 调用可能遗漏；某项时间线修复，也可能只覆盖其中一条路径。
因此，这次改造主要增加了工具注册、参数校验、计划预览和状态保护，并让实际编辑进入共享的业务执行路径。
新增加的审核界面和提示文案，也直接覆盖了项目现有的 13 种界面语言。
工具能调用，也要让 Agent 知道如何使用
除了运行时接口，我们还补充了面向 Agent 的说明材料：
- 描述实际能力和限制的使用指南。
- 提供推荐操作流程的 Skill 文档。
- 位于
/.well-known/agent-skills/index.json的发现索引。 - 用于关联说明文档的 HTTP
Link响应头。 - 更新后的
llms.txt文档入口。
这里需要区分两个层面：这些文件帮助 Agent 发现和理解网站能力；真正执行工具调用，仍然依赖浏览器或宿主对 WebMCP 的支持。
部署时也检查了不存在的协议路径，确保它们返回真实的 404。单页应用如果把所有路径都回退到首页，很容易让探测程序把一份 HTML 页面误认为有效的协议响应。
实际验证了什么？
我们在浏览器里验证了前面的编辑案例：将两个总计 10 秒的片段重新排序，并裁剪其中一个片段，得到 8 秒的时间线；随后通过撤销恢复到 10 秒。
项目中还保留了一个结束位置超过媒体结尾的范围标记，用来检查注释是否会错误地延长媒体时长。验证过程中，标记得以保留，媒体时长也没有被它拉长。
此外，我们检查了编辑后的播放头定位、重复应用、状态变化后的撤销限制，以及可编辑项目文件下载。代码检查、构建和 GitHub CI 均已通过，线上部署也核对了发现文档和资源内容。
这些验证说明第一阶段的编辑闭环可以工作。目前还没有足够的对照数据，可以据此宣称效率提升了多少倍。
数据边界同样需要说清楚：检查工具不会直接返回媒体文件字节，但会向调用方返回必要的项目元数据和已有字幕文本。接入时应当逐项明确这些内容，而不能笼统地认为浏览器内调用就意味着没有数据流向 Agent 宿主。
我认为，这次实践最有价值的收获，是让编辑器拥有了一套更明确的操作契约：有哪些能力、接受什么参数、何时允许执行、结果怎样检查、出现问题如何恢复。
WebMCP 的接口和生态还会继续演进，而这些工程能力会持续帮助应用与 AI Agent 协作。
