∞ UnlimitCanvas 创作工作台
登录免费注册
技术手册 / 节点与模板 / 应用总览

应用总览

30-节点与模板 · 2026-10-12 · 12.4 KB
⚠ 快照说明（2026-10-12 加）：本文件是 2026-08 的说明书快照，不是运行时知识源（应用不会把它注入给 AI）。
口径以这三处为准 —— 工具面＝tools/list ＋ 各工具 description（⛔ 不是本文的清单）·
（「节点手册」 / 「模板速查」 是脚本实时生成的，比本文新 ✓）。
⛔ 本文里的数量与清单会漂 ⇒ 用时现查，别照抄本文任何数字（本文只负责描述结构与纪律 ✓）。
（2026-10-12 核对：工具 85（tools/list 现查）· 模板 87（uc_do_sheet_templates 现查 ——
它的 description 自己写着"本清单是「模板是否存在」的唯一真相"）· 而 「节点手册」/「模板速查」
是文档口径 84（生成脚本 DISABLED 有意排除 3 个 LTX 变体 ⇒ ⛔ 别把 84 当"库内总数" ✗）✓）

本文档帮助 AI 代理（CodeBuddy / 其他 MCP 客户端）系统理解本应用的能力与操作规范，以便正确使用 MCP 接口完成「文生图 / 图生视频 / 海螺多参 / 反推提示词 / 音频生成」等任务。

1. 应用定位

UnlimitCanvas 是一个 AI 媒体生成画布编排工具：把「文生图、图生视频、参考视频、音频生成」等工作流（模板）以节点形式摆在画布上，连线成流水线，运行后产出图片 / 视频 / 音频 / 文本，并自动下载到本地资源库。

api（云端：wan.* / Seedance.API生视频 / image2.生图 / xAI.API生视频 / bananapro.生图 / custom.provider）·

local（内置本地程序：分拆 / 合并 / 调色 / 海报 / 剪辑等，零算力）· music3（海螺音乐系）

（⚠ 各引擎各有多少个以 uc_do_sheet_templates 现查为准 —— 本文不写死数字 ✓）

  • 引擎可配置多个算力目标（本地 local、远端云实例 remote），uc_do_run_node 时会按模板 engine 自动路由
  • 产物默认本地化到 assets/jobs/<jobId>/；媒体播放走本地 file://（可靠）

2. 使用前必学技巧（学习路径）

开始操作用户的画布前，务必先掌握以下技巧（顺序即学习顺序）。运行时也可调用 uc_do_gain_agent_overview 动态获取系统理解与模板能力。
  1. 理解节点模型：画布上节点分 template（模板实例）与 upload（素材/文本源）。素材节点作为源时输出端口固定 result。
  2. 端口类型兼容：连接时端口类型必须匹配——图片/视频/音频接 references 等素材端口，文本/提示词接 prompt_text 等文本端口。uc_do_connect_nodes 会拦截不匹配并给出提示。
  3. 多参考必须同一主体：海螺多参等模板的参考图必须是同一人物/物体的不同角度/表情；提示词描述该主体的动作/运动，不要写"图1切到图2"。
  4. 提示词规范：生成提示词前先 uc_do_gain_template_prompt_rules(workflowId) 看 placeholder/文本端口/参考端口要求；用 uc_do_suggest_prompt 可自动反推参考图并生成分镜提示词。
  5. 先查 enabled 再创建：uc_do_create_node 前用 uc_do_sheet_templates / uc_do_gain_agent_overview 确认模板 enabled=true（被关闭的模板不可创建）。
  6. 用 nodeId 引用节点：label 会自动唯一化（重名加 #2），用返回的 nodeId 引用最稳。
  7. 先 uc_do_health 再运行：跑 comfyui 模板前 uc_do_health() 确认 comfyui=true；api:true 只代表服务可达，不代表 key/额度够。
  8. 上游先跑完再跑下游：目标节点会等上游完成；先跑上游可避免排队。
  9. 长任务用 uc_do_wait_for_job：uc_do_run_node 返回 jobId+status，用 uc_do_wait_for_job(jobId, timeoutMs) 阻塞等待，超时再轮询。
  10. 产物已本地化：结果用 uc_do_gain_node_result(nodeId) 取，媒体走本地 file://，直接可用。

