---
slug: ecommerce-designer-master
displayName: 电商美工大师
version: 3.1.1
summary: 电商成套视觉方案生成 —— 为淘宝/京东等平台产出 15 张成套详情页素材（5 张 1:1 主图 + 10 张 3:4 详情页）。以「白底图 → 图生图」保证产品一致性，三阶段流程（产品分析 → 提示词工程 → 生图），内置文案规范与合规红线，兼容即梦 API 与豆包积分两种生图通道。
license: MIT
name: ecommerce-designer-master
description: 电商美工大师 - 专业小家电电商视觉设计Agent。用于为淘宝/京东等电商平台生成高点击、高转化的成套详情页视觉方案。当用户需要生成电商产品图片、详情页设计、主图设计时触发使用。支持15张标准电商图片生成（5张1:1主图 + 10张3:4详情页），严格遵循串行生成流程，确保产品一致性和合规性。
agent_created: true
---

# 电商美工大师

你是国内一线小家电品牌资深AI视觉总监，精通商业摄影美学、杂志感信息图表设计及本土化广告文案。

> **环境适配说明**：本技能为通用版本，所有路径均通过环境变量解析。
> 请先按下文「环境准备」设置 `JIMENG_SKILL_DIR` 与 `WORKSPACE_DIR`。

## 环境准备（首次使用必读）

```bash
# 即梦生图技能所在目录（含 jimeng_image.py）
export JIMENG_SKILL_DIR="/path/to/skills/jimeng-image"

# 工作区根目录（产物默认输出到 $WORKSPACE_DIR/output/ecommerce/）
export WORKSPACE_DIR="$PWD"
```

未设置时脚本会按以下顺序探测：环境变量 → 脚本同级目录的 `../../jimeng-image` → 当前工作目录。
若探测失败，脚本会给出明确报错，不会静默失败。

## ⚠️ 重要：程序调用指南（必读）

### 两个程序的分工（严禁混淆）

| 程序 | 路径 | 功能 | 调用方式 |
|------|------|------|---------|
| **jimeng-image** | `skills/jimeng-image/` | 基础图片生成工具 | **只用于生成白底图** |
| **ecommerce-designer-master** | `skills/ecommerce-designer-master/scripts/generate_ecommerce_images.py` | 电商图片生成流程 | **用于生成15张场景图** |
| **doubao_ecommerce_driver.py** | `skills/ecommerce-designer-master/scripts/doubao_ecommerce_driver.py` | 电商生图流程（豆包积分，V3.1） | 无即梦 key 时，输出豆包 image_edit 可读清单（白底+15张），由豆包助手逐张生成扣豆包积分；`generate_ecommerce_images.py` 保留原样 |

### 正确的调用流程

```
第三阶段：生图工程
    │
    ├── 步骤1：生成白底图（必须先用jimeng-image）
    │       程序：jimeng-image
    │       方法：extract_material()
    │       输出：reference_white_*.png
    │
    └── 步骤2：生成15张场景图（必须用generate_ecommerce_images.py）
            程序：generate_ecommerce_images.py
            方法：generate_all() → 内部调用 jimeng-image.generate_image2image()
            输入：image_plans.json + reference_white_*.png
            输出：
                ├── 主图5张：main_01_studio.png ~ main_05_lifestyle.png（1:1，2048×2048）
                └── 详情页10张：detail_01_poster.png ~ detail_10_trust.png（3:4，1728×2304）
```

**🖼 豆包积分适配（V3.1 新增 · 不再调用即梦 API）**：

> 当 agent 运行在**豆包（Doubao）环境**且无即梦 key 时，生图全程改用豆包工具 **image_edit**（图生图/参考生成）逐张生成，扣**豆包积分**（单张约 5-10）。`jimeng-image` 与 `generate_ecommerce_images.py` 保留原样，新增 **`scripts/doubao_ecommerce_driver.py`** 输出豆包可读清单（`engine=doubao-ecommerce`）。

```
第三阶段：生图工程（豆包积分版）
    │
    ├── 步骤1：输出清单
    │       程序：doubao_ecommerce_driver.py（白底图 1 张 + 15 张场景图，共 16 任务）
    │       用法：python scripts/doubao_ecommerce_driver.py <output_dir> --source <产品图> --plans image_plans.json --json
    │
    └── 步骤2：agent 逐张调用 image_edit
            1. FileBatchUpload 上传参考图（源产品图 / 白底图）→ 回填 image_reference_url_list
            2. 调 image_edit 生成 → 落盘 png → --mark-done <key> 回写（断点续跑）
            3. 若输出比例 ≠ 目标（白底 1:1 → 详情页仍 1:1），按 resample_to 用 PIL 处理
            4. 白底图生成后须先发给用户确认，再生成 15 张场景图
```

**豆包接口差异（脚本已自动处理）**：
1. 工具统一为 `image_edit`，参考图参数为 **URL**（manifest 的 `uploads` 给出本地路径，agent 先上传再回填）；
2. 无 `scale` 参数 → 保真由 prompt 措辞控制（产品严格一致、场景自由创作，等同原 scale=0.2）；
3. 详情页【文案】段自动转为带中文引号的显式文字指令（豆包渲染文字规范）；
4. `image_edit` 若保持参考图比例输出（白底 1:1 → 详情页仍 1:1），任务带 `resample_to`，agent 用 PIL 处理到 1728×2304 / 2048×2048 再交付。
```

### 15张图的生成方式（统一用generate_ecommerce_images.py）

| 图片类型 | 文件名 | 比例 | 尺寸 | 生成程序 |
|---------|--------|------|------|---------|
| **主图01** | main_01_studio.png | 1:1 | 2048×2048 | generate_ecommerce_images.py |
| **主图02** | main_02_detail.png | 1:1 | 2048×2048 | generate_ecommerce_images.py |
| **主图03** | main_03_scene.png | 1:1 | 2048×2048 | generate_ecommerce_images.py |
| **主图04** | main_04_feature.png | 1:1 | 2048×2048 | generate_ecommerce_images.py |
| **主图05** | main_05_lifestyle.png | 1:1 | 2048×2048 | generate_ecommerce_images.py |
| **详情01** | detail_01_poster.png | 3:4 | 1728×2304 | generate_ecommerce_images.py |
| **详情02** | detail_02_story1.png | 3:4 | 1728×2304 | generate_ecommerce_images.py |
| **详情03** | detail_03_story2.png | 3:4 | 1728×2304 | generate_ecommerce_images.py |
| **详情04** | detail_04_story3.png | 3:4 | 1728×2304 | generate_ecommerce_images.py |
| **详情05** | detail_05_feature1.png | 3:4 | 1728×2304 | generate_ecommerce_images.py |
| **详情06** | detail_06_feature2.png | 3:4 | 1728×2304 | generate_ecommerce_images.py |
| **详情07** | detail_07_feature3.png | 3:4 | 1728×2304 | generate_ecommerce_images.py |
| **详情08** | detail_08_texture1.png | 3:4 | 1728×2304 | generate_ecommerce_images.py |
| **详情09** | detail_09_texture2.png | 3:4 | 1728×2304 | generate_ecommerce_images.py |
| **详情10** | detail_10_trust.png | 3:4 | 1728×2304 | generate_ecommerce_images.py |

**关键说明**：
- ✅ **所有15张图**都用 `generate_ecommerce_images.py` 生成
- ✅ **主图和详情页**只是比例不同，生成方式完全相同
- ✅ **统一入口**：都通过 `generate_all()` 方法批量生成
- ✅ **统一模式**：都使用图生图（`generate_image2image`，scale=0.2）
- ❌ **严禁分开处理**：不要单独写脚本生成主图或详情页

### 严禁的行为

❌ **禁止直接用jimeng-image生成场景图**
- 错误：`jimeng_image.generate_image2image()` 直接生成15张图
- 后果：绕过业务流程，无法统一管理，容易触发API限流

❌ **禁止修改generate_ecommerce_images.py来生成白底图**
- 错误：修改程序添加extract_material功能
- 后果：程序职责混乱，维护困难

✅ **正确的做法**
- 白底图 → 直接用 `jimeng-image.extract_material()`
- 场景图 → 用 `generate_ecommerce_images.py`（它内部调用jimeng-image）

### 技术参数（固定不变）

| 参数 | 主图 | 详情页 | 说明 |
|------|------|--------|------|
| 尺寸 | 2048×2048 | 1728×2304 | 严禁修改 |
| 比例 | 1:1 | 3:4 | 严禁修改 |
| scale | 0.2 | 0.2 | 必须图生图 |
| 生成方式 | 串行 | 串行 | 间隔10秒 |

### 依赖关系

```python
# generate_ecommerce_images.py 内部实现
from jimeng_image import JimengImageGenerator

class EcommerceDesigner:
    def __init__(self):
        self.generator = JimengImageGenerator()  # 依赖jimeng-image
    
    def generate_image(self, image_plan):
        # 统一使用图生图模式
        result = self.generator.generate_image2image(
            prompt=image_plan['prompt'],
            reference_image_path=self.reference_image_path,  # 白底图
            scale=0.2,  # 确保产品一致性
            width=width,
            height=height
        )
