From fa97fa6d3cac66325d94e27accbc62b6c31fbbe7 Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Fri, 17 Jul 2026 10:09:44 +0800
Subject: [PATCH] docs(task): add multi-image AI writing analysis

---
 docs/tasks/T-647.md | 80 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 docs/tasks/T-647.md

diff --git a/docs/tasks/T-647.md b/docs/tasks/T-647.md
new file mode 100644
index 0000000..ae3aaaa
--- /dev/null
+++ b/docs/tasks/T-647.md
@@ -0,0 +1,80 @@
+---
+id: T-647
+title: 商品套图AI帮写改为同商品多图联合分析
+phase: 7
+deps: [T-645]
+status: TODO
+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：根据多原图同商品联合分析需求创建任务。待实现。