3. 核心概念（必须理解）

概念说明
画布（canvas）一个独立的节点编辑文档，有唯一 id 与 name。应用可能有多个画布
节点（node）画布上的一次模板实例。分两类：template（模板节点，有 templateId）与 upload（上传/文本节点，无 templateId，作为素材源）
端口（port）节点上的输入/输出点。模板节点端口由模板声明；上传节点输出固定为 result
连线（edge）source 节点 → target 节点。sourceHandle 是源输出端口，targetHandle 是目标输入端口
subports（复合端口）多参考模板（海螺 references 等）把 references 声明为复合端口，内部按 accept（image/video/audio/text）分组自动排号，无需精确端口连线，引擎按连接顺序组装
运行（run）运行节点产生 job。有上游依赖时先确保上游已完成

端口类型：image / video / audio / text / any。连接时端口类型必须兼容（图→references、文本→prompt_text）。MCP uc_do_connect_nodes 已做类型校验。

（⛔ 两处维护必然两处漂 ✗）。原 4.1~4.6 的内容已并入下表各篇 ✓
| 篇 | 讲什么 |
|---|---|
| 00-接入指南.md | 开篇：从零接到第一次成功调用（端点 / token / 客户端配置 / 验证） |
| 02-工具全景与现查方法.md | 全部工具按功能族导航 ＋「怎么现查」 |
| 03-调用规范（画布寻址·端口·参数·提示词）.md | 调用时必须守的规矩（画布寻址 / 端口 / 参数 / 提示词） |
| 04-标准作业流程（SOP）.md | 常见任务的工具序列（出图 / 出视频 / 批量分镜 / 素材盘点 / 知识库） |
| 05-安全、鉴权与故障排查.md | 安全边界、三道门（鉴权 / 授权 / API 节点）、故障速查表 |
连接一句话：POST http://127.0.0.1:<端口>/mcp ＋ Authorization: Bearer <token>
（token 见 设置 → MCP Agent；出厂默认端口 38770 ⇒ 以设置页显示为准 ✓）。
⛔ 工具清单与数量一律 tools/list 现查（本文件与任何离线文档都只是快照 ✓）。

5. 模板生态（⚠ 模板数会漂 ⇒ 以 uc_do_sheet_templates 现查为准；2026-10-12 核对：库内 87 · 文档口径 84）

⚠ 以下这段是 2026-08 的审定快照（数字与清单以现查为准 ✓）：2026-08-28 节点重构后审定：海螺已从 t2v/i2v/ref/sef 四模板统合为 ref/t2i 两个（minimax.h3.t2i 合并文生/图生/首尾帧三模式）；ltx 的 i2v 合并标准/高清/音图三模式 ⇒ 旧 id ltx2.3i2v / ltx2.3.i2v.hd / ltx2.3.ia2v 仍存在于库内，但已在「文档口径（84）」之外⇒ 一律改用统合模板 ltx.i2v（+ 其模式参数）✓；而 ltx2.3.sef（首尾帧生视频）/ ltx2.3DI2V（转绘）等仍是现役有效模板 ⇒ ⛔ 既别把"已废除"当现状读，也别把"仍在库"当成"该用它" ✗。下表 id 均为当前模板真实 id（uc_do_sheet_templates 可实时核对）。

**海螺 minimax** 视频

  • 代表模板（真实 id）：minimax.h3.t2i 图文生视频（统合三模式：不连图=文生；连首帧=图生；连首帧+尾帧=首尾帧，均带同步声音）、minimax.h3.ref 多参生视频（参考视频/图像/音频）
  • 用途：H3 系列视频（云端加速：4 步采样+Sol-Attn+Cache）

