# V2 图片处理方案

> 状态：方案设计（**图片方案 B 已拍板** 2026-08-15；套图落地节奏待定）
> 上游：[V2 总览](./README.md) · [V2 架构](./architecture.md)
> 相关：V1 [`docs/studio/image-edit.md`](../studio/image-edit.md) · `ecommerce-image-suite/` 源码与 `SKILL.md`

---

## 1. 先厘清：这是「两种不同的能力」，不是二选一的替代品

用户提出的两个方案，本质是把两种**不同粒度**的图片能力放在一起比了：

| | 现有 studio「AI 生图」 | ecommerce-image-suite「电商套图」 |
|---|---|---|
| 模型 | 万相 `wanx2.1-imageedit`（+ qwen-image-edit 系列） | `wan2.7-image-pro` / 豆包 `doubao-seedream` / GPT-image 等 |
| 形态 | **单图编辑**：换背景/去水印/局部重绘/加文字/风格化 | **套图生成**：原图 → 8~9 张营销图 |
| 输入 | 一张底图 + 一句指令 | 商品原图（1~3 张）+ 卖点文案 |
| 输出 | 1 张改好的图 | 白底主图/核心卖点图/卖点图/材质图/场景图/模特图/多场景拼图/详情图/三角度 |
| 适用 | 「修一张图」：白底、去水印、补字 | 「产出一整套」：营销素材、详情页 |
| 成本 | 单次编辑（百炼按张计） | 一套 8~9 张 × 单张价 + 1 次视觉分析 |

**结论先行**：这两个是**互补**的，不是谁替代谁。所以不存在真正的「方案一 vs 方案二」，而是「只保留一个」还是「两个都要」。

---

## 2. 对 Ozon 跟卖场景，真正刚需是什么

跟卖（从竞品页采集 → 自己上品）的图片痛点很具体：

1. **白底主图**：Ozon 主图要求纯白底、无文字、无水印。竞品图往往带背景/水印/营销字。
2. **去水印/去字**：采集来的图常带竞品水印。
3. **补充营销图**：主图之外，详情页要卖点图、场景图、模特图（服饰类）。

| 痛点 | 最合适的工具 | 成本 |
|---|---|---|
| 白底 / 去水印 / 去字 / 换背景 | **`wanx2.1-imageedit`（单图编辑）** | 单张，便宜，可控 |
| 整套营销图 / 模特图 / 场景图 / 详情图 | **ecommerce-image-suite（套图）** | 一套多张，按需 |

**单图编辑是高频刚需**（几乎每个商品都要做白底），**套图是选配**（服饰/需要营销图的类目才用，且部分类目 Ozon 主图够用）。

---

## 3. 方案对比

### 方案 A：只集成 ecommerce-image-suite，去掉 wanx2.1-imageedit

- ✅ 简单：图片能力一个入口，前端一套 UI。
- ❌ **贵且不划算**：白底/去水印这种单图需求，也要走整套生成（8~9 张），大量浪费。
- ❌ **产出不完全对口**：套图里只有「白底主图」一张符合 Ozon 主图规范；卖点图/场景图**带营销文字**，不能当 Ozon 主图（Ozon 主图禁文字水印），只能进详情/补充。
- ❌ 丢掉了「改一张图」的精细控制（局部重绘、加字、改背景强度），这些 wanx2.1-imageedit 已经做好且便宜。

### 方案 B：套图 + 保留 wanx2.1-imageedit（改名「智能修图」），高低搭配 ✅ **已选（2026-08-15）**

- 高频单图需求（白底/去水印/换背景/加字）→ **智能修图**（wanx2.1-imageedit，已有代码，复用改名）。
- 低频整套需求（卖点图/场景图/模特图/详情图）→ **电商套图**（ecommerce-image-suite）。
- ✅ 两者共用 `DASHSCOPE_API_KEY`，无额外对接成本。
- ✅ 现有 `server/api/image.py` + `services/image_edit.py` + studio `AiImagePage` 整套**原样保留**，只是改个名字和菜单。
- ✅ 成本可控：默认用便宜的修图，需要时再整套。

**成本佐证**（来自 ecommerce-image-suite `references/providers.md`）：

| 供应商/模型 | 单价 | 参考图 | 国内直连 |
|---|---|---|---|
| 千问 `wan2.7-image-pro` | ¥0.14/张 | ✅ | ✅ |
| 豆包 `doubao-seedream-4-5` | ¥0.12/张 | ✅ | ✅ |
| Gemini 3.1-flash-image | $0.03/张 | ✅ | 需代理 |
| GPT-image-1.5 | $0.04~0.2/张 | ✅ | 需代理 |
| Stability core | $0.03/张 | ❌ | 需代理 |

一套 8 张 ≈ ¥0.96~1.12（国内直连），加一次视觉分析（qwen-vl-max）。单图编辑是「按需 1 张」，成本远低于整套。

> **纠正一个直觉**：套图「贵」不在单张价，而在「一次要生成一整套」。单张价其实比很多平台便宜。所以「方案 B 更贵」不成立——方案 B 反而因为默认走单图编辑而更省。

---

## 4. 命名与入口（方案 B 落定后的 UI）

studio 编辑页「图片」面板里，每张图/每个插槽提供两类操作：

| 菜单 | 能力 | 底层 |
|---|---|---|
| **智能修图** | 白底、去水印、换背景、局部重绘、加文字、风格化 | `wanx2.1-imageedit`（`/api/image/edit`） |
| **电商套图** | 从商品原图生成整套营销图（可勾选图型） | ecommerce-image-suite（`/api/image/suite`） |

