147 lines
7.7 KiB
Markdown
147 lines
7.7 KiB
Markdown
---
|
||
name: relight
|
||
summary-en: Smart relighting — freely adjust light direction, intensity, and color.
|
||
summary-cn: 智能重打光,自由调整光线方向、强度和色彩
|
||
display-name-zh: 光影工作室
|
||
trigger-words: [重打光, 改打光, 打光, relight, change lighting, re-light]
|
||
description: |
|
||
上传图片后,通过 3D 灯光球面板控制光线方向 / 强度 / 色彩,选择背景模式与氛围特效,一键重新照亮画面。提供 20 种风格预设和 25 种氛围特效,也支持自由编辑最多 3 盏灯源(类型 / 角度 / 色温或 HEX)
|
||
allowed-tools: hub_open_remote_tool_gui, hub_submit_dag, hub_upload_to_cdn
|
||
version: 1.0.5
|
||
tags: [Image, Creative]
|
||
tags-cn: [图片, 创意]
|
||
exported-by: 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`，入参:
|
||
|
||
```ts
|
||
{
|
||
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`：
|
||
|
||
- 图片：``
|
||
- 视频：`` 或链接 `[查看视频](<...>)`
|
||
- 其他文件：`[<描述>](<...>)`
|
||
|
||
⚠️ 纯文本（如「已生成」「已保存」）不会渲染媒体，**必须用 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 注入
|