调用规范（画布寻址 · 端口 · 参数 · 提示词）

本专题手工维护。本文是调用时必须守的规矩（都是实测最容易翻车的地方）。

工具清单见 02-工具全景与现查方法.md；流程见 04-标准作业流程（SOP）.md。

1. 画布寻址：永远带上 canvasId（最重要的一条）

所有操作类工具（建/删/写/连/移/改/运行/取结果/上传素材/改画布名/清空，共 15 个）都接受可选 canvasId：

推荐做法（长任务/批量尤其要这样）

uc_do_new_canvas()      → 拿 canvasId（或 uc_do_sheet_canvases 选一张）
   ↓（此后每个调用都带上 canvasId）
... 建节点 / 连线 / 写参数 / 跑 / 取结果 ...

• 例外（按全局 jobId 寻址，不需要 canvasId）：uc_do_gain_job_status · uc_do_wait_for_job · uc_do_cancel_job · uc_do_sheet_jobs
• uc_do_new_canvas 本身没有 canvasId 语义（它就是造画布）

好处：任务结束后，用户能直接在 UI 里看到/删除你建好的画布 ✓

2. 节点模型与端口（连线最容易踩的坑）

节点两类：template（模板实例，有 templateId）· upload（上传/文本源，无 templateId）

坐标：uc_do_create_node 不传 position 时自动网格排布（Y 间距 720 / X 间距 500，各限 5000，排满一列右移一列，基准＝锚点）⇒ 连续创建自动成网格；要精确摆位才传 position:{x,y}。

引用节点：用返回的 nodeId（label 会自动唯一化：重名加 #2）⇒ ⛔ 别用 label 当标识。

3. 参数与提示词

• 参数：uc_do_write_node_params(nodeId, params, canvasId?) 会按模板的 parameters 校验 ⇒ 未知键直接报错（这是好事：早失败早改）✓ 先 uc_do_gain_template_guide(workflowId) 看有哪些参数
• 提示词：

1. 先 uc_do_gain_template_prompt_rules(workflowId) ⇒ 看 placeholder / 文本端口 / 参考端口要求
2. 首选 uc_do_suggest_prompt(workflowId, imagePaths[], motionHint?) ⇒ 反推参考图 + 按模板规范生成分镜式提示词
3. 海螺：uc_do_gain_hailuo_prompt_spec / uc_do_fix_hailuo_prompt（strictPromptGuide=true 的模板必须严格遵循官方指南）
4. 写入：uc_do_write_node_prompt(nodeId, prompt, canvasId?)

• 多参考必须同一主体：参考图是同一人物/物体的不同角度/表情；提示词写动作/运动，⛔ 别写"图1切到图2"

4. 模板可用性：enabled 是硬门

• 用户可在「模板管理」里开关任意模板；被关的模板 enabled=false（出现在 templateSwitch.disabledTemplateIds）
• ⛔ 不创建/不运行 enabled=false 的模板
• uc_do_sheet_templates / uc_do_gain_agent_overview 每次调用都实时读设置 ⇒ 用户说"我关了某模板"或长任务中途，重新查一次即可拿到最新状态 ✓

5. 运行与等待

uc_do_run_node(nodeId, canvasId?)        → jobId + status
uc_do_wait_for_job(jobId, timeoutMs?)    → 阻塞等待（默认 300s、2s 轮询；可用 brief）
uc_do_gain_job_status(jobId)             → 需要自己轮询时用
uc_do_gain_node_result(nodeId, canvasId?)→ 取产物（文件路径，本地化 ⇒ 直接可用）
uc_do_cancel_job(jobId)                  → 取消

• 上游先跑完再跑下游：目标节点会等上游完成，但先跑上游能避免排队 ✓
• 跑 comfyui 模板前先 uc_do_health()（api:true 只说明服务可达，不代表 key/额度够）
• 产物默认本地化到 assets/jobs/<jobId>/，播放走本地 file://（可靠 ✓）

6. 创作者画布 / 导演台的额外规矩

• 创作者画布＝普通项目画布（folderId='folder_creator'，canvasType=project）；打开后 UI 出现「视频创作导演台 / 蓝图 / 全局设定」
• 导演台计划存在画布 canvasGlobals.director（assets / shots / engines / ui）⇒ 驱动流程前先 uc_do_gain_canvas_globals 读懂它，⛔ 别盲目建节点
• 写 canvasGlobals 用 uc_do_write_canvas_globals（浅合并；director 要传完整对象）
• 媒体产出节点用 uc_do_create_media_node：inputAssets（端口ID→资产列表，直填免连线）、mergeVideos（顺序＝拼接顺序）、params.filename、groupName（建即归组）
• 批量产出后用 uc_do_gain_group_nodes(groupName) 看哪些镜头已出 / 失败 ✓
• 海报/剪辑类人机协同节点：Agent 沙箱会拒绝（属设计，不是 bug ✓）

7. 写操作前的登记（应用侧硬要求）

• 动用户的画布前，先 uc_do_gain_canvas_rules()：读画布范式规则并登记"已读" ⇒ 未登记时写操作可能被拒
• 需要用户拍板时用 uc_do_ask_user（渲染成可点选项）；长任务用 uc_do_plan_write 落一张任务清单卡（3~8 步）

8. 一条"标准动作"顺序（照着走不会错）

① uc_do_gain_agent_overview      拿系统理解（首次必做）
② uc_do_gain_canvas_rules        读规则 + 登记已读（写前置）
③ uc_do_health                   跑本地引擎前确认 comfyui=true
④ uc_do_sheet_templates          确认目标模板 enabled=true
⑤ uc_do_new_canvas / sheet_canvases   拿 canvasId（此后都带上）
⑥ uc_do_gain_template_guide + prompt_rules   看端口/参数/提示词规范
⑦ uc_do_create_node → connect_nodes → write_node_params / write_node_prompt
⑧ uc_do_run_node → uc_do_wait_for_job → uc_do_gain_node_result
⑨（可选）uc_do_ensure_group / uc_do_gain_group_nodes  归档与验收