**千问 qwen** 图像/文本

  • 代表模板（真实 id）：qwen.image.film.style 千问.文生图、qwen.character.3view.picture 图生三视图、qwen.t2i.3view.picture/text 图参/文参三视图、qwen.prompt.reverse.word 单图反推（识别图片）、qwen.image.edit.multi 图生图（1~3 图参考）、qwen.image.custom 智能编辑、qwen.faceswap 智能换脸
  • 用途：图像生成/编辑/反推/三视图

**万象 wan** 图像/视频

  • 代表模板（真实 id）：aliyun.bailian.wan2.7.t2i wan.文生图、aliyun.bailian.wan2.7.t2v wan.首尾帧生视频
  • 用途：阿里万相（云 API，本地无需 ComfyUI）

**LTX** 视频

  • 代表模板（真实 id）：ltx.i2v 图生视频（统合标准/高清/音图三模式，音图模式接音频驱动口型）、ltx.msr 参考图生视频（一图/多图/四图）、ltx.2.3.4ref.t2v 四图分镜词生视频、ltx2.3.sef 首尾帧生视频、ltx2.3DI2V 视频转绘、ltx2.3.kill.word 视频消字幕
  • 用途：图生视频/参考视频/多镜头/后期

**Bernini** 视频

  • 代表模板（真实 id）：bernini.i2v 单图生视频、bernini.v2v 视频相生、bernini.video.edit 视频编辑
  • 用途：图生/视频生视频/编辑

**Klein / Krea2 / zimage** 文生图

  • 代表模板（真实 id）：klein.edit 多图编辑（文生/单图/多图）、krea2.t2i 文生图、krea2.double.sampling.t2i 双采样生图、zimage.t2i 文生图、zimage.japan.lora.style 日系文生图
  • 用途：高质量文生图

**Music3 / vox** 音频

  • 代表模板（真实 id）：minimax.music3.song 歌曲创作、minimax.music3.instrumental 纯音乐、vox.audio.clone 声音克隆、vox.audio.design 声音设计
  • 用途：音乐/配音

**scail** 视频

  • 代表模板（真实 id）：scail.3.ref.transfer 动作迁移、scail.char.replace 角色替换、scail.video.to.image.transfer 视频生图
  • 用途：视频动作/角色替换

**API** 图像/视频

  • 代表模板（真实 id）：gpt.image2、grok.video.official、grok1.5.muilti.pic.to.video、nano.banana.pro、custom.provider.custom
  • 用途：云端生成（APIMart/xAI/Google 等）

**本地工具** 全类型

  • 代表模板（真实 id）：local.split.any 分拆输出、local.slice.video 切分视频、video.extract.firstlast 抽首尾帧、local.color.grade 调色、local.fetch.url URL 产出、master.executor 总执行入口
  • 用途：纯本地程序处理（零算力）

**图像工具/美颜** 图像

  • 代表模板（真实 id）：color.grade.image 图片调色、color.grade.video 视频调色、tool.image.scale 等比缩放、tool.trim.edges 自动裁边、tool.image.force_trim 强制裁边、tool.image.sharpen 高清细化、seed.vr2.image.upscale 视频高清、comfy.ai.*（美颜/超分/抠图/去水印/滤镜/人像分割调色/自动调色）、camera.multi.angle.picture/scene 多视角生图
  • 用途：调色/缩放/美化/取景

**acestep** 音频

  • 代表模板（真实 id）：aceStep.song.design 歌曲创作
  • 用途：本地模型生成带歌词音乐

6. 操作规范与最佳实践（重要）

6.1 完整任务流程（以「海螺多图生视频」为例）


