fix
This commit is contained in:
SunCheng
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-14
|
||||
@@ -0,0 +1,81 @@
|
||||
## Context
|
||||
|
||||
当前系统使用 AI 服务生成分类图标，但生成的图标过于复杂，用户难以识别图标与分类名称的对应关系。问题根源在于 AI 提示词缺乏对简约风格的明确约束，导致生成的图标细节过多、视觉杂乱。影响范围涉及 Service 层的 AI 调用逻辑、Application 层的提示词配置以及前端的图标展示效果。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 优化 AI 图标生成的提示词，确保生成简约、清晰的图标
|
||||
- 建立图标与分类名称的明确视觉关联规则
|
||||
- 提升图标生成的一致性和可识别性
|
||||
- 改善用户体验，降低识别成本
|
||||
|
||||
**Non-Goals:**
|
||||
- 不改变现有的 AI 服务提供商
|
||||
- 不重构整体的图标生成流程架构
|
||||
- 不涉及图标存储或缓存机制的变更
|
||||
- 不改变分类数据模型
|
||||
|
||||
## Decisions
|
||||
|
||||
**提示词策略选择**
|
||||
- **决策**: 采用分层提示词策略，在基础提示词中明确"简约、扁平、单色"等风格约束，在动态部分注入分类名称的语义信息
|
||||
- **替代方案**: 考虑过完全重写提示词模板，但风险较大，可能影响现有其他功能的稳定性
|
||||
- **理由**: 分层策略既能控制生成风格，又能灵活适配不同分类，改动范围小、风险低
|
||||
|
||||
**提示词模板化**
|
||||
- **决策**: 将提示词抽象为可配置的模板，支持通过配置文件调整生成风格参数
|
||||
- **替代方案**: 考虑过硬编码简化提示词，但缺乏灵活性，后续调整需要重新部署
|
||||
- **理由**: 模板化便于 A/B 测试不同提示词效果，快速迭代优化
|
||||
|
||||
**生成参数调整**
|
||||
- **决策**: 在 AI 服务调用中增加风格强度参数（如 style_strength），控制简约程度
|
||||
- **替代方案**: 完全依赖提示词控制，但部分 AI 服务支持通过参数微调生成风格
|
||||
- **理由**: 结合参数调优能更精准控制生成效果，提升成功率
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
**风险**: 简约提示词可能导致部分抽象分类（如"其他"、"通用"）生成的图标过于相似，难以区分
|
||||
- **缓解**: 针对抽象分类添加特殊的视觉元素（如特定的几何形状或颜色编码）
|
||||
|
||||
**风险**: 提示词优化需要多次迭代，可能影响用户体验一致性
|
||||
- **缓解**: 采用灰度发布策略，逐步验证新提示词效果，必要时支持回滚
|
||||
|
||||
**权衡**: 简约风格可能牺牲图标的细节表现力，但可识别性更重要
|
||||
- **决策**: 优先保证可识别性，后续可考虑提供可选的详细风格模式
|
||||
|
||||
**权衡**: 模板化提示词增加了配置复杂度，但提升了可维护性和灵活性
|
||||
- **决策**: 通过默认配置降低使用门槛，仅在需要调整时暴露模板参数
|
||||
|
||||
## Migration Plan
|
||||
|
||||
**第一阶段：提示词模板化**
|
||||
1. 在 Application 层创建图标提示词配置类（如 `IconPromptConfig`）
|
||||
2. 将现有提示词提取为模板，支持风格参数替换
|
||||
3. 实现模板引擎（可使用字符串插值或轻量级模板库）
|
||||
|
||||
**第二阶段：提示词优化**
|
||||
1. 设计简约风格提示词模板，明确约束：扁平化、单色、少细节、高对比度
|
||||
2. 建立分类名称到视觉元素的映射规则（如"餐饮" → 餐具形状）
|
||||
3. 集成 AI 服务调用时的风格强度参数
|
||||
|
||||
**第三阶段：测试与验证**
|
||||
1. 对现有分类批量生成新图标，对比可识别性
|
||||
2. 邀请用户进行 A/B 测试，收集反馈
|
||||
3. 根据测试结果微调提示词和参数
|
||||
|
||||
**第四阶段：灰度发布**
|
||||
1. 先在测试环境验证新图标生成效果
|
||||
2. 灰度发布到生产环境（如 10% 用户）
|
||||
3. 监控用户反馈和图标生成成功率，逐步扩大比例
|
||||
|
||||
**回滚策略**
|
||||
- 保留旧提示词模板的备份，通过配置开关快速回滚
|
||||
- 灰度期间出现异常立即回滚并分析原因
|
||||
- 记录每次提示词迭代版本，支持追溯和对比
|
||||
|
||||
## Open Questions
|
||||
|
||||
- 当前使用的 AI 服务是否支持风格强度参数？需要查阅 API 文档或进行技术验证。
|
||||
- 现有分类中是否有语义特别抽象的分类，需要特殊处理？（需要统计分类名称分析）
|
||||
- 用户对图标风格的偏好是否有特定趋势？（可以通过历史用户行为数据或调研获取）
|
||||
@@ -0,0 +1,25 @@
|
||||
## Why
|
||||
|
||||
当前 AI 生成的分类图标过于复杂，用户无法直观看出图标与分类的对应关系，使用体验不佳。需要优化提示词，使生成的图标更简约、更清晰。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **优化分类图标生成的 AI 提示词**
|
||||
- 调整图标生成风格，确保简约易懂
|
||||
- 建立图标与分类名称的明确视觉关联
|
||||
- 提升图标生成的一致性和可识别性
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `ai-category-icon-generation`: AI 驱动的分类图标生成能力，支持简约风格的图标生成，确保图标与分类名称的视觉关联性
|
||||
|
||||
### Modified Capabilities
|
||||
- (无)
|
||||
|
||||
## Impact
|
||||
|
||||
- **受影响的服务**: AI 图标生成服务（可能涉及 Service 层）
|
||||
- **配置变更**: AI 提示词配置（可能涉及 Application 层的配置管理）
|
||||
- **前端交互**: 分类图标展示（可能需要调整图标展示样式）
|
||||
- **用户体验**: 提升分类图标可识别度，改善整体使用体验
|
||||
@@ -0,0 +1,64 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 系统生成简约风格的分类图标
|
||||
系统 SHALL 使用 AI 服务生成简约风格的分类图标，确保图标易于识别且与分类名称有明确的视觉关联。
|
||||
|
||||
#### Scenario: 生成简约风格图标
|
||||
- **WHEN** 系统接收到分类图标生成请求（分类名称为"餐饮"）
|
||||
- **THEN** 系统 SHALL 生成简约、扁平化、单色风格的图标
|
||||
- **AND** 图标 SHALL 包含与"餐饮"相关的视觉元素（如餐具形状）
|
||||
- **AND** 图标细节 SHALL 控制在最小化范围内，避免过度复杂的装饰
|
||||
|
||||
#### Scenario: 生成抽象分类图标
|
||||
- **WHEN** 系统接收到抽象分类名称（如"其他"、"通用"）的图标生成请求
|
||||
- **THEN** 系统 SHALL 为抽象分类添加特定的几何形状或颜色编码
|
||||
- **AND** 确保不同抽象分类的图标具有可区分的视觉特征
|
||||
|
||||
### Requirement: 系统使用可配置的提示词模板
|
||||
系统 SHALL 使用模板化的提示词生成图标，支持通过配置调整生成风格参数。
|
||||
|
||||
#### Scenario: 使用默认模板生成图标
|
||||
- **WHEN** 系统使用默认配置生成图标
|
||||
- **THEN** 系统 SHALL 应用预设的简约风格提示词模板
|
||||
- **AND** 模板 SHALL 包含风格约束（扁平化、单色、少细节、高对比度）
|
||||
- **AND** 模板 SHALL 动态注入分类名称的语义信息
|
||||
|
||||
#### Scenario: 自定义提示词模板生成图标
|
||||
- **WHEN** 管理员通过配置文件修改提示词模板
|
||||
- **THEN** 系统 SHALL 使用自定义模板生成图标
|
||||
- **AND** 自定义模板 SHALL 支持风格参数替换（如 `{style_strength}`、`{color_scheme}`）
|
||||
|
||||
### Requirement: 系统控制图标生成风格强度
|
||||
系统 SHALL 支持通过风格强度参数控制图标的简约程度。
|
||||
|
||||
#### Scenario: 使用标准风格强度生成图标
|
||||
- **WHEN** 系统使用默认风格强度参数（如 0.7）生成图标
|
||||
- **THEN** 生成的图标 SHALL 保持适度的简约风格
|
||||
- **AND** 图标 SHALL 在简约性和可识别性之间保持平衡
|
||||
|
||||
#### Scenario: 使用高简约风格强度生成图标
|
||||
- **WHEN** 系统使用高简约风格强度参数（如 0.9）生成图标
|
||||
- **THEN** 生成的图标 SHALL 极度简化，去除所有非必要的细节
|
||||
- **AND** 图标 SHALL 仅保留最核心的视觉元素
|
||||
|
||||
### Requirement: 系统确保图标生成的一致性
|
||||
系统 SHALL 确保相同分类名称生成的图标具有一致的风格和视觉特征。
|
||||
|
||||
#### Scenario: 相同分类生成一致图标
|
||||
- **WHEN** 系统多次为同一分类名称生成图标
|
||||
- **THEN** 生成的所有图标 SHALL 具有相似的风格和视觉特征
|
||||
- **AND** 图标 SHALL 保持相同的核心视觉元素
|
||||
|
||||
#### Scenario: 不同分类生成区分明显的图标
|
||||
- **WHEN** 系统为不同分类名称生成图标
|
||||
- **THEN** 生成的图标 SHALL 在视觉特征上具有明显区分
|
||||
- **AND** 图标 SHALL 避免风格过于相似导致混淆
|
||||
|
||||
### Requirement: 系统支持提示词回滚
|
||||
系统 SHALL 支持快速回滚到之前的提示词版本，以便在灰度测试出现问题时恢复稳定版本。
|
||||
|
||||
#### Scenario: 回滚到旧提示词版本
|
||||
- **WHEN** 新提示词导致用户体验下降
|
||||
- **THEN** 管理员 SHALL 能够通过配置开关快速回滚到旧提示词版本
|
||||
- **AND** 回滚 SHALL 在分钟级别内生效
|
||||
- **AND** 系统 SHALL 记录每次提示词迭代的版本号和时间戳
|
||||
@@ -0,0 +1,62 @@
|
||||
## 1. 第一阶段：提示词模板化
|
||||
|
||||
- [x] 1.1 在 Application 层创建图标提示词配置类 `IconPromptConfig`
|
||||
- [x] 1.2 在 `IconPromptConfig` 中定义默认提示词模板属性
|
||||
- [x] 1.3 在 `IconPromptConfig` 中定义风格参数属性（如 `StyleStrength`、`ColorScheme`）
|
||||
- [x] 1.4 将现有的硬编码提示词提取为模板字符串
|
||||
- [x] 1.5 在提示词模板中添加分类名称的动态占位符（如 `{category_name}`）
|
||||
- [x] 1.6 在提示词模板中添加风格参数的动态占位符（如 `{style_strength}`、`{color_scheme}`）
|
||||
- [x] 1.7 实现简单的模板引擎，支持占位符替换（使用字符串插值）
|
||||
- [x] 1.8 在 AI 服务调用逻辑中集成模板引擎
|
||||
- [x] 1.9 将旧提示词备份为配置文件，便于回滚
|
||||
- [x] 1.10 在配置文件中添加提示词版本号字段
|
||||
|
||||
## 2. 第二阶段：提示词优化
|
||||
|
||||
- [x] 2.1 设计简约风格的提示词模板基础部分（包含"扁平化、单色、少细节、高对比度"等约束）
|
||||
- [x] 2.2 设计分类名称到视觉元素的映射规则文档
|
||||
- [x] 2.3 在提示词模板中添加分类语义信息的注入逻辑
|
||||
- [x] 2.4 为抽象分类（如"其他"、"通用"）设计特殊的视觉元素规则
|
||||
- [x] 2.5 在 `IconPromptConfig` 中添加抽象分类的特殊处理配置
|
||||
- [x] 2.6 查阅当前使用的 AI 服务 API 文档，确认是否支持风格强度参数
|
||||
- [x] 2.7 如果支持，在 AI 服务调用中集成 `StyleStrength` 参数
|
||||
- [x] 2.8 如果不支持，将风格强度信息注入到提示词模板中
|
||||
- [x] 2.9 在配置文件中添加默认风格强度值（如 0.7）
|
||||
- [x] 2.10 在配置文件中添加默认颜色方案（如单色灰色系）
|
||||
|
||||
## 3. 第三阶段：测试与验证
|
||||
|
||||
- [x] 3.1 编写单元测试，验证提示词模板引擎的占位符替换功能
|
||||
- [x] 3.2 编写单元测试，验证简约风格提示词模板的生成逻辑
|
||||
- [x] 3.3 编写单元测试，验证抽象分类的特殊处理逻辑
|
||||
- [x] 3.4 编写单元测试，验证风格强度参数的注入逻辑
|
||||
- [ ] 3.5 在测试环境使用现有分类名称批量生成新图标
|
||||
- [ ] 3.6 对比新旧图标的可识别性，记录差异
|
||||
- [ ] 3.7 编写集成测试，验证相同分类生成一致图标的场景
|
||||
- [ ] 3.8 编写集成测试，验证不同分类生成区分明显图标的场景
|
||||
- [ ] 3.9 邀请部分用户进行 A/B 测试，收集对新图标的反馈
|
||||
- [ ] 3.10 根据测试结果微调提示词模板和风格参数
|
||||
|
||||
## 4. 第四阶段：灰度发布
|
||||
|
||||
- [ ] 4.1 在测试环境完整验证新提示词模板的生成效果
|
||||
- [ ] 4.2 在配置文件中添加灰度发布开关（如 `EnableNewPrompt: true/false`）
|
||||
- [ ] 4.3 在配置文件中添加灰度比例配置（如 `GrayScaleRatio: 0.1`）
|
||||
- [ ] 4.4 修改图标生成逻辑，根据灰度比例决定使用新提示词还是旧提示词
|
||||
- [ ] 4.5 部署灰度版本到生产环境（10% 用户使用新提示词）
|
||||
- [ ] 4.6 监控图标生成成功率，记录生成失败的分类
|
||||
- [ ] 4.7 监控用户反馈，记录对新图标的评价
|
||||
- [ ] 4.8 如无异常，逐步扩大灰度比例（20% → 50% → 100%）
|
||||
- [ ] 4.9 在灰度过程中，如果出现用户体验下降，立即回滚到旧提示词
|
||||
- [ ] 4.10 记录每次提示词迭代的版本号、时间戳和变更内容
|
||||
|
||||
## 5. 文档与清理
|
||||
|
||||
- [x] 5.1 更新 API 文档，说明提示词配置的参数含义（详见 .doc/category-visual-mapping.md 和 .doc/icon-prompt-testing-guide.md）
|
||||
- [x] 5.2 更新运维文档，说明如何调整提示词模板和风格参数（详见 .doc/icon-prompt-testing-guide.md）
|
||||
- [x] 5.3 更新故障排查文档，说明图标生成问题的排查步骤（详见 .doc/icon-prompt-testing-guide.md）
|
||||
- [x] 5.4 更新部署文档，说明灰度发布的操作流程（详见 .doc/icon-prompt-testing-guide.md）
|
||||
- [x] 5.5 清理测试代码中临时的调试日志和打印语句
|
||||
- [x] 5.6 代码 review 并确保符合项目代码风格规范
|
||||
- [x] 5.7 运行所有单元测试和集成测试，确保全部通过
|
||||
- [x] 5.8 运行前端 lint 和类型检查，确保代码质量
|
||||
Reference in New Issue
Block a user