---
id: T-655
title: 按逐图主图模式生成对应参考图规则提示词
phase: 7
deps: [T-654]
status: DONE
created: 2026-07-17
---

## 问题 / 背景

商品套图提示词设置弹窗的首行需要统一显示“生成目标”，不能继续使用“套图名称”。同时，“每张上传图分别作为主图生成”会改变当前 job 的参考图语义，但现有 `{参考图规则}` 没有根据该开关切换，模型可能无法区分单主图模式和逐图主图模式。

## 目标

让提示词预览、实际生成 job 和保存的 prompt 快照使用与 `per_image_primary` 一致的参考图规则：

- 勾选“每张上传图分别作为主图生成”时，使用逐图主参考图规则。
- 未勾选时，使用第一张上传图作为主商品图、其他图片仅作参考的规则。
- 新默认提示词结构的第一行标签固定为“生成目标：”，不再输出“套图名称：”。

## 方案

### 1. 生成目标首行

- 默认模板和“恢复默认”模板的第一行使用：

  ```text
  生成目标：{生成目标}
  ```

- 提示词设置弹窗预览和新建 job 必须使用同一个 renderer，不能只改 GUI 显示文字而保留旧的实际请求。
- 已存在的用户旧模板继续遵守 T-654 的兼容策略，不静默覆盖用户文件；用户保存新模板或恢复默认后使用“生成目标”。

### 2. 参考图规则映射

`product_suite_prompt_context()` 根据归一化设置的 `per_image_primary` 生成 `{参考图规则}` 的内容：

- 勾选逐图主图时，变量值必须严格为：

  ```text
  当前上传图片是本任务唯一主参考图；保持商品主体、款式、颜色和关键细节准确；不编造用户与参考图均未提供的信息。
  ```

- 未勾选逐图主图时，变量值必须严格为：

  ```text
  使用第一張上傳圖作為主商品圖，其餘圖片只作為參考。
  ```

模板中的“参考图规则：”标签由模板本身负责；变量值不得额外重复该标签或追加旧的序号文字，避免预览与最终请求出现重复内容。

### 3. 规划与快照一致性

- `build_suite_prompt()`、`build_job_specs()` 和提示词弹窗预览都必须把当前 `per_image_primary` 设置传入同一上下文。
- 切换该勾选项后，当前任务的分类数量、逐图展开规则和参考图规则必须使用同一份设置快照；不能出现 job 数量已经切换但提示词仍使用另一模式的情况。
- 每个 job 保存最终渲染后的完整 prompt；生成过程中修改勾选项或模板只影响下一轮，不改写已提交任务。
- 新增规则不改变 T-654 已确定的分类顺序、分类数量、固定分类目标描述、自定义分类名称注入和点数计算。

## 验收要点

- 打开提示词设置并恢复默认后，第一行显示“生成目标：”，新默认预览中不存在“套图名称：”。
- 未勾选逐图主图时，预览和实际新 job 的 `{参考图规则}` 均为“使用第一張上傳圖作為主商品圖，其餘圖片只作為參考。”。
- 勾选逐图主图时，预览和实际新 job 的 `{参考图规则}` 均为“当前上传图片是本任务唯一主参考图；保持商品主体、款式、颜色和关键细节准确；不编造用户与参考图均未提供的信息。”。
- 两种模式下都不出现旧的“序号%d”附加文本，也不重复“参考图规则：”标签。
- 切换模式后，`build_job_specs()` 的逐图展开数量和每个 job 的 prompt 与当前设置一致。
- 预览文本与冻结到 job 的 prompt 完全一致。
- 已有旧模板仍可按 T-654 兼容规则读取；不会因启动或打开弹窗而静默覆盖用户模板。
- 现有商品套图生成、历史记录、导出，以及蝦皮采集和更新流程不回归。

## 文档同步

实现时同步更新：

- `docs/routes.md`：商品套图提示词设置和逐图主图规则。
- `docs/04-architecture.md`：`per_image_primary` 与参考图规则的上下文契约。
- `docs/api.md`：`product_suite_prompt_context()`、`build_suite_prompt()` 和 job prompt 快照说明。
- 本任务文件：执行记录、验证命令和最终状态。

## 边界（不改什么）

- 不修改 cmhub 接口、模型别名、图片下载或并发策略。
- 不改变 T-654 的分类默认数量和固定目标描述。
- 不修改 Shopee/CDP 采集、上传、拖拽和更新逻辑。
- 不静默迁移或覆盖用户已有的自定义提示词模板。

## 执行记录

- 2026-07-17：根据逐图主图开关与参考图规则不一致的问题创建任务，待实现。
- 2026-07-17：完成按 `per_image_primary` 切换参考图规则；变量值不再重复“参考图规则：”标签或追加序号，默认模板继续使用“生成目标”。
- 2026-07-17：同步更新路由、架构和 API 文档，补充单主图/逐图主图的 renderer、job prompt 和预览一致性测试。
- 2026-07-17：验证通过 `python -m ruff check app tests main.py`、`python -m compileall app main.py`、`python -m unittest discover -s tests`，共 580 个测试通过。