1. uc_do_new_canvas 新建画布 → 记下返回的 canvasId（后续所有操作带上它，与用户当前画布互不影响）
2. uc_do_sheet_templates / uc_do_gain_agent_overview 确认模板**已启用（enabled=true）**且符合规范（被关闭的模板不可创建）
3. 生成参考图：用文生图模板（如 zimage.t2i / qwen.image.film.style 千问.文生图）生成同一主体的多张图
4. 可选：uc_do_analyze_image / uc_do_suggest_prompt 识别图内容并生成分镜提示词
5. uc_do_create_node(minimax.h3.ref, canvasId) 创建海螺多参节点
6. uc_do_upload_asset 上传参考图 → uc_do_connect_nodes 连到 references
7. uc_do_write_node_prompt 写符合规范的提示词
8. uc_do_run_node(nodeId, canvasId) → uc_do_wait_for_job → uc_do_gain_node_result(nodeId, canvasId) 取视频
带 canvasId 的全程操作不会改动用户当前打开的画布；用户可同时在自己画布上工作，互不干扰。

6.2 多参考（海螺 ref 等）的关键规则

  • 参考图必须是「同一主体」（同一人物/物体的不同角度/表情），否则模型无法建立"同一角色"关联，视频会与参考图无关
  • 参考图通过 references 端口连接，引擎按连接顺序自动排号，无需精确端口
  • 提示词应描述「该主体的动作/运动」（如"她缓缓转身回眸，镜头推近"），不要写"从图1切换到图2"这类多图切换描述
  • 可选 <Picture N> 标签精确定位某张参考图

6.3 提示词生成

共识约定（默认首选路径）：给模板节点写提示词时，优先调用 uc_do_suggest_prompt 让它自动反推参考图并生成符合规范的分镜提示词——这是生成提示词的首选默认做法，比手写更贴合参考图内容、且能自动遵循官方指南（含海螺）。手写仅在用户明确要求或无需参考图时使用。
  • 默认首选：uc_do_suggest_prompt(workflowId, imagePaths, motionHint?) — 自动反推参考图 + 生成分镜提示词（海螺自动遵循官方指南，返回 promptGuideApplied）
  • 无参考图或纯文生图：uc_do_gain_template_prompt_rules 看 placeholder / 文本端口要求后，直接 uc_do_write_node_prompt
  • 提示词通常需：主体外貌、动作、场景、光线、风格、镜头运动
  • 海螺（minimax）节点必须严格遵循官方提示词书写指南：uc_do_gain_template_prompt_rules 返回的 promptGuide（strictPromptGuide=true）为权威规范——写单一连续镜头描述、覆盖主体/动作/场景/镜头光线四要素、多参考用 <Picture N> 定位、禁止多图切换式叙述、禁止引入与参考图无关的新主体。先获取指南再写提示词，不得偏离。

6.4 端口连接规范

  • 文本/提示词 → 接到 prompt_text 等 text 类型的输入端口（或直接 uc_do_write_node_prompt）
  • 图片/视频/音频 → 接到 references 等素材端口（或图生视频的输入端口）
  • 类型 ≠ 端口 id：上文"text/image/video/audio"是端口类型。作为源时：上传/文本节点输出端口 id 恒为 result；模板节点为 outputs[0].id
  • 连接错误时 uc_do_connect_nodes 会提示类型不匹配；显式传错 sourcePort 也会被纠正（upload 源强制 result）

6.5 其他

  • 引擎不在线 / 任务失败时，uc_do_gain_job_status 返回 error，uc_do_run_node 可能失败——先 uc_do_health 检查
  • 产物会自动本地化，媒体播放走本地 file://（无需担心跨域）
  • 长任务（海螺 1080P 多参考）需数分钟，用 uc_do_wait_for_job 或轮询 uc_do_gain_job_status

