跳到正文
阿里雲開發者社區 AI·· 3 小時前AI 評分56

Timeline Studio：我如何用 Skill + MCP 實現 AI 智能體剪輯

从自然语言到可编辑时间线：我如何用 Skill + MCP 实现 AI 代理剪辑

AI 導讀

作者在開源項目 Timeline Studio 中實作 AI 智能體剪輯架構，將意圖理解與確定性工程操作分開，並保留可編輯的 .timeline 工程及影片成片。系統以版本化 JSON 計劃和共用命令引擎執行操作，並提供語義差異檢查、版本衝突處理和重複操作防護。超出本地渲染路徑範圍的工程會被拒絕，複雜合成則需使用瀏覽器編輯器的渲染路徑。

正文

简介： Timeline Studio 是一个开源AI视频编辑框架，首创“代理剪辑”架构：将大模型意图理解与确定性工程操作分离，通过结构化JSON计划、版本化时间线（.timeline工程）、多端统一命令引擎（CLI/MCP/浏览器），实现可追溯、可重试、可持续修改的智能剪辑。支持旁白驱动剪辑、语义差异预览、幂等操作与本地优先渲染。

让 AI 剪视频，最直接的思路是让大模型生成一条 FFmpeg 命令。

但真正做过视频项目就会发现，生成 MP4 只是其中一步。用户还会继续提出修改：

“第二个镜头短一点。”

“这段旁白往后移，字幕一起移动。”

“改成竖屏，但保留现在的剪辑结构。”

如果交付物只有视频文件，每次修改都可能变成重新编写脚本、重新组织素材。要让 AI 参与持续创作，就需要把它接入一个有明确数据模型、编辑规则和验证机制的时间线系统。

我在开源项目 Timeline Studio 中实现了一套这样的代理剪辑架构：通过 Skill 描述工作流程，通过结构化命令执行编辑，通过 CLI、MCP 和浏览器工具连接不同运行环境，最终同时保留可编辑工程和视频成片。

项目地址：MartinDelophy/ai-video-editor

在线体验：Timeline Studio

一、先确定交付物：视频之外，还要保留工程

Timeline Studio 是一个本地优先的浏览器视频编辑器。代理剪辑沿用编辑器的数据模型，将 .timeline 工程作为后续修改的依据。

在本地命令路径中，.timeline 是包含 project.json 和媒体文件的归档。导入媒体时，命令层会探测必要的时长与尺寸，计算 SHA-256，并将素材写入归档。

这样，一个剪辑结果可以同时包含：

  • 可继续编辑的轨道、片段、字幕和音频关系；
  • 工程使用的媒体文件；
  • 用于检查修改结果的版本与操作记录；
  • 根据工程生成的视频成片。

用户拿到工程后，可以继续在编辑器里调整；Agent 接到新需求后，也能读取当前工程再修改，而不必从上一段自然语言对话里猜测时间线状态。

二、把“理解需求”和“执行编辑”分开

这套系统中，Agent 负责理解意图、分析素材和提出编辑计划。真正改变工程的操作，由确定性的命令层完成。

整体调用关系可以简化为：

用户需求 + 素材证据
        ↓
Skill：分析、规划、选择执行路径
        ↓
结构化编辑计划
        ↓
CLI / 本地 STDIO MCP / 浏览器 WebMCP
        ↓
共享命令注册表、校验与状态变换
        ↓
新工程 / 浏览器历史记录 / 视频导出

这里最重要的工程选择，是让不同入口复用同一套编辑规则。

CLI 可以处理本地工程文件；本地 MCP 为 Agent 提供工具接口；浏览器 WebMCP 在宿主支持时操作已打开的编辑器。它们的状态与提交方式有所区别，但应尽量汇入共享命令引擎，避免出现三套互不一致的剪辑实现。

否则，同一个“移动片段”需求，可能在命令行里只移动音频，在浏览器里却连字幕一起移动。

三、用 JSON 计划表达编辑意图

大模型直接操作内部工程 JSON，容易遗漏轨道约束、素材引用和时间映射。因此，项目提供了版本化命令计划。