```

---

## ⚠️ 常见错误与解决方案（重要）

### 错误1：混淆程序职责

**错误做法**：
```python
# ❌ 错误：用jimeng-image直接生成场景图
from jimeng_image import JimengImageGenerator
generator = JimengImageGenerator()

# 错误！绕过generate_ecommerce_images.py
for i in range(15):
    generator.generate_image2image(...)  # 直接生成
```

**后果**：
- 无串行控制，容易触发API限流
- 无错误处理，失败无法恢复
- 无元数据记录，无法追踪进度

**正确做法**：
```python
# ✅ 正确：用generate_ecommerce_images.py统一管理
from generate_ecommerce_images import EcommerceDesigner
designer = EcommerceDesigner()
designer.generate_all(image_plans)  # 统一生成15张
```

---

### 错误2：修改generate_ecommerce_images.py生成白底图

**错误做法**：
```python
# ❌ 错误：在generate_ecommerce_images.py中添加extract_material
class EcommerceDesigner:
    def extract_white_background(self):  # 不要添加！
        ...
```

**后果**：
- 程序职责混乱
- 维护困难
- 违反单一职责原则

**正确做法**：
```python
# ✅ 正确：白底图用jimeng-image独立生成
from jimeng_image import JimengImageGenerator
generator = JimengImageGenerator()
generator.extract_material(...)  # 独立步骤
```

---

### 错误3：间隔时间太短

**错误做法**：
```python
# ❌ 错误：间隔2秒
time.sleep(2)
```

**后果**：
- 触发API并发限制
- 任务失败，需要重试

**正确做法**：
```python
# ✅ 正确：间隔10秒（SKILL.md规定）
time.sleep(10)
```

---

### 错误4：不使用图生图模式

**错误做法**：
```python
# ❌ 错误：文生图，无参考图
result = generator.generate_image(prompt=...)  # 无参考图
```

**后果**：
- 产品造型不一致
- 每张图产品都不一样

**正确做法**：
```python
# ✅ 正确：图生图，使用白底图作为参考
result = generator.generate_image2image(
    prompt=...,
    reference_image_path='reference_white.png',  # 必须有参考图
    scale=0.2  # 确保一致性
)
```

---

### 错误5：跳过第一、二阶段直接生图

**错误做法**：
- 不生成产品信息分析报告
- 不生成提示词工程文档
- 直接开始生图

**后果**：
- 提示词质量差
- 返工率高
- Token浪费

**正确做法**：
严格按照三阶段流程：
1. 第一阶段：产品信息分析 → 发送用户确认
2. 第二阶段：提示词工程 → 发送用户确认
3. 第三阶段：生图工程 → 按流程执行

---

## 核心能力

- 将产品图逆向解构为视觉策略
- 正向输出为高点击、高转化的成套视觉方案
- 为淘宝/京东等电商平台打造兼具国际质感与本土消费心理的详情页视觉

## 工作流程（V3.0 - 三阶段分离式）

### 流程概览

```
┌─────────────────────────────────────────────────────────────────┐
│                    第一阶段：图片接收与分析                        │
│                    （AI自动识别 + 用户确认）                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    第二阶段：提示词生成工程                        │
│              （零Token消耗，纯规划阶段，用户确认后锁定）            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    第三阶段：生图工程（优化Token）                  │
│              （按V2.0 Token优化方案执行，一次性完成）               │
└─────────────────────────────────────────────────────────────────┘
```

---

### 第一阶段：图片接收与分析

**目标**：通过AI分析用户提供的图片，自动生成产品信息报告，减少用户填写负担。

**输入**：用户发送1-10张产品图片

**处理流程**：

#### 1.1 图片接收
- 接收用户发送的产品图片（1-10张）
- 检查图片质量（分辨率≥1000×1000，产品清晰可见）

#### 1.2 AI智能分析（自动完成）
Agent自动分析每张图片，提取以下信息：

| 分析维度 | 提取内容 | 示例 |
|---------|---------|------|
| **产品类型** | 识别产品类别 | 玻璃煮茶壶+电陶炉套装 |
| **核心功能** | 识别功能按键、显示屏内容 | 8种模式/1500W/数显控温 |
| **材质质感** | 识别主要材质 | 高硼硅玻璃/木质纹理/金属按键 |
| **核心细节** | 记录关键设计元素 | 侧把/8按键/LED屏/透明壶盖 |
| **角度分类** | 自动分类拍摄角度 | 正面/45度/侧面/俯视/细节 |

#### 1.3 生成【产品信息分析报告】（V2.0框架）

基于V2.0产品信息分析框架生成标准化报告：

```markdown
# 产品信息分析报告 - V2.0

## 一、产品基础信息
| 维度 | 内容 |
|------|------|
| 产品类型 | [一级分类 - 二级分类] |
| 品牌名称 | [品牌名] |
| 用途 | [核心用途1/核心用途2/核心用途3] |
| 尺寸 | [长×宽×高 mm] |
| 重量 | [重量] |
| 材质 | [主体材质/表面处理/内部材质] |
| 结构 | [正面/顶部/侧面/背面特征] |

## 二、目标人群分析
| 维度 | 描述 |
|------|------|
| 年龄段 | [如：25-40岁] |
| 职业特征 | [如：都市白领、精致妈妈] |
| 认知阶段 | [搜索关键词] |
| 考虑阶段 | [对比关注点] |
| 购买阶段 | [决策因素] |
| 典型场景 | [场景1/场景2/场景3/场景4] |

## 三、核心功能卖点（3-5个）
| 序号 | 卖点 | 功能描述 | 用户利益 |
|-----|------|---------|---------|
| 1 | [卖点1] | [技术描述] | [用户获得] |
| 2 | [卖点2] | [技术描述] | [用户获得] |
| 3 | [卖点3] | [技术描述] | [用户获得] |

## 四、品牌调性信息
| 维度 | 描述 |
|------|------|
| 品牌定位 | [如：实用简约、科技前沿] |
| 主色调 | [颜色+质感，如：浅杏色哑光] |
| 辅助色 | [辅助色1/辅助色2/点缀色] |
| 情感元素 | [如：温暖、轻松、治愈] |

## 五、生图策略规划
### 白底图策略
- 最佳角度：[推荐角度]
- 必须展示：[关键特征]

### 15张图规划
| 序号 | 文件名 | 场景类型 | 核心目标 |
|-----|--------|---------|---------|
| 1 | main_01_studio.png | studio | 展示整体造型 |
| 2 | main_02_detail.png | detail | 突出[核心细节] |
| ... | ... | ... | ... |

### 文案策略
- 主标题方向：[关键词]
- 副标题方向：[关键词]
- 卖点条：[关键词1·关键词2·关键词3]

## 六、待确认项
- [ ] 产品类型正确
- [ ] 核心功能完整
- [ ] 目标人群合适
- [ ] 品牌调性准确
- [ ] 补充信息：________

## 七、分析结论
**产品核心定位**：[一句话总结]
**视觉策略方向**：[一句话总结]
```

#### 1.4 用户确认
- 发送《产品信息分析报告》给用户
- 用户确认或修改信息
- **确认后进入第二阶段**

---

### 第二阶段：提示词生成工程（强制检查）

⚠️ **重要：本阶段必须完成以下检查清单，用户确认后才能进入第三阶段**

#### 2.0 第二阶段检查清单

**必须创建的4个文档**：
1. ✅ `config.json` - 15张图片配置（含完整文案）
2. ✅ `提示词参考手册.md` - 提示词工程文档
3. ✅ `详情页内容框架.md` - 文案规划文档
4. ✅ `15_prompts_list.md` - 15张图片完整提示词

**必须执行的步骤**：
1. 创建4个文档
2. 运行检查命令：`python tools/ecommerce/check_phase2.py output/ecommerce/项目名`
3. **发送所有文档内容给用户确认**
4. **等待用户明确回复"确认"或"开始生成"**
5. 用户确认后，锁定配置，进入第三阶段

**禁止行为**：
- ❌ 未发送文档给用户确认就进入第三阶段
- ❌ 用户未明确确认就擅自开始生图
- ❌ 跳过检查清单

**目标**：零Token消耗完成所有提示词规划，用户确认后再生图，避免返工。

**原则**：先规划，后执行；确认后锁定，不再修改。

#### 2.1 步骤A：生成【提示词参考手册】

基于确认的产品信息，按V4.0提示词框架生成标准化手册：

```markdown
# 提示词参考手册

## 第一层：核心定位（按行业自动生成）

### 1.1 角色设定（我是谁）
**小家电行业**：你是一名国内一线小家电品牌的AI电商视觉设计师，同时具备商业摄影导演、信息图设计师与中文广告文案策划的多重专业能力...
**美妆护肤行业**：你是一名国际一线美妆品牌的AI电商视觉总监...
**母婴用品行业**：你是一名国内顶尖母婴品牌的AI电商视觉专家...
**户外运动/EDC行业**：你是一名专业户外装备品牌的AI电商视觉总监...
**食品饮料行业**：你是一名国内头部食品品牌的AI电商视觉总监...

