docs: 更新 README 与 API 文档，描述提示词优化链路

- README 新增提示词优化链路章节（流程图 + 特性 + API 说明） - docs/api.md 新增提示词优化接口文档与调用链路 - 更新架构描述：PromptBuilder → PromptOptimizer
2026-05-24 20:45:24 +08:00
parent 9ca1e65221
commit 36a6465f26
6 changed files with 244 additions and 41 deletions
@@ -8,7 +8,7 @@ Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 可替换 AI

 ## 文档索引

- [后端工程](backend.md) — 分层结构、管线设计（PromptBuilder → AssetGenerator → QualitySupervisor → FormatAdapter）、风格模型
+- [后端工程](backend.md) — 分层结构、管线设计（PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter）、风格模型
 - [前端工程](frontend.md) — 组件树、状态管理、路由、WebSocket 通信
 - [异步任务](async-tasks.md) — 任务队列、状态机、并发控制、失败重试
 - [数据存储](database.md) — SQLite 选型、表结构、本地文件存储
@@ -172,6 +172,57 @@ Token 过期或无效时返回：
 |------|------|---------|
 | 原密码错误 | 400 | 原密码不正确 |

+## 提示词优化
+
+将用户标签和原始描述送入 LLM，生成规范化三段式提示词。前端组件收集用户标签和原始提示词后，调用本接口获取优化结果，用于预览或直接发起素材生成。
+
+| 状态 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| [x] | POST | `/api/v1/prompt/optimize` | 提示词优化 |
+
+### POST /api/v1/prompt/optimize
+
+```json
+{
+  "tags":      ["像素", "战士", "黑暗"],
+  "assetType": "sprite",
+  "prompt":    "我要一个拿着大剑的战士角色，背景是黑暗地牢",
+  "userNote":  "需要武器发光特效"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `tags` | string[] | 是 | 用户选择的风格标签，至少 1 个 |
+| `assetType` | string | 是 | 素材类型：`sprite` / `background` / `ui` / `animation` |
+| `prompt` | string | 否 | 用户输入的原始提示词描述 |
+| `userNote` | string | 否 | 额外补充说明 |
+
+响应：
+
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": {
+    "prompt": "【主题】一个融合像素、战士元素的游戏角色精灵图...\n【风格】色彩鲜明；细节丰富...\n【技术】输出格式: spritesheet...",
+    "rawText": "【主题】一个融合像素..."
+  }
+}
+```
+
+**链路：**
+
+```
+POST /api/v1/prompt/optimize
+  → handler.PromptOptimize 解析请求
+    → service.RunPromptAgent 执行 Eino Chain
+      → formatMetaPrompt:  构建元提示词（角色设定 + 标签 + 原始描述 + 素材类型）
+      → llmRefine:        调用 OpenAI 兼容 Chat Completions API
+                            └── 无 API key → 回退模板生成
+    → 返回 PromptAgentOutput { prompt, rawText }
+```
+
 ## 工程管理

 需认证。以下接口均需通过 Cookie 携带 Token，工程归属于当前登录用户。
@@ -358,7 +409,7 @@ Token 过期或无效时返回：
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `projectId` | string | 是 | 工程 ID，用于获取工程风格 |
-| `prompt` | string | 是 | 用户原始文本，后端 PromptBuilder 负责三段式重写 |
+| `prompt` | string | 是 | 用户原始文本，后端 PromptOptimizer/PromptAgent 负责提示词优化 |
 | `assetType` | string | 是 | 素材类型：`sprite` / `background` / `ui` / `animation` |
 | `taskStyle` | object | 否 | 任务级别风格覆盖（同名键覆盖工程风格） |
 | `params.resolution` | int | 否 | 分辨率，默认 64 |
@@ -466,7 +517,7 @@ Token 过期或无效时返回：

 ```typescript
 interface PipelineProgress {
-  stage: 'prompt_builder' | 'asset_generator' | 'quality_supervisor' | 'format_adapter';
+  stage: 'prompt_optimizer' | 'asset_generator' | 'quality_supervisor' | 'format_adapter';
  status: 'running' | 'completed' | 'failed';
  progress: number;       // 0-100
  message?: string;       // 阶段描述
@@ -482,8 +533,8 @@ interface PipelineProgress {
 消息示例（正常流程）：

 ```json
-{"stage":"prompt_builder","status":"running","progress":0}
-{"stage":"prompt_builder","status":"completed","progress":100}
+{"stage":"prompt_optimizer","status":"running","progress":0}
+{"stage":"prompt_optimizer","status":"completed","progress":100}
 {"stage":"asset_generator","status":"running","progress":0}
 {"stage":"asset_generator","status":"completed","progress":100}
 {"stage":"quality_supervisor","status":"running","progress":0}
