# SKYHORSE 画布 MCP — 给 AI 助手的操作手册

> 这份文档是给 AI 助手（Claude Code、Codex、Cursor、Hermes 等）读的。把它整页复制给你的助手，或者让助手自己读取 https://studio.skyhorse.ai/docs/mcp.md 。
> 给人看的版本：https://studio.skyhorse.ai/docs/mcp.html
> 版本：MCP 1.11（2026-10-26）

## 你是谁，在做什么

你通过 MCP 操作 SKYHORSE 画布——一个做 AI 短剧的生产工作台。画布由节点（文本、图片生成、视频生成、音频生成、视频合成、分镜表）和连线（谁是谁的提示词 / 参考 / 素材）组成。你的工作是替人搭建和运行这张画布：建节点、连参考、批量生成、检查结果、合成成片。

你用的是**某位员工的令牌**。你能看到的画布、花的额度、留下的操作记录，都是这位员工的。请像在别人的工位上工作一样谨慎。

## 接入

服务地址：`https://api.skyhorse.ai/mcp`（HTTP 传输），认证头 `Authorization: Bearer sk-员工的令牌`。

Claude Code：
```
claude mcp add --transport http skyhorse-canvas https://api.skyhorse.ai/mcp --header "Authorization: Bearer sk-员工的令牌"
```
Codex（`~/.codex/config.toml`）：
```toml
[mcp_servers.skyhorse-canvas]
url = "https://api.skyhorse.ai/mcp"
http_headers = { Authorization = "Bearer sk-员工的令牌" }
```
Cursor / Windsurf / 通用 JSON：
```json
{"mcpServers":{"skyhorse-canvas":{"url":"https://api.skyhorse.ai/mcp","headers":{"Authorization":"Bearer sk-员工的令牌"}}}}
```
Hermes（`~/.hermes/config.yaml`）：
```yaml
mcp_servers:
  skyhorse-canvas:
    url: https://api.skyhorse.ai/mcp
    headers: { Authorization: "Bearer sk-员工的令牌" }
    timeout: 300
```
接通验证：调用 `list_canvases`，返回画布列表即可。

## 工具一览（43 个）

读取（免费）：`list_canvases` `read_canvas` `list_models` `list_assets` `list_jobs` `job_status` `view_result`
素材库与运镜（免费）：`list_library`（人物 / 场景 / 道具 / 音频，员工定稿的素材）`use_library_item`（放到画布，可 `connect_to`）`save_to_library`（定稿存回）`list_camera_moves`（运镜标签与提示词）`optimize_prompt`（扩写提示词，返回文本不自动写入）
搭建（免费）：`create_canvas` `rename_canvas`
分镜工作台（免费）：`read_storyboard` `add_shots`（AI 自己拆剧本写镜头表；每镜 duration 在视频模型范围内，超出钳边界并返回 warnings；新镜头都是草稿）`update_shot`（锁定字段不动；已确认改创作字段→需复核；duration 超范围拒绝）`remove_shots`（已确认/锁定需 confirmed: true）
文件夹（免费；接口里叫 project）：`list_projects`（全部文件夹：画布数、最近编辑、封面）`create_project`（新建文件夹）`update_project`（重命名 / 设置封面）`set_canvas_project`（把画布放进文件夹，空字符串 = 移出到「全部」）`restore_project`
资产归类（免费）：`asset_folders` `list_assets`（按 project_id / category 过滤）`file_asset`
删除类（唯一）：`delete_project` —— 文件夹连同画布进最近删除，30 天可恢复；**必须先得到人的确认**，调用时带 `confirmed: true`。
找回（免费）：`list_versions` `restore_version`（画布历史版本，每 10 分钟一版、保留 7 天）、`list_deleted_canvases` `restore_canvas`（最近删除，30 天内） `add_node` `update_node` `connect` `disconnect` `expand_storyboard` `import_asset` `upload_media` `capture_frame` `select_result` `arrange_canvas` `restore_layout`
花钱：**只有 `generate`**（图片 / 视频 / 音频生成）。
不花钱但耗时：`compose`（服务器 ffmpeg 合成）。

除 `delete_project`（需人确认）外没有删除工具。节点、画布、素材的删除只能人在界面里做；删掉的画布 30 天内可用 `restore_canvas` 找回，删掉的文件夹用 `restore_project`。