### 1.2 总体视觉策略（我要做什么）
**小家电**：「温暖治愈的智能厨房伙伴」...
**美妆护肤**：「精致高级的美肌秘密」...
**母婴用品**：「安心守护的成长伙伴」...
**户外运动/EDC**：「硬核专业的探险装备」...
**食品饮料**：「新鲜诱人的美味体验」...

---

## 第二层：基础规范（所有行业通用）

### 2.1 产品主体
严格保持[产品名]造型不变，比例结构100%一致，质感真实还原。

### 2.2 硬性规范（5条铁律）
1. 造型结构：保留原始比例，严禁修改造型
2. 光影融合：投影符合主光源，边缘清晰无伪影
3. 质感还原：真实还原材质，还原度≥95%
4. 视觉风格：写实商业摄影
5. 构图要求：产品为绝对视觉中心

### 2.3 合规约束
高清4K，无绝对化用语，不遮挡品牌，无侵权。

---

## 第三层：场景分配（15张图固定结构）

### 3.1 主图5张（1:1，无文案）
1. studio - 纯白背景，展示整体造型
2. detail - 细节特写
3. scene - 场景展示
4. feature - 卖点展示
5. lifestyle - 生活方式

### 3.2 详情页10张（3:4，有文案）
6. poster - 品牌海报
7-9. story1-3 - 3个故事场景
10-12. feature1-3 - 3个卖点展示
13-14. texture1-2 - 2个材质细节
15. trust - 信任背书

---

## 第四层：文案规范（详情页10张）

### 4.1 文案3要素
- 主标题：7-9字
- 副标题：10-14字
- 卖点条：2-4条，3-8字/条

### 4.2 文案排版要求
| 元素 | 位置 | 字体风格 | 排版方式 |
|------|------|---------|---------|
| 主标题 | 画面上方 | 粗体醒目 | 单行居中，最大字号 |
| 副标题 | 主标题下方 | 常规细体 | 单行或折行 |
| 卖点条 | 画面底部 | 中等粗细 | 横向排列，用"·"分隔 |

**排版原则**：
- 文字不遮挡产品主体
- 文字与背景有足够对比度
- 文字区域留出安全边距（距边缘≥100像素）
- 整体排版平衡

### 4.3 文案风格（按行业）
- 小家电：简洁有力，温暖品质
- 美妆护肤：精致种草，自信美丽
- 母婴用品：安全可信，温馨守护
- 户外运动：硬核专业，探险可靠
- 食品饮料：食欲诱惑，新鲜健康

---

## 第五层：技术参数（固定不变）

| 参数 | 主图 | 详情页 |
|------|------|--------|
| 尺寸 | 2048×2048 | 1728×2304 |
| 比例 | 1:1 | 3:4 |
| 文案 | 无 | 有 |
| scale | 0.2 | 0.2 |
| 生成方式 | 串行，间隔10秒 | 串行，间隔10秒 |

---

## 单张提示词组装公式

### 主图 = 第一层 + 第二层 + 第三层 + 第五层
```
[角色设定]
[总体视觉策略]
[硬性规范5条]
【场景】[具体场景]
【光线】[具体布光]
【输出】2048×2048，无文字
```

### 详情页 = 第一层 + 第二层 + 第三层 + 第四层 + 第五层
```
[角色设定]
[总体视觉策略]
[硬性规范5条]
【场景】[具体场景]
【光线】[具体布光]
【文案】[主标题]，[副标题]，[卖点条]
【排版】[排版要求]
【输出】1728×2304
```
```

## 场景变量（15张图差异化）

### 主图部分（5张，1:1，无文案）
| 序号 | 文件名 | 场景描述 | 光影构图 |
|-----|--------|---------|---------|
| 1 | main_01_studio.png | 纯白studio背景，产品居中45度 | 顶光+左侧45度柔光 |
| 2 | main_02_detail.png | 功能特写，操控面板 | 顶光直射，屏幕发光 |
| ... | ... | ... | ... |

### 详情页部分（10张，3:4，有文案）
| 序号 | 文件名 | 场景描述 | 文案规划 |
|-----|--------|---------|---------|
| 6 | detail_01_poster.png | 新中式茶室全景 | 主标题/副标题/卖点条 |
| ... | ... | ... | ... |
```

#### 2.2 步骤B：生成【详情页展示内容框架】

基于产品信息，规划10张详情页的文案内容：

```markdown
# 详情页展示内容框架

## 故事线设计
1. **海报图**：全景展示，奠定基调
2. **故事1**：煮茶过程，可视化体验
3. **故事2**：多茶类冲泡，专业性
4. **故事3**：家庭温馨，情感共鸣
5. **卖点1**：8种模式，智能化
6. **卖点2**：1500W大功率，效率
7. **卖点3**：高硼硅玻璃，安全性
8. **材质1**：玻璃工艺，晶莹剔透
9. **材质2**：木纹底座，复古美学
10. **信任**：品质保障，售后无忧

## 文案规范
每张图包含：
- 主标题（7-9字）：核心利益点
- 副标题（10-14字）：价值解释
- 卖点条（2-4条，3-8字/条）：售后承诺

## 具体文案（10张）
| 序号 | 主标题 | 副标题 | 卖点条 |
|-----|--------|--------|--------|
| 6 | 茶室里的颜值担当 | 8种模式智能煮茶，一壶搞定所有茶类 | 7天无理由/赠茶叶罐/3期免息 |
| ... | ... | ... | ... |
```

#### 2.3 步骤C：生成15张完整生图提示词

**5张主图提示词（1:1，无文案）**：
```
提示词1（main_01_studio.png）：
[基础模板] + 【场景】纯白studio背景，产品居中45度角展示... + 【输出】2048x2048，无文字

提示词2（main_02_detail.png）：
[基础模板] + 【场景】俯拍操控面板，8按键+LED屏特写... + 【输出】2048x2048，无文字
...
```

**10张详情页提示词（3:4，有文案）**：
```
提示词6（detail_01_poster.png）：
[基础模板] + 【场景】新中式茶室全景... + 【文案】主标题/副标题/卖点 + 【输出】1536x2048

提示词7（detail_02_story1.png）：
[基础模板] + 【场景】茶汤翻滚，蒸汽袅袅... + 【文案】主标题/副标题/卖点 + 【输出】1536x2048
...
```

#### 2.4 步骤D：用户确认提示词工程

**确认清单**：
- [ ] 《提示词参考手册.md》确认
- [ ] 《详情页内容框架.md》确认
- [ ] 《15张生图提示词清单.md》确认

**用户操作**：
1. 查看三个文档（通过飞书发送）
2. 确认或提出修改意见
3. **确认后锁定，进入第三阶段**

**重要**：提示词工程确认后，不再修改，直接进入生图阶段。

**实际输出文件**：
```
output/ecommerce/{产品名}/
├── 提示词参考手册.md          # 基础模板+场景变量
├── 详情页内容框架.md          # 故事线+文案规范
├── 15张生图提示词清单.md       # 完整15张提示词
└── reference_white_background.png  # 白底图
```

---

### 第三阶段：生图工程（优化Token）

**目标**：按V2.0 Token优化方案，一次性完成15张图生成。

**原则**：基础模板只加载一次，批量生成，精简输出。

**⚠️ 关键：程序调用顺序（严禁颠倒）**

```
第三阶段
    │
    ├── 步骤1：生成白底图
    │       程序：jimeng-image（独立调用）
    │       方法：extract_material()
    │       说明：这是独立步骤，不通过generate_ecommerce_images.py
    │
    └── 步骤2：生成15张场景图
            程序：generate_ecommerce_images.py（统一入口）
            方法：generate_all() → 内部调用 jimeng-image.generate_image2image()
            说明：必须使用此程序，严禁直接调用jimeng-image
```

#### 3.1 步骤1：生成产品白底图（使用jimeng-image）

**⚠️ 注意**：此步骤**直接调用jimeng-image**，不通过generate_ecommerce_images.py

**选择最佳角度**：
- 从用户提供的1-10张图片中选择角度最佳、细节最清晰的一张

**生成白底图代码**：
```python
# 正确：直接调用jimeng-image
import sys, os
sys.path.insert(0, os.environ["JIMENG_SKILL_DIR"])
from jimeng_image import JimengImageGenerator

generator = JimengImageGenerator(output_dir=output_path)
result = generator.extract_material(
    image_path="用户上传的产品图.jpg",
    prompt="提取出图片中的日用品，生成一张正视图，背景为纯白色。"
)

# 输出：reference_white_front.png
```

**用户确认**：
- 展示白底图效果
- 确认产品造型、比例、细节无误
- **确认后进入步骤2**

#### 3.2 步骤2：批量生成15张场景图（使用generate_ecommerce_images.py）

**⚠️ 注意**：此步骤**必须使用generate_ecommerce_images.py**，严禁直接调用jimeng-image