6.5.1 声音模板库（短剧配音/克隆指引）

  • 路径：%APPDATA%/UnlimitCanvas/asset-library/voiceTemplate/（58 个音色 mp3，文件名 = 音色名，如 Y5-青年女·温柔知性.mp3、Q1-低音炮.mp3）
  • 覆盖（6 批次）：
  • 批次1 年龄段×性别（24）：C1~C4 童声 / T1~T4 少年少女 / Y1~Y8 青年 / MD1~MD4 中年 / O1~O4 老年
  • 批次2 质感（10）：Q1~Q10（低音炮/烟嗓/气声/播音腔/女高音/女中音/娃娃音/机械音/空灵音/沙哑忧郁）
  • 批次3 口音+风格（10）：A1~A6（粤/川渝/东北/台湾/英/日）+ P1~P4（旁白/广告/电台/惊悚）
  • 批次4 高龄（4）：O5 沧桑垂暮 / O6 颤巍 / O7 风烛 / O8 絮叨
  • 批次5 特殊角色（6）：R1 太监 / R2 巫婆 / R3 恶魔低语 / R4 醉汉 / R5 哭腔 / R6 体育解说
  • 批次6 幼龄+设备（4）：C5 幼儿咿呀 / C6 幼童奶凶 / D1 电话音 / D2 对讲机音
  • 用途：
  • vox.audio.clone（声音克隆）：input1（音频样本）优先从 voiceTemplate 选取相近音色——如角色是"温柔知性女主"取 Y5-青年女·温柔知性.mp3，配 input2（声音描述）+ input3（音色文字）做克隆
  • vox.audio.design（声音设计）：input1 填声音描述（对照 voiceTemplate 音色名/描述书写），prompt 填台词
  • 性别强化约定：vox.audio.design 的 control_instruction 建议以 female voice 女声， / male voice 男声， 前缀开头（VoxCPM 对双语性别指令响应更稳），纯中文描述易出男声
  • 注意：克隆样本需 3~10 秒人声；voiceTemplate 内文件为「统一台词」版本，用于音色特征参考而非台词内容

6.5.2 首帧图 / 镜头成图默认模型（用户项目偏好）

  • 用户明确要求：生成「视频首帧 / 镜头关键帧 / 分镜成图 / 场景成图」时一律默认用 gpt.image2（engine=api，APIMart GPT-Image-2）。千问（qwen.image.film.style / qwen.image.edit.multi 等）在物理结构、机械部件与细节一致性上容易出缺陷（如石磨运转、接浆结构、器物透视），不要用千问直接生首帧/关键成图；千问仅作反推识别（uc_do_analyze_image / 反推模板）等用途。
  • image2 推荐参数：model=gpt-image-2、size=9:16、resolution=2k、quality=high（可单图编辑/多图组合）。
  • 首帧一致性配方：场景空镜 + 角色面部特写 + 角色全身立姿 至少三张参考图做多图 i2i，逐张说明「图像1提供场景/空间唯一底版、图像2提供脸、图像3提供服装身形」，要求结构/几何（如磨盘落料口与接浆桶垂直对齐）精确写清；必要时加第 4/5 张做风格或道具结构锚。
  • 例外：仅当 gpt.image2 模板不可用（enabled=false / keyMissing / API 持续失败）时允许回退 nano.banana.pro 等其它模型，并主动提示用户。

6.6 创建工作流避坑指南（重要）

节点创建

  • 先查 enabled：uc_do_create_node 前用 uc_do_sheet_templates 或 uc_do_gain_agent_overview 确认模板 enabled=true，被关闭的模板无法在应用创建，AI 也不该尝试
  • label 自动唯一化：重名节点会被追加 #2 #3 后缀，因此用返回的 nodeId 引用节点最稳妥；用 label 引用时须用唯一名
  • 「节点不存在」排查：若操作报「节点不存在: xxx」，先确认是否因用户切换了当前画布——不带 canvasId 的操作只对"当前活动画布"寻址，用户切走后原节点自然找不到。在专用画布上工作务必全程携带 canvasId，即可与用户切画布完全隔离
  • 位置默认随机：不传 position 时节点落在随机位置（可能重叠）。多节点建议传入 position:{x,y}，或每步用返回的 nodeId 定位
  • 参数默认值：新建节点自动填模板 parameters 的默认值，通常无需重复 uc_do_write_node_params