@@ -497,7 +548,7 @@ interface PipelineProgress {
 ```json
 {"stage":"quality_supervisor","status":"running","progress":0}
 {"stage":"quality_supervisor","status":"failed","progress":100,"retryCount":1,"rejectReason":"风格不一致"}
-{"stage":"prompt_builder","status":"running","progress":0}
+{"stage":"prompt_optimizer","status":"running","progress":0}
 {"stage":"asset_generator","status":"running","progress":0}
 {"stage":"quality_supervisor","status":"completed","progress":100}
 {"stage":"format_adapter","status":"completed","progress":100,"result":{"assets":[...]}}
@@ -75,9 +75,9 @@ JobQueue.Pop() 取出 taskId
    ├── 2. 查询 task + project_style
    ├── 3. 构造 PipelineInput
    ├── 4. RunPipeline(ctx, input)
-    │       ├── PromptBuilder → stage 更新
+    │       ├── PromptOptimizer → stage 更新
    │       ├── AssetGenerator → stage 更新
-    │       ├── QualitySupervisor → stage 更新（可能触发重试分支）
+    │       ├── QualitySupervisor → stage 更新（可能触发重优化分支）
    │       └── FormatAdapter → stage 更新
    ├── 5. 保存素材到本地，写入 asset 表
    ├── 6. 更新 task.status = completed
@@ -125,7 +125,7 @@ func (s *TaskService) StartWorkers(n int) {

 | 阶段 | stage 值 | 进度范围 | 说明 |
 |------|----------|---------|------|
-| 提示词构建 | `prompt_builder` | 0-20% | 合并风格，生成三段式提示词 |
+| 提示词优化 | `prompt_optimizer` | 0-20% | 调用 PromptAgent/LLM 优化提示词，合并风格与技术参数 |
 | 素材生成 | `asset_generator` | 20-60% | 调用 AI 推理 API 出图 |
 | 质量检查 | `quality_supervisor` | 60-80% | 视觉模型质检 |
 | 格式适配 | `format_adapter` | 80-100% | 格式转换、spritesheet 打包、保存素材 |
@@ -136,10 +136,10 @@ func (s *TaskService) StartWorkers(n int) {

 ### 质检重试（管线内重试）

-QualitySupervisor 质检不通过时，Eino Graph 分支回到 PromptBuilder 重新生成：
+QualitySupervisor 质检不通过时，Eino Graph 分支回到 PromptOptimizer 重新优化提示词：

 ```
-QualitySupervisor -- fail --> PromptBuilder --> AssetGenerator --> QualitySupervisor
+QualitySupervisor -- fail --> PromptOptimizer --> AssetGenerator --> QualitySupervisor
 QualitySupervisor -- pass --> FormatAdapter
 ```

@@ -3,7 +3,7 @@
 ## 技术选型

 - **HTTP 框架**：Gin
- **管线编排**：[Eino](https://github.com/cloudwego/eino) `compose.Graph` — 四阶段管线，含质检→重生成分支
+- **管线编排**：[Eino](https://github.com/cloudwego/eino) `compose.Graph` — 三阶段管线，含质检→重优化分支
 - **AI 组件**：Eino 的 model / tool 组件，统一接口便于替换模型提供商

 ## 分层结构
@@ -18,7 +18,7 @@ backend/internal/
 │   ├── generate.go       # 生成任务提交 / 查询 / WebSocket
 │   └── project_style.go  # 工程风格 CRUD
 ├── service/              # 业务逻辑层
-│   ├── pipeline.go       # [已有] Eino compose.Graph 编排：PromptBuilder → AssetGenerator → QualitySupervisor → FormatAdapter
+│   ├── pipeline.go       # [已有] Eino compose.Graph 编排：PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter
 │   ├── nodes.go          # [已有] 管线四个节点的实现（每个节点单一职责）
 │   ├── types.go          # [已有] 管线输入/状态/输出的显式结构体定义
 │   ├── inference.go      # [已有] AI 推理 API 调用封装（当前为 mock 实现）
@@ -50,11 +50,11 @@ backend/internal/

 ## 多阶段生成管线

-gen2d 的核心生成流程采用 Eino `compose.Graph` 编排的四阶段管线，含质检不通过时的重生成分支。
+gen2d 的核心生成流程采用 Eino `compose.Graph` 编排的三阶段管线，含质检不通过时的重优化分支。

 ```mermaid
 flowchart LR
-    A["PromptBuilder\n(提示词工程)"] --> B["AssetGenerator\n(AI 出图)"]
+    A["PromptOptimizer\n(提示词优化 + 风格合并)"] --> B["AssetGenerator\n(AI 出图)"]
    B --> C["QualitySupervisor\n(质检)"]
    C -- pass --> D["FormatAdapter\n(格式适配)"]
    C -- fail --> A
@@ -62,16 +62,16 @@ flowchart LR

 ### 各阶段职责

-#### 1. PromptBuilder
+#### 1. PromptOptimizer

- **输入**：用户文本 + 素材类型标签 + 工程风格 + 任务风格覆盖 + 技术参数
+- **输入**：用户文本 + 素材类型标签 + 工程风格 + 任务风格覆盖 + 技术参数 + Tags
 - **输出**：三段式完整生成提示词
 - **职责**：
-  1. 解析用户文本，提取核心内容作为【主题】
-  2. 合并工程风格与任务风格覆盖（任务同名键覆盖工程），生成【约束】（含负面提示词）
-  3. 注入素材类型、分辨率等技术参数作为【内容】
-  4. 拼接为最终提示词
-  5. **重试时**：将上次质检的 RejectReason 注入【约束】段，指导 AI 修正问题
+  1. 合并工程风格与任务风格覆盖（任务同名键覆盖工程），转为自然语言风格描述
+  2. 有标签时调用 PromptAgent（LLM）生成规范化三段式提示词
+  3. 无标签时直接拼接原始 Prompt + 技术参数
+  4. **重试时**：将上次质检的 RejectReason 注入输入，指导 LLM 修正问题
+  5. 未配置 LLM API key 时自动回退到模板生成，不阻塞管线

 **风格合并**：

@@ -81,17 +81,17 @@ finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)

 工程风格保证同一工程下所有素材风格一致；任务风格仅覆盖需要差异化的键。