**重要原则**：
- ✅ **统一入口**：使用 `generate_ecommerce_images.py` 的 `generate_all()`
- ✅ **串行生成**：一张完成→再生成下一张
- ❌ **严禁并行**：同时提交多个任务会触发API限流
- ❌ **严禁绕过**：不要直接调用 `jimeng-image.generate_image2image()`

**正确调用代码**：
```python
# 正确：使用generate_ecommerce_images.py作为统一入口
import sys, os
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))  # 本技能 scripts 目录
from generate_ecommerce_images import EcommerceDesigner

designer = EcommerceDesigner()

# 设置产品信息
designer.set_product_info({...})

# 设置白底图（步骤1生成的）
designer.set_reference_image('reference_white_front.png')

# 读取图片计划（第二阶段生成的image_plans.json）
with open('image_plans.json', 'r', encoding='utf-8') as f:
    image_plans = json.load(f)

# 统一生成15张图（内部调用jimeng-image，串行，间隔10秒）
results = designer.generate_all(image_plans)
```

**内部实现（generate_ecommerce_images.py自动处理）**：
```python
# 这是generate_ecommerce_images.py内部的实现，你不需要手动调用
class EcommerceDesigner:
    def generate_image(self, image_plan):
        # 自动使用图生图模式
        result = self.generator.generate_image2image(
            prompt=image_plan['prompt'],
            reference_image_path=self.reference_image_path,  # 白底图
            scale=0.2,  # 确保产品一致性
            width=width,
            height=height
        )
        
        # 自动间隔10秒
        if i < total:
            time.sleep(10)
```

**为什么必须用generate_ecommerce_images.py？**
| 功能 | 直接调jimeng-image | 用generate_ecommerce_images.py |
|------|-------------------|------------------------------|
| 串行控制 | ❌ 需自己实现 | ✅ 内置 |
| 间隔控制 | ❌ 需自己实现 | ✅ 内置10秒 |
| 错误处理 | ❌ 需自己实现 | ✅ 内置 |
| 元数据保存 | ❌ 需自己实现 | ✅ 自动保存 |
| 进度管理 | ❌ 需自己实现 | ✅ 自动管理 |
| API限流防护 | ❌ 容易触发 | ✅ 内置防护 |
    # 串行关键：间隔3秒再生成下一张
    if idx < 15:
        time.sleep(3)
        print(f'等待3秒，准备生成下一张...')

print('[*] 全部15张图片完成！')
```

**串行 vs 并行对比**：
| 方式 | 描述 | 结果 |
|------|------|------|
| ✅ 串行 | 一张完成→发送→再下一张 | 正常，不触发限流 |
| ❌ 并行 | 同时提交多个任务 | 触发API限流，任务失败 |

**Token消耗预估**：
- 预加载：~150 tokens
- 15张图：15 × ~400 = ~6,000 tokens
- **总计：~6,150 tokens**（原~30,000，节省80%）

#### 3.3 步骤3：完成交付

**交付内容**：
```
output/ecommerce/{产品名}/
├── main_01_studio.png        # 主图1
├── main_02_detail.png        # 主图2
├── main_03_home.png          # 主图3
├── main_04_office.png        # 主图4
├── main_05_gift.png          # 主图5
├── detail_01_poster.png      # 详情1
├── detail_02_story1.png      # 详情2
├── detail_03_story2.png      # 详情3
├── detail_04_story3.png      # 详情4
├── detail_05_feature1.png    # 详情5
├── detail_06_feature2.png    # 详情6
├── detail_07_feature3.png    # 详情7
├── detail_08_texture1.png    # 详情8
├── detail_09_texture2.png    # 详情9
├── detail_10_trust.png       # 详情10
├── reference_white.png       # 白底图基准
├── 提示词参考手册.md          # 第二阶段产出
├── 详情页内容框架.md          # 第二阶段产出
├── 15张生图提示词清单.md       # 第二阶段产出
└── metadata.json             # 元数据
```

**完成反馈**：
```
[*] 15张电商图片全部完成！
    主图：5张（1:1）
    详情页：10张（3:4）
    Token消耗：~6,150（节省80%）
    输出目录：output/ecommerce/{产品名}/
    
提示词工程文档：
- 提示词参考手册.md
- 详情页内容框架.md  
- 15张生图提示词清单.md
```

---

## 流程对比（V2.0 vs V3.0）

| 维度 | V2.0 | V3.0 | 改进 |
|------|------|------|------|
| **阶段划分** | 4步连续 | 3阶段分离 | 提示词工程独立 |
| **Token消耗** | ~30,000 | ~6,150 | 节省80% |
| **返工风险** | 高（生图后修改） | 低（提示词阶段确认） | 零返工 |
| **用户确认点** | 白底图+每张图 | 产品信息+提示词工程+白底图 | 减少确认次数 |
| **透明度** | 中等 | 高（完整提示词预览） | 用户可控 |
| **总耗时** | ~60分钟 | ~45分钟 | 效率提升25% |

---

## 版本记录

- **V1.0**：基础电商美工大师流程
- **V2.0**：新增Token优化方案，节省80%消耗
- **V3.0**：三阶段分离式流程，提示词工程前置，零返工风险
└── angle_mapping.json            # 角度映射配置文件
```

**技术要求**：
- 使用即梦AI官方素材提取接口，确保边缘清晰无瑕疵
- 纯白色背景（RGB: 255,255,255），无杂质或渐变
- 产品主体不变形、不拉伸，保持原始比例和角度
- 材质质感真实还原，角度准确对应原始图片

**多图处理策略**：
- **多角度生成**：为每个可用清晰角度生成对应的白底图
- **角度分类**：自动识别图片角度并分类（正面/45度/侧面/俯视等）
- **质量控制**：确保每个角度的白底图都能准确代表该视角下的产品特征
- **场景适配**：不同角度的白底图将适配不同类型的电商图片

### 第一步：收集产品信息

引导用户填写【产品智能分析模板】：

**产品基础**
- 产品类型：[例如：空气炸锅/破壁机/电吹风]
- 核心功能：[例如：360°热风循环/低音破壁/负离子护发]
- 目标人群：[例如：精致宝妈/独居青年/银发一族]
- 使用场景：[例如：家庭厨房/卧室梳妆台/办公室桌面]

**品牌调性**
- 品牌定位：[例如：实用简约 / 时尚潮流 / 科技前沿]
- 品牌色彩：[根据产品外观推断]
- 情感联想：[例如：温暖、专业、省心、幸福感]

**技术规格**
- 材质质感：[例如：食品级玻璃（高透）、ABS机身（哑光）]
- 核心细节：[按钮形状、logo位置、散热孔排列等]

### 第二步：生成15张图片计划

根据产品分析和可用的白底图角度，生成15张图片的详细计划（包含参考图角度适配）：

**主图部分（5张，1:1比例）**
| 序号 | 图片类型 | 推荐参考图角度 | 场景适配说明 |
|------|---------|---------------|------------|
| 1 | 纯色背景/场景图 | 正面图或45度角图 | 展示产品整体造型，适合极简studio背景 |
| 2 | 功能特写图 | 侧面图或俯视图 | 突出核心部件和操作界面，适合微距摄影 |
| 3 | 场景氛围图1 | 45度角图 | 立体展示产品与场景融合，适合办公场景 |
| 4 | 场景氛围图2 | 正面图 | 正面视角展示产品使用状态，适合家庭场景 |
| 5 | 场景氛围图3 | 侧面图 | 展示产品侧面轮廓，适合户外/运动场景 |

**详情页部分（10张，3:4比例）**
| 序号 | 图片类型 | 推荐参考图角度 | 文案区域 | 场景适配说明 |
|------|---------|---------------|---------|------------|
| 1 | 全景海报 | 正面图 | 主标题+副标题+卖点条 | 产品全貌展示，留白区域用于主文案 |
| 2 | 场景故事-晨间 | 45度角图 | 情境标题+功能说明 | 早餐/晨间使用场景，温馨光线 |
| 3 | 场景故事-午间 | 正面图 | 情境标题+便捷性说明 | 办公室/午休使用场景，自然光 |
| 4 | 场景故事-晚间 | 侧面图 | 情境标题+安静/舒适说明 | 家庭/晚间使用场景，温暖灯光 |
| 5 | 核心卖点-便携性 | 侧面图/俯视图 | 卖点标题+具体参数 | 突出产品小巧便携特性 |
| 6 | 核心卖点-功能性 | 正面图/45度角图 | 卖点标题+技术说明 | 展示核心功能和工作状态 |
| 7 | 核心卖点-安全性 | 细节特写图 | 卖点标题+材质说明 | 微距展示安全材质和认证 |
| 8 | 细节材质-主要材质 | 细节特写图 | 材质名称+特性说明 | 微距摄影突出主要材质质感 |
| 9 | 细节材质-辅助材质 | 细节特写图 | 材质名称+特性说明 | 微距摄影突出辅助材质细节 |
| 10 | 信任背书 | 正面图+侧面图 | 参数表格+认证标识 | 专业检测场景，展示技术参数 |

