chengma/cmshoppe
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(tasks): refine T-637 prompt dialog spec after review

Browse Source 
- promote {套图分类} to required placeholder
- forbid literal braces in v1 instead of escape rules
- restore-default only refills editor; disk write goes through save
- pin preview index placeholder values
- degrade differentiation text and collapse blank lines when count is 1
- add pure-logic-first implementation order note

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-07-16 14:43:35 +08:00
co-authored by Claude Fable 5
parent 51d5fb9370
commit 2abde42862
1 changed files with 13 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tasks/T-637.md
+13 -8
View File
@@ -32,6 +32,8 @@ created: 2026-07-16
## 实现方案 ## 实现方案
> 推进顺序建议：先完成纯逻辑（renderer、占位符校验、默认模板、分类说明迁移进 `build_job_specs()`）并测试绿，再动弹窗 GUI，最后补打包断言；避免 20 条验收项一次性集中风险。
### 1. 主界面标题行 ### 1. 主界面标题行
- 调整 `ProductSuiteTab._build_prompt_section()` 的标题行顺序： - 调整 `ProductSuiteTab._build_prompt_section()` 的标题行顺序：
@@ -51,10 +53,10 @@ created: 2026-07-16
- 弹窗使用可调整的左右分栏，初始比例 `1:1`，设置合理最小尺寸；左侧是可编辑模板，右侧是只读最终提示词预览。 - 弹窗使用可调整的左右分栏，初始比例 `1:1`，设置合理最小尺寸；左侧是可编辑模板，右侧是只读最终提示词预览。
- 第一行从左到右提供： - 第一行从左到右提供：
- 「保存」：校验通过后原子写入用户模板，并显示轻量中文成功提示； - 「保存」：校验通过后原子写入用户模板，并显示轻量中文成功提示；
- 「恢复默认」：二次确认后用安装包内置模板覆盖当前用户模板，同时更新编辑区和预览区；恢复完成后已落盘，不要求再次点击保存； - 「恢复默认」：二次确认后仅把内置模板回填到编辑区并刷新预览，**不直接写盘**；确认弹窗需明示会丢弃编辑区当前未保存修改。落盘仍走「保存」，未保存关闭时由统一的三选项流程兜底，保证全程只有「保存」一条原子写盘路径；
- 右侧「预览分类」下拉框：默认选中「白底图」，可切换当前固定分类和当前项目已有自定义分类。 - 右侧「预览分类」下拉框：默认选中「白底图」，可切换当前固定分类和当前项目已有自定义分类。
- 左侧编辑区顶部提供「插入变量」菜单或按钮菜单。用户选择变量后，在当前光标位置插入，不要求手工记忆占位符。 - 左侧编辑区顶部提供「插入变量」菜单或按钮菜单。用户选择变量后，在当前光标位置插入，不要求手工记忆占位符。
- 右侧预览区不可编辑、不可获得保存语义；内容使用当前商品任务的真实平台、地区、语言、比例、商品 ID、分类、参考图序号和卖点。当前值为空时使用明确的中文示例值，内部 `draft_` 标识不得出现在预览中。 - 右侧预览区不可编辑、不可获得保存语义；内容使用当前商品任务的真实平台、地区、语言、比例、商品 ID、分类、参考图序号和卖点。预览的序号类占位符使用固定值：`{主参考图序号}`＝1、`{分类序号}`＝1、`{分类总数}`＝该分类当前配置数量，不随预览分类切换之外的因素变化。当前值为空时使用明确的中文示例值，内部 `draft_` 标识不得出现在预览中。
- 编辑内容变化后使用约 `200ms` 单次防抖刷新，连续输入不得触发大量重复渲染或造成界面卡顿。 - 编辑内容变化后使用约 `200ms` 单次防抖刷新，连续输入不得触发大量重复渲染或造成界面卡顿。
- 关闭存在未保存修改的弹窗时，提供「保存」「不保存」「取消」三种中文选择；保存校验失败时保持弹窗打开。 - 关闭存在未保存修改的弹窗时，提供「保存」「不保存」「取消」三种中文选择；保存校验失败时保持弹窗打开。
@@ -78,9 +80,9 @@ created: 2026-07-16
{商品卖点与要求} {商品卖点与要求}
``` ```
- `{分类要求}`、`{图片比例}`、`{参考图规则}`、`{商品卖点与要求}`为必需占位符；缺失时预览区显示中文校验结果，「保存」禁用。 - `{分类要求}`、`{套图分类}`、`{图片比例}`、`{参考图规则}`、`{商品卖点与要求}`为必需占位符；缺失时预览区显示中文校验结果，「保存」禁用。`{套图分类}`列为必需是因为固定分类的说明文案不保证包含分类名，删掉后最终提示词可能丢失分类信息。
- 未知占位符、未闭合花括号和渲染后仍残留的占位符都视为错误，不得静默原样发送给模型。 - 未知占位符、未闭合花括号和渲染后仍残留的占位符都视为错误，不得静默原样发送给模型。
- 重复使用合法占位符允许保存；普通花括号文本如确有需要，应定义明确转义规则并覆盖测试，不使用字符串猜测。 - 重复使用合法占位符允许保存；第一版模板**不支持字面花括号**，任何非合法占位符形式的花括号一律校验报错，不定义转义规则，也不做字符串猜测。
- 占位符替换必须使用结构化上下文字典和统一 renderer，不允许在 GUI 中连续手写 `.replace()` 拼接另一套规则。 - 占位符替换必须使用结构化上下文字典和统一 renderer，不允许在 GUI 中连续手写 `.replace()` 拼接另一套规则。
### 4. 默认模板和分类要求 ### 4. 默认模板和分类要求
@@ -103,6 +105,7 @@ created: 2026-07-16
- 将当前仅存在于 GUI 的固定分类说明迁移或集中到业务层，渲染为 `{分类要求}`；GUI 通过同一来源显示说明，不能复制另一份字典。 - 将当前仅存在于 GUI 的固定分类说明迁移或集中到业务层，渲染为 `{分类要求}`；GUI 通过同一来源显示说明，不能复制另一份字典。
- 自定义分类的 `{分类要求}`必须明确包含自定义分类名称，例如「生成商品套图中的『使用方法图』，按照该分类名称表达用途」，不能使用不含分类名的泛化文案。 - 自定义分类的 `{分类要求}`必须明确包含自定义分类名称，例如「生成商品套图中的『使用方法图』，按照该分类名称表达用途」，不能使用不含分类名的泛化文案。
- `{差异化要求}`至少包含分类内序号和“与本分类其他图片采用不同构图、角度或场景”的约束。若第一版没有可靠的商品语义，不自动编造具体卖点、参数或使用场景。 - `{差异化要求}`至少包含分类内序号和“与本分类其他图片采用不同构图、角度或场景”的约束。若第一版没有可靠的商品语义，不自动编造具体卖点、参数或使用场景。
- 退化规则：分类总数为 1 时 `{差异化要求}`渲染为空，最终提示词不得出现“与本分类其他图片不同”这类无意义残句；renderer 需折叠占位符独占一行且替换为空后产生的空白行。
- `{参考图规则}`必须与当前实际请求一致。每个 `image_studio_job` 只有一个 `source_asset_id` 时，应明确表述当前图片是本任务唯一主参考图，不得声称未提交的其他图片也参与参考。 - `{参考图规则}`必须与当前实际请求一致。每个 `image_studio_job` 只有一个 `source_asset_id` 时，应明确表述当前图片是本任务唯一主参考图，不得声称未提交的其他图片也参与参考。
### 5. 强制保护规则 ### 5. 强制保护规则
@@ -143,15 +146,16 @@ created: 2026-07-16
- [ ] 点击「提示词设置」打开左右等宽弹窗，左侧可编辑、右侧只读，默认预览白底图最终提示词。 - [ ] 点击「提示词设置」打开左右等宽弹窗，左侧可编辑、右侧只读，默认预览白底图最终提示词。
- [ ] 预览分类下拉可以切换固定分类和当前自定义分类；切换只刷新预览，不修改项目配置。 - [ ] 预览分类下拉可以切换固定分类和当前自定义分类；切换只刷新预览，不修改项目配置。
- [ ] 从「插入变量」菜单选择每个合法变量，都会插入到当前光标位置并在约 200ms 后刷新预览。 - [ ] 从「插入变量」菜单选择每个合法变量，都会插入到当前光标位置并在约 200ms 后刷新预览。
- [ ] 当前商品数据完整时，预览正确替换平台、地区、语言、比例、商品 ID、参考图序号、分类序号/总数和商品卖点。 - [ ] 当前商品数据完整时，预览正确替换平台、地区、语言、比例、商品 ID 和商品卖点；序号类占位符按约定固定为主参考图序号 1、分类序号 1/该分类配置总数。
- [ ] 临时草稿预览使用 `未绑定商品` 或等价中文值，不显示内部 `draft_` 标识。 - [ ] 临时草稿预览使用 `未绑定商品` 或等价中文值，不显示内部 `draft_` 标识。
- [ ] 删除必需占位符、输入未知变量、花括号未闭合或渲染残留变量时不能保存，并显示中文校验错误。 - [ ] 删除必需占位符、输入未知变量、花括号未闭合或渲染残留变量时不能保存，并显示中文校验错误。
- [ ] 固定分类说明实际进入提示词；自定义分类提示词明确包含自定义分类名称。 - [ ] 固定分类说明实际进入提示词；自定义分类提示词明确包含自定义分类名称。
- [ ] 同一分类多张任务的最终提示词包含各自序号/总数和差异化要求，不再完全相同。 - [ ] 同一分类多张任务的最终提示词包含各自序号/总数和差异化要求，不再完全相同。
- [ ] 分类总数为 1 时，该分类最终提示词不含差异化残句，也不留悬空空行。
- [ ] 参考图规则与实际单个 `source_asset_id` 一致，不声称未提交图片参与参考。 - [ ] 参考图规则与实际单个 `source_asset_id` 一致，不声称未提交图片参与参考。
- [ ] 强制商品一致性、禁止虚构参数/价格/尺码等规则始终出现在最终预览和真实请求中，用户不能从编辑器删除。 - [ ] 强制商品一致性、禁止虚构参数/价格/尺码等规则始终出现在最终预览和真实请求中，用户不能从编辑器删除。
- [ ] 保存后关闭并重启程序仍加载用户模板；已有用户模板不会被启动初始化或软件升级覆盖。 - [ ] 保存后关闭并重启程序仍加载用户模板；已有用户模板不会被启动初始化或软件升级覆盖。
- [ ] 「恢复默认」经确认后立即恢复、落盘并刷新预览，只影响商品套图模板。 - [ ] 「恢复默认」经确认后回填编辑区并刷新预览，不直接写盘；经「保存」后才落盘，且只影响商品套图模板。
- [ ] 弹窗存在未保存修改时关闭会出现保存/不保存/取消三选项，任何失败都不损坏原模板。 - [ ] 弹窗存在未保存修改时关闭会出现保存/不保存/取消三选项，任何失败都不损坏原模板。
- [ ] 同一 context 下右侧预览文本与新建 job 保存的最终 prompt 完全一致。 - [ ] 同一 context 下右侧预览文本与新建 job 保存的最终 prompt 完全一致。
- [ ] 生成开始后再修改模板不影响本轮已经冻结的 job；历史重试继续使用历史 prompt 快照。 - [ ] 生成开始后再修改模板不影响本轮已经冻结的 job；历史重试继续使用历史 prompt 快照。
@@ -161,8 +165,8 @@ created: 2026-07-16
## 测试要求 ## 测试要求
- 新增纯逻辑测试覆盖全部合法占位符、必需变量、未知变量、未闭合/转义花括号、重复变量、强制规则追加和 Unicode 文本。 - 新增纯逻辑测试覆盖全部合法占位符、必需变量（含 `{套图分类}`）、未知变量、未闭合/字面花括号报错、重复变量、强制规则追加和 Unicode 文本。
- 覆盖白底图、其他固定分类、自定义分类、正式商品、临时草稿、分类多张和单参考图 context。 - 覆盖白底图、其他固定分类、自定义分类、正式商品、临时草稿、分类多张、分类总数为 1 的差异化退化与空行折叠，以及单参考图 context。
- 覆盖用户模板首次初始化、不覆盖已有文件、原子保存失败保持原文件和恢复默认。 - 覆盖用户模板首次初始化、不覆盖已有文件、原子保存失败保持原文件和恢复默认。
- `tests/test_product_suite_gui.py` 覆盖标题行按钮顺序、AI 帮写运行时取消按钮、弹窗初始分栏、默认白底图、分类切换、变量插入、防抖刷新、只读预览、保存校验和未保存关闭三选项。 - `tests/test_product_suite_gui.py` 覆盖标题行按钮顺序、AI 帮写运行时取消按钮、弹窗初始分栏、默认白底图、分类切换、变量插入、防抖刷新、只读预览、保存校验和未保存关闭三选项。
- 覆盖预览 renderer 与 `build_job_specs()` 最终 prompt 相等，以及生成运行中模板变更不污染本轮 job。 - 覆盖预览 renderer 与 `build_job_specs()` 最终 prompt 相等，以及生成运行中模板变更不污染本轮 job。
@@ -197,4 +201,5 @@ git diff --check
## 执行记录 ## 执行记录
- 2026-07-16 补：按全栈评审调整规格——`{套图分类}`升为必需占位符；第一版禁止字面花括号（不做转义规则）；「恢复默认」改为只回填编辑区、落盘统一走「保存」；预览序号类占位符固定值约定；分类总数为 1 时差异化要求退化为空并折叠空行；补充纯逻辑先行的推进顺序建议。
- 待实现。 - 待实现。