画布 MCP 使用指南

复制给 AI 助手 mcp.md 是专门写给 Claude Code / Codex / Cursor 读的操作手册（流程、费用规则、何时停下问人）。点按钮复制全文，粘给助手即可；也可以让助手直接读取 https://studio.skyhorse.ai/docs/mcp.md。

让你自己的 AI 助手（Claude Code、Codex、Cursor、Hermes 等）直接操作 SKYHORSE 画布。

这是什么

画布 MCP 服务让你的 AI 助手读画布、加节点、连线、生成图片/视频/音频、合成成片、上传和导入素材、直接拿到成品文件。地址 https://cn-api.skyhorse.ai/mcp，用你自己的令牌登录。

助手做的每一步都像你在画布上亲手操作：打开同一画布的同事会实时看到节点出现；所有生成费用记在你的令牌上。助手不能删除任何节点或画布。

准备：生成自己的令牌

1. 登录网关后台 https://cn-api.skyhorse.ai，进入「令牌」页。
2. 新建一个令牌，名称写清用途（例如「我的 Claude Code」），额度按需设置。
3. 复制以 sk- 开头的令牌。它和你在 Studio 里用的是同一种，可以直接复用现有的。

接入步骤

只需要两样东西：服务地址 https://cn-api.skyhorse.ai/mcp 和你的令牌。下面把 sk-你的令牌 换成自己的。

Claude Code（终端里执行一次）

claude mcp add --transport http skyhorse-canvas https://cn-api.skyhorse.ai/mcp --header "Authorization: Bearer ***"

Codex（编辑 ~/.codex/config.toml，加在末尾）

[mcp_servers.skyhorse-canvas]
url = "https://cn-api.skyhorse.ai/mcp"
http_headers = { Authorization = "Bearer sk-你的令牌" }

Cursor / Windsurf / 其他支持 MCP 的工具（MCP 设置里粘贴）

{"mcpServers":{"skyhorse-canvas":{"url":"https://cn-api.skyhorse.ai/mcp","headers":{"Authorization":"Bearer sk-你的令牌"}}}}

验证：在助手里说「列出我的画布」，能返回画布列表就接通了。

能做什么

助手会自己选工具，你只需要用人话描述目标。下表是它手里的 43 个工具。

生成和在画布里手动点「生成」完全一样：同样的模型、同样的价格，结果同样进入资产库。合成、上传不收费。

1.11 版（2026-10-26）：分镜脚本工作台

画布的脚本节点升级为全屏分镜工作台（镜头表：时长 / 画面描述 / 景别 / 光影 / 对白 / 音效 / 运镜，状态 草稿·已确认·需复核，逐字段锁定，拖拽排序，重新拆分出差异候选）。助手与它的分工：

• AI 可以自己拆剧本：读完剧本后用 add_shots 把镜头写进脚本节点（省略 node_id 即新建）。每镜 duration 必须在脚本所选视频模型的单段范围内（Seedance 2.5 为 4–30s、MiniMax 为 5–15s……），超出会被钳到边界并在 warnings 里说明；更长的动作请拆成多镜。
• 新镜头一律是草稿，助手不能确认镜头——确认由人在画布「打开分镜脚本」里做；也只有全部确认后才能「同步到画布」。
• read_storyboard 读整表（含每镜状态、锁定字段、汇总与时长范围）；update_shot 改字段：锁定的字段不动（返回 skipped），已确认的镜头改了创作字段会回到「需复核」；remove_shots 删已确认或锁定的镜头需 confirmed: true。
• expand_storyboard 仍可一步建表并展开节点，现在写的是 v2 镜头表，字段扩展为 description / lighting / dialogues[] / sound_effects / camera，时长同样按模型范围校验。

1.10 版（2026-10-22）：首页按文件夹组织

首页是两层：文件夹 → 画布。一个剧本一个文件夹，里面放它的全部画布；没放进文件夹的画布在「全部」。接口和工具名里这个文件夹叫 project（历史原因），助手对人说话时一律叫「文件夹」。