-**三段式提示词结构**：
+**三段式提示词结构**（由 PromptAgent / LLM 生成）：

 ```
 【主题】用户的原始描述核心内容
-【约束】风格键值对生成的约束条件 + 负面提示词 + [重试时] 上次质检问题：{rejectReason}
-【内容】素材类型、分辨率、帧数等技术参数
+【风格】风格描述与视觉特征
+【技术】素材类型、分辨率、帧数等技术参数
 ```

 #### 2. AssetGenerator

- **输入**：PromptBuilder 的输出
+- **输入**：PromptOptimizer 的输出
 - **输出**：原始生成图片（单张或多张）
 - **职责**：调用 AI 推理 API 出图。不同素材类型的差异化需求已在上一步注入提示词中。
 - **接口规范**：统一采用 OpenAI 兼容的 `/v1/images/generations` 格式。多张生成通过 `n` 参数请求，实际支持数量取决于后端模型（如 DALL-E 3 仅支持 `n=1`，需多次调用模拟多张）。
@@ -100,7 +100,7 @@ finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)

 - **输入**：原始生成图片 + 风格配置
 - **输出**：通过 / 不通过 + 不通过的原因
- **职责**：通过视觉模型检查素材是否符合提示词要求与风格约束。不通过时，Graph 分支将 RejectReason 回填到 PipelineState，路由回 PromptBuilder 重新生成（最多 3 次，超过则降级输出）。
+- **职责**：通过视觉模型检查素材是否符合提示词要求与风格约束。不通过时，Graph 分支将 RejectReason 回填到 PipelineState，路由回 PromptOptimizer 重新生成（最多 3 次，超过则降级输出）。

 #### 4. FormatAdapter

