---
id: T-647
title: 商品套图AI帮写改为同商品多图联合分析
phase: 7
deps: [T-645]
status: DONE
created: 2026-07-17
---

## 问题 / 背景

⑥「商品套图」的「AI帮写」已通过 `vision_alias` 将当前商品项目中可用的本地原图按 `source_order` 取前8张，一次提交给 cmhub 图片理解接口。当前固定提示词虽然要求从图片提炼卖点，但没有明确“这些图片属于同一个商品 ID 的多角度/细节/展示图”，部分模型会按输入顺序返回“1、……；2、……；3、……”的逐图描述。

逐图清单不适合直接写入「商品卖点与要求」：后续白底图、场景图和卖点图需要的是一份统一、可编辑、可复用的商品事实与套图画面要求，而非每张原图的独立说明。用户需要模型把多张同商品原图作为同一证据集联合理解，输出一份套图分析结果。

## 方案

### 1. 固定提示词改为多图联合分析契约

修改 `app/ai.py` 中商品套图图片理解提示词的组装逻辑（当前 `_compose_product_suite_vision_prompt()`）：

- 明确说明本次传入的图片均属于当前同一商品 ID，可能包含主视图、多角度、细节、包装、场景或不同展示图；模型必须综合全部图片后作出一份统一判断；
- 明确禁止输出“图1/图2/第N张”或按图片编号逐条罗列的理解结果，也不要逐图复述；
- 保持当前“只采信图片可见事实、已有要求只作补充约束、不得编造材质/尺寸/功能/认证/价格/物流”等安全事实边界；
- 当图片确有可见的颜色、款式、配件、包装或规格差异时，输出为“可见差异或待确认项”，不能把冲突信息强行合并为一个确定事实；不能凭图片顺序猜测主款、附赠品或变体关系；
- 输出必须是可直接回填到「商品卖点与要求」的中文纯文本，使用稳定分段结构：

  ```text
  商品概述：
  可确认卖点：
  适用人群与场景：
  套图画面要求：
  待确认或避免编造的信息：
  ```

- 输出语言继续服从当前任务设置；不要求 JSON、Markdown 表格、图片编号、接口字段或模型解释过程，避免给现有可编辑文本框引入解析/迁移需求。

### 2. 保持现有提交范围与调用边界

- 继续只读取当前 `SuiteTaskState` 对应商品项目的可用本地原图，按 `source_order` 顺序取前8张；商品原图勾选状态仍不参与本任务，超过8张继续给出既有中文提示；
- 继续使用一次 `POST /api/v1/analyze/images` 请求中的 `images` 数组发送这些图片，不拆成逐图请求、不增加并发、不改变 `vision_alias`、超时、点数或重试语义；
- 当前「商品卖点与要求」已有内容继续以“补充约束”进入上下文，模型返回文本仍复用既有用户编辑冲突确认和自动保存逻辑；
- 不把完整提示词、图片路径、base64、接口 URL、Key 或上游原始响应显示给用户或持久化到 SQLite。

### 3. 测试与文档

- `tests/test_ai.py`：断言多图图片理解请求仍是一条请求、`images` 保持有序，并且发送的 `prompt` 包含同商品联合分析、禁止逐图编号、统一输出分段、可见差异和避免编造的契约；
- `tests/test_product_suite_gui.py`：覆盖当前商品项目取前8张的顺序与提示不回归，并确认原图勾选状态不改变 AI帮写的输入图片集合；
- 同步更新 `docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`，明确多图 AI帮写输出的是商品级联合分析，而不是逐图识别结果；
- 运行：

  ```bash
  py -3.10 -m unittest tests.test_ai tests.test_product_suite_gui tests.test_workers
  py -3.10 -m unittest discover -s tests
  py -3.10 -m ruff check app tests main.py
  py -3.10 -m compileall app main.py
  git diff --check
  ```

## 验收要点

- [ ] 当前商品项目的多张原图仍以一次图片理解请求提交，数量、大小、顺序和 `vision_alias` 规则不变。
- [ ] 图片理解提示词明确这些图属于同一个商品的多角度/细节/展示证据集，要求综合分析。
- [ ] 返回文本不应要求或鼓励“图1、图2、图3”逐图描述，而是输出一份商品级套图分析。
- [ ] 返回内容包含商品概述、可确认卖点、适用人群与场景、套图画面要求、待确认或避免编造的信息五个稳定分段。
- [ ] 图片存在可见差异时，结果说明差异或待确认项，不虚构统一规格、不按图片编号猜测关系。
- [ ] 用户已有卖点仍是补充约束；请求期间编辑文本的确认覆盖、取消、超时、计费、中文脱敏提示均不回归。
- [ ] 不影响②AI生成、⑥正式套图生图、生成轮次/历史、Shopee CDP、采集、更新或账号管理。

## 边界（不改什么）

- 不增加“按勾选原图识图”、逐图识图、图片对比、自动筛图或多轮汇总功能。
- 不修改 cmhub API、`vision_alias` 配置、请求图片数量/大小限制、超时、网络重试、点数或模型选择。
- 不让模型输出 JSON 或强制结构化解析，不改「商品卖点与要求」的数据库字段或自动保存机制。
- 不修改⑥正式生图提示词模板、分类/数量、job、轮次、历史、终选或导出逻辑。
- 不修改 Shopee CDP、商品采集、②AI生成、③更新蝦皮、账号管理或设置模块。

## 执行记录

- 2026-07-17：根据多原图同商品联合分析需求创建任务。待实现。
- 2026-07-17：更新 `ai._compose_product_suite_vision_prompt()`，将同一商品项目的多张原图明确为联合证据集，禁止图号式逐图输出；要求按任务语言输出商品概述、可确认卖点、适用人群与场景、套图画面要求、待确认或避免编造的信息五个独立段落，并保留可见差异和禁止编造约束。
- 2026-07-17：补充图片理解请求的一次请求、联合提示词契约测试；扩展商品套图 GUI 回归测试，确认即使原图勾选状态只选中其他图片，AI帮写仍按 `source_order` 使用前8张可用本地图。
- 2026-07-17：同步更新 `docs/04-architecture.md`、`docs/api.md`、`docs/routes.md` 的同商品多图联合理解语义。
- 验证通过：`py -3.10 -m unittest tests.test_ai tests.test_product_suite_gui tests.test_workers`（114 项）、`py -3.10 -m unittest discover -s tests`（568 项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。