• list_projects 返回全部文件夹（画布数、最近编辑、封面、单画布时的 first_canvas_id）；list_canvases 每张画布带 project_id（空 = 在「全部」）。
• create_project 新建文件夹；update_project 重命名 / 设置封面；set_canvas_project 把画布放进文件夹（空字符串 = 移出到「全部」）。文件夹只有一层，没有子文件夹。
• delete_project 是唯一的删除类工具：文件夹连同画布进最近删除，30 天内 restore_project 可恢复；调用必须带 confirmed: true，即助手要先问过人。
• 画布上生成的素材自动归入画布所在的文件夹；素材库条目可标「本文件夹 / 全局」，list_library(project_id) 返回本文件夹 + 全局。

1.9 版（2026-10-20）：素材库、运镜、提示词优化

• 素材库：list_library 看员工整理好的人物 / 场景 / 道具 / 音频；use_library_item 把一条放到画布上（等同从素材库拖入，可直接 connect_to 某个视频节点）；save_to_library 把定稿图或音频存回去。做剧集先看素材库，优先用定妆图，不要自己重生成。
• 运镜：list_camera_moves 列出 23 个内置运镜和员工自定义的，每个带 mark（如 [运镜:镜头前推]）和生成时替代它的提示词。在视频提示词里直接写 mark，可多个、可穿插在句中；expand_storyboard 每一行可带 camera: key，展开时自动加到镜头的视频提示词末尾。
• 提示词优化：optimize_prompt 把一句简短描述扩写成分镜式提示词（主体 → 总述 → 镜头 → 画风），原文的名词、时间和标签保留；返回文本，由助手决定是否写入节点。
• 读画布更省：视频和图片结果多了 thumbnail_url（首帧 / 预览 JPG）；视频节点带 camera_moves（解析出的运镜标签）；从素材库放入的节点带 library_item。便签（员工给人看的标注）不再出现在 read_canvas 里。

1.8 版（2026-10-12）：资产库按项目和用途归档

注：1.10 起首页改为「文件夹 → 画布」两层，下文的「项目」即现在的「文件夹」；画布放进文件夹的操作改在首页完成（拖拽或画布菜单「移动到文件夹…」）。

• 项目：画布菜单里「所属项目」选一次（或新建）。一部剧的几张画布绑同一项目，它们生成的素材进同一个文件夹树，分镜画布可以直接拿总画布上定稿的定妆图。
• 自动归类：新生成的素材按用途归到 定妆 / 场景 / 道具 / 风格 / 分镜图 / 镜头 / 成片 / 配乐 / 配音 / 上传 / 待归类。依据先是画布结构（节点名、分镜连线、被几个节点引用），再是提示词，最后才让 AI 看图。节点起名规范归类就准：「定妆 林辰」「场景 破饭馆」「E1-05」。
• 资产库界面：点左上角文件夹按钮展开项目 → 用途树（默认停在当前画布的项目）；AI 归的类显示灰标，把资产拖到左边另一个文件夹即人工纠正，之后不再被改。旧资产原样在「历史资产」里，不重新分类。
• 原来按提示词打的通用标签（人物/场景/商品）停用。

1.7 版（2026-10-12）：删除可恢复、历史版本、覆盖防护

• 删除画布进「最近删除」，30 天内可恢复（画布菜单底部 / MCP restore_canvas）。同一账号下几个人共用时，谁误删都能找回。
• 历史版本：每次保存的画布文档都留档（每 10 分钟最多一版，保留 7 天），画布菜单「历史版本」或 MCP list_versions / restore_version 一键恢复。恢复前的当前版本也会留档，所以恢复本身可以撤销。
• 覆盖防护：一台电脑带着几天前的旧副本打开画布，不再能把同事的内容整个替换掉——旧副本只会并入（本机节点写入、共享节点不删），服务端还有第二道闸：任何一次改动删掉一半以上节点会被回滚并记录。
• 保存失败会告诉你：协作服务写数据库失败时，所有正在编辑的人页面顶部会出红色提示，不再静默丢。
• 画布数据每小时快照到 S3、每日全量备份也同步到 S3，服务器本身无法删除这些备份。