下面是一个简化示例：

{
   
  "schemaVersion": 1,
  "project": "/projects/input.timeline",
  "baseRevision": 12,
  "dryRun": false,
  "operations": [
    {
   
      "id": "trim-opening-001",
      "type": "visual.trim",
      "clipId": "visual-123",
      "sourceIn": 1.2,
      "sourceOut": 8.4
    },
    {
   
      "id": "move-voice-001",
      "type": "timed.move",
      "track": "audio",
      "clipId": "voice-1",
      "start": 3
    }
  ],
  "output": {
   
    "project": "/projects/output.timeline"
  }
}

这份计划表达的是两个明确意图：调整指定视频的源素材区间，将指定旁白移到工程第 3 秒。

片段 ID 和版本号需要先从实际工程读取。示例中的数值不能直接套用到任意项目。

几个字段承担了不同职责：

字段 作用
schemaVersion 标识命令协议版本
baseRevision 校验计划基于哪个工程版本
operations[].id 标识一次操作，支持幂等处理
type 限定可执行的编辑行为
output.project 指定新的工程输出位置

命令层负责验证片段、参数与工程状态，而不是假设模型生成的每个字段都正确。

四、修改之前，先看语义差异

代理剪辑需要回答一个很具体的问题：这次操作究竟会改动什么？

项目采用的执行顺序是：

inspect → plan → validate → diff → apply → inspect

先读取工程，再构造计划；先查看变化，再提交修改。

命令行调用示例：

npm run agent -- project.inspect /projects/input.timeline

node skills/edit-timeline-studio/scripts/validate_edit_plan.mjs \
  /projects/plan.json

npm run agent -- project.diff /projects/plan.json

npm run agent -- project.run /projects/plan.json

这里有两层校验。

独立计划校验器检查 JSON 传输结构、时间字段和重复操作 ID。project.diff 则读取实际工程，使用与正式执行相同的注册表和状态变换逻辑，检查操作是否受支持、版本是否匹配、目标片段是否存在。

它返回的是工程语义上的变化，例如片段新增、删除、顺序变化、字段变化以及时长变化。

这种差异比直接比较整个工程 JSON 更适合审阅，也便于 Agent 判断自己的计划有没有误伤其他轨道。

五、用版本、幂等和事务处理重试

Agent 调用工具时，可能遇到响应中断、重复调用或状态过期。编辑接口需要把这些情况当作正常工程问题处理。

1. 版本冲突

计划携带 baseRevision。如果用户已经修改工程，旧计划中的新操作会遇到版本冲突。

此时应该重新读取状态、重新评估计划，避免覆盖用户刚完成的编辑。

2. 重复操作

操作具有稳定 ID。已经应用过的操作 ID 不应再次产生编辑结果。

这能避免重试导致同一片段被重复插入，或者同一操作执行两遍。

3. 批量提交

一批操作需要通过完整校验后再写出结果。执行失败时，不应留下只完成一半的输出工程。

本地 CLI 和 MCP 还要求写入新的工程路径，并拒绝覆盖输入或已存在的输出。这样，原始工程始终可以保留，修改结果也便于比较。

六、时间映射决定剪辑是否准确

视频编辑中至少存在两种时间：

  • 素材时间：原始文件中的位置；
  • 工程时间：片段在最终时间线中的位置。

对于固定倍速片段，两者的映射可以表示为：

sourceTime = sourceIn + (timelineTime - clipStart) × speed

使用速度曲线后，素材时间需要根据速度随时间的变化累积计算。

这会影响切分、裁剪、关键帧、字幕、缩略图以及音画同步。Agent 即使正确识别了“动作发生在素材第 8 秒”，也不能简单把这个数字当作工程中的切点。

因此，剪辑分析需要保存源素材时间证据，实际编辑则交给共享时间映射与命令逻辑处理。

同样，主画面通常是连续排列的顺序轨道，而旁白、字幕和画中画具有显式时间。主画面长度变化是否带动其他轨道，还要结合波纹编辑、链接关系和轨道锁定状态判断。

七、旁白先形成时间骨架，再安排画面

