cmshoppe/docs/tasks/T-655.md

id, title, phase, deps, status, created

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

问题 / 背景

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

目标

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

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

方案

1. 生成目标首行

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

  生成目标：{生成目标}
  

• 提示词设置弹窗预览和新建 job 必须使用同一个 renderer，不能只改 GUI 显示文字而保留旧的实际请求。

• 已存在的用户旧模板继续遵守 T-654 的兼容策略，不静默覆盖用户文件；用户保存新模板或恢复默认后使用“生成目标”。

2. 参考图规则映射

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

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

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

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

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

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

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 个测试通过。