gen2d/docs/multi-agent-pipeline.md

# 多阶段生成管线

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

```mermaid
flowchart LR
    A["PromptBuilder\n(提示词工程)"] --> B["AssetGenerator\n(AI 出图)"]
    B --> C["QualitySupervisor\n(质检)"]
    C -- pass --> D["FormatAdapter\n(格式适配)"]
    C -- fail --> A
```

---

## 1. PromptBuilder

- **输入**：用户文本 + 素材类型标签 + 工程风格 + 任务风格覆盖 + 技术参数
- **输出**：三段式完整生成提示词
- **职责**：
  1. 解析用户文本，提取核心内容作为【主题】
  2. 合并工程风格与任务风格覆盖（任务同名键覆盖工程），生成【约束】（含负面提示词）
  3. 注入素材类型、分辨率等技术参数作为【内容】
  4. 拼接为最终提示词

### 风格合并

```go
finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
```

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

### 三段式提示词结构

```
【主题】用户的原始描述核心内容
【约束】风格键值对生成的约束条件 + 负面提示词
【内容】素材类型、分辨率、帧数等技术参数
```

## 2. AssetGenerator

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

## 3. QualitySupervisor

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

## 4. FormatAdapter

- **输入**：通过质检的图片 + 素材类型
- **输出**：游戏引擎可用的素材文件 + 元数据
- **职责**：格式转换、spritesheet 打包、元数据生成。
- **示例**：输入 4 张 64×64 的角色行走帧 PNG → 输出一张 256×64 的 spritesheet + JSON 元数据（帧尺寸、帧数、锚点偏移），可直接拖入 Unity 2D Animation 使用。