cmshoppe/docs/tasks/T-658c.md

---
id: T-658c
title: 商品套图多图参考生成计划与提示词一致性
status: DONE
phase: 7
deps: [T-655, T-656, T-657, T-658b]
created: 2026-07-17
---

# T-658c 商品套图多图参考生成计划与提示词一致性

## 问题 / 背景

当前 `{参考图规则}` 已由 T-657 统一带有 `参考图规则:` 前缀，但内容只覆盖单图。多图提交后，最终提示词必须准确说明主图和参考图数量，且预览内容要与新建 job 使用同一套 context。

## 方案

- 由统一 helper 根据“逐图主图勾选状态、实际可用图片数量、cmhub 裁剪上限”生成参考图规则。
- 单图保持 T-657 的现有中文表述和前缀：`参考图规则:当前上传图片是本任务唯一主参考图；...`。
- 多图使用明确的序号规则：第 1 张为主商品图，第 2 至 N 张仅作风格、构图、场景或排版参考，不得替换主商品。
- `build_job_specs()` 与提示词设置弹窗共用同一 context 构造函数，不能在 GUI 和生成层分别拼接规则。
- 预览没有图片资产时按 0/1 张显示单图规则；正式生成时以实际提交数量为准。
- 白底图、场景图、模特场景图、细节说明图、卖点图和自定义分类继续使用现有目标描述与数量配置。
- 确认弹窗的数量和点数仍按 job 请求数计算；超过 8 张时说明仅使用前 7 张参考图。

## 验收要点

- 单图、3 张、8 张上传图的 prompt 规则分别准确。
- 勾选逐图主图时每个 job 都使用单图规则；不勾选时使用多图规则。
- 预览 prompt 与实际 `build_job_specs()` 生成的 prompt 完全一致。
- 上传 1 张时两种模式行为一致，不出现空参考图描述。
- 当前 T-657 的变量清单、必需变量、`生成目标：{套图名称},{生成目标}` 格式不回退。

## 边界（不改什么）

- 不新增或删除提示词占位符。
- 不改变 cmhub 接口 payload、数据库迁移和蝦皮/CDP 操作。
- 不实现多 SKU 自动识别和图片语义分组。

## 验证

```bash
py -3.10 -m unittest tests.test_product_suite
py -3.10 -m unittest tests.test_product_suite_gui
py -3.10 -m ruff check app tests main.py
py -3.10 -m compileall app main.py
git diff --check
```

## 执行记录

- 2026-07-17：新增 `product_suite_reference_rule()` 与参考图数量计算 helper，单图和多图规则都保留 `参考图规则:` 前缀；多图规则中的 N 以实际提交总图片数渲染。
- 2026-07-17：`build_job_specs()` 以冻结的 `reference_asset_ids` 数量构建 job prompt；提示词设置弹窗接收当前可用原图数并使用同一 context，预览与新 job prompt 保持一致。
- 2026-07-17：补充单图、逐图主图、多图及3张原图预览一致性测试；同步路由、架构和 API 文档。
- 验证通过：`py -3.10 -m unittest tests.test_product_suite tests.test_product_suite_gui`（66项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。离屏 GUI 测试有 Qt 字体/插件告警，但无测试失败。