Popiai-skill仓库

7.7 KiB

Raw Blame History

name	summary-en	summary-cn	display-name-zh	trigger-words	description	allowed-tools	version	tags	tags-cn	exported-by
relight	Smart relighting — freely adjust light direction, intensity, and color.	智能重打光,自由调整光线方向、强度和色彩	光影工作室	[重打光改打光打光 relight change lighting re-light]	上传图片后,通过 3D 灯光球面板控制光线方向 / 强度 / 色彩,选择背景模式与氛围特效,一键重新照亮画面。提供 20 种风格预设和 25 种氛围特效,也支持自由编辑最多 3 盏灯源(类型 / 角度 / 色温或 HEX)	hub_open_remote_tool_gui, hub_submit_dag, hub_upload_to_cdn	1.0.5	[Image Creative]	[图片创意]	MiniMax-hub

Relight

智能重打光,自由调整光线方向、强度和色彩

参数

ID	类型	必填	取值约束	说明
input_img	file(image/*)	是	—	用户上传的原图,要被重打光的目标图片。可由主站通过 params:inject 预填 CDN URL(string,以 https:// 开头),GUI 会渲染为已上传态
reference_img	file(image/png)	是	—	(GUI 内部自动生成)客户端用 three.js 离屏渲染当前 3D 灯光球状态后导出的 PNG。GUI 在 emit
light1	string	是	—	(GUI 内部自动生成)第 1 盏灯的 JSON 串,形如 {\
light2	string	是	—	(GUI 内部自动生成)第 2 盏灯的 JSON 串,格式同 light1,无第 2 盏灯时传空字符串占位。禁止主站通过 params:inject 注入此字段
light3	string	是	—	(GUI 内部自动生成)第 3 盏灯的 JSON 串,格式同 light1,无第 3 盏灯时传空字符串占位。禁止主站通过 params:inject 注入此字段
background	string	是	—	(GUI 内部自动生成)背景模式:default 保留原背景,black 纯黑背景,white 纯白背景。禁止主站通过 params:inject 注入此字段
effect	string	是	—	(GUI 内部自动生成)氛围特效业务值字符串,如
user_intent	string	否	—	用户的附加要求(可选,中英文均可),GUI 暴露一个输入框让用户填(如\

执行流程

STEP 1: 打开 GUI 收集参数

调用 hub_open_remote_tool_gui，入参:

{
  tool_name: "relight",
  entry: "scripts/index.js",
  initial_params?: { /* 可选,用户在对话里已经给出的具体参数,key 对齐"参数"表里的 id */ },
}

预填规则:如果用户在对话中已经明确给出某个参数的具体值,把它们打包进 initial_params 一并传入,GUI 挂载后会自动预填,用户无需再次输入。没明确给值的参数不要瞎猜,留给 GUI 表单收集即可。

附件预填(本工具的 file 参数:input_img):

用户消息可能以系统自动注入的 [User attached files: <path1>, <path2>, ...] 开头 —— 这是文件路径,不是用户手打的文字。出现这种情况时必须按下表把附件路径塞进 initial_params,即使用户文字里没说"用这张图":

参数 id	accept	取值规则
`input_img`	`image/*`	附件列表中第一个匹配该 MIME 的路径

补充约束:

匹配到的本地路径先调 hub_upload_to_cdn({ file_path: "<本地路径>" }) 获取 CDN URL,再把 URL 塞进 initial_params[<id>]
没匹配到的 file 字段:不传(留给 GUI 表单让用户上传)
同一字段有多张匹配:只取第一个,其余交给 GUI

示例:

用户消息: [User attached files: /Users/me/face.webp]\n\n/relight
先上传: hub_upload_to_cdn({ file_path: "/Users/me/face.webp" }) → 返回 CDN URL
再调用: hub_open_remote_tool_gui({ tool_name: "relight", entry: "scripts/index.js", initial_params: { input_img: "<CDN URL>" } })

initial_params 仅用于调用时的预填。GUI 打开后由用户操作,不要尝试再用其他方式去操控 GUI。

GUI 提交后,系统会注入一条 user message,形如:

User submitted GUI form for tool "relight". 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 后直接进入下一步，严格禁令

❌ 禁止重新调用 hub_open_remote_tool_gui(无论是否改 initial_params)—— 用户已经在 GUI 里确认过参数,你不是产品经理,不要替用户改主意。同一 turn 内重开 GUI 会让新 link 覆盖旧 pending、UI 永远停在 "Thinking..."、用户被迫重填,直接死循环
❌ 禁止在对话流输出"本次方案 / 这版思路 / 我再帮你调整一版 / 我重新设计一下"之类的二次提案文本 —— 参数已经 lock,不要"反悔"

如果你判断 GUI 提交的参数确实不合理,只有两个合法选项:(a) 照常进入下一步,让后端报错后再用错误信息向用户解释;(b) 完全终止本次任务并向用户说明原因。绝对不是悄悄重开 GUI。

STEP 2: 执行 relight

前置条件：收到 collect GUI 表单提交数据。

文件参数处理：以下参数值若为本地路径（非 https URL），先调 hub_upload_to_cdn({ file_path: "<本地路径>" }) 获取 CDN URL 再填入 inputs：

input_img
reference_img

调用 hub_submit_dag：

字段	值
dag_id	`"510954878823452675"`
inputs	`{ "input_img": <params.input_img>, "reference_img": <params.reference_img>, "light1": <params.light1>, "light2": <params.light2>, "light3": <params.light3>, "background": <params.background>, "effect": <params.effect>, "user_intent": <params.user_intent> }`
asset_keys	`["relight_image_v4"]`

提交后立即结束当前 turn（gateway 后台轮询，完成时自动注入新 user message 唤醒）。

STEP 3: 渲染资产

收到最后一步完成消息后，注入的 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(gateway 已下载到 workspace 并通过 recordAsset 注册到画布);若该条目无 local_path(本步骤未声明该 key 为 asset_keys),fallback 用 url：

图片：![描述](<asset_outputs[i].local_path \|\| asset_outputs[i].url>)
视频：![描述](<asset_outputs[i].local_path \|\| asset_outputs[i].url>) 或链接 [查看视频](<...>)
其他文件：[<描述>](<...>)

⚠️ 纯文本（如「已生成」「已保存」）不会渲染媒体，必须用 markdown 语法。

`status: "failed"`

向用户报告 error_message，建议调整输入后重试。不要自动 retry。

`status: "timeout"`

任务已被 gateway abort（30 分钟未完成），向用户报告超时并建议稍后重试。

严格禁令（适用所有步骤）

❌ 禁止重新调用 hub_open_remote_tool_gui —— 流水线在跑，再开 GUI = 旧 link 被覆盖 + UI 卡在 "Thinking..." + 用户被迫重填，死循环
❌ 禁止用 question / ask 工具通知用户等待 — UI 已有 loading 反馈
❌ 禁止主动调用 hub_query_dag_result — gateway 会回调，主动查会浪费 turn 还可能 race condition
❌ 禁止重复 submit_dag — 会在后端创建多个任务，消耗用户配额
❌ 禁止 sleep / 自旋 — 事件驱动，等待靠 gateway 注入

7.7 KiB Raw Blame History