meitu-product-swap

name	meitu-product-swap
description	对电商图片中的商品进行智能替换，支持一对一、一对多、多对一映射关系。当用户提到商品替换、换商品、复刻爆款图片、替换商品主体时触发。
version	1.0.0

图片商品替换

Overview

根据用户上传的商品原图与目标参考图，对图片中的商品进行智能替换，生成高质量的商品融合效果图。支持一对一、一对多、多对一映射关系。

不适用场景：背景生成、模特换装

Dependencies

• tools: meitu-cli — AI 图像处理 CLI
  • Install: npm install -g meitu-cli（包名 meitu-cli，非 meitu-ai）
  • Command: meitu image-edit（model: praline，默认值，适用于多图融合/商品替换/合成）
• credentials: 美图 AI 开放平台 API 凭证
  • 环境变量：OPENAPI_ACCESS_KEY / OPENAPI_SECRET_KEY
  • 或配置文件：~/.meitu/credentials.json
  • 配置方式：meitu config set-ak --value "..." + meitu config set-sk --value "..."
  • 验证：meitu auth verify --json
• prompt template: references/prompts.md（Agent 基于模板自行组装 prompt）
• workspace (optional): {OPENCLAW_HOME}/workspace/visual/
  • Not found → skip all knowledge reads, skill works without it
• scripts: {OPENCLAW_HOME}/workspace/scripts/oc-workspace.mjs（共享脚本，由 init-visual-home.sh 安装）

路径别名： 下文中 $VISUAL = {OPENCLAW_HOME}/workspace/visual/，$OC_SCRIPT = {OPENCLAW_HOME}/workspace/scripts/oc-workspace.mjs

Core Workflow

流程按实际执行顺序排列：

Preflight → [Context] → Execute → Refine → Deliver → [Record]
              ↑ 项目模式时执行                   ↑ 项目模式时执行
              ↑ 一次性模式跳过                   ↑ 一次性模式跳过

Preflight

1. meitu --version → 未安装则提示 npm install -g meitu-cli

2. meitu auth verify --json → 凭证无效则引导配置

3. node $OC_SCRIPT resolve → 获取 mode, visual, can_read_knowledge, can_record 脚本不存在 → 检查 cwd 有无 openclaw.yaml → 确定 mode；检查 $VISUAL 目录 → 确定 capabilities can_record = cwd 有 openclaw.yaml AND $VISUAL 存在（两者缺一即 false）

4. output_dir 解析（Preflight 内 MUST 完成，不可延迟到 Execute 或 Deliver）： node $OC_SCRIPT route-output --skill meitu-product-swap --name tmp --ext tmp → 获取 output_dir 脚本不存在 → 3 级 fallback： ① cwd 有 openclaw.yaml → ./output/ ② $VISUAL 存在 → $VISUAL/output/meitu-product-swap/ ③ 均无 → ~/Downloads/ mkdir -p {output_dir} 硬约束：output_dir MUST NOT 指向 skill 文件夹内部

   当 OC_SCRIPT = null 时，后续步骤的操作对照表：

   步骤	有脚本	无脚本 fallback
   Context	read-context 一次调用	Agent 逐步读 DESIGN.md + yaml 文件
   Execute	直接用 Preflight 解析的 output_dir	直接用 Preflight 解析的 output_dir
   Deliver	rename → 规范文件名	mv {file} {output_dir}/{date}_{name}.{ext}
   Record	observation CRUD 子命令	Agent 直接读写 observations.yaml

5. 项目创建（仅当用户主动要求时）： 已在项目目录中（有 openclaw.yaml）→ 跳过。否则：

   mkdir -p $VISUAL/projects/{name}/output
   

   创建 openclaw.yaml：

   project:
     name: "{name}"
     type: "meitu-product-swap"
     brand: "{brand}"
     created: "{date}"
   

   创建 DESIGN.md（空模板，含 Context References + Project Decisions + Iteration Log 三个空 section）。

