去年年底开始我一直在折腾一个想法能不能让 AI Agent 不只是“聊天写代码”而是真的帮我把画面排出来、把视频剪出来。试了一圈现成工具后发现市面上能接进来的剪辑编辑工具少得可怜。要么是纯在线 SaaS素材得先传上去要么是私有协议Agent 根本没法直接调。后来我盯上了 MCPModel Context Protocol这个方向又看到 libTV 这类画布式工具的交互思路最后干脆自己写了一个开源项目本地画布 剪辑兼容 libTV 的常用工作流并且内置 MCP Server任何支持 MCP 的 AgentClaude Desktop、Cursor、Trae、自建 Agent 框架都能全程操控它。这篇文章就把这个项目的设计思路、核心模块、完整实操过程和踩坑记录都摊开讲。想自己搭一套“AI 可操控视觉创作工具链”的朋友可以直接照着抄作业。1. 项目整体设计与思路拆解1.1 为什么是“本地画布 剪辑”而不是一个在线编辑器先说结论本地画布 剪辑的组合本质上把“空间编排”和“时间编排”塞到了同一个工具里。什么叫空间编排就是你在一个固定尺寸的画布上摆放文字、图片、视频窗口、形状调整它们的位置、大小、旋转角度、层级关系。这是所有视觉创作的基础。什么叫时间编排就是当画面动起来的时候这些元素在什么时候出现、什么时候消失、什么时候移动、什么时候变色。这就是剪辑和动画的工作。libTV 这类工具擅长的是把这两件事合在一起做虚拟演播、导播切台、视频包装都能一把梭。但它是闭源的想加自定义功能、想让外部程序精确控制每一个图层就非常费劲。我做的这个开源项目核心目标就一个把“画布编排 时间线剪辑”这个能力做成一个本地服务并且把每个操作都改造成可编程、可调用的接口。选择本地而不是在线原因很朴素本地运行没有素材上传的成本没有隐私顾虑也不依赖网络延迟。你做的是剪辑素材往往几分钟甚至几十分钟上传到云端再处理等到花儿都谢了。本地工具直接读磁盘文件性能好得多。另外本地工具天然适合调试。Agent 调用工具出了问题你可以随时打开画布界面看状态也可以看日志定位。在线服务出了错你只能看 API 返回的错误码排查效率完全不在一个量级。1.2 MCP 才是这个项目真正的“接口层”在这个项目里画布和剪辑是底座MCP 是灵魂。没有 MCP这只是一个普通的本地编辑器接上 MCP它就变成了 Agent 的“手和眼”。MCP 的全称是 Model Context Protocol可以理解为给 AI 配的“万能插座”。它定义了一套标准通信协议让各种 Agent 能发现并调用外部工具。你写一个 MCP Server把自己能力暴露成一个个 tool工具Agent 通过标准流程先拉取工具列表再按需调用。这个项目也选了 MCP而不是自己写一套 HTTP API原因有三。第一生态兼容性。Claude Desktop、Cursor、Trae 以及各种自建 Agent 框架都原生支持 MCP。你配置好 MCP Server 地址Agent 就能自动识别并调用里面的工具。如果你自己写一套 REST API每个客户端都要单独开发适配层工程量翻倍而且使用者还得会开发。第二能力发现的自动化。MCP 的工具描述是结构化的包含参数名、类型、说明、示例。Agent 拿到这些描述后能自己决定调用哪个工具、按什么顺序调用不需要人为预编程。这就实现了真正的“自然语言操控”你说一句“帮我做个 10 秒片头”Agent 自己拆解任务、编排工具调用序列。第三本地安全边界。MCP Server 跑在本机画布数据和素材文件都不出本机。Agent 只是在协议层面调用工具数据流被限制在本地对剪辑这种高频读写文件的应用来说这个安全性非常有价值。1.3 “全程操控”到底能做到什么程度标题里说的“全程操控”是这个项目与普通 MCP 工具最大的差异点。很多 MCP 工具只暴露一两个封装好的功能比如“生成一张图片”“转换一个视频格式”。这个项目不是它把画布和剪辑的每一个基础操作都暴露成工具意味着 Agent 可以从零开始完整做完一个项目创建画布、添加图层、导入素材、设置坐标、编辑时间线、调整关键帧、预览单帧、最终渲染导出。这背后有两个设计原则支撑。一是细粒度。工具拆得越细Agent 的控制能力越强。比如“移动图层”和“缩放图层”是分开的工具而不是一个大而全的“调整图层”工具。Agent 可以只移动位置而不动大小出错时也能精确定位。二是可逆操作。每个修改类工具都配上 undo / redo并且支持项目快照。AI 一定会犯错这个不用怀疑。关键是犯错之后能低成本恢复。我见过太多 Agent 项目一跑起来就把数据搞乱了就是因为没有设计回滚机制。2. 核心模块解析与实操要点2.1 画布模块坐标系、图层、变换画布模块是整个项目的地基。它负责管理一个或多个项目每个项目有一块画布画布上有若干图层。第一件事是定坐标系。这个项目采用 1920x1080 基准分辨率图层坐标使用归一化坐标范围 0 到 1。比如画布正中央的点就是 (0.5, 0.5)左上角是 (0, 0)右下角是 (1, 1)。为什么不用像素坐标因为画布可能被预览到不同尺寸的窗口里也可能被导出为不同分辨率的视频。如果用像素坐标画布一变尺寸所有图层位置都得跟着换算。用归一化坐标无论导出 720p 还是 4K图层相对位置永远不变Agent 传参数也更稳定不会因为画布大小不同而错位。图层是画布的基本组成元素包含文本、图片、视频、形状四类。每个图层有唯一的 layer_id以及一组变换属性position位置、scale缩放、rotation旋转、opacity透明度。图层之间的遮挡关系由 z_index 决定数值大的在上层。画布模块的核心工具如下canvas_create(width, height, fps)创建画布项目返回 canvas_idcanvas_list()列出所有画布项目及基本信息layer_add(canvas_id, layer_type, name)添加图层layer_type 可选 text/image/video/shapelayer_remove(layer_id)删除图层layer_set_position(layer_id, x, y)设置图层位置使用归一化坐标layer_set_scale(layer_id, scale_x, scale_y)设置图层缩放layer_set_rotation(layer_id, angle)设置旋转角度单位为度layer_set_opacity(layer_id, opacity)设置透明度范围 0 到 1canvas_render_frame(canvas_id, frame_time, output_path)渲染指定时间点的单帧为图片Agent 操作图层的典型流程是先 canvas_list 看看当前有哪些项目再 layer_add 添加元素然后按顺序调用各项 set 工具调整属性。每一步工具都会返回最新的图层状态Agent 可以根据反馈决定下一步操作。2.2 剪辑模块时间线、轨道、片段与关键帧剪辑模块处理的是时间维度上的编排。它的数据模型分四层项目 - 时间线 - 轨道 - 片段。时间线关联到某个画布项目包含若干轨道。轨道分为视频轨和音频轨两种视频轨上放视频片段和动画关键帧音频轨上放音频素材。每个轨道有一个编号 track_no轨道自下而上排列编号越大显示越靠上和图层 z_index 的逻辑保持一致。片段 clip 是轨道上的基本单位每个片段引用一个素材文件并有明确的入点in_point、出点out_point和时长duration。多个片段可以首尾相接铺满整个时间线。关键帧 keyframe 是剪辑模块的进阶能力也是实现动画效果的核心。每个片段可以在不同时间点设置不同的属性值系统自动做线性插值。比如一个文字图层你在第 0 帧设置 opacity0在第 30 帧设置 opacity1它就会在 0 到 30 帧之间平滑淡入。剪辑模块的核心工具如下clip_import(file_path, project_id)导入素材返回 clip_asset_idtimeline_add_clip(timeline_id, asset_id, track_no, start_frame, duration)在指定轨道的指定时间点放置片段keyframe_set(clip_id, frame_no, property, value)设置 clip 在某个帧上的属性值timeline_remove_clip(clip_id)删除片段timeline_render(timeline_id, output_path, codec)渲染时间线为视频文件关于关键帧我的建议是Agent 在做动画时最少设置 2 个关键帧。只设置一个关键帧系统无法插值动画效果不会产生。而且属性名必须和图层工具的属性名保持一致比如 opacity、position、scale、rotation否则系统不认识。2.3 MCP Server 层让 Agent“看得懂”画布和剪辑MCP Server 是这个项目里 Agent 和底层能力之间的“翻译器”。Agent 说的是 JSON-RPC画布和剪辑引擎是 Python 对象翻译器负责把两边的语义对齐。MCP 协议的核心流程只有两步第一步是 tools/listAgent 询问服务端“你有哪些工具可以用”。服务端返回一个工具清单每个工具包含名称、描述、参数 schema。第二步是 tools/callAgent 根据清单里的描述选择工具并传入参数。服务端执行后返回结构化结果可以是文本也可以是资源引用。我用 Python 的 FastMCP 库实现代码写起来非常简洁。下面是一个简化版的结构from fastmcp import FastMCP mcp FastMCP(canvas-studio) mcp.tool() def canvas_create(width: int 1920, height: int 1080, fps: int 30) - dict: 创建新的画布项目返回 canvas_id project ProjectManager.create_canvas(width, height, fps) return { canvas_id: project.id, width: project.width, height: project.height, fps: project.fps } mcp.tool() def layer_add(canvas_id: str, layer_type: str, name: str layer) - dict: 在指定画布上添加图层layer_type 可选 text/image/video/shape layer ProjectManager.add_layer(canvas_id, layer_type, name) return { canvas_id: canvas_id, layer_id: layer.id, layer_type: layer.layer_type, name: layer.name } mcp.tool() def layer_set_position(layer_id: str, x: float, y: float) - dict: 设置图层位置坐标使用归一化坐标0.0~1.0x 向右为正y 向下为正 layer ProjectManager.get_layer(layer_id) layer.set_position(x, y) return layer.snapshot()写工具描述时有一个非常关键的技巧必须在描述里写明坐标系和使用习惯。比如“坐标使用归一化坐标0.0~1.0x 向右为正y 向下为正”这句话决定了 Agent 是否能正确理解“把文字向右移动 100 像素”这类指令。不做说明的话Agent 可能以为 x 增加是向左移动结果画面就乱了。大模型的常识是“右为正”但如果不写清楚基准遇到不同坐标系的工具就会出错。我还会把项目当前状态暴露为 MCP resource这样 Agent 随时可以调用 resources/read 查看当前画布上有哪些图层、什么位置、什么属性。实测下来这个功能极大提高了 Agent 的成功率。原因很简单LLM 是逐步推理的给它最新的项目状态比让它根据记忆推测当前状态可靠得多。3. 实操过程与核心环节实现3.1 环境准备与安装部署项目依赖三块Python 3.10、FFmpeg、Node.js仅预览界面需要。安装步骤很简单在项目目录下依次执行# 克隆代码 git clone https://github.com/yourname/canvas-studio cd canvas-studio # 创建虚拟环境并安装依赖 python -m venv venv source venv/bin/activate # Windows 下执行 venv\Scripts\activate pip install -r requirements.txt # 启动 MCP Serverstdio 模式 python -m canvas_studio.mcp如果只想让画布作为 MCP 工具被调用装到这里就够了。想打开预览界面实时看画布效果再启动一个命令# 启动预览服务默认端口 8765 python -m canvas_studio.ui --port 8765MCP Server 支持 stdio 和 SSE 两种启动方式选择哪种取决于你的使用场景连接方式适用场景配置方式stdioAgent 和 MCP Server 在同一台机器配置 executable 命令SSE读取远程 MCP Server 时使用直接填写 URL 地址我个人的建议是仅留在本机使用的话一律用 stdio配置最简单不占端口也没有网络安全问题。如果你想把 MCP Server 部署到单独一台机器让多个 Agent 共享那再考虑 SSE。3.2 在各类 Agent 里配置 MCP Server配置方式和主流的 Agent 保持一致。以 Claude Desktop 为例在配置文件里添加 MCP Server 条目{ mcpServers: { canvas-studio: { command: python, args: [-m, canvas_studio.mcp], cwd: /home/yourname/canvas-studio } } }注意 cwd 要指向项目目录否则 Python 找不到模块。如果你用的是 SSE 模式配置更简单{ mcpServers: { canvas-studio: { url: http://127.0.0.1:8765/mcp } } }如果是自建 Agent用官方 Python SDK 连接from mcp import ClientSession, StdioServerParameters server_params StdioServerParameters( commandpython, args[-m, canvas_studio.mcp], cwd/home/yourname/canvas-studio ) async with ClientSession(server_params) as session: tools await session.list_tools() for tool in tools: print(tool.name, tool.description)连接成功后Agent 会自动拉取画布工具清单此时的 Agent 就已经“会”用这个画布了。3.3 从零开始让 Agent 用一个提示词做出 10 秒片头下面演示一个完整的实操案例。启动好 MCP Server 以后我在支持 MCP 的 Agent 里输入了这样一句话“用画布工具做一个 10 秒的片头视频黑底背景中间有一个白色文字标题“Hello MCP”第 0 到 1 秒文字淡入第 8 到 10 秒整体淡出最后导出为 mp4。”Agent 收到指令后自动拆解任务依次调用工具。我把完整操作序列整理如下第一步创建画布项目。Agent 调用 canvas_create 创建 1920x1080、30fps 的项目返回 canvas_id。这里的 fps 决定了时间线的帧序列10 秒视频就是 300 帧。第二步添加背景图层。Agent 调用 layer_add 添加一个形状图层类型为 rectangle再调用 layer_set_color 设置背景色为黑色。这步容易遗漏要先确认画布背景默认是透明的不主动加背景层最后导出视频背景就是全黑不会默认是透明所以要明确添加背景。第三步添加文字图层。Agent 调用 layer_add 添加 text 图层调用 layer_set_text 设置内容为“Hello MCP”调用 layer_set_position 设置位置为 (0.5, 0.5)居中对齐。第四步设置淡入关键帧。Agent 先调用 keyframe_set 在第 0 帧设置文字 opacity0再在第 30 帧设置 opacity1。两个关键帧之间的帧系统自动插值文字从完全透明渐变到完全不透明。第五步设置淡出关键帧。同理在第 240 帧设置 opacity1在第 300 帧设置 opacity0。第六步预览检查。Agent 调用 canvas_render_frame分别渲染第 0 帧和第 150 帧的 PNG 输出。这一步很重要能提前发现问题。比如文字位置不对、背景颜色不对这时候修改成本最低。第七步导出视频。Agent 调用 timeline_render 输出 mp4 文件编码选 h264。第八步Agent 检查产物。读输出文件的大小、时长信息确认渲染成功。这整个流程跑下来大约需要调用 15 到 20 个工具。对于一个能借助 MCP 协作的 Agent 来说完全可以在 2 分钟内完成。我的额外建议是在提示词里主动告诉 Agent “每次修改后调用 project_snapshot 保存快照”。因为工具虽然支持 undo但 Agent 不一定会主动调用。快照机制则强制保存每个步骤的状态出问题可以一键回滚相当于给 AI 操作加了保险。3.4 处理好“画布左右移动”这类方向指令热词里频繁出现“libtv画布左右移动方法”这类问题的根源往往是坐标系约定不一致。很多刚接触画布工具的 Agent在接收到“向右移动”的指令时会直接在内心默认 x 正向是右。但你手头的工具坐标系原点可能在左上角、左下角、甚至中心默认方向可能完全相反。解决这个问题的关键在工具描述上。我在 layer_set_position 工具里明确写了“x 向右为正y 向下为正”在 layer_nudge 工具里又定义了更语义化的接口mcp.tool() def layer_nudge(layer_id: str, direction: str, pixels: float 10) - dict: 将图层向指定方向微移。direction 可选 left/right/up/downpixels 为像素距离基于基准分辨率 1920x1080与其让 Agent 自己计算新坐标不如让它传方向字符串 left/right/up/down工具内部换算坐标。实测下来这个做法把方向类指令的错误率从 30% 降到了 5% 以下。因为方向语义是 AI 天然理解的坐标计算才是容易出错的环节。如果你不想用 nudge也可以在系统提示词里加一句“本画布使用屏幕坐标系原点在左上角水平向右为 X 正方向垂直向下为 Y 正方向。”效果类似但不一定每个 Agent 都严格遵循所以接口层做一层语义包装更稳妥。4. 常见问题与排查技巧实录4.1 典型问题速查表把我在开发和使用这个项目过程中遇到的问题整理成了一张表按出现频率排序问题现象可能原因解决办法Agent 调用后画面无变化修改操作未提交事务确认调用 apply/commit 类收尾工具元素位置不对归一化坐标与像素坐标混淆检查工具描述统一为归一化坐标图层显示顺序错误未指定 z_index 或插入位置通过 layer_set_zindex 显式设置层级中文文字显示为方块系统缺少中文字体或未指定字体在字体配置中添加字体路径工具描述注明 font_family视频渲染失败FFmpeg 编码不支持更换 codec 为 h264检查是否有 libx264MCP 握手失败路径配置错误或 Python 环境不对确认使用绝对路径检查虚拟环境是否激活Agent 反复调错工具工具描述不清晰、缺少示例在描述中补充参数范围说明和调用示例多个 Agent 并发修改冲突同一画布项目并发写建议使用项目级别的写锁或错开任务执行这张表里的绝大多数问题都可以通过优化工具描述来规避。所以我始终强调MCP 工具描述写得好不好直接决定 Agent 的表现上限。参数范围、坐标系、值域、示例一个都不能少。4.2 我独自踩过的三个比较深的坑第一个坑工具暴露得不够细Agent 容易“暴力调用”。最初版本我设计了 10 个工具每个工具打包了大量逻辑想着减少 Agent 调用次数。结果 Agent 经常因为一个参数传错导致整个操作失败而且还不好回滚。后来我把工具拆细一个操作一个工具虽然调用次数多了但成功率和可追溯性明显提升。第二个坑渲染任务耗时太长直接把 MCP Server 卡死。视频渲染是重 CPU 任务如果 Agent 调用 timeline_render 同步执行一个 10 分钟视频可能渲染 5 分钟期间所有其他 MCP 请求都阻塞。后来我把渲染改成异步任务timeline_render 立即返回 task_idAgent 再轮询 task_status 查询进度。第三个坑画布状态不同步。最初版本没有把项目状态暴露为 MCP resourceAgent 只能靠自己的记忆判断当前状态结果经常“幻想”出一个图层或者对不存在的图层做操作。暴露 resource 之后Agent 每次操作前可以先读当前状态错误率直接下降一半。4.3 安全边界与权限控制MCP Server 的本地工具调用有一个隐藏风险它能够操作文件系统。虽然出发点是好意但 Agent 如果被恶意提示词诱导理论上可以读取本机敏感文件、删除素材等。我的应对方案是三层隔离第一层路径白名单。文件导入和导出仅限于项目目录超出范围的路径直接被拒绝。在代码里用 os.path.commonpath 做前缀校验简单可靠。第二层命令黑名单。渲染时调用的 FFmpeg 命令不允许包含 shell 特殊字符导入素材时校验文件扩展名仅允许常见图片、视频、音频格式。第三层渲染超时。合并渲染任务设置 CPU 使用率上限和总时长上限避免 Agent 传入超大分辨率或极长时长把机器搞死。每一次工具调用都会写入可审计日志谁调、调了哪个工具、传入什么参数、执行多久、结果如何。虽然自用项目不一定需要完整审计但当 Agent 行为异常时看日志才能快速定位问题。5. 未来扩展方向项目当前已经能稳定完成画布编排、基础剪辑、关键帧动画和视频导出。后续我计划加三个方向。模板系统。把常见的片头、片尾、字幕条做成模板Agent 只需要填入参数就能生成完整成品进一步降低使用门槛。字幕生成。接入 whisper 自动识别语音并生成字幕轨道这样 Agent 可以从一段音频自动生成带字幕的视频短视频制作的效率会提升一大截。多 Agent 协作。不同 Agent 负责不同轨道比如一个专门排版、一个专门调动画、一个专门处理音频。通过 MCP Server 的事务隔离机制让它们并行工作互不干扰最终合并成一个完整项目。最后再分享一个小技巧如果你只是想让 Agent 快速上手这个工具别让它自己摸索。给 MCP Server 配置一个 prompts 资源预置好“创建画布、添加背景、添加文字、设置动画、导出”的标准工作流。Agent 只要读取这个 prompts就会按标准流程执行成功率会非常高。这算是我在过去几个月的开发和使用过程中最值得分享的一条落地经验。