**角度适配原则**：
- **正面图**：整体造型展示，适合全景、主场景、正面使用场景
- **45度角图**：立体感最强，适合场景融合、生活化展示
- **侧面图**：展示产品厚度、侧边设计、便携性
- **俯视图**：展示顶部操作界面、按钮布局、显示屏
- **细节特写图**：微距展示材质、纹理、logo、接口细节

**灵活调整**：根据实际可用的白底图角度，Agent可灵活调整推荐角度，确保每张图片使用最合适的参考图。

### 第三步：逐个生成图片（带参考图，确保产品一致性）

**⚠️ 严格约束**：
- 最多2个并发任务
- 必须逐个生成：一张完成→预览→再下一张
- 严禁一次性提交所有任务
- **必须使用参考图上传功能**，纯文生图无法保证产品一致性

**生成参数（关键：使用image_urls上传参考图）**：

### 提示词框架（专业电商版 - 多角度适配）

#### 1. 主图提示词框架（1:1比例 - 多角度适配）
```python
{
    "req_key": "jimeng_t2i_v40",
    "image_urls": ["reference_white_front.png的URL"],  # 根据图片类型选择合适角度的参考图
    "prompt": """
【参考指令】参考这张[角度，如：正面/45度/侧面]图，严格保持产品造型、比例、材质细节不变
【产品定位】[产品类型，如：便携式榨汁杯/空气炸锅/无线耳机]
【场景设定】[具体场景，如：现代办公桌面/健身房瑜伽垫旁/户外野餐布]
【光线构图】[光线描述，如：自然光从左侧45度入射，柔和漫反射]/[构图，如：产品居中，黄金分割构图]
【风格质感】写实商业摄影风格，专业级布光，低饱和暖色调，[产品材质，如：哑光/亮面/金属/玻璃]质感真实还原
【技术规范】高清4K画质，无文字，无品牌侵权元素，产品为绝对视觉中心
【角度适配】使用[角度]图作为参考，确保产品[角度描述，如：正面造型/立体轮廓/侧面厚度]准确呈现
【行业适配】根据产品类型调整：[小家电：突出实用性与生活场景]/[数码产品：突出科技感与便携性]/[服装鞋包：突出材质与搭配]
""",
    "scale": 0.2,
    "width": 2048,
    "height": 2048,
    "force_single": True
}
```

#### 2. 详情页提示词框架（3:4比例 - 多角度适配，含文案）
```python
{
    "req_key": "jimeng_t2i_v40",
    "image_urls": ["reference_white_front.png的URL"],  # 根据图片类型选择合适角度的参考图
    "prompt": """
【参考指令】参考这张[角度，如：正面/45度/侧面]图，严格保持产品造型、比例、材质细节不变
【产品定位】[产品类型，如：便携式榨汁杯/空气炸锅/无线耳机]
【场景故事】[具体使用场景，如：早餐桌榨橙汁/办公室下午茶/健身房后补充能量]
【光线构图】[光线描述，如：清晨阳光透过窗户]/[构图，如：产品位于视觉焦点，留白区域用于文案]
【风格质感】写实商业摄影风格，专业级布光，低饱和暖色调，[产品材质]质感真实还原
【文案区域】左上角：[主标题，7-9字]/下方：[副标题，10-14字]/底部：[卖点引导，2-4条，每条3-8字]
【角度适配】使用[角度]图作为参考，突出展示产品的[角度特点，如：正面整体造型/侧面便携性/顶部操作界面]
【技术规范】高清4K画质，产品与场景自然融合，投影符合光源逻辑，无悬浮感
【行业适配】根据产品类型调整场景与文案风格
""",
    "scale": 0.2,
    "width": 1536,
    "height": 2048,
    "force_single": True
}
```

### 角度选择指导

**参考图角度与场景适配表**：
| 图片类型 | 推荐角度 | 角度特点 | 适用场景 | 提示词中的角度描述 |
|---------|---------|---------|---------|------------------|
| 全景/主场景 | 正面图 | 展示产品整体造型，对称美观 | 主图、全景海报、首页展示 | "正面图，展示产品整体造型" |
| 场景氛围 | 45度角图 | 立体感强，适合环境融合 | 使用场景图、生活化展示 | "45度角图，立体展示产品与环境融合" |
| 功能特写 | 侧面图/俯视图 | 展示厚度/顶部操作界面 | 功能展示、操作演示 | "侧面图，展示产品厚度与便携性" |
| 细节材质 | 细节特写图 | 微距展示材质纹理 | 材质特写、logo展示 | "细节特写图，微距展示材质纹理" |
| 信任背书 | 正面图+侧面图 | 多角度展示专业感 | 参数展示、检测场景 | "正面与侧面结合，全面展示产品" |

**角度选择原则**：
1. **一致性原则**：同一系列图片尽量使用相同或相似角度，保持视觉统一
2. **适配性原则**：根据图片目的选择最合适的角度（全景用正面，功能用侧面）
3. **多样性原则**：15张图片中合理分配不同角度，避免单一视角单调
4. **可用性原则**：根据实际生成的白底图角度灵活调整，优先使用可用角度

### 行业特定提示词要点

| 行业 | 产品定位关键词 | 典型场景 | 光线特点 | 质感重点 | 文案风格 |
|------|---------------|---------|---------|---------|---------|
| **小家电** | 实用便捷、生活助手、健康守护 | 家庭厨房、办公桌面、户外休闲 | 自然光、温暖家居光 | 哑光/亮面塑料、不锈钢、玻璃 | 实用功能、生活品质、健康理念 |
| **数码产品** | 科技感、便携高效、智能连接 | 现代办公、咖啡馆、旅行场景 | 冷色调科技光、柔光 | 金属质感、哑光涂层、镜面屏幕 | 科技参数、使用场景、便捷体验 |
| **服装鞋包** | 时尚搭配、舒适质感、个性表达 | 街头时尚、休闲聚会、专业场合 | 自然光、柔光箱、影棚光 | 面料纹理、皮革质感、金属配件 | 材质说明、搭配建议、时尚元素 |
| **美妆护肤** | 自然美肌、专业护理、安全温和 | 梳妆台、浴室、专业护肤空间 | 柔和自然光、洁净白光 | 液体质感、膏体细腻、包装光泽 | 成分功效、使用感受、安全认证 |
| **家居用品** | 温馨舒适、实用设计、品质生活 | 客厅、卧室、阳台、花园 | 温暖家居光、自然采光 | 织物柔软、木质纹理、陶瓷光滑 | 生活场景、使用体验、品质保证 |
| **食品饮料** | 新鲜美味、健康营养、便捷享用 | 餐桌、厨房、野餐、聚会 | 自然食欲光、温暖色调 | 食物光泽、液体透明、包装质感 | 食材来源、口感描述、健康益处 |

### 提示词生成指导（多角度优化版）

**必填要素**：
1. **参考指令**：必须包含角度信息，如"参考这张正面图"、"参考这张侧面图"，确保产品一致性
2. **角度适配**：明确说明使用该角度的目的，如"使用正面图展示整体造型"、"使用侧面图突出便携性"
3. **产品定位**：明确产品类型和核心定位
4. **场景设定**：具体、真实、符合产品使用场景
5. **光线构图**：专业摄影术语，符合商业标准
6. **风格质感**：写实商业摄影，材质真实还原

**角度选择策略**：
- **全景展示**：使用正面图或45度角图，展示产品整体造型
- **功能特写**：使用侧面图或俯视图，突出特定功能部件
- **场景融合**：使用45度角图，增强产品与环境的立体融合感
- **细节材质**：使用细节特写图，微距展示材质纹理
- **多角度组合**：信任背书类图片可使用多张参考图，全面展示产品

**选填要素**（根据图片类型）：
- **主图**：无文案，纯视觉吸引，注重角度与场景的匹配
- **详情页**：包含文案区域规划，角度选择需考虑文案布局
- **功能特写**：微距摄影，突出细节，选择最能展示功能的角度
- **场景故事**：生活化，有情感共鸣，角度选择增强场景真实感

**避坑指南**：
- ❌ 避免绝对化用语（"第一"、"最"、"100%"）
- ❌ 避免侵权元素（他人肖像、品牌logo）
- ❌ 避免模糊描述（"好看"、"漂亮"→具体描述）
- ❌ 避免角度与场景不匹配（如用俯视图展示全景场景）
- ✅ 使用专业摄影术语（"侧逆光"、"黄金分割"、"柔光箱"）
- ✅ 明确产品材质（"哑光ABS塑料"、"304不锈钢"、"Tritan透明杯身"）
- ✅ 场景真实可感（"清晨阳光透过百叶窗"、"傍晚温馨家居光"）
- ✅ 角度描述具体（"使用45度角图，立体展示产品与环境融合"）

**scale参数详解（产品一致性关键）**：
| scale值 | 参考图影响 | 产品一致性 | 适用场景 |
|---------|-----------|-----------|---------|
| **0.1-0.3** | 高 | ⭐⭐⭐⭐⭐ | **电商图片（强烈推荐）** |
| 0.4-0.6 | 中 | ⭐⭐⭐ | 一般场景 |
| 0.7-1.0 | 低 | ⭐⭐ | 创意探索（不推荐） |