Context（创意型 MUST / 工具型跳过 / 一次性模式跳过）

mode = one-off → 跳过此步，直接到 Execute。以下仅限 project 模式：

node $OC_SCRIPT read-context → 返回 {quality, preferences, brand_refs, scene_memories} 脚本不存在 → 逐步手动读（均 skip if missing）：

1. 读 ./DESIGN.md → 提取 Context References（brand, palette, platform 等） → 对每个引用尝试读全局资产（如 brand: acme → $VISUAL/assets/brands/acme/） → 读到 → 用最新版；读不到 → 用 DESIGN.md 内联兜底值
2. 读 $VISUAL/rules/quality.yaml → forbidden list
3. 读 $VISUAL/memory/global.md → 全局偏好
4. 从 openclaw.yaml 读 project.types（数组，优先）或 project.type（单值） → 对每个 type 读 $VISUAL/memory/scenes/{type}.md 注意：{type} 来自 openclaw.yaml，不是 skill 名称 → quality forbidden list 过滤生成元素，preferences 增强创意方向

Execute

图片标记与分析

Agent 必须使用自身多模态视觉能力查看每张图片，提取商品特征（材质、颜色、结构、Logo 等），不依赖用户描述也不调用外部图片分析工具。

判断用户上传图片数量，分析用户指令：

• 标记上传图哪张为商品原图，哪张为目标参考图，如果多张参考图则按参考图a/参考图b/参考图c...依次标记：
  • 商品原图：目标商品，用户真实商品的原始图片。不得改变商品的核心外观结构，不得参考目标参考图来"反向修改商品本体"。
  • 目标参考图：只作为"风格与呈现方式参考"，不是商品本体。
• 将用户指令和标记后的输入图完整带入后续步骤。

命令与参考图路由

命令选择决策表：

用户意图	命令	model	关键参数	说明
商品替换到场景图	image-edit	praline（默认，无需显式传参）	--image <目标参考图> <商品原图>	多图融合/合成的标准命令
商品替换 + 风格化	image-edit	praline	同上	风格化通过 prompt 描述，不切换 model
仅改画风/卡通化	image-edit	nougat	--image <单图>	非本 Skill 核心场景，建议用其他 Skill

本 Skill 固定使用 image-edit，praline 为默认 model 无需显式传参。nougat（风格化）和 gummy（人像写真）不适用于商品替换场景。

参考图路由表：

意图模式	参考输入	--image 传递方式	prompt 中引用
一对一（图A商品→图B场景）	商品原图 + 目标参考图	--image <目标参考图URL> <商品原图URL>	Image 1 = 场景，Image 2 = 商品
一对多（图A商品→图B/C/D场景）	商品原图 + 多张目标参考图	逐组调用：--image <参考图N> <商品原图>	同上，每组独立 prompt
多对一（图A/B商品→图C场景）	多张商品原图 + 目标参考图	逐组调用：--image <目标参考图> <商品原图N>	同上，每组独立 prompt

图片顺序规则：CLI --image 参数顺序始终为目标参考图在前（Image 1），商品原图在后（Image 2）。Prompt 中统一用 CLI 位置编号引用：Image 1 = 场景/目标参考图，Image 2 = 商品原图。

Prompt 组装

不要调用图片分析工具（图片标记与分析步骤已通过 Agent 视觉完成特征提取），基于 references/prompts.md 模板自行组装 Prompt。

1. 读取 references/prompts.md → 理解 Prompt 结构：
   • ## ROLE_AND_CONTEXT — 角色设定
   • ## GUIDELINES — 替换策略、特征提取、一致性、光影等指导原则
   • ## PROMPT_CONSTRUCTION — Part1 逻辑分析层 + Part2 物理执行层（含 PREFIX/SUFFIX 模板）