1.6 版（2026-10-11）：助手能看到结果；重启不丢任务

• view_result：原来生成完只返回链接，Codex / Claude Code 这类助手不会去下载看图，等于盲选。现在这个工具直接把画面作为图片返回——图片节点给缩放图（长边默认 1024），视频节点给首→尾等间隔抽帧拼成的一条（默认 3 帧，最多 6）。助手能自己发现画崩、黑屏、人物不一致、上下镜接不上，决定重跑还是选用。免费。
• 任务表存 Redis：原来 job_id 只在 MCP 进程内存里，服务一发布就"任务不存在"，助手容易重提一遍、花两次钱。现在任务记录保存 6 小时；生成一旦提交到网关，任务就记住网关的句柄，服务重启后助手再问一次 job_status 就会接着等，结果照常写回节点，不用也不该重新 generate。

推荐流程里加一步：generate → job_status → view_result → 不行就改提示词重跑，行就 select_result。

1.5 版（2026-10-11）：「整理」按集与镜头排

原来的「整理」（画布按钮和 arrange_canvas 都是）按"谁依赖谁"分列，这是程序看图的方式，不是人看片的方式：派生定妆多一层、多集混放、补拍打乱顺序，任一出现就乱。现在改为按剧作结构排：

• 设定区（左上）：剧本、风格段一行；定妆、场景、道具各自成行（按名字前缀「定妆 / 场景 / 道具」识别）。
• 每集一条横带：分镜表节点在最左，然后每镜一列——分镜图在上、视频在下——按镜头号 1→N 从左到右；该集的配乐和成片放在带尾。
• 归档区（最下）：分段合成、分段成品、测试节点等认不出归属的东西，不再混进正文。

怎么认出"第几集第几镜"：分镜表的 shot 连线（用 expand_storyboard 或画布「展开为节点」建的）最可靠；其次是名字（E2-05、第2集 第7镜、镜头 5、配乐 第三集、第1集 成片）；都认不出的可以用 sections 显式指定分区。随手命名的画布只能先归档再手工分区——整理的上限取决于建画布时有没有留结构。

整理前会自动把原位置存档，restore_layout 一键还原（MCP 从外部改的位置不进浏览器的 Ctrl+Z）。172 个节点约 1 秒。画布右键菜单里保留了旧的「按连线整理」。

1.4 版新增（2026-10-11）：整条短剧流程

对照团队实际做片的方法（定妆图 → 分镜表 → 逐镜生成 → 截帧接戏 → 多版挑选 → 合成），补齐了助手原来做不了的几步：

• 分镜表一键展开 expand_storyboard：给 rows（每行 number / duration / image_prompt / video_prompt / dialogue）、角色定妆图节点、全片风格段，一次建出脚本节点和每镜的「镜头 N」分镜图 + 「镜头 N 视频」，角色图自动连到每张分镜图，风格段自动追加到每条提示词末尾——不用再把同一段话手工贴进二十个提示词。时长自动卡到模型范围。然后用 generate 批量生成。
• 截帧接戏 capture_frame：从视频结果截 first / last / 某一秒（如 "12.7"）成图片节点，connect_to 直接连到下一镜做参考，提示词里写「衔接上一镜 @ImageN」即可。免费，由服务器完成。
• 选用版本 select_result：一个节点生成多次会有多版，助手可以按人的指示选用第几版（read_canvas 带 detail=true 能看到每一版的链接）；下游已生成的节点会标为过期。哪一版能用仍由人在画布里看着定，助手只负责搭和跑。
• 参考视频：视频可以连到视频做动效参考（人名条批量出动效的做法），连线规则和画布完全一致，不合法的连线会用画布同样的话解释原因。
• 大文件上传：成片这类大文件先用令牌把原始字节 POST 到 https://cn-api.skyhorse.ai/v1/studio/media（视频 ≤ 512 MB），再把返回的 media_id 传给 upload_media。