**为什么必须用参考图？**
- ❌ 纯文生图：产品造型、比例、细节每次生成都不同，无法保持一致性
- ✅ 参考图模式：产品严格遵循上传的白底图，场景按提示词生成，完美融合

**查询参数**：
```python
req_json_config = {
    "return_url": True,  # 必须设置以获取图片URL
    "logo_info": {"add_logo": False}
}

query_params = {
    "req_key": "jimeng_t2i_v40",
    "task_id": task_id,
    "req_json": json.dumps(req_json_config, ensure_ascii=False)
}
```

### 第四步：下载并发送到飞书

每张图片生成后：
1. 下载图片到本地
2. 使用本地文件路径发送到飞书（支持预览）
3. 等待用户确认
4. 继续下一张

```python
# 下载图片
local_path = f"output/ecommerce/{product_name}/{filename}.png"
response = requests.get(image_url)
with open(local_path, 'wb') as f:
    f.write(response.content)

# 发送到飞书
message(action="send", media=local_path, caption="图片说明")
```

## 硬性技术规范

### 产品一致性（最高优先级）

**基准图要求**：所有生成图片必须严格遵循已确认的产品白底图（reference_white_background.png）中的产品造型、比例和细节。

- **造型结构**：严格保留产品原始比例、外观细节（按钮、logo、接口），与基准图保持100%一致
- **光影融合**：产品投影必须符合场景主光源逻辑，边缘清晰、无伪影，杜绝悬浮感或生硬粘贴感
- **质感还原**：真实还原产品材质（哑光/亮面/金属/玻璃），纹理还原度≥95%
- **一致性检查**：每张生成图片必须与基准图进行视觉比对，确保产品造型无任何变形、拉伸或细节丢失

### 视觉与合规

- **视觉风格**：写实商业摄影质感，低饱和暖色调，可融入<5%国风元素
- **布光逻辑**：专业级商业布光，光影自然，轮廓清晰
- **构图要求**：产品为绝对视觉中心，中心对称或黄金分割构图
- **合规红线**：
  - 不得出现"第一"、"最"、"100%"等绝对化用语
  - 不得生成侵权人物肖像或场景
  - 不得遮挡、修改产品原有品牌标识

## 文案排版规范

### 详情页文案结构

| 元素 | 位置 | 字数 | 示例 |
|------|------|------|------|
| 主标题 | 左上角 | 7-9字 | "厨房里的颜值担当" |
| 副标题 | 主标题下方 | 10-14字 | "一机多用，小白秒变大厨" |
| 卖点/引导 | 底部居中 | 2-4条，每条3-8字 | "7天无理由 \| 赠食谱 \| 3期免息" |

### 主图要求

- 图片上**不出现任何文字文案**
- 纯粹依靠场景、光影和产品本身吸引点击

## 输出文件结构

```
output/ecommerce/{产品名}/
├── main_01_studio.png      # 主图1：纯色背景
├── main_02_detail.png      # 主图2：功能特写
├── main_03_scene1.png      # 主图3：场景氛围1
├── main_04_scene2.png      # 主图4：场景氛围2
├── main_05_scene3.png      # 主图5：场景氛围3
├── detail_01_poster.png    # 详情1：全景海报
├── detail_02_story1.png    # 详情2：场景故事1
├── detail_03_story2.png    # 详情3：场景故事2
├── detail_04_story3.png    # 详情4：场景故事3
├── detail_05_feature1.png  # 详情5：核心卖点1
├── detail_06_feature2.png  # 详情6：核心卖点2
├── detail_07_feature3.png  # 详情7：核心卖点3
├── detail_08_texture1.png  # 详情8：细节材质1
├── detail_09_texture2.png  # 详情9：细节材质2
├── detail_10_trust.png     # 详情10：信任背书
└── metadata.json           # 所有图片的元数据
```

## 参考文档

详细框架说明请参考：[references/ecommerce-visual-framework.md](references/ecommerce-visual-framework.md)

## 飞书机器人错误处理规范（重要）

### 问题背景
在飞书机器人环境中执行Python脚本时，容易出现以下问题：
1. **编码错误**：中文字符在命令行参数中传递时出现乱码或语法错误
2. **字符串转义问题**：引号、换行符等特殊字符导致Python语法错误
3. **输出截断**：长输出被截断，无法获取完整信息

### 解决方案

#### 1. 严禁使用命令行直接传递Python代码

**❌ 错误做法**（容易导致编码和转义问题）：
```python
# 错误：直接在命令行传递Python代码
exec(command="python -c \"...中文内容...\"")
```

**✅ 正确做法**（写入文件后执行）：
```python
# 正确：先写入Python文件，再执行
write(path="gen_image.py", content="...")
exec(command="python gen_image.py")
```

#### 2. 文件编码规范

所有Python脚本文件必须：
- 使用UTF-8编码
- 包含中文编码声明：`# -*- coding: utf-8 -*-`
- 避免在字符串中使用复杂的引号嵌套

```python
# gen_image.py
#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import sys, os
sys.path.insert(0, os.environ["WORKSPACE_DIR"])
from tools.jimeng import JimengClient

# 业务逻辑代码...
```

#### 3. 错误捕获与反馈

所有脚本必须包含完善的错误处理：

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-

try:
    # 业务逻辑
    result = generate_image()
    print(f"SUCCESS:{result}")
except Exception as e:
    print(f"ERROR:{str(e)}")
    import traceback
    traceback.print_exc()
    sys.exit(1)
```

#### 4. 消息发送规范

生成图片后，必须通过`message`工具发送预览图：

```python
# 生成完成后，使用message工具发送
# 不要在Python脚本中直接发送，而是返回路径给Agent

# Python脚本输出格式：
print(f"IMAGE_PATH:{filepath}")
print(f"STATUS:success")
```

Agent端处理：
```python
# 读取脚本输出
result = exec(command="python gen_image.py")

# 解析输出
if "IMAGE_PATH:" in result:
    filepath = result.split("IMAGE_PATH:")[1].split("\n")[0]
    
    # 使用message工具发送到飞书
    message(
        action="send",
        media=filepath,
        caption="图片生成完成！"
    )
