不要让 Agent 直接剪片：用 Velorn 的本地 MCP 把视频时间线编辑变成“先预览、后执行”的流程
AI 生成视频进入剪辑阶段后，问题往往不在于能否再生成一个镜头，而在于如何让 Agent 参与真实的时间线工作：它要识别缺失素材、检查画面连续性、准备字幕或导出，同时又不能因为一句模糊指令就移动一批片段、触发 GPU 生成或把交付文件覆盖掉。
Velorn 是一款 GPL-3.0 开源桌面视频工作站，提供 Windows、macOS 与 Linux 的发布包。它把项目资产、时间线编辑、字幕、导出与基于 ComfyUI 的生成流程放进同一应用，并在桌面应用内部提供一个本地 HTTP MCP 服务。重点不只是“让 Claude Code 或 Codex 会操作剪辑软件”，而是给高成本、不可轻易回滚的视频操作加上可检查的阶段边界。
本文以 Velorn v0.3.27 的公开文档为依据，介绍一条更稳妥的使用方式：先读取项目状态，先返回修改预览，再经人工批准执行；生成和导出另作确认。
为什么视频时间线不适合一句话直接修改
代码改错可以查看 diff、回滚提交；视频工程的代价却分散在时间线、磁盘文件、GPU 队列和外部服务额度中。比如“把节奏慢的镜头删掉并导出竖版”至少包含四类风险：
- Agent 可能把“慢”理解为错误的片段，或者忽略一个被禁用但仍需要保留的镜头；
- 删除、移动或替换片段会改变时长、转场和音频同步；
- 调用生成工作流可能依赖本地 ComfyUI、模型和节点，并消耗显卡时间或云端额度；
- 导出、导入媒体、创建项目与生成资产会写入文件，并不都进入普通的撤销栈。
Velorn 的 MCP 文档把服务限定在 127.0.0.1:19790。这是一个重要的默认边界：它不是可直接暴露到局域网或公网的云 API；只要桌面应用运行，本机能连接此端口的进程就能请求 MCP。因此不应把它反向代理出去，也不应把“仅本地监听”误解为无需管理本机进程权限。
第一步：只连接本机正在打开的项目
启动 Velorn、打开项目后，在 Settings > Agents (MCP) 确认服务状态为 Running。官方给出的 Codex 连接命令如下：
codex mcp add velorn --url http://127.0.0.1:19790/mcp
Claude Code 的 HTTP 连接方式则是：
claude mcp add --transport http velorn http://127.0.0.1:19790/mcp
连接成功并不代表 Agent 已经“看懂”工程。一个较好的首轮指令是要求它调用 get_mcp_recipes、get_project 和 get_timeline，只总结当前项目、活跃时间线、可用审查步骤和风险，不进行任何修改。这样可以先确认三个事实：当前是否真的打开了目标项目、时间线快照是否可用、后续工具是否需要项目上下文。
如果要验证服务本身，文档还给出了 JSON-RPC 的只读探测形式。这里使用 tools/list，不会改变项目：
curl -s http://127.0.0.1:19790/mcp \
-H "Content-Type: application/json" \
-d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}"
不要把工具目录当成固定接口。Velorn 明确建议 MCP 客户端在运行时用 tools/list 发现 schema；工具会增长，参数也应以实际返回的定义为准。
第二步：把“剪辑建议”拆成可复查的检查项
在要求 Agent 处理时间线前，先让它完成健康检查，而不是直接说“修好视频”。官方建议的交付前顺序是：读取项目和时间线，运行 check_media_health、analyze_timeline 与 check_export_readiness。它们分别帮助发现缺失或零字节素材、时间线层面的异常，以及标准导出可能遇到的阻塞项或警告。
对于镜头连续性，可以让 Agent 通过 inspect_visible_shots 按可见镜头抽样，或者用 inspect_timeline_range 取得一个范围内的采样接触表。需要定位某个片段时，先用 find_timeline_items 搜索，再用 inspect_clip 检查目标。这个“搜索—检查—修改”顺序看似多了一步，却避免了自然语言里的“开头那个采访镜头”“中间过渡”被错误映射到实际片段。
审查结果应被要求输出为有限、可行动的清单，例如：缺失文件、潜在黑帧、音频增益异常、导出分辨率不匹配，以及每项建议影响的 clip ID 或时间范围。先让人判断建议是否合理，再进入写操作；不要把审查报告自动解释成执行授权。
第三步：所有写操作先走 previewOnly
Velorn 的多数写入型工具支持 previewOnly，许多默认即为预览模式。预览返回计划操作及建议的 apply 调用；只有再次把同一个动作设为 false 才会真正应用。以添加一条时间线标记为例：
{
"tool": "add_timeline_markers",
"arguments": {
"markers": [
{
"timeSeconds": 12.5,
"label": "检查镜头连续性",
"color": "#ffa500"
}
],
"previewOnly": true
}
}
预览阶段应让 Agent 说明：将修改哪些对象、预期结果是什么、是否会写磁盘、是否可能触发生成或消耗额度。用户确认后，才用相同参数并改为 "previewOnly": false。对多步动作，文档建议先调用 create_project_checkpoint，再使用 run_mcp_action_plan 执行已批准的动作序列，以便从检查点开始并在第一个错误处停止。
时间线中普通的编辑操作会进入 Velorn 的撤销系统，但这不是万能回退：项目创建、项目复制、导入媒体、生成资产和导出文件都可能写入磁盘。因此“能 Undo”不能替代前置确认；尤其是生成、导出和文件导入，应当作为单独的批准点。
ComfyUI 生成：先检查依赖，再排队
Velorn 可以围绕本地 ComfyUI 执行图工作流，但它不是 ComfyUI 的替代品。公开 README 说明，当前生成能力需要同一台机器上运行的本地 ComfyUI；普通时间线编辑、字幕和导出则不以此为前提。连接默认指向 http://127.0.0.1:8188，桌面应用只支持 localhost/loopback 的 ComfyUI 端点。
当 Agent 要从时间线画面生成或替换镜头时，建议按以下顺序：先用 inspect_timeline_frame 确认来源画面，再以 list_velorn_workflows 查看本机可用工作流；调用 prepare_generation_from_timeline_context 时保持预览；确认后才排入队列，并使用 get_generation_status 查询结果。若是外部社区工作流，则应先预览 import_comfyui_workflow 的依赖报告，检查缺失节点、模型引用和安装范围；安装也必须先预览再批准。
这种分层能把失败定位得更清楚。生成失败时，不要让 Agent 盲目反复排队；先检查 ComfyUI 连接、启动器日志、节点可用性和工作流结构。Velorn 提供 diagnose_comfyui_connection、get_comfyui_launcher_logs、validate_comfyui_nodes 和 inspect_velorn_workflow 来分别覆盖这些问题。
适用边界：把 Agent 当作受约束的剪辑协作者
Velorn 的 MCP 更适合已有明确项目边界的工作：生成前的时间线体检、镜头抽样审查、为已确认的问题准备标记、基于现有片段预览替换方案，以及交付前的导出检查。它不适合把创意判断、版权确认和最终交付责任完全交给自动化流程。
一条可落地的团队约定是：读操作可自动执行；普通时间线写操作必须展示预览；触发生成、下载依赖、写磁盘或开始导出时必须二次确认；最终由人复查时间线和导出文件。 还应把每次批准绑定到可识别的项目版本：记录项目名称、活跃时间线、检查时间、目标片段或时间范围，以及批准的操作摘要。这样，当一次导出出现画面、音频或时长差异时，团队可以回到检查报告和预览计划，而不是在聊天记录里猜测 Agent 曾经做过什么。
对批量任务尤其要限制范围。例如“清理整条时间线”应先拆成媒体健康检查、标记候选问题、预览一组小范围修复、人工审看，再决定是否扩大到下一段。若预览发现目标不明确、素材缺失或依赖异常，应停在报告阶段，不把不确定性转换成写入动作。对跨项目复用的提示词，也应保留“不得执行修改”的审查版本，避免把上一次的授权上下文误带到另一个交付工程。
这样，Agent 获得的是项目感知能力，而不是未经约束的剪辑权限。对希望把 AI 接入媒体生产的开发者而言，这比“让模型一键完成视频”更接近可审计、可复用的工程工作流。