推荐给助手的流程：导入或生成角色定妆图 → expand_storyboard → 检查提示词 → generate 分镜图 → 人挑版 → generate 视频 → capture_frame 接戏并补拍 → compose 合成（可带字幕）→ arrange_canvas 整理。

1.3 版新增（2026-10-10）：布局不再重叠

之前助手建的节点会叠在一起（放置时按 340 像素错开，而图片/视频节点实际宽 520，且不检查是否压到别的节点）。现在：

• 自动找空位：新节点按画布里同一套规则放置——有输入时放在输入节点右侧一整个节点宽的位置，没有输入时放到画布最下方；被占了就按真实节点尺寸找最近的空位，不会压到任何已有节点。
• 一键整理：新工具 arrange_canvas 把节点按依赖关系从左到右分列（文本和定妆照在左，分镜图居中，视频靠右，合成最右），同一列按建立顺序从上到下排（第 1 镜在最上）。可以整理全画布，也可以只整理刚建好的一批节点（node_ids），其余不动；给 origin 可指定摆放的左上角。只改位置，不改任何内容和连线。

建议让助手在建完一批节点后调一次 arrange_canvas；已经乱掉的旧画布也可以直接让它整理。

1.2 版新增（2026-10-06）

直接拿到成品文件

以前生成结果只有一个 mediaId，助手得去资产库按大小反查，容易下错。现在每个结果（job_status、read_canvas、list_assets 都一样）带齐这些字段：

按类型排队，可批量提交

以前所有生成共用 3 个位置，几秒钟的配音要和出图、视频抢。现在按类型分队列，同一令牌同时跑：图片 4 · 视频 3 · 音频 4 · 合成 2。generate 可以给 node_ids 一次提交最多 24 个节点（任一节点有问题整批不提交，不会花冤枉钱），超出并发的排队等待，job_status 会告诉你前面还有几个。

Gemini 配音（gemini-tts / gemini-lite-tts）连发会被 Google 限流：现在同时只跑 2 条，遇到限流自动等待重试（最多 3 次），不再直接判失败。

上传本地文件

upload_media 可以把助手本地的 PNG / JPG / WebP / MP4 / WebM / MP3 / WAV / M4A / OGG（≤ 32 MB）传上来，直接成为画布上一个带结果的节点——本地做的图、上一集的定妆照都能进画布当参考，音频和视频同时进资产库。

参数写错会报错

以前拼错参数名或给了模型不支持的值也会被收下，以为生效了其实没有。现在 add_node / update_node 会校验每个参数名和取值，写错直接报错并列出可选项。让助手先 list_models 看一眼最省事。几个要点：

• gemini-tts / gemini-lite-tts：只出 wav；没有 language / speed，用 style 一句话描述语气。一个音频节点一个声音；两个人物对话就建两个音频节点各选音色（双人对话功能已于 2026-10-27 下线）。
• eleven-music：只出 mp3，不认 wav；duration 5–300 秒，instrumental 纯音乐。
• seed-audio：可以连入最多 3 段参考音频；minimax / eleven-v3：只出 mp3。
• 视频：每个模型的时长范围、画幅、清晰度不同（如 seedance-2.5 只有 480p / 720p，1080p 要选 fal/seedance-2.5）。

合成成片：时间轴与字幕

compose 让合成节点把视频片段拼成一部成片，免费，由服务器完成：

• 顺序：clips 里列出视频节点的顺序就是成片顺序；没连到合成节点的素材会自动连上。
• 每段起止：offset（从这段的第几秒开始取）、duration（取几秒）、muted（静音原声）。
• 音轨：audio 每条给 start（成片第几秒起）、volume（0–2，默认 0.8），最多 8 条。
• 字幕：subtitles 每条 {text, start, end}（成片时间轴，秒）烧录进画面，支持中文；subtitle_style 可调 size（像素）、position（bottom / top / center）、color / outline（六位十六进制）、margin、bold。