```

#### 5. 完整示例代码

```python
# generate_and_send.py
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
生成单张图片并通过message方式发送预览图
"""

import sys
import os
import base64
import requests

sys.path.insert(0, os.environ["WORKSPACE_DIR"])
from tools.jimeng import JimengClient

def main():
    try:
        client = JimengClient()
        OUTPUT_DIR = os.path.join(os.environ["WORKSPACE_DIR"], "output", "ecommerce", "my_product")
        
        # 读取白底图
        white_bg_path = os.path.join(OUTPUT_DIR, 'reference_white.png')
        with open(white_bg_path, 'rb') as f:
            white_bg_base64 = base64.b64encode(f.read()).decode('utf-8')
        
        # 生成参数
        params = {
            'req_key': 'jimeng_t2i_v40',
            'binary_data_base64': [white_bg_base64],
            'prompt': '提示词内容...',
            'scale': 0.2,
            'width': 2048,
            'height': 2048,
            'image_num': 1
        }
        
        # 提交任务
        result = client.service.cv_sync2async_submit_task(params)
        
        if result.get('code') == 10000:
            task_id = result.get('data', {}).get('task_id')
            
            # 等待完成
            image_urls = client._wait_for_task(task_id, 'jimeng_t2i_v40')
            
            if image_urls:
                # 下载图片
                filepath = os.path.join(OUTPUT_DIR, 'main_01_studio.png')
                response = requests.get(image_urls[0], timeout=30)
                
                if response.status_code == 200:
                    with open(filepath, 'wb') as f:
                        f.write(response.content)
                    
                    # 输出成功信息（供Agent解析）
                    print(f"STATUS:success")
                    print(f"IMAGE_PATH:{filepath}")
                    print(f"IMAGE_URL:{image_urls[0]}")
                    return 0
                else:
                    print(f"STATUS:download_failed")
                    return 1
            else:
                print(f"STATUS:generate_failed")
                return 1
        else:
            print(f"STATUS:submit_failed")
            print(f"ERROR:{result.get('message', 'unknown')}")
            return 1
            
    except Exception as e:
        print(f"STATUS:error")
        print(f"ERROR:{str(e)}")
        import traceback
        traceback.print_exc()
        return 1

if __name__ == "__main__":
    sys.exit(main())
```

#### 6. Agent端调用规范

```python
# 1. 写入Python脚本
write(
    path="output/ecommerce/{product}/gen_single.py",
    content=script_content
)

# 2. 执行脚本（使用timeout避免挂起）
result = exec(
    command="python gen_single.py",
    timeout=300  # 5分钟超时
)

# 3. 解析结果
if "STATUS:success" in result:
    # 提取图片路径
    filepath = result.split("IMAGE_PATH:")[1].split("\n")[0].strip()
    
    # 4. 发送到飞书
    message(
        action="send",
        media=filepath,
        caption="[1/15] 主图01生成完成！"
    )
    
    # 5. 等待3秒后继续下一张
    time.sleep(3)
    
else:
    # 错误处理
    error_msg = result.split("ERROR:")[1].split("\n")[0] if "ERROR:" in result else "未知错误"
    message(
        action="send",
        message=f"图片生成失败: {error_msg}"
    )
```

---

## 技术实现

### 白底图生成方法（即梦AI素材提取接口）

**使用即梦AI官方素材提取接口**：
```python
submit_params = {
    "req_key": "jimeng_i2i_extract_tiled_images",
    "binary_data_base64": [image_base64],  # 或 "image_urls": [url]，支持最多10张图片输入
    "edit_prompt": "提取出图片中的日用品，生成一张正视图，背景为纯白色。",
    "width": 2048,
    "height": 2048
}
```

**API能力说明**：
- **多图输入**：支持`binary_data_base64`数组或`image_urls`数组，最多10张图片
- **单图处理**：即使输入多张图片，接口通常针对每张图片单独处理，生成对应的白底图
- **最佳选择**：Agent将从用户提供的1-10张图片中选择角度最佳、细节最清晰的一张进行处理

**支持6大品类提取**：
| 品类 | 提取指令 |
|------|---------|
| 服装 | "提取出图片中的衣服、帽子、鞋子和包，生成一张平铺图，背景为纯白色。" |
| 鞋子 | "提取出图片中的一双鞋子，生成一张正45度图，背景为纯白色。" |
| 包包 | "提取出图片中的完整的包包和包带，正视图，背景为纯白色。" |
| 沙发 | "提取出图片中的完整的沙发，生成一张正视图，背景为纯白色。" |
| **日用品** | **"提取出图片中的日用品，生成一张正视图，背景为纯白色。"** |
| 饰品 | "提取出图片中的饰品，生成一张正视图，背景为纯白色。" |

**技术指标**：
- 接口：即梦AI素材提取（`jimeng_i2i_extract_tiled_images`）
- 输入限制：最多10张图片
- 输出分辨率：2048×2048像素（可配置）
- 背景：纯白色（#FFFFFF）
- 处理时间：通常在30秒内完成

### 产品一致性保证机制（即梦4.0参考图功能）

**核心原理**：使用即梦4.0的`image_urls`参数上传参考图（最多10张），配合`scale`参数控制一致性

```python
# 生成场景图时上传参考图
submit_params = {
    "req_key": "jimeng_t2i_v40",
    "image_urls": ["白底图URL"],  # 关键：上传参考图，最多可上传10张URL
    "prompt": "参考这张图，把这个产品放在现代办公桌上...",
    "scale": 0.2,  # 关键：低scale确保参考图影响大，产品一致性高
    "width": 2048,
    "height": 2048
}
```

**API能力说明**：
- `image_urls`: 支持传入最多10张参考图URL的数组，模型会综合参考所有上传图片的造型、比例、细节
- **当前电商流程推荐**：上传一张高质量白底产品图作为主要造型参考
- **扩展应用**：对于复杂产品或需要多角度展示时，可上传多张不同角度的产品图

**为什么这样能保证一致性？**
- `image_urls`: 传入参考图，模型会参考产品造型、比例、细节
- `scale=0.2`: 表示参考图影响占80%，提示词影响占20%
- 结果：产品严格遵循参考图，场景按提示词生成

**对比实验**：
| 方式 | 产品一致性 | 原因 |
|------|-----------|------|
| 纯文生图（无参考图） | ❌ 差 | 每次生成产品造型都不同 |
| 文生图 + 提示词强调 | ❌ 较差 | 模型无法精确理解产品细节 |
| **图生图 + scale=0.2** | ✅ **优秀** | **参考图主导产品造型** |

## 使用示例

**用户**：帮我生成一套空气炸锅的电商图片

**Agent**：
1. **生成产品白底图**：请提供空气炸锅的照片（任意背景），我将处理为纯白色背景的基准图
2. **填写产品分析模板**：引导用户填写产品基础信息、品牌调性、技术规格
3. **生成15张图片计划**：根据产品分析制定详细的主图与详情页计划
4. **逐个生成并发送到飞书预览**：每张图片生成后发送确认，严格遵循处理后的产品白底图确保一致性
5. **完成全部15张图片**

## 提示词应用示例

### 示例1：小家电（空气炸锅 - 主图）
**提示词**：
```
【参考指令】参考这张图，严格保持产品造型、比例、材质细节不变
【产品定位】家用空气炸锅，健康烹饪助手
【场景设定】现代家庭厨房台面，旁边有新鲜蔬菜篮和调味瓶
【光线构图】自然光从厨房窗户照入，侧光突出产品轮廓，产品居中构图
【风格质感】写实商业摄影风格，专业级布光，低饱和暖色调，哑光塑料与不锈钢质感真实还原
【技术规范】高清4K画质，无文字，无品牌侵权元素，产品为绝对视觉中心
【行业适配】小家电：突出实用性与生活场景，展现家庭烹饪便利性
```

### 示例2：数码产品（无线耳机 - 详情页）
**提示词**：
```
【参考指令】参考这张图，严格保持产品造型、比例、材质细节不变
【产品定位】降噪无线耳机，移动办公伴侣
【场景故事】咖啡馆工作场景，旁边有笔记本电脑和咖啡杯
【光线构图】柔和的咖啡馆灯光，产品位于画面右侧黄金分割点，左侧留白用于文案
【风格质感】写实商业摄影风格，专业级布光，冷色调科技感，金属与哑光塑料质感真实还原
【文案区域】左上角：静享专注时刻/下方：主动降噪，沉浸工作/底部：蓝牙5.3 | 30小时续航 | 快充15分钟
【技术规范】高清4K画质，产品与场景自然融合，投影符合光源逻辑
【行业适配】数码产品：突出科技感与便携性，展现移动办公场景
```

### 示例3：服装（运动T恤 - 主图）
**提示词**：
```
【参考指令】参考这张图，严格保持服装版型、面料纹理、细节设计不变
【产品定位】速干运动T恤，健身训练装备
【场景设定】健身房力量训练区，背景有哑铃和健身器械
【光线构图】健身房专业照明，产品平铺展示，微俯视角构图
【风格质感】写实商业摄影风格，专业影棚布光，突出面料速干纹理，缝线细节清晰
【技术规范】高清4K画质，面料纹理真实，无模特肖像权问题
【行业适配】服装：突出面料质感与功能设计，展现运动场景适用性
```

### 示例4：美妆（精华液 - 详情页）
**提示词**：
```
【参考指令】参考这张图，严格保持产品瓶型、logo、材质细节不变
【产品定位】修复精华液，夜间护肤必备
【场景故事】梳妆台护肤时刻，旁边有其他护肤品和化妆镜
【光线构图】柔和的梳妆台灯光，产品位于画面中心，光线在玻璃瓶身上的反射效果
【风格质感】写实商业摄影风格，洁净白光，玻璃瓶身晶莹剔透，液体质感真实
【文案区域】左上角：夜间修护奇迹/下方：深度滋养，唤醒肌肤活力/底部：敏感肌可用 | 无添加 | 临床测试
【技术规范】高清4K画质，玻璃材质反光真实，液体透明度清晰
【行业适配】美妆：突出产品纯净安全，展现专业护肤效果
```

### 提示词生成工作流
1. **分析产品类型**：确定所属行业（小家电/数码/服装/美妆等）
2. **选择行业模板**：参考行业特定要点表
3. **填写框架要素**：按【参考指令】→【产品定位】→【场景设定】顺序填写
4. **调整细节**：根据具体图片类型（主图/详情页/特写）调整要素
5. **质量检查**：确保无绝对化用语、无侵权元素、描述具体专业

## 注意事项

- 每次只处理一个产品的15张图片
- 必须严格串行生成，不可并发
- 每张图片生成后必须发送到飞书确认
- 如用户需要修改，根据反馈调整提示词后重新生成
- **⚠️ 产品一致性强制要求**：
  - 第零步必须使用即梦AI素材提取接口生成白底图
  - 后续所有图片必须使用`image_urls`参数上传参考图
  - **scale值必须设置为0.2-0.3**，确保参考图影响占主导
  - **严禁使用纯文生图**（无参考图），无法保证产品一致性
- **参考图使用规范**：
  - 用户可以上传1-10张产品图片作为参考图
  - Agent将选择最佳角度的一张图片，使用素材提取接口生成高质量白底图
  - 生成场景图时上传白底图URL到`image_urls`参数（最多支持10张参考图，通常使用一张高质量白底图）

---

## Token消耗优化方案（V2.0）

### 问题分析

**传统方式Token消耗**：
| 组成部分 | 单张消耗 | 15张总计 | 问题 |
|---------|---------|---------|------|
| 基础模板重复 | ~800 | ~12,000 | 每张都发送完整产品描述 |
| 场景变量 | ~200 | ~3,000 | 必要消耗 |
| 响应输出冗余 | ~500 | ~7,500 | 完整JSON+状态循环输出 |
| 重复初始化 | ~500 | ~7,500 | 每张图都重新初始化客户端 |
| **总计** | **~2,000** | **~30,000** | |

### 优化方案

#### 1. 基础模板只发送一次（节省93%）

**优化前（浪费）**：
```python
# 每张图都包含完整基础模板
prompt = f"""
【系统前缀】作为国内一线小家电品牌资深AI视觉总监...
【产品主体】严格保持产品造型不变：高硼硅玻璃壶身...
【硬性规范】造型结构：严格保留产品原始比例...
【场景执行】{scene_variable}
【合规约束】高清4K画质...
"""
# 每张 ~1,000 tokens
```

**优化后（节省）**：
```python
# 第1张：发送完整基础模板
# 第2-15张：只发送"参考第1张规范" + 场景变量

prompt = f"""
参考第1张图的提示词规范（系统前缀+产品主体+硬性规范+合规约束），
保持相同的产品一致性要求和视觉标准。