**内容突然少了 / 被覆盖了**：先 `list_versions` 看历史版本，告诉人哪一版的节点数对得上，人确认后再 `restore_version`。不要自己决定恢复。

## 节点与连线的规则

- 节点类型 `kind`：`text` 文本 | `image` 图片生成 | `video` 视频生成 | `audio` 音频/配乐 | `compose` 视频合成 | `script` 分镜表（由 `expand_storyboard` 创建）。员工放的便签（`note`）是给人看的标注，`read_canvas` 不返回，你也不能创建。
- `read_canvas` 里从素材库放入的节点带 `library_item`（素材 id）；视频节点带 `camera_moves`（提示词里解析出的运镜标签）。
- 连线角色自动判断：文本→任何生成节点 = 提示词；图片→图片/视频 = 参考；视频→视频 = 参考（动效参考）；视频/音频→合成 = 素材；音频→音频 = 参考音色。
- 视频**不能**直接连到图片做参考。要用某一帧当参考，先 `capture_frame` 截成图片节点。
- 参考图的顺序就是提示词里 `@Image1`、`@Image2` … 的编号，按连接先后排。`connect_from` 列表顺序即编号顺序。
- 每个模型的参考数量上限不同（Seedance 2.5 视频 30 张图；GPT-Image 16 张），超过会被拒并说明原因。
- 不能连成环。
- 参数（模型、时长、画幅、清晰度……）先 `list_models` 看可选值再写；写错会被校验拒绝并列出可选值。

## 短剧标准流程（按这个顺序）

0. **分镜**：要拆剧本时用 `add_shots` 写镜头表（先 `list_models` 看所选视频模型的时长范围，每镜 duration 落在范围内；写完告诉人去画布「打开分镜脚本」确认，确认由人做）；改表用 `read_storyboard` + `update_shot`。
0. **先看文件夹** `list_projects`：首页是两层「文件夹 → 画布」，一个剧本一个文件夹（接口字段叫 project，对人说「文件夹」）。要开新剧先 `create_project` 建文件夹，新画布建好后 `set_canvas_project` 放进去；`list_canvases` 的每张画布带 `project_id`（空 = 在「全部」）。
1. **读画布** `read_canvas(detail=true)`：看已有什么——定妆图、风格段、分镜表、已生成的镜头。不要重复建已有的东西。
2. **设定区**：**先 `list_library`**——员工定稿的人物 / 场景 / 道具 / 音频都在素材库，有就 `use_library_item` 放到画布（这是和员工共用的唯一通道，不要自己重生成已有的定妆图）。没有的才 `add_node(kind=image)` + `generate`，或 `import_asset` 从历史资产取；人认可的定稿用 `save_to_library` 存回去。节点命名用「定妆 林辰」「场景 破饭馆前厅」「道具 菜谱」这种前缀——`arrange_canvas` 靠它分区。全片风格段放一个 `text` 节点。
3. **展开分镜表** `expand_storyboard(rows, characters, style, video_params, image_params)`：一次建出所有镜头的分镜图节点 + 视频节点，角色图自动连参考，风格段自动追加。`rows` 每行 `{number, duration, image_prompt, video_prompt, dialogue, camera}`；`camera` 是运镜 key（`list_camera_moves` 里的 `key`，如 `dolly_in` / `zoom_in` / `static`），展开时自动在该镜视频提示词末尾加 `[运镜:名字]`。`video_prompt` 只写人物动作和声音，镜头运动交给 `camera`。镜头命名建议 `E1-05` 格式（第 1 集第 5 镜）。
4. **生成分镜图** `generate(node_ids=[所有镜头的 image_node])`，用 `job_status(wait=true)` 等（一次最多等 120 秒，没完就再调）。
5. **看图** `view_result` 逐张检查：人物是否和定妆一致、构图是否对、有没有画崩。有问题改提示词 `update_node` 后重新 `generate`（会多出一版，用 `select_result` 选）。**连续两次重跑还不行就停下问人**，不要无限重试。
6. **运镜与提示词**：手写视频提示词时，运镜用标签 `[运镜:名字]`（`list_camera_moves` 的 `mark`），可多个、可穿插在句中，如「她推开门 [运镜:镜头前推] 停在窗边 [运镜:环绕拍摄]」；生成时标签原位替换为该运镜的提示词，其余文字一字不动。写不好可先 `optimize_prompt` 扩写，看过再 `update_node` 填入。
7. **生成视频** `generate(node_ids=[所有 video_node])`。视频贵（约为图片的 10–30 倍），生成前先确认分镜图已经是人认可的。
8. **接戏**：相邻镜头画面要连贯时，`capture_frame(上一镜视频, position="last", connect_to=[下一镜视频])`，并在下一镜提示词里写「衔接上一镜 @ImageN」。
9. **看视频** `view_result(frames=4)`：首→尾抽帧，看动作是否合理、有没有黑屏/闪烁/人物变形。只想看首帧时用结果里的 `thumbnail_url`（JPG），比下载视频快得多。
10. **配乐与配音**：`add_node(kind=audio)` + `generate`；音频连到合成节点。
11. **合成** `add_node(kind=compose)`，视频按顺序 `connect` 进去，`compose(subtitles=[...])` 可烧字幕。免费。
12. **整理** `arrange_canvas`：设定区 → 每集一行 → 归档。只改位置。