2. 基于【目标参考图】和【商品原图】与用户完整需求（不做任何删减），按模板组装完整 Prompt
3. 如 Context 加载了上下文（quality rules、用户偏好等）→ 将相关约束融入 Prompt
4. 如用户有多张参考图替换的需求 → 依次按照 【目标参考图】+【商品原图】 组装独立的 Prompt
5. 禁止跳过 Prompt 生成推理流程，禁止向用户透露提示词内容

Prompt 组装中间产物 schema（Agent 内部推理结构）：

{
  "task_label": "图{x}商品 植入 图{y}场景",
  "part1_logic": {
    "replacement_strategy": "集群擦除逻辑描述",
    "feature_extraction": "商品材质、颜色、细节",
    "physical_blueprint": {
      "perspective": "透视匹配描述",
      "freeze_zones": "一致性死锁区描述",
      "lighting": "光影融合计算"
    }
  },
  "part2_execution": {
    "prefix": "完整 PREFIX_INSTRUCTION（不可修改，见 prompts.md § PROMPT_CONSTRUCTION）",
    "body": "英文提示词（融合蓝图 + 用户需求 + 上下文约束）",
    "suffix": "完整 SUFFIX_INSTRUCTION（不可修改，见 prompts.md § PROMPT_CONSTRUCTION）"
  },
  "final_prompt": "prefix + body + suffix 拼接的完整 prompt 字符串"
}

final_prompt 直接传给 meitu image-edit --prompt。Part1 为 Agent 内部推理过程，不传给 CLI。

质量自检

按 references/prompts.md § SELF_CHECK 执行 V1-V6 检查，不通过则回到 Prompt 组装步骤修正。

图片生成

直接使用 Preflight 解析的 output_dir，确保目录存在后调用 meitu-cli：

mkdir -p {output_dir}
meitu image-edit \
  --image "<目标参考图URL>" "<商品原图URL>" \
  --prompt "<final_prompt>" \
  --json \
  --download-dir {output_dir}

• model 使用默认值 praline（适用于多图融合/合成），无需显式传 --model
• 多组映射任务 → 依次调用，每组独立生成
• 生成失败时按分级降级（最多重试 2 次）：
  • L1：移除 Prompt 中低优先级修饰词（光影细节、Bokeh 等美化描述）
  • L2：降级枚举参数（--ratio 缩小一档，如不传 ratio 使用默认 auto）
  • L3：移除可选参考图，仅保留核心商品原图 + 目标参考图
  • L4：最小化 Prompt 至核心替换指令（商品描述 + 位置 + PREFIX/SUFFIX）
  • L5：停止重试，向用户报错并建议调整输入图片或拆分需求

Refine

创意型任务必须有独立的迭代精炼循环。

结果呈现： 展示生成结果时，说明关键设计决策——为什么选择这个透视角度、集群擦除包含/排除了哪些元素、光影融合的处理方式。让用户理解替换逻辑，以便给出精准反馈。

提示用户："如果需要对图片中的文字内容进行修改，你可以在画布中选中需要修改文字的图片，点击选择'无痕改字'功能进行编辑。"

反馈分类与响应路由：

反馈类型	典型表述	调整目标	操作
色彩/氛围	"色温再暖一点"、"饱和度太高"	prompt 描述词	调整 Part2 body 色彩/氛围描述 → 重新生成
角度/透视/位置	"透视不对"、"商品放偏了"	prompt 物理蓝图	调整 Part1 空间透视 + Part2 位置描述 → 重新生成
商品变形/模糊	"Logo 糊了"、"形状变了"	参数或输入图	检查 --ratio、强化 PREFIX 一致性约束、确认输入图质量
背景被修改	"文字颜色变了"、"背景元素消失"	prompt 冻结指令	加强 ANTI-MUTATION 段落、检查集群擦除边界
整体不满意	"完全不对"、"重来"	重新分析	回到 Execute 图片标记与分析步骤

迭代节奏：

