cmshoppe/docs/tasks/T-647.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-647	商品套图AI帮写改为同商品多图联合分析	7	T-645	TODO	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张”或按图片编号逐条罗列的理解结果，也不要逐图复述；

• 保持当前“只采信图片可见事实、已有要求只作补充约束、不得编造材质/尺寸/功能/认证/价格/物流”等安全事实边界；

• 当图片确有可见的颜色、款式、配件、包装或规格差异时，输出为“可见差异或待确认项”，不能把冲突信息强行合并为一个确定事实；不能凭图片顺序猜测主款、附赠品或变体关系；

• 输出必须是可直接回填到「商品卖点与要求」的中文纯文本，使用稳定分段结构：

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

• 输出语言继续服从当前任务设置；不要求 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帮写输出的是商品级联合分析，而不是逐图识别结果；

• 运行：

  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：根据多原图同商品联合分析需求创建任务。待实现。