From 35dc010d44add2197bc2084d2b586ba336e4856d Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Fri, 17 Jul 2026 15:58:26 +0800
Subject: [PATCH] docs(tasks): add reference prompt rule task

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

diff --git a/docs/tasks/T-655.md b/docs/tasks/T-655.md
new file mode 100644
index 0000000..be3b1e9
--- /dev/null
+++ b/docs/tasks/T-655.md
@@ -0,0 +1,89 @@
+---
+id: T-655
+title: 按逐图主图模式生成对应参考图规则提示词
+phase: 7
+deps: [T-654]
+status: TODO
+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：根据逐图主图开关与参考图规则不一致的问题创建任务，待实现。