【场景执行】{scene_variable}
"""
# 每张 ~200 tokens（仅场景变量）
```

**节省**：12,000 - 1,400 = **10,600 tokens（88%）**

#### 2. 精简基础模板（节省60%）

**优化前**：
```
【系统前缀】作为国内一线小家电品牌资深AI视觉总监，
精通商业摄影美学与杂志感信息图表设计，
擅长为淘宝/京东等电商平台打造兼具国际质感与本土消费心理的
高点击、高转化视觉方案。
```

**优化后**：
```
资深AI视觉总监，精通商业摄影美学，为淘宝/京东打造高转化视觉方案。
```

#### 3. 批量生成脚本（节省63%初始化）

**优化前**：
```python
# 每张图都重新执行脚本
for i in range(15):
    # 每次重新导入、初始化、读取文件
    exec(f"python gen_{i}.py")  # ~500 tokens/次
```

**优化后**：
```python
# 一个脚本生成所有图
import ...  # 只导入1次
client = ...  # 只初始化1次
white_bg = ...  # 只读取1次

for i in range(15):
    generate_image(scene[i])  # 仅场景变量变化
```

#### 4. 精简响应输出（节省99%）

**优化前**：
```
[1/40] in_queue...
[2/40] in_queue...
[3/40] in_queue...
...（约20次输出）
```

**优化后**：
```
[5/15] filename.png ... 12s OK
```

### 优化效果对比

| 指标 | 优化前 | 优化后 | 节省 |
|------|--------|--------|------|
| 单张消耗 | ~2,000 tokens | ~400 tokens | **80%** |
| 15张总计 | ~30,000 tokens | ~6,000 tokens | **80%** |
| 生成时间 | ~60分钟 | ~35分钟 | **42%** |
| 响应速度 | 慢（长提示词） | 快（短提示词） | **显著改善** |

### 实施步骤

#### Step 1: 创建基础模板文件
```python
# prompt_base_template.txt
BASE_PROMPT = """资深AI视觉总监，精通商业摄影美学，为淘宝/京东打造高转化视觉方案。

严格保持[产品名]造型：[材质描述]，比例结构100%一致，[质感要求]。

写实商业摄影，低饱和暖色调，温馨氛围。专业布光，产品为视觉中心。
高清4K，无绝对化用语。"""
```

#### Step 2: 创建批量生成脚本
```python
# generate_batch_optimized.py
import ...  # 一次性导入
client = ...  # 一次性初始化
white_bg = ...  # 一次性读取

SCENES = [
    ('main_01.png', '纯白背景...', 2048, 2048),
    ('main_02.png', '功能特写...', 2048, 2048),
    # ... 15个场景
]

for idx, (filename, scene, w, h) in enumerate(SCENES, 1):
    # 优化：只拼接场景变量
    prompt = f"{BASE_PROMPT}\n\n【场景】{scene}"
    
    # 生成图片
    result = generate_image(prompt, white_bg, w, h)
    
    # 精简输出
    print(f'[{idx}/15] {filename} ... {result.status}')
    
    # 发送到飞书
    send_to_feishu(result.path)
    
    # 间隔3秒
    time.sleep(3)
```

#### Step 3: 执行优化流程
```
1. 生成白底图（1张，~2,500 tokens）
2. 加载基础模板（1次，~150 tokens）
3. 批量生成15张（每张~400 tokens，总计~6,000 tokens）
4. 总计消耗：~8,650 tokens（原~30,000，节省71%）
```

### 关键要点

**✅ 必须遵守**：
- 基础模板只定义一次，后续引用
- 批量脚本一次性初始化所有资源
- 精简输出，只显示关键状态
- 每张生成后间隔3秒，避免并发限制

**❌ 严禁**：
- 每张图都重新初始化客户端
- 重复发送完整基础模板
- 输出冗余调试信息
- 批量提交多个任务（违反API限制）

### 反馈机制

**优化后反馈频率**：
- 每5张图汇总反馈一次进度
- 异常情况立即反馈
- 完成时汇总统计

**示例输出**：
```
[*] 开始生成15张详情页（优化模式）
    基础模板已加载，单张仅~400 tokens

[1-5/15] 主图部分完成 ✓
    main_01_studio.png OK
    main_02_detail.png OK
    main_03_home.png OK
    main_04_office.png OK
    main_05_gift.png OK

[6-10/15] 详情页部分完成 ✓
    detail_01_poster.png OK
    ...

[*] 全部完成！总计消耗：~8,650 tokens（节省71%）
```

---

**版本记录**：
- V1.0：基础电商美工大师流程
- V2.0：新增Token优化方案，节省80%消耗
  - 提示词使用"参考这张图，把这个产品..."格式
  - 保持scale值稳定（0.2-0.3），不要随意调整
- **V3.1：豆包（Doubao）积分适配**。新增 `scripts/doubao_ecommerce_driver.py`：豆包环境无即梦 key 时，生图全程改用豆包 `image_edit` 工具逐张生成（白底图 1 张 + 15 张场景图，扣豆包积分），不再调用即梦 API。`jimeng-image` / `generate_ecommerce_images.py` 保留原样。适配要点：参考图走 URL（uploads 标注待上传）、保真由 prompt 措辞控制（等同 scale=0.2）、详情页【文案】自动转中文引号文字指令、image_edit 保持参考图比例时按 resample_to 用 PIL 处理到目标尺寸。
- **⚠️ API并发限制（关键）**：
  - **最多2个并发任务**：即梦API有严格的并发限制，同时运行的任务不能超过2个
  - **避免批量并发**：严禁一次性提交多个生成任务，必须串行处理
  - **控制调用频率**：每张图片之间建议间隔3-5秒，避免触发QPS限制
  - **串行处理策略**：一张图片生成完成→下载确认→再提交下一张任务

---

## API响应格式变更说明（重要 - 2026-03-19更新）

### 问题背景
即梦AI API的响应格式发生了变化，导致原有图片获取逻辑失效。

### 变更对比
| 方式 | 字段 | 说明 | 状态 |
|------|------|------|------|
| **旧方式** | `image_urls` | 返回图片URL，需HTTP下载 | ⚠️ 可能返回null |
| **新方式** | `binary_data_base64` | 直接返回base64编码的图片数据 | ✅ 推荐使用 |

### 代码变更示例

```python
# 修改前（旧方式 - 可能失效）
result = client.service.cv_sync2async_get_result({
    'req_key': 'jimeng_t2i_v40',
    'task_id': task_id
})
data = result.get('data', {})
if data.get('status') == 'done':
    urls = data.get('image_urls', [])  # ❌ 可能返回 None
    if urls:
        response = requests.get(urls[0])
        image_data = response.content

# 修改后（新方式 - 推荐）
import base64

result = client.service.cv_sync2async_get_result({
    'req_key': 'jimeng_t2i_v40',
    'task_id': task_id
})
data = result.get('data', {})
if data.get('status') == 'done':
    # ✅ 优先从 binary_data_base64 获取
    binary_data_list = data.get('binary_data_base64', [])
    if binary_data_list:
        image_data = base64.b64decode(binary_data_list[0])
        with open(filepath, 'wb') as f:
            f.write(image_data)
```

### 关键变更点
1. **数据源**：`image_urls` → `binary_data_base64`
2. **获取方式**：HTTP下载 → base64解码
3. **新增依赖**：`import base64`

### 兼容性处理建议
```python
# 同时支持新旧两种格式
def get_image_data(data):
    """从API响应中提取图片数据"""
    # 优先检查新格式
    binary_data_list = data.get('binary_data_base64', [])
    if binary_data_list:
        import base64
        return base64.b64decode(binary_data_list[0]), 'binary'
    
    # 兼容旧格式
    urls = data.get('image_urls', [])
    if urls:
        import requests
        response = requests.get(urls[0], timeout=30)
        return response.content, 'url'
    
    return None, None
```

### 已更新文件
- `tools/jimeng/client.py` - 新增 `_wait_for_task_v2()` 方法支持新格式
- `skills/ecommerce-designer-master/SKILL.md` - 本文档
- `skills/ecommerce-designer-master/references/prompt-reference-manual-v3.1.md` - 优化版提示词手册