@@ -128,7 +128,7 @@ type PipelineInput struct {
 // PipelineState Graph 全局状态，通过 WithGenLocalState 注入
 type PipelineState struct {
    Input        PipelineInput
-    FinalPrompt  string            // PromptBuilder 输出的三段式提示词
+    FinalPrompt  string            // PromptOptimizer 输出的三段式提示词
    RawImages    []GeneratedImage  // AssetGenerator 输出的原始图片
    PassQuality  bool              // QualitySupervisor 质检结果
    RejectReason string            // 质检不通过原因
@@ -146,7 +146,7 @@ type PipelineOutput struct {

 ```go
 const (
-    nodePromptBuilder      = "prompt_builder"
+    nodePromptOptimizer      = "prompt_optimizer"
    nodeAssetGenerator     = "asset_generator"
    nodeQualitySupervisor  = "quality_supervisor"
    nodeFormatAdapter      = "format_adapter"
@@ -160,7 +160,7 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {
    )

    // 添加节点
-    _ = g.AddLambdaNode(nodePromptBuilder, promptBuilderNode,
+    _ = g.AddLambdaNode(nodePromptOptimizer, promptBuilderNode,
        compose.WithStatePreHandler(promptBuilderPreHandler),   // 重试时注入 RejectReason
        compose.WithStatePostHandler(promptBuilderPostHandler))
    _ = g.AddLambdaNode(nodeAssetGenerator, assetGeneratorNode,
@@ -170,8 +170,8 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {
    _ = g.AddLambdaNode(nodeFormatAdapter, formatAdapterNode)

    // 连线：正常路径
-    _ = g.AddEdge(compose.START, nodePromptBuilder)
-    _ = g.AddEdge(nodePromptBuilder, nodeAssetGenerator)
+    _ = g.AddEdge(compose.START, nodePromptOptimizer)
+    _ = g.AddEdge(nodePromptOptimizer, nodeAssetGenerator)
    _ = g.AddEdge(nodeAssetGenerator, nodeQualitySupervisor)
    _ = g.AddEdge(nodeFormatAdapter, compose.END)

@@ -184,9 +184,9 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {
            if state.RetryCount >= 3 {
                return nodeFormatAdapter, nil // 超过重试次数，降级输出
            }
-            return nodePromptBuilder, nil // 重生成
+            return nodePromptOptimizer, nil // 重生成
        },
-        map[string]bool{nodePromptBuilder: true, nodeFormatAdapter: true},
+        map[string]bool{nodePromptOptimizer: true, nodeFormatAdapter: true},
    ))

    return g, nil
@@ -199,13 +199,13 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {

 | 节点 | Lambda 输入→输出 | State 交互 | 职责 |
 |------|-----------------|-----------|------|
-| PromptBuilder | `PipelineInput → string` | PreHandler 读取 RejectReason，PostHandler 写入 FinalPrompt | 合并风格 → 生成三段式提示词（重试时注入质检问题） |
+| PromptOptimizer | `PipelineInput → string` | PreHandler 读取 RejectReason，PostHandler 写入 FinalPrompt | 合并风格 → 生成三段式提示词（重试时注入质检问题） |
 | AssetGenerator | `string → []GeneratedImage` | PostHandler 写入 RawImages | 调用 AI 推理 API 出图 |
 | QualitySupervisor | `[]GeneratedImage → bool` | PostHandler 写入 PassQuality + RejectReason + RetryCount | 视觉模型质检 |
 | FormatAdapter | `[]GeneratedImage → PipelineOutput` | 无 | 格式转换、spritesheet 打包 |

 ```go
-// PromptBuilder 节点：接收输入，输出提示词
+// PromptOptimizer 节点：接收输入，输出提示词
 var promptBuilderNode = compose.InvokableLambda(func(ctx context.Context, in PipelineInput) (string, error) {
    return buildPrompt(in), nil
 })
@@ -263,7 +263,7 @@ func RunPipeline(ctx context.Context, in PipelineInput) (*PipelineOutput, error)
 | Project | 顶层容器，用户创建的项目 | 1──1 ProjectStyle, 1──N Task |
 | ProjectStyle | 工程级键值对风格配置，保证同一工程下所有素材风格一致 | 属于 Project |
 | Task | 工程下的单次生成请求，包含用户文本、素材类型、任务风格覆盖、技术参数、状态、结果 | 属于 Project, 1──N Asset |
-| Prompt | PromptBuilder 输出的三段式提示词（主题+约束+内容），管线中间产物，不持久化 | 由 Task 生成 |
+| Prompt | PromptOptimizer 输出的三段式提示词（主题+约束+内容），管线中间产物，不持久化 | 由 Task 生成 |
 | Asset | 生成结果素材，关联到任务，包含 URL、元数据（分辨率、帧数、格式） | 属于 Task |

 ER 关系图与外键约束详见 [数据存储 — ER 关系](database.md#er-关系)。
@@ -300,7 +300,7 @@ type TaskStyle struct {
 finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
 ```

-任务同名键覆盖工程风格，由 PromptBuilder 节点在生成提示词时执行合并。
+任务同名键覆盖工程风格，由 PromptOptimizer 节点在生成提示词时执行合并。

 ## 缓存层

@@ -130,7 +130,7 @@ sequenceDiagram

 | 阶段 | 说明 | ProgressBar 展示 |
 |------|------|-----------------|
-| `prompt_builder` | 合并风格，生成三段式提示词 | 第 1 步 |
+| `prompt_optimizer` | 调用 PromptAgent/LLM 优化提示词，合并风格 | 第 1 步 |
 | `asset_generator` | 调用 AI 推理 API 出图 | 第 2 步 |
 | `quality_supervisor` | 视觉模型质检 | 第 3 步（可能回退到第 1 步） |
 | `format_adapter` | 格式转换、spritesheet 打包 | 第 4 步 |
@@ -233,7 +233,7 @@ interface GenerationStore {
 }

 type PipelineStage =
-  | 'prompt_builder'
+  | 'prompt_optimizer'
  | 'asset_generator'
  | 'quality_supervisor'
  | 'format_adapter';