8.9 KiB
| name | summary-en | summary-cn | display-name-zh | trigger-words | description | allowed-tools | version | tags | tags-cn | exported-by |
|---|---|---|---|---|---|---|---|---|---|---|
| n-storyboard | Multi-panel storyboard from a story | 把故事拆成 N 宫格分镜整图 | 多宫格分镜 | [多宫格分镜 n宫格分镜 故事分镜图 storyboard story panel grid multi panel storyboard] | 根据故事文本和宫格设置(2x2/3x3/4x4) + 单格比例 + 可选参考图,生成多宫格分镜整图。 | hub_open_remote_tool_gui, hub_submit_dag | 1.0.2 | [Image Storyboard Layout] | [图片 分镜 排版] | MiniMax-hub |
N Storyboard
把故事拆成多宫格分镜整图,可选参考图
参数
| ID | 类型 | 必填 | 取值约束 | 说明 |
|---|---|---|---|---|
| grid_setting | string | 是 | — | 宫格配置 JSON 字符串,形如 {\ |
| user_prompt | string | 是 | — | 用户故事描述,中英文皆可 |
| aspect_ratio | enum | 是 | "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | 单格(也即整图,因为 N×N 方形宫格)的宽高比 |
| reference_image_1 | file(image/*) | 否 | — | 可选参考图 1 (CDN URL);未提供时传空字符串 |
| reference_image_2 | file(image/*) | 否 | — | 可选参考图 2 (CDN URL);未提供时传空字符串 |
| reference_image_3 | file(image/*) | 否 | — | 可选参考图 3 (CDN URL);未提供时传空字符串 |
| reference_image_4 | file(image/*) | 否 | — | 可选参考图 4 (CDN URL);未提供时传空字符串 |
全局禁令
- ❌ 禁止调用
save_file_to_session工具 — 本工具产生的所有资产 gateway 已自动保存到 workspace 并通过recordAsset注册到画布,任何手动保存(save_file_to_session/curl/wget/download_videos等)都会让同一资产入两次库。完成后只需用 markdown 媒体语法引用local_path/ 脚本outputs返回的路径即可。
执行流程
STEP 1: 打开 GUI 收集参数
调用 hub_open_remote_tool_gui,入参:
{
tool_name: "n-storyboard",
entry: "scripts/index.js",
initial_params?: { /* 可选,用户在对话里已经给出的具体参数,key 对齐"参数"表里的 id */ },
}
预填规则:如果用户在对话中已经明确给出某个参数的具体值(例如"用 kissing 这个 pose"、"prompt 写'夕阳下奔跑'"),把它们打包进 initial_params 一并传入,GUI 挂载后会自动预填,用户无需再次输入。没明确给值的参数不要瞎猜,留给 GUI 表单收集即可。
附件预填(本工具的 file 参数:reference_image_1、reference_image_2、reference_image_3、reference_image_4):
用户消息可能以系统自动注入的 [User attached files: <path1>, <path2>, ...] 开头 —— 这是文件路径,不是用户手打的文字。出现这种情况时必须按下表把附件路径塞进 initial_params,即使用户文字里没说"用这张图":
| 参数 id | accept | 取值规则 |
|---|---|---|
reference_image_1 |
image/* |
附件列表中第一个匹配该 MIME 的路径 |
reference_image_2 |
image/* |
附件列表中第一个匹配该 MIME 的路径 |
reference_image_3 |
image/* |
附件列表中第一个匹配该 MIME 的路径 |
reference_image_4 |
image/* |
附件列表中第一个匹配该 MIME 的路径 |
补充约束:
- 把匹配到的本地路径直接塞进
initial_params[<id>](GUI 会识别本地路径并自动上传到 CDN,agent 不要自己调hub_upload_to_cdn/upload_to_cdn) - 没匹配到的 file 字段:不传(留给 GUI 表单让用户上传)
- 同一字段有多张匹配:只取第一个,其余交给 GUI
示例:
- 用户消息:
[User attached files: /Users/me/face.webp]\n\n/n-storyboard - 应调用:
hub_open_remote_tool_gui({ tool_name: "n-storyboard", entry: "scripts/index.js", initial_params: { reference_image_1: "/Users/me/face.webp" } })
initial_params 仅用于 open_remote_tool_gui 调用时的预填。GUI 打开后由用户操作,不要尝试再用其他方式去操控 GUI。
STEP 2: 接收用户提交
GUI 提交后,系统会注入一条 user message,形如:
User submitted GUI form for tool "n-storyboard". Form data:
{ "params": { ... }, "files": [{ "param_id": "...", "url": "...", "name": "...", "type": "..." }] }
把 files[].url 按 param_id 匹配到对应字段(params[<param_id>] = files[i].url),组装出完整的 DAG inputs。无需再次上传文件(GUI 已通过 sdk.uploadFile 上传到 CDN)。
收到 form data 后直接进入 STEP 3,严格禁令
- ❌ 禁止重新调用
hub_open_remote_tool_gui(无论是否改initial_params)—— 用户已经在 GUI 里确认过参数,你不是产品经理,不要替用户改主意。同一 turn 内重开 GUI 会让新 link 覆盖旧 pending、UI 永远停在 "Thinking..."、用户被迫重填,直接死循环 - ❌ 禁止在对话流输出"本次方案 / 这版思路 / 我再帮你调整一版 / 我重新设计一下"之类的二次提案 —— 参数已经 lock,不要"反悔"
如果你判断 GUI 提交的参数确实不合理,只有两个合法选项:(a) STEP 3 照常 submit,让 DAG 后端报错,你再用错误信息向用户解释;(b) 完全终止本次任务并向用户说明原因。绝对不是悄悄重开 GUI。
STEP 3: 调用 hub_submit_dag
用上一步组装好的 inputs 调用工具:
| 字段 | 值 |
|---|---|
| dag_id | "508770976364388360" |
| inputs | { "grid_setting": "<宫格配置 JSON 字符串,形如 {\>", "user_prompt": "<用户故事描述,中英文皆可>", "aspect_ratio": "16:9", "reference_image_1": "<cdn_url>", "reference_image_2": "<cdn_url>", "reference_image_3": "<cdn_url>", "reference_image_4": "<cdn_url>" } |
| asset_keys | [](始终传空数组) |
inputs 格式约束:
- 所有 value 必须是字符串字面量(包括数字、布尔)
- 上方"参数"表中所有参数都必须传递,可选参数无值时传空字符串
""占位 - file 类型参数填 CDN URL(
https://...开头)
出参:{ run_id: string, estimated_seconds: number }
STEP 4: 提交后立即结束当前 turn
submit_dag 返回后,当前 turn 必须立即结束。Gateway 在后台代理轮询(15s 间隔,30 分钟超时),完成时会自动注入新 user message 唤醒。
严格禁令
- ❌ 禁止重新调用
hub_open_remote_tool_gui—— submit_dag 已发出,任务在跑;再开 GUI = 同一任务排队两次 + 旧 link 被新 link 覆盖 + UI 永远卡在 "Thinking..." + 用户被迫重填,死循环。这是同一 turn 内最常见、危害最大的违规,任何"我再帮你调整一版"的冲动都意味着你已经踩进死循环 - ❌ 禁止在对话流输出"本次方案 / 这版思路 / 我再设计一版"之类二次提案文本 —— 参数已交给 DAG,你不是产品经理,不要替用户改主意
- ❌ 禁止用
question/ask工具"通知用户等待"或"询问是否继续" — UI 已自带 loading 反馈,question 会卡住对话流,DAG 完成消息排队进不来 - ❌ 禁止主动调用
hub_query_dag_result— gateway 会回调,主动查会浪费 turn 还可能 race condition - ❌ 禁止重复
submit_dag— 会在后端创建多个任务,消耗用户配额 - ❌ 禁止输出"任务进行中,请稍候"之类的中间态文本 — 会让 UI 误以为在等用户回复
- ❌ 禁止 sleep / 自旋 / 任何形式的等待 — 事件驱动,等待靠系统注入
STEP 5: 处理完成消息
注入的 user message 形如:
Async task completed:
{
"task_id": "<run_id>",
"status": "succeeded" | "failed" | "timeout",
"outputs": { ... },
"asset_outputs": [
{ "key": "image", "status": "finished", "url": "https://cdn...", "local_path": "..." }
],
"error_message": null
}
status: "succeeded"
用 markdown 媒体语法插入资产,从 asset_outputs 中遍历 status == "finished" 的条目:
- 图片:
 - 视频:
或链接[查看视频](<local_path>) - 其他文件:
[<描述>](<local_path>)
关键约束:
- ✅ 必须用
local_path(gateway 已自动下载到 workspace 并通过recordAsset注册到画布) - ❌ 不要用
url(CDN URL 仅作 fallback,直接用会让画布丢失资产引用) - ❌ 禁止调用
save_file_to_session/curl/wget/download_videos等下载工具 — gateway 已下载,重复会让同一资产入两次库 - ⚠️ 纯文本(如「已生成」「已保存」)不会渲染媒体,必须用 markdown 语法
status: "failed"
向用户报告 error_message,建议调整输入后重试。不要自动 retry。
status: "timeout"
任务已被 gateway abort(30 分钟未完成),向用户报告超时并建议稍后重试。
排查参考
submit_dag调用本身报错(返回非 ok):检查 inputs 是否完整,所有 key 都必须传(可选项传"")- 完成消息一直没来:用户应能看到 UI 端 loading;若超过 30 分钟仍无完成消息,gateway 可能已 abort,等下一次用户主动操作