对于教程、产品介绍和叙事类内容，我在 Skill 中采用了“先确定声音，再精剪画面”的工作方式。

执行过程大致是：

  1. 保留可用的原始讲话，或编写旁白。
  2. 按自然呼吸短句分段生成音频。
  3. 测量实际音频长度，试听并确认。
  4. 建立旁白时间线。
  5. 根据声音安排镜头和字幕。

这样能避免画面先被固定为某个时长，随后再强行加速旁白。

字幕与音频也有显式关联。移动仍然链接的旁白时，相关字幕可以一起移动；新增旁白字幕前，需要先准备对应的语音片段，避免工程里出现有字幕却没有声音的段落。

中文及中英混合旁白的既定路线使用浏览器本地 Hojo TTS Light 80M，提供晴岚、若溪两种内置参考声音。具体模型下载与运行仍需要相应的浏览器环境。

八、MCP 提供接口，Skill 提供工作方法

在这个项目里，Skill 与 MCP 各自解决不同问题。

Skill 描述素材分析、剪辑规划、执行路径、能力边界和交付验证。MCP 则把确定性的工程操作暴露为工具。

本地 STDIO MCP 提供的工具包括：

timeline_project_inspect
timeline_track_inspect
timeline_clip_inspect
timeline_project_diff
timeline_project_apply
timeline_project_render

适配器复用现有命令层，不重新实现剪辑逻辑。

Skill 可以独立安装：

npx skills add MartinDelophy/ai-video-editor \
  --skill edit-timeline-studio

本地 MCP 则需要仓库及其 Node.js 依赖：

git clone https://github.com/MartinDelophy/ai-video-editor.git
cd ai-video-editor
npm install

npm run mcp

安装 Skill 不等于安装媒体工具、模型和完整运行环境。项目提供依赖检查入口，先检查缺失项，再按实际任务准备环境。

九、工程可编辑与视频可渲染，需要分别验证

编辑成功，不意味着所有功能都能通过同一条渲染路径输出。

当前本地 project.render 支持文档规定的主画面、旁白与音乐子集，通过 FFmpeg 输出 H.264/AAC MP4，并使用 ffprobe 检查尺寸、时长与音轨。

对于字幕、画中画、转场、视觉效果等超出该本地渲染路径范围的工程，系统会拒绝，而不是静默忽略。复杂合成需要使用浏览器编辑器的渲染路径。

这条边界非常重要：一个工具返回成功，却漏掉用户需要的字幕，比明确报告不支持更难排查。

交付验证也需要分层进行：

  • 检查工程结构、素材引用和时间关系；
  • 重新打开工程，确认可继续编辑；
  • 检查导出文件的媒体参数；
  • 播放关键剪辑边界，并实际试听音频。

十、从哪里开始阅读源码

如果想了解实现，可以从这些入口开始：

入口 关注内容
skills/edit-timeline-studio/SKILL.md Agent 工作流程与执行边界
src/lib/projectCommandEngine.js 共享工程命令引擎
scripts/timeline-command.mjs 本地工程读取、导入、执行与渲染
skills/edit-timeline-studio/mcp/server.mjs STDIO MCP 适配
src/hooks/useWebMcpEditor.js 浏览器编辑器工具接入
src/lib/projectRenderPlan.js 本地渲染计划构建

完整命令说明见：Agent 命令参考。

这套实践让我越来越明确：代理剪辑的难点，在于把模型的编辑判断落实为可检查、可重试、可继续修改的工程操作。

目前项目已经开放源码。如果你正在研究 Agent 工具调用、MCP、浏览器媒体处理，或者希望把自己的剪辑流程变成可复用的 Skill，欢迎阅读代码、提出 Issue，也欢迎通过 PR 补充共享命令与渲染能力。

GitHub 仓库：Timeline Studio / ai-video-editor
案例与剪辑实践：Timeline Studio Handbook
在线编辑器：直接体验

來源：阿里雲開發者社區 AI · developer.aliyun.com

#教學/實踐#Agent#MCP/工具調用#影片#部署/工程#GitHub