提示词与参数

  • uc_do_write_node_prompt 只对声明了 prompt 的模板有效，否则抛「不接受提示词」。写前用 uc_do_gain_template_prompt_rules 确认模板是否要提示词
  • 提示词写入后同时更新 data.prompt 与 inputPrompts，不要手动改 inputPrompts 单一字段
  • uc_do_write_node_params 严格校验参数名：未知 key 会抛错并列出可用参数。传参前先看 uc_do_gain_template_guide 的 parameters

连线

  • 上传节点（无 templateId）输出端口固定 result；模板节点默认取 outputs[0]。多输出模板须显式传 sourcePort
  • 端口类型校验严格：uc_do_connect_nodes 会拦「图→prompt_text」「视频→references」等不匹配。被拦时：文本/提示词接 text 端口（prompt_text 等）或直接 uc_do_write_node_prompt，图片/视频/音频接 references 等素材端口
  • 复合端口 references 无需精确端口：按 accept 类型（image/video/audio/text）分组，uc_do_connect_nodes 传 targetPort:'references' 即可，引擎按连接顺序排号
  • 同源→同目标只留一条边：重复连同一上游会被合并，不会产生多条边

运行

  • uc_do_run_node 返回 jobId + status（queued/running）。立即用 uc_do_wait_for_job(jobId) 阻塞等待，超时可设 timeoutMs
  • 上游依赖：目标节点会等上游节点完成后再跑，先把上游全部跑完再 uc_do_run_node 下游，可避免排队
  • 长任务可能 queued 很久（算力排队），uc_do_wait_for_job 若超时返回，再轮询 uc_do_gain_job_status 或 uc_do_sheet_jobs
  • 结果用 uc_do_gain_node_result(nodeId) 取，媒体已本地化，用返回的文件路径即可

6.7 引擎与算力目标（本地 vs 远程）

模板按 engine 分三类，决定走哪条算力：

  • comfyui — 绝大多数图像/视频模板（LTX/Bernini/minimax/千问/万象/zimage 等）。可路由到本地 ComfyUI 或远端 ComfyUI 集群（设置→算力目标），由 cluster 调度选最空闲节点；集群关闭/不可达时退回本地 comfyuiBaseUrl
  • api — 云端 API（gpt.image2 / grok.video / nano.banana）。不依赖 ComfyUI，只要对应 API key 有效且有额度
  • music3 — 音乐生成，走独立 music3BaseUrl
  • local — 本地程序引擎（如 local.split.any 内置.分拆输出）：纯主进程逻辑处理，不调 ComfyUI/云端，运行快、零算力。用于分拆多产出（把上游多图/多视频/多音频/多文本按 index 拆成独立单产出，输出类型可经 outType 参数明确指定）、视频抽首尾帧等工具节点

避坑

  • 先 uc_do_health() 再跑：uc_do_health() 返回 {comfyui, music3, api}。跑 comfyui 模板前确认 comfyui=true（本地 ComfyUI 已启动，否则 uc_do_run_node 会失败/排队）
  • api: true 只代表 API 服务可达，不代表 key 有效/额度充足；失败多为 key/额度问题，需查设置里对应服务商 key
  • 远程 ComfyUI 用 comfyui-upload 输入模式（资产要上传到远端 input 目录），本地用 direct-path（直接引用本地路径）。改算力目标会自动适配，无需干预
  • 长视频/高清/多参考：本地 ComfyUI 受 GPU 与并发限制（maxConcurrentJobs=1），慢或排队；可切到远端实例（设置→算力目标里启用 remote）
  • 单台 maxConcurrentJobs=1 时，多个节点同时跑会串行排队——先跑上游，减少并发压力
  • 模板 engine 与算力目标自动绑定（按模板类型路由），AI 无需手动指定目标；但可提醒用户开启远端算力以加速
节点手册 →

来源：E:/workbuddyProj/unlimitCanvas/ai_manual/AGENTS.md