## 费用规则（必须遵守）

- 只有 `generate` 花钱。每次调用 `generate` 前，**先说明要生成几个节点、什么类型**，批量超过 8 个视频或 24 个图片时先征得同意。
- 不要为了"多几个备选"主动多生成。人要几版就几版。
- 任务失败（`status=failed`）看 `error` 原因再决定：参数/提示词问题改了再提；上游限流（`ahead` 排队）等就行，**不要重复提交同一个节点**——节点显示「生成中」时重提会被拒绝，但 failed 后重提是会再扣费的。
- 问 `job_status` 时如果看到 `resumed: true`，说明服务刚重启过，任务已被接管，继续等即可，不要重新 generate。
- 并发上限：图 4 / 视频 3 / 音频 4 / 合成 2（每令牌）。排队是正常的，`ahead` 是前面还有几个。

## 什么时候停下来问人

- 要花钱而人没明确说"生成"（例如人只说"把分镜表展开"，那就只展开，不生成）。
- 同一个镜头重跑 2 次仍不满意。
- 画布上已有同名节点或已有结果，不确定是覆盖还是新建。
- 要在多人共用的画布（名字含「总画布」或节点很多且不是你建的）上大改。
- 要合成成片——先把 `view_result` 的抽帧给人看一遍，人点头再 `compose`。
- 遇到「没有这个画布的权限」「令牌无效」：这是账号问题，告诉人，不要换别的画布继续。

## 禁止

- 不要自己决定"这版能用"就跑下一步花钱的操作。你负责搭、跑、检查、汇报；**哪一版能用由人定**。
- 不要把令牌写进任何输出、日志、提交。
- 不要为绕过参考数量 / 大小限制而压缩或裁剪图片。
- 不要用 `update_node` 改别人正在编辑的节点的提示词（看 `status` 和最近更新时间，有疑问就问）。
- 不要连续轮询 `job_status` 不带 `wait`；用 `wait=true`。

## 常见情况

- **上传大文件**：`upload_media(data=base64)` 限 32 MB。更大的视频先 `POST https://api.skyhorse.ai/v1/studio/media`（原始字节，带同一个令牌，视频 ≤ 512 MB），拿到 `media_id` 后 `upload_media(media_id=...)`。
- **结果链接**：每个结果带 `download_url`（带令牌下载）和 `content_url`（签名直链，15 分钟有效，不带令牌）。给人看链接用 `content_url`。
- **多版结果**：`read_canvas(detail=true)` 看每版；`select_result(index)` 选用；下游已生成的节点会被标为过期（需要重跑才能反映新选择）。
- **布局乱了**：`arrange_canvas`；不满意 `restore_layout` 还原。
- **接不上戏**：用尾帧参考（第 7 步），同时在提示词里明确写上一镜结尾的动作状态。

## 汇报格式

每完成一个阶段，用一段话汇报：做了什么、花了多少次 `generate`（几图几视频）、哪些需要人看（附 `content_url`）、下一步建议。不要贴 JSON。