ecommerce-image-suite

# 电商套图生成助手 ## 概览 本 Skill 实现从「商品原始图片 + 卖点信息」到「完整电商套图」的一键生成流程： ``` ① 上传商品图片（必须）+ 输入卖点信息（可选） ↓ ② AI 视觉分析：提取商品主体，智能生成卖点文案（可编辑） ↓ ③ 选择平台规范 + 套图类型（7种标准图） ↓ ④ AI 生成每张图的详细 Prompt（可编辑） ↓ ⑤ 调用图像生成 API，输出完整套图（文案由生图模型直接渲染） ↓ ⑥ 平台文案（可选）→ ⑦ 详情页 HTML（可选） ↓ ⑧ 产品展示视频生成（可选，基于套图，需用户确认） ``` --- ## ⛔ 前置检查：API Key 验证（必须最先执行） **在执行任何其他操作之前**，Agent 必须先完成以下验证。若验证失败，**立即停止，不得调用任何工具或执行任何后续步骤**。 ### 验证步骤 运行供应商检测脚本： ```bash python3 scripts/check_providers.py ``` 解析输出中的 `configured` 数组： - **如果 `configured` 为空数组 `[]`**： > ❌ **配置缺失，任务终止。** > > 向用户输出以下消息，然后**立即停止，不再调用任何工具**： > > --- > **未检测到任何图像生成 API Key，无法继续操作。** > > 请至少配置以下供应商之一（国内用户推荐前两个）： > > | 供应商 | 环境变量 | 说明 | > |--------|---------|------| > | 阿里云通义 | `DASHSCOPE_API_KEY` | 国内直连，推荐 | > | 字节跳动豆包 | `ARK_API_KEY` | 国内直连 | > | OpenAI | `OPENAI_API_KEY` | 需代理 | > | Google Gemini | `GEMINI_API_KEY` | 需代理 | > | Stability AI | `STABILITY_API_KEY` | 需代理 | > > 配置方法： > ```bash > export DASHSCOPE_API_KEY="sk-..." # 推荐，国内直连 > # 或 > export ARK_API_KEY="..." > ``` > 加入 `~/.zshrc` 后执行 `source ~/.zshrc` 使其永久生效，然后重新启动对话。 > --- > > **⚠️ Agent 规则：输出上述消息后，立即终止本次任务。不得继续分析图片、生成 Prompt 或调用任何其他工具。** - **如果 `configured` 非空**：记录可用供应商列表，继续执行第一步。 ### check_providers.py 脚本报错处理 若脚本本身执行失败（非零退出码或输出异常），**将完整错误信息输出到对话**，格式如下，然后停止： > ❌ **供应商检测脚本执行失败，任务终止。** > > 错误详情： > ``` > [此处粘贴脚本的完整 stdout + stderr 输出] > ``` > 请检查 Python 环境（需 Python 3.8+）及脚本路径是否正确。 --- ## 触发入口：判断是否已上传图片 > ⚠️ **Agent 必须在第一步开始前执行此判断，决定对话起点。** ### 情况 A：用户触发时【未上传图片】 用户说了类似「帮我做电商套图」「我要给某商家出套图」但**没有附带任何图片**时，Agent **禁止直接进入第一步**，必须先走以下引导流程： **1. 发送欢迎 + 图片输入引导（一条消息完成）：** > 好的，我来帮您生成完整的电商套图！ > > 在上传图片前，先了解一下最佳输入方案，**图片质量直接决定生成效果**： > > --- > > **请选择您的图片输入方式：** > > | 编号 | 方式 | 效果 | 适用情况 | > |------|------|------|---------| > | **① 正面 + 背面（平铺）** | ⭐⭐⭐⭐⭐ 最佳 | AI 全面理解正背面结构，材质图自动用背面细节 | 服装/鞋类**强烈推荐** | > | **② 单张正面（平铺）** | ⭐⭐⭐⭐ 优秀 | 标准正面展示，效果稳定 | 仅有一张时首选 | > | **③ 正面 + 背面（挂拍）** | ⭐⭐⭐⭐ 优秀 | 悬挂构图，适合有衣架的商家 | 有挂拍图时推荐 | > | **④ 单张挂拍** | ⭐⭐⭐ 良好 | 悬挂构图，效果较平铺略差 | 仅有挂拍图时 | > | **⑤ 模特实拍** | ⭐⭐⭐ 良好 | AI 提取商品特征，去除模特 | 有模特图时可用 | > > 💡 **小贴士**：多张图必须是**同一商品**，不同颜色/款式请分批处理；平铺图请确保平整无褶皱。 > > 📋 **CLI 环境（如 Claude Code）**：无法直接拖拽上传图片，请提供以下任一方式： > - 本地文件路径（如 `/Users/me/photos/product.jpg`） > - 远程图片 URL（如 `https://example.com/product.jpg`） > - Base64 字符串（`data:image/jpeg;base64,/9j/4AAQ...`） > - Base64 文件路径（文件内容为 base64 编码的图片数据） > > 请选择编号（或直接上传图片 / 提供路径或 URL，我会自动识别类型），然后提供图片即可开始。 **2. 等待用户回复：** - 用户选择编号后，记录 `input_image_type`（见映射表），再提示提供对应数量的图片（图形界面：上传图片；CLI：提供本地路径 / URL / base64） - 用户直接上传图片或提供路径/URL/base64（未选编号），自动检测 `input_image_type`，进入情况 B **编号 → `input_image_type` 映射：** | 编号 | `input_image_type` | |------|-------------------| | ① | `flat_lay_front_back` | | ② | `flat_lay` | | ③ | `hanging_front_back` | | ④ | `hanging` | | ⑤ | `model` | --- ### 情况 B：用户触发时【已上传图片】 用户在同一条消息中**附带了图片**时，Agent **直接进入第一步**，无需重复引导。 自动检测 `input_image_type`（见第二步 Step A），跳过欢迎引导。 --- ## 第一步：收集输入信息 ### 必须项 - **商品图片**：用户上传的原始商品图，**支持 1-3 张同一商品的不同角度/拍摄方式** - 平铺图（flat lay）、挂拍图（hanging）、模特实拍图（model）均可 - 多图时，Agent 综合所有图片分析，提取更完整的商品信息 - 多图仅用于分析参考，生成套图时以 `--product` JSON 驱动，不直接传入多图 ### 可选项（若用户未提供，AI 将自动从图片中分析生成） | 字段 | 说明 | |------|------| | 商品名称 | 如"黑色碎花交叉细吊带荷叶边下摆连衣裙" | | 核心卖点 | 材质、版型、设计特点等 3-5 条 | | 适用人群 | 如"追求甜美法式风格的年轻女性" | | 期望场景 | 如"海边度假、浪漫约会、周末聚会" | | 规格参数 | 材质、颜色、版型、领型、袖长等 | --- ## 第二步：AI 分析与卖点生成 > **🤖 商品识别三级优先策略（Agent 必须按顺序判断，不得跳级）：** > > | 优先级 | 条件 | 执行方式 | > |--------|------|----------| > | **① 最高** | Agent 自身具备视觉理解能力（如 Claude Vision、GPT-4o 等多模态模型） | **直接使用 Agent 内置能力**分析图片，输出卖点 JSON。**禁止调用任何外部脚本。** | > | **② 次之** | Agent 不具备原生视觉能力，但**拥有图像识别相关工具**（如 `analyze_image`、`img_recognize`、`vision_tool` 等） | **调用 Agent 内置工具**分析图片，输出卖点 JSON。 | > | **③ 兜底** | Agent 既无原生视觉能力、也无视觉工具 | **调用 `scripts/analyze.py` 脚本**（见下方说明）。**禁止让用户手动描述商品，禁止凭空生成商品描述。** | > > ⚠️ **严禁行为**：在未尝试上述三级方案的情况下，直接询问用户「请描述一下您的商品」。 ### ⚠️ 确定输出目录（output_dir） > ⚠️ **Agent 必须先检查已有目录，按最大编号 +1 递增，禁止直接使用 001！** **每个商品任务使用独立子目录**，避免多批次生成图与 `generate_result.json` 互相覆盖。 **自动递增规则**： 1. 检查 `./output/` 下已有三位数编号子目录（`001/`、`002/`、`003/`、`004/`……） 2. 取最大编号 +1 作为本次目录（如已有 `004/` 则本次使用 `005/`） 3. 若 `./output/` 不存在或为空，则从 `001` 开始 **Agent 操作流程**： 1. **先检查已有目录**（必须执行）： ```bash # Bash 方式 if [ -d "./output" ]; then n=$(ls -d ./output/[0-9][0-9][0-9] 2>/dev/null | sort | tail -1 | grep -oE '[0-9]+$') next=$(printf "%03d" $((${n:-0} + 1))) echo "检测到已有目录，将使用: ${next}" else next=001 echo "output 目录为空，将从 001 开始" fi ``` 2. **创建输出目录**： ```bash output_dir="$(pwd)/output/${next}" mkdir -p "${output_dir}" echo "本次套图将保存到: ${output_dir}" 3. **告知用户**： > 检测到已有商品任务（最高编号：004），本次将使用 **output/005/**。 > 直接继续，或输入自定义目录名（如 `黑色连衣裙`）。 **同一任务使用多个模型时**：在任务子目录下再创建模型名子目录（如 `output/001/nano-banana/`、`output/001/gpt-image-1.5/`）。 **多模型子目录**（同一任务对比不同模型效果）： ```bash # 首个模型 output_dir="$(pwd)/output/001/nano-banana" mkdir -p "${output_dir}" # 后续模型 output_dir_2="$(pwd)/output/001/gpt-image-1.5" mkdir -p "${output_dir_2}" ``` **非 Bash 客户端**：用文件系统工具列出 `./output/` 子目录，找最大数字编号 +1；若无法判断则默认 `./output/001/`。 用户也可**自定义目录名**（如按商品命名）。 记录 `output_dir` 后，后续所有步骤统一使用此路径。 > ⚠️ **常见错误**：直接使用 `output/001/` 会覆盖之前的任务！必须先检查最大编号。 --- ### ⚠️ 图片预处理（最先执行，所有步骤的前提） > 用户上传的图片保存在 session 临时目录，脚本运行时可能因路径失效或权限问题无法访问。**必须在调用任何脚本前将图片复制到 `{output_dir}/` 下。** ```bash # 将所有用户上传的商品图片复制到工作区（路径以实际上传路径为准） cp "/absolute/path/to/用户上传图1.jpg" "{output_dir}/front.jpg" cp "/absolute/path/to/用户上传图2.jpg" "{output_dir}/back.jpg" # 若有背面图 ``` 复制完成后，后续所有脚本一律使用 `{output_dir}/front.jpg`、`{output_dir}/back.jpg` 等**工作区绝对路径**，不得直接使用用户上传的原始路径。 **Agent 操作规则：** 1. 用 Bash `cp` 命令将每张上传图复制到 `{output_dir}/` 2. `output_dir` 已在上一步创建，无需重复 `mkdir` 3. 复制成功后记录工作区路径，后续 `--product-images`、`--model-image`、`analyze.py` 参数全部使用工作区路径 --- ### 视觉分析步骤 **Step A：判断 `input_image_type`（必须，影响生图构图）** | 用户提供的图片 | `input_image_type` | 说明 | |--------------|-------------------|------| | 1 张平铺图（正面） | `flat_lay` | 默认，标准正面平铺 | | 2 张平铺图（正面 + 背面） | `flat_lay_front_back` | 最佳组合；背面图自动用于材质图 | | 1 张挂拍图 | `hanging` | 构图自动改为挂拍悬挂风格 | | 2 张挂拍图（正面 + 背面） | `hanging_front_back` | 背面挂拍用于材质图 | | 1 张模特实拍 | `model` | AI 提取商品特征，构图提示去除模特 | **Step B：确定参考图列表（决定 `--product-images` 参数）** > 使用图片预处理步骤中复制到 `{output_dir}/` 的绝对路径，不得使用用户上传的原始路径。 - 1 张图 → `--product-images {output_dir}/front.jpg` - 正反 2 张 → `--product-images {output_dir}/front.jpg,{output_dir}/back.jpg`（顺序必须：正面在前） - 3 张 → `--product-images {output_dir}/front.jpg,{output_dir}/back.jpg,{output_dir}/detail.jpg` **生图脚本自动按图类型选图**： | 套图类型 | 使用哪张图 | |---------|-----------| | 白底主图、核心卖点图、卖点图、场景图、模特图、多场景图 | 第 1 张（正面） | | 材质图 | 第 2 张（背面/细节）；无则用第 1 张 | **Step C：分析商品信息** 1. 识别商品类型、颜色、款式、设计元素，多图时综合所有图片信息 2. 提取精确视觉特征：主色、辅助色、印花图案、领型、廓形、下摆、面料质感、季节属性 3. 基于视觉特征推断材质、功能卖点，生成每个卖点的视觉关键词（用于放大镜气泡） 4. 生成结构化卖点 JSON（格式见下），供第四步生成 generate.py 参数使用 ### 卖点 JSON 结构（丰富版） ```json { "product_name": "黑色碎花交叉细吊带荷叶边下摆连衣裙", "product_category": "连衣裙", "product_subtype": "吊带裙", "product_type": "服装", "visual_features": { "main_color": "黑色", "secondary_colors": ["淡粉色樱花", "白色"], "pattern": "碎花印花", "neckline": "V领交叉细吊带", "silhouette": "鱼尾A字", "hemline": "荷叶边双层", "length": "短裙/中裙", "fabric_texture": "轻盈飘逸", "season": "春夏" }, "selling_points": [ { "type": "design", "title": "个性交叉领口", "description": "V领结合多重细绑带设计，凸显优雅锁骨曲线", "visual_keywords": ["cross-strap neckline", "V-neck detail", "collarbone"], "icon": "design", "en": "Cross-strap V-neckline", "zh": "个性交叉领口" }, { "type": "pattern", "title": "唯美碎花印花", "description": "黑色底面点缀淡雅樱花图案，营造复古浪漫氛围", "visual_keywords": ["floral print pattern", "cherry blossom motif"], "icon": "design", "en": "Floral Print", "zh": "唯美碎花印花" }, { "type": "silhouette", "title": "灵动鱼尾设计", "description": "下摆采用层次感荷叶边，行走间灵动飘逸", "visual_keywords": ["ruffle hemline layers", "flowy silhouette"], "icon": "fit", "en": "Ruffle Hemline", "zh": "灵动鱼尾设计" } ], "target_audience": "追求个性时尚、喜爱甜美法式风格的年轻女性", "target_scenes": ["海边度假", "浪漫约会", "周末聚会", "盛夏日常"], "target_scene_envs": [ "tropical beach with golden sand and turquoise ocean, bright midday sunlight", "romantic outdoor restaurant terrace at dusk, warm candlelight, string lights",