成片 ≤ 15 分钟，成功后同样带 download_url / asset_id，也会出现在资产库。

可以这样说

• 「列出我的画布，打开『总画布』，告诉我有哪些视频节点还没生成」
• 「新建一个叫『第二集 分镜』的画布，按我这份分镜表建 12 个视频节点，每个 10 秒 720p，提示词写进去，先不要生成」
• 「把资产库里叫『秦回定妆』的图导入画布，连到所有视频节点做参考」
• 「把第 3 镜的提示词改成夜景，换成 9:16，然后生成，生成完告诉我」
• 「给这个画布加一个音频节点，用 Eleven Music 生成 60 秒悬疑配乐，纯音乐」
• 「把这 12 句旁白节点一起生成，完成后把音频文件都下载到 ./voice/ 目录」
• 「把我本地的 cover.png 传上去，连到所有视频节点做参考」
• 「把 1 到 8 镜按顺序合成一部 9:16 的片子，配上旁白和配乐，旁白词做成字幕放在底部」
• 「这个画布太乱了，帮我整理一下布局」
• 「把这份分镜表展开成镜头，角色用画布上的 Leo 和 Mira 定妆图，风格段用『文本 3』那段，9:16 720p，先不要生成」
• 「截『视频 4』的尾帧，连到『视频 5』做参考，然后重新生成视频 5」
• 「『视频 12』用第 2 版」

涉及花钱的步骤，建议先让助手把节点和提示词搭好，你在画布里看一眼再说「生成」。

规则与注意

• 费用：只有 generate 花钱，记在你的令牌上，和画布里手动生成同价；合成、上传、下载不收费。给助手用的令牌设个额度上限，它就不可能超支。
• 权限：助手只能打开你自己能打开的画布，看不到别人的。
• 不删除：助手没有删除节点、删除画布、删除素材的工具，这些只能你在界面里做。
• 和同事协作：助手的改动和同事在同一画布上同时编辑是同一机制，只改被操作的节点，不会覆盖别人正在编辑的内容。在总画布这种多人共用的画布上动手前，建议先在群里说一声。
• 撤销：助手加的节点和连线可以在界面里照常删除；已经生成的结果和手动生成的一样不会被撤销撤掉。
• 日志：每次工具调用都记录是哪个账号、哪个令牌、什么时间做了什么，管理员可查。

常见问题

助手说「令牌无效」：检查配置里的令牌是否以 sk- 开头、有没有多空格，以及该令牌在后台是否已被禁用或过期。

助手说「没有这个画布的权限」：画布属于别的账号。让画布的主人操作，或者自己新建一个。

生成了但画布上没看到：刷新一下画布。视频生成要几分钟，节点会先显示「生成中」。

我能给助手上传文件吗：能，用 upload_media（≤ 32 MB）。更大的文件先在画布或 Studio 里上传到资产库，再让助手用 import_asset 放到画布上。

助手说「同时最多 N 个」或任务一直 queued：这是按类型的并发上限（图 4 / 视频 3 / 音频 4），排队的会自动按顺序开始，不用重复提交；job_status 里的 ahead 是前面还有几个。

助手说某个参数「无效」并列了一串可选值：这是校验在起作用，按列出的值改即可；不同模型的可选值不一样，让助手先 list_models。

重启后 job_status 说「没有这个任务」：任务进度在内存里，服务更新会丢；看画布上节点的状态，结果已经写在节点上，若仍显示生成中就重新 generate（未完成的不扣费，已完成的结果不会丢）。

多个助手能同时用吗：能，每个用自己的令牌即可；同一个画布上多个助手和多个人可以一起工作。

服务地址会变吗：不会，固定是 https://cn-api.skyhorse.ai/mcp。