现有的「AI 图生图」独立页保留，改名「智能修图」，作为单图精修工作台；「电商套图」作为编辑页图片面板里的一个按钮/抽屉。

---

## 5. 电商套图的集成方式（ecommerce-image-suite 是「脚本+Skill」，不是服务）

`ecommerce-image-suite` 目前是给 Agent/人用的 **脚本 + Skill** 形态（`analyze.py` + `generate.py`，Apache-2.0），不是现成 API。要集成进 studio，有三档：

| 档 | 做法 | 代价 | 建议 |
|---|---|---|---|
| L1 快速 | 服务端 subprocess 调 `analyze.py`/`generate.py` | 依赖 Python 环境、脚本路径、退出码解析；无并发控制 | 验证期可用 |
| L2 正式 ✅ | 把 `generate.py` 的 **prompt 引擎 + 供应商调用**抽成 `services/image_suite.py`（纯 Python 模块，直接在 FastAPI 里调 DashScope/豆包） | 移植 prompt 模板与参数（图型 9 种、6 套视觉模板、平台规范），约 1~2 天 | **推荐** |
| L3 独立服务 | 套图做成独立微服务，HTTP 调用 | 重，单人项目不值 | 不建议 |

**L2 的关键取舍**：ecommerce-image-suite 里有大量「Agent 交互」逻辑（模特选择、模板推荐、场景推荐、确认步骤），这些在 studio 里**不该照搬**。V2 只取它的**生成引擎**（图型 Prompt 模板 + 供应商 API 调用），把交互简化成 studio 表单：

- 输入：选 1~3 张商品原图（素材库已有）+ 卖点文案（可自动从 `products.raw`/`copy` 取，可手改）+ 勾选图型（白底主图/卖点图/场景图/…）+ 目标语言（俄文）。
- 输出：生成结果逐张进素材库（`product_assets`，group_key 标 `generated`），用户挑图再进 `products.images`。
- 视觉分析（analyze 那步）：一期跳过（直接让用户填卖点），二期可调 qwen-vl-max 自动提炼卖点。

> 注意：ecommerce-image-suite 的图型 Prompt 模板当前是为**国内平台/Amazon**写的（中文/英文文案、平台字体规范）。Ozon 是俄文市场，**俄文文案渲染需要新增一套俄文 Prompt 约束**（或先出英文/无文字图，俄文文案靠前端叠加，见 §7）。这是集成里唯一需要新做的实质工作。

### 5.1 已知坑（源码级核对，服务端集成必须处理）

| 坑 | 说明 | 对策 |
|---|---|---|
| `generate.py` 全局禁用 SSL 校验 | 脚本为方便本地跑图关闭了 TLS 验证 | 服务端集成（L1/L2）**必须移除**，恢复正常 TLS，否则是安全漏洞 |
| 退出码恒 0，单张失败不中断 | 成败不反映在退出码上 | 以 `generate_result.json` 为**唯一真源**逐张判成败；失败图重试或标记 |
| 文档与代码不一致 | Gemini 端点、豆包/视频模型版本、README 称"无 LICENSE"但实为 Apache-2.0 等 | 以 `generate.py` 实际调用为准，逐供应商核对后再落地 |
| 输出固定中文文件名 | `白底主图.jpg` 等中文命名 | 转存七牛时改用英文/序号命名，避免 Ozon 与跨平台文件名问题 |

### 5.2 用 SKILL.md 当 studio 向导蓝图（可选）

`SKILL.md` 里那段「上传原图 → 分析卖点 → 选平台/图型/模板/模特 → 生成 → 确认」的对话流，本身是经过打磨的**交互蓝图**。做 studio「电商套图」抽屉时可直接参照它，把多步向导固化成表单步骤（原图选择 → 卖点确认 → 图型勾选 → 模板/模特 → 生成），省去重新设计交互的成本。

---

## 6. 七牛存储（贯穿所有图片路径）

| 来源 | 处理 |
|---|---|
| 采集源图 | 插件传 URL → 服务端下载（带 Referer）→ 转存七牛 → `product_assets.qiniu_url` |
| 智能修图结果 | DashScope 返回 URL（24h）→ 服务端下载 → 转存七牛 → 返回七牛 URL |
| 套图结果 | 同上 |
| 前端水印合成 | studio canvas 合成 → 上传七牛（服务端中转或直传 token） |

**为什么必须转存**：Ozon `images` 只收公网可访问 URL（Ozon 服务器主动拉取）；阿里云结果 URL 24h 失效且无 CORS；源站 URL 可能防盗链/失效。七牛是稳定公网源。

一期建议**服务端中转上传**（改动小、无前端直传的 token 复杂度）；量大后再切前端直传 + 上传 token。

---

## 7. 推荐落地顺序（务实版）

1. **一期只做「智能修图」**（已有代码）：白底/去水印/换背景。这是最高频、最省、复用度最高的部分。`/api/image/edit` 加七牛转存即可。
2. **二期集成「电商套图」**：按 §5 L2 抽 `services/image_suite.py`，先支持 `white_bg / key_features / selling_pt / material / lifestyle / model / multi_scene` 几个高频图型，俄文文案先出英文/无字版本。
3. **三期**：俄文文案渲染（新增俄文 Prompt 约束或前端叠字）、视觉分析自动提炼卖点、模特库接入（45 位内置模特）。

---

## 8. 决策记录

- ✅ **图片方案：已选 B（高低搭配）**（2026-08-15）：集成 ecommerce-image-suite「电商套图」+ 保留 wanx2.1-imageedit（改名「智能修图」）。
- ⏳ 待定：**电商套图一期就做，还是先只交付「智能修图」跑通闭环、套图二期再加**（见 [`migration.md`](./migration.md) §7）。