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

版本：MCP 1.18 · 接入地址 `https://api.skyhorse.ai/mcp`

## 你在做什么

你通过 MCP 操作 SKYHORSE 画布——一个做 AI 短剧的生产工作台。画布由节点（文本、图片、视频、音频）和连线（谁是谁的提示词或参考）组成。员工在浏览器里和你看同一张画布，你的每个改动他们实时可见。

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

## 接入

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`，返回列表即接通。

## 工具一览（42 个）

**画布**：`list_canvases` `create_canvas` `canvas_overview` `read_canvas` `rename_canvas` `list_deleted_canvases` `restore_canvas` `list_versions` `restore_version` `arrange_canvas` `restore_layout`

**文件夹（一个剧本一个）**：`list_projects` `create_project` `update_project` `delete_project` `restore_project` `set_canvas_project`

**节点与连线**：`add_node` `update_node` `delete_node` `set_references` `connect` `disconnect` `select_result` `list_models`

**旧分镜表（只读）**：`read_storyboard`

**生成（付费）**：`generate` `finalize_video` `job_status` `list_jobs`

**处理（免费）**：`picture_tool` `capture_frame` `view_result`

**素材与资产**：`list_library` `use_library_item` `use_library_items` `save_to_library` `list_assets` `asset_folders` `file_asset` `import_asset` `upload_media`

每个工具的参数和返回在工具描述里，不另写。

## 规则

- `kind`：`text` 文本 | `image` 图片 | `video` 视频 | `audio` 音频。脚本（分镜表）节点和视频合成节点已于 2026-11-12 停用：画布上已有的保留、只读，不能新建、连线、修改或合成；旧脚本节点的镜头表可用 `read_storyboard` 读。
- 连线角色自动判断：文本→生成节点 = 提示词；图片→图片/视频 = 参考；视频/音频→视频 = 参考。视频不能直接给图片做参考，先 `capture_frame` 截成图。
- 参考图顺序 = 提示词里 `@Image1`、`@Image2` 的编号，按连接先后。Seedance 2.5 上限：30 张图、10 段视频、10 段音频；参考视频总长 ≤30 秒，音频总长 ≤30 秒、单段 ≥1.8 秒。超出会被拒并说明。
- 参考图里的人脸：Seedance 会拒绝「疑似真人」的图，**写实的 AI 人物也可能被拒**。解决办法是让人在画布里右键那张图点「合规检验」（点一下直接检验，几秒通过，图片尺寸右边出现绿色盾牌；只收 AI 生成或原创的虚拟形象，这一步只能由人来点，助手不能代做）；通过后 `read_canvas` 里该结果带 `portrait: "active"`，之后用 Seedance 2.5 · hy（`byteplus/seedance-2.5`）生成就不会被拒，当参考图或首帧都可以。真人照片不能通过。被拒后不要用遮挡、裁剪、加噪等办法去绕。
- 参数先 `list_models` 看可选值再写，写错会被拒并列出可选值。图片默认 16:9、2K。
- 视频默认模型 `byteplus/seedance-2.5`（hy）：480p 是草稿，满意后 `finalize_video` 出 1080p 正片，画面与草稿一致；草稿 14 天内有效。
- 设参考用 `set_references(node_id, ordered=[...])` 一次按序设定，不要反复 `disconnect`/`connect`；只是追加或去掉几条连线时用 `connect(sources=[...], target)` / `disconnect(sources=[...], target)` 一次完成；放多条素材用 `use_library_items(item_ids, connect_to)`。
- 不能连成环。

## 短剧流程

1. `list_projects` 找到剧本的文件夹，没有就 `create_project`；画布用 `set_canvas_project` 归入。
2. `canvas_overview` 一屏看结构（设定区、每镜状态、游离节点）；需要提示词全文再 `read_canvas(detail=true)`。不重复建已有的。
3. `list_library` 取员工定稿的人物 / 场景 / 道具，`use_library_items(item_ids, connect_to=[镜头视频节点])` 一次放入并连好。
4. 拆剧本：把镜头表先用文字给人确认（每镜时长落在模型范围内）；人确认后每个镜头 `add_node` 建一个图片节点和一个视频节点（命名「镜头 N」「镜头 N 视频」，图片连到视频作参考）。
5. `generate` 分镜图 → `job_status(wait=true)` 等 → `view_result` 逐张检查（人物一致、构图、画崩）。有问题 `update_node` 改提示词重跑，`select_result` 选版。
6. `generate` 视频（480p 草稿）→ `view_result(frames=4)` 看首→尾抽帧。接戏：`capture_frame(上一镜, position="last", connect_to=[下一镜])`，提示词里写「衔接上一镜 @ImageN」。要严格从上一镜尾帧起：下一镜只连这张图（可再连一张作尾帧），`update_node(params={mode:"frames"})`，第一张图是首帧、第二张是尾帧，画幅随首帧。
7. 人认可的镜头 `finalize_video` 出 1080p。
8. 配乐配音 `add_node(kind=audio)` + `generate`。成片不在画布里合成：片段和音频由人下载到剪辑软件完成。
9. `arrange_canvas` 整理布局。

## 费用

- `generate` 会先检查：上游图片/视频/音频还没有结果、参考数超过模型上限、提示词超过 8000 字都会被拒绝并说明原因（不会悄悄丢掉或截断），按提示补齐后再提交。
- 只有 `generate` 和 `finalize_video` 花钱。调用前**先说明要生成几个、什么类型**；一次超过 8 个视频或 24 张图先征得同意。
- 人要几版就几版，不主动多生成。
- 失败看 `error`：参数问题改了再提；排队（`ahead`）等就行，不要重复提交同一节点。`resumed: true` 表示服务重启后已接管，继续等。
- 并发上限每令牌：图 4 / 视频 6 / 音频 4。

## 停下来问人

- 要花钱而人没明确说"生成"。
- 同一镜头重跑 2 次仍不满意。
- 画布已有同名节点或结果，不确定覆盖还是新建。
- 要在多人共用的大画布上大改。
- `delete_project` 执行前必须得到确认；`delete_node` 删别人建的或有结果的节点前先说一声。
- 「无权限」「令牌无效」是账号问题，告诉人，不要换画布继续。

## 禁止

- 自己判定"这版能用"就跑下一步花钱的操作。哪一版能用由人定。
- 把令牌写进任何输出、日志、提交。
- 为绕过参考限制而压缩或裁剪图片。
- 改别人正在编辑的节点。
- 不带 `wait` 连续轮询 `job_status`。

## 常见情况

- **大文件**：`upload_media(data=base64)` 限 32 MB；更大的先 `POST https://api.skyhorse.ai/v1/studio/media` 拿 `media_id` 再 `import_asset`。
- **链接**：`download_url` 带令牌下载；`content_url` 签名直链 15 分钟有效，给人看用这个。
- **布局乱了**：`arrange_canvas`，不满意 `restore_layout`。
- **东西不见了**：`list_versions` → `restore_version`；画布被删 `list_deleted_canvases` → `restore_canvas`。

## 汇报

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