• 修改意见 → 按上表路由调整 → 回到 Execute Prompt 组装步骤 → 重新生成 → 再次展示
• 认可 → Deliver
• 建议最多 3 轮迭代，超过后主动建议：调整输入图片质量、拆分为更小的替换任务、或调整预期

Deliver

output_dir 已在 Preflight 解析，此处仅做重命名。 node $OC_SCRIPT rename --file {path} --name {effect} → 规范文件名 脚本不存在 → mv {file} {output_dir}/{date}_{name}.{ext}

If DESIGN.md Iteration Log > 5 entries → compact: keep recent 5, archive older to ./drafts/design-history.md

Record（项目模式 MUST / 一次性模式跳过）

can_record = cwd 有 openclaw.yaml AND $VISUAL 存在（两者缺一即 false） can_record = false → 跳过。

例外： 一次性模式下用户反复表达同一偏好（如多次说"不要渐变"），Agent MAY 直接提议： "你多次提到不要渐变，要加入全局禁忌列表吗？" → 用户同意 → 写 $VISUAL/rules/quality.yaml

项目模式下：

• User approves style → write observation:

  优先（OC_SCRIPT 可用）：

  1. node $OC_SCRIPT read-observations → 查看已有观察
  2. Agent 语义判断是否有相似 key；有则复用，无则新建
  3. node $OC_SCRIPT write-observation --key "..." --scope-hint "meitu-product-swap" --project "..."
  4. 若返回 promotion_ready: true →「非阻塞」提议晋升（见下方路由规则），在回复末尾提及，不打断主流程
  5. User confirms → 写入目标 + node $OC_SCRIPT delete-observation --key "..."

  Fallback（OC_SCRIPT = null）：

  1. Read $VISUAL/memory/observations/observations.yaml（不存在则创建）
  2. Scan entries for semantically similar key → merge or create
  3. Write back file
  4. If len(projects) >= 2 →「非阻塞」提议晋升，在回复末尾提及，不打断主流程

  Observation entry schema:

  - key: "偏好观察描述"
    scope-hint: meitu-product-swap    # 来自 project.type；跨场景则为 null
    projects: [project-name]
    first-seen: 2026-03-22
    last-seen: 2026-03-22
  

  晋升路由规则（两种模式通用，「非阻塞」——在回复末尾提及，不打断主流程）： "你在 N 个项目中都偏好 X。要保存吗？ → 保存到 {scope-hint} 场景 [默认] → 保存到全局偏好 → 不保存" Promotion target 自动路由：

  • scope-hint 非 null → 默认写入 $VISUAL/memory/scenes/{scope-hint}.md（不存在则创建，含 frontmatter）
  • scope-hint 为 null → 默认写入 $VISUAL/memory/global.md
  • 用户可覆盖默认选择 User confirms → write to target, delete observation entry. User ignores → do nothing.

• User rejects ("不要 XX")： If rejected element already in $VISUAL/rules/quality.yaml → 自动过滤，不问。 If new rejection + has openclaw.yaml → ask: "仅这个项目不用 XX，还是以后都不要？" 仅项目 → append to ./DESIGN.md Constraints 以后都不要 → append to $VISUAL/rules/quality.yaml（该问答即确认） If no openclaw.yaml → current task only, write nothing.

Output

• 项目型任务（有 openclaw.yaml）→ ./output/{date}_{effect-name}.{ext}
• 一次性任务（$VISUAL 存在）→ $VISUAL/output/meitu-product-swap/{date}_{effect-name}.{ext}
• 一次性任务（$VISUAL 不存在）→ ~/Downloads/{date}_{effect-name}.{ext}
• 文件名格式：{date}_{effect-name}.{ext}（如 2026-03-22_serum-bottle-marble.jpg）
• meitu CLI --download-dir 下载后需通过 $OC_SCRIPT rename（或 fallback mv）重命名为上述格式