企业官网建设流程全解析

去年年底开始，我一直在折腾一个想法：能不能让 AI Agent 不只是“聊天写代码”，而是真的帮我把画面排出来、把视频剪出来。

试了一圈现成工具后发现，市面上能接进来的剪辑编辑工具少得可怜。要么是纯在线 SaaS，素材得先传上去；要么是私有协议，Agent 根本没法直接调。后来我盯上了 MCP（Model Context Protocol）这个方向，又看到 libTV 这类画布式工具的交互思路，最后干脆自己写了一个开源项目：本地画布 + 剪辑，兼容 libTV 的常用工作流，并且内置 MCP Server，任何支持 MCP 的 Agent（Claude 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_id
• canvas_list()：列出所有画布项目及基本信息
• layer_add(canvas_id, layer_type, name)：添加图层，layer_type 可选 text/image/video/shape
• layer_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 到 1
• canvas_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 帧设置 opacity=0，在第 30 帧设置 opacity=1，它就会在 0 到 30 帧之间平滑淡入。

剪辑模块的核心工具如下：

• clip_import(file_path, project_id)：导入素材，返回 clip_asset_id
• timeline_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/list，Agent 询问服务端“你有哪些工具可以用”。服务端返回一个工具清单，每个工具包含名称、描述、参数 schema。

第二步是 tools/call，Agent 根据清单里的描述，选择工具并传入参数。服务端执行后返回结构化结果，可以是文本，也可以是资源引用。

我用 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.0），x 向右为正，y 向下为正""" layer = ProjectManager.get_layer(layer_id) layer.set_position(x, y) return layer.snapshot()

写工具描述时有一个非常关键的技巧：必须在描述里写明坐标系和使用习惯。

比如“坐标使用归一化坐标（0.0~1.0），x 向右为正，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 Server（stdio 模式） python -m canvas_studio.mcp

如果只想让画布作为 MCP 工具被调用，装到这里就够了。想打开预览界面实时看画布效果，再启动一个命令：

# 启动预览服务，默认端口 8765 python -m canvas_studio.ui --port 8765

MCP Server 支持 stdio 和 SSE 两种启动方式，选择哪种取决于你的使用场景：

我个人的建议是：仅留在本机使用的话，一律用 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( command="python", 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 帧设置文字 opacity=0，再在第 30 帧设置 opacity=1。两个关键帧之间的帧，系统自动插值，文字从完全透明渐变到完全不透明。

第五步，设置淡出关键帧。同理，在第 240 帧设置 opacity=1，在第 300 帧设置 opacity=0。

第六步，预览检查。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/down，pixels 为像素距离（基于基准分辨率 1920x1080）"""

与其让 Agent 自己计算新坐标，不如让它传方向字符串 left/right/up/down，工具内部换算坐标。实测下来，这个做法把方向类指令的错误率从 30% 降到了 5% 以下。因为方向语义是 AI 天然理解的，坐标计算才是容易出错的环节。

如果你不想用 nudge，也可以在系统提示词里加一句：“本画布使用屏幕坐标系，原点在左上角，水平向右为 X 正方向，垂直向下为 Y 正方向。”效果类似，但不一定每个 Agent 都严格遵循，所以接口层做一层语义包装更稳妥。

4. 常见问题与排查技巧实录

4.1 典型问题速查表

把我在开发和使用这个项目过程中遇到的问题整理成了一张表，按出现频率排序：

这张表里的绝大多数问题，都可以通过优化工具描述来规避。所以我始终强调：MCP 工具描述写得好不好，直接决定 Agent 的表现上限。参数范围、坐标系、值域、示例，一个都不能少。

4.2 我独自踩过的三个比较深的坑

第一个坑：工具暴露得不够细，Agent 容易“暴力调用”。最初版本我设计了 10 个工具，每个工具打包了大量逻辑，想着减少 Agent 调用次数。结果 Agent 经常因为一个参数传错导致整个操作失败，而且还不好回滚。后来我把工具拆细，一个操作一个工具，虽然调用次数多了，但成功率和可追溯性明显提升。

第二个坑：渲染任务耗时太长，直接把 MCP Server 卡死。视频渲染是重 CPU 任务，如果 Agent 调用 timeline_render 同步执行，一个 10 分钟视频可能渲染 5 分钟，期间所有其他 MCP 请求都阻塞。后来我把渲染改成异步任务：timeline_render 立即返回 task_id，Agent 再轮询 task_status 查询进度。

第三个坑：画布状态不同步。最初版本没有把项目状态暴露为 MCP resource，Agent 只能靠自己的记忆判断当前状态，结果经常“幻想”出一个图层，或者对不存在的图层做操作。暴露 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，就会按标准流程执行，成功率会非常高。这算是我在过去几个月的开发和使用过程中，最值得分享的一条落地经验。