gen2d/docs/architecture.md

# gen2d 多智能体架构设计

## 概述

gen2d 是一个 AI 驱动的 2D 游戏素材生成工具。核心思路是采用**多智能体协作流水线**，将素材生成拆分为 **处理前 → 处理中 → 处理后** 三个阶段，每个阶段由专门的 subagent 负责。

## 整体架构

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  PromptBuilder │ ──▶ │ AssetGenerator │ ──▶ │  PostProcess  │
│   (提示词工程)  │     │   (AI 出图)    │     │ (质检+格式适配) │
└──────────────┘     └──────────────┘     └──────────────┘
```

三个 Agent 顺序执行，无需主控编排——上一步的输出即是下一步的输入。

---

## 一、处理前 — 提示词工程 & 风格注入

### 1.1 PromptBuilder Agent

将用户输入一次性加工为最终生成提示词，合并了原本分散在多个步骤中的提示词改写、风格注入、管线标签拼接。

- **输入**：用户原始文本 + 素材类型标签 + StyleSeed 对象 + 技术参数
- **输出**：直接可用于 `AssetGenerator` 的完整提示词
- **处理逻辑**：
  - 补全缺失细节（根据素材类型推断默认视角、构图等）
  - 注入游戏美术专用术语（pixel art / hand-drawn / vector flat 等）
  - 注入 StyleSeed 风格参数（色板、线条粗细、参考图特征向量）
  - 拼接管线兼容性标签（`--ar 1:1 --res 64x64 --format png --alpha` 等）
  - 添加质量关键词和负向提示词

**StyleSeed 数据结构**（前端维护，透传至 PromptBuilder）：
  - `palette`: 主色调 + 辅助色 + 高光/阴影色
  - `lineWeight`: 线条粗细等级
  - `styleRef`: 参考图特征向量（可选，来自用户上传的参考图）
  - `resolution`: 目标分辨率 (16/32/48/64/128/256)
  - `artStyle`: 美术风格枚举 (pixel/cartoon/hand-drawn/vector/flat)

---

## 二、处理时 — 生成 & 风格控制

### 2.1 AssetGenerator（统一生成 Agent）

所有素材类型共用同一个生成 Agent，调用底层 AI 推理 API 出图。不同素材类型的差异化需求已在预处理阶段由 `PromptBuilder` 按 `assetType` 注入到提示词中，不体现在生成阶段。

原本归属在"生成 Agent"上的特殊约束（帧间一致性、边缘拼接、UI 安全区、视差层、帧循环等），本质上是**后处理阶段**的验证和适配工作，应下沉到 `QualitySupervisor` 和 `FormatAdapter` 中按 `assetType` 做策略分发。

### 2.2 序列帧生成策略

对于多帧动画（角色行走、特效等），逐帧独立生成容易出现帧间外观不一致。采用 **版图生成法**：

- AI 生成一张包含完整动作序列的大图（action plate），帧按网格排列
- 后处理阶段由 `FormatAdapter` 按网格坐标切分为单帧
- 一张版图内的角色外观、光影、比例天然一致

### 2.3 两阶段生成机制

- **Phase 1 — 低分辨率预览**：以目标分辨率的 1/4 快速生成缩略图，用户确认方向
- **Phase 2 — 高分辨率出图**：确认后生成全分辨率素材
- 减少无效生成消耗，节省 API 调用成本

---

## 三、处理后 — 质量监督 & 管线适配

### 3.1 QualitySupervisor Agent

- **职责**：评估生成素材质量，决定是否需要重新生成
- **检查维度**：
  - 边缘清晰度（无模糊/锯齿）
  - Alpha 通道正确性（背景是否完全透明）
  - 风格一致性（与 StyleSeed 的偏差是否在阈值内）
  - 分辨率匹配（输出尺寸是否与目标一致）
  - 帧完整性（多帧素材是否缺帧）
  - 无缝拼接（瓦片类素材的四边连接测试）
- **输出**：每张素材的质量评分 (0-100) + 问题描述
- **决策**：评分 < 阈值 → 自动触发重新生成（最多重试 3 次）

### 3.2 FormatAdapter Agent

- **职责**：将原始生成结果转换为游戏引擎可用的格式
- **功能**：
  - **版图拆分**：将序列帧版图按网格切分为单帧（配合 2.2 版图生成法）
  - **SpriteSheet 打包**：将单帧图片合并为 spritesheet，生成 JSON/CSV 元数据（帧位置、尺寸、锚点、碰撞框）
  - **元数据生成**：
    ```json
    {
      "frames": [
        {
          "name": "walk_down_0",
          "rect": [0, 0, 64, 64],
          "anchor": [32, 56],
          "duration": 100
        }
      ],
      "meta": { "size": [512, 512], "format": "RGBA8888" }
    }
    ```
  - **引擎导出**：可选生成 `.aseprite` 元数据或 Unity `.meta` 文件
  - **命名规范化**：确保输出遵循 `{category}_{name}_{index}.png`

### 3.3 Cache & Dedup

- **请求去重**：相同 `(提示词, 参数, StyleSeed)` 的生成请求直接返回缓存结果
- **缓存分层**：
  - L1: 内存 LRU（热点素材快速响应）
  - L2: 本地文件/对象存储（持久化，跨实例共享）

---

## 四、API 设计

所有接口统一前缀 `/api/v1/`，统一响应格式：

```json
{ "code": 0, "message": "ok", "data": {} }
```

### 4.1 素材生成

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/generate` | 提交生成任务，返回 jobId |
| GET | `/api/v1/generate/:jobId` | 查询任务状态与进度 |
| GET | `/api/v1/generate/:jobId/result` | 获取生成结果（素材 URL + 元数据） |
| WS | `/api/v1/generate/:jobId/ws` | WebSocket 实时进度推送 |

请求体示例 (POST /api/v1/generate)：

```json
{
  "prompt": "a brave knight in shining armor",
  "assetType": "sprite",
  "styleSeedId": "seed_abc123",
  "params": {
    "resolution": 64,
    "frames": { "directions": 8, "framesPerDirection": 4 },
    "format": "spritesheet"
  }
}
```

### 4.2 风格管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/style/seed` | 创建风格种子（可上传参考图） |
| GET | `/api/v1/style/seed/:id` | 获取风格种子详情 |
| GET | `/api/v1/style/seeds` | 列出所有风格种子 |
| POST | `/api/v1/style/extract` | 从参考图提取风格特征向量 |

### 4.3 缓存管理

| 方法 | 路径 | 说明 |
|------|------|------|
| DELETE | `/api/v1/cache/:key` | 清除特定缓存 |
| POST | `/api/v1/cache/clear` | 批量清除缓存 |

---

## 五、后端分层结构

```
backend/internal/
├── handler/              # HTTP handlers（薄层，只做参数绑定 + 调用 service）
│   ├── generate.go       # 生成任务提交 / 查询 / WebSocket
│   ├── style.go          # 风格种子 CRUD + 特征提取
│   └── health.go         # [已有] 健康检查
├── service/              # 业务逻辑层
│   ├── pipeline.go       # 核心管线：接收请求 → PromptBuilder → AssetGenerator → QualitySupervisor → FormatAdapter
│   ├── inference.go      # AI 推理 API 调用封装（可替换模型提供商）
│   └── style.go          # 风格种子管理 & 参考图特征提取
├── model/                # 数据模型 / DTO
│   ├── response.go       # [已有] 统一响应
│   ├── task.go           # 生成任务 & 素材
│   └── style.go          # 风格种子
├── middleware/            # 中间件
│   ├── cors.go
│   ├── logger.go
│   └── ratelimit.go
├── config/               # [已有] 配置
│   └── config.go
├── queue/                # 异步任务队列
│   └── jobqueue.go
└── cache/                # 缓存层（请求去重 + 结果缓存）
    └── cache.go
```

### 分层原则

- **handler**：只做参数绑定、校验、调用 service、返回响应。一个 handler 对应一组 API 路由。
- **service**：承载所有业务逻辑。`pipeline.go` 是唯一编排入口，不再拆分成 orchestrator/preprocess/generator/postprocess 四个文件——这些是同一根管线的顺序步骤，拆开反而增加耦合面。
- **model**：纯数据结构，不含业务逻辑。

---

## 六、前端集成

### 核心交互流程

```
用户输入提示词 → 选择风格种子 → 配置参数 → 提交生成
   → 轮询/WebSocket 进度 → 预览缩略图 → 确认/调整 → 下载素材包
```

### 关键组件树

```
App
├── AssetGenerator        # 生成工作台（主页面）
│   ├── PromptInput       # 提示词输入 + 素材类型选择
│   ├── StyleSelector     # 风格种子选择器（含预览色板）
│   ├── ParamPanel        # 参数面板（分辨率/帧数/格式/引擎）
│   └── ReferenceUpload   # 参考图上传
├── GenerationProgress    # 生成进度展示
│   ├── ProgressBar       # 总进度
│   ├── ThumbnailGrid     # 缩略图网格（低分辨率预览）
│   └── AssetCard         # 单张素材预览 + 质量评分
├── StyleManager          # 风格种子管理
│   └── StylePalette      # 色板可视化
└── ExportPanel           # 导出面板
    ├── FormatSelector    # 格式选择（spritesheet/json/unity/godot）
    └── DownloadButton    # 打包下载
```

### 状态管理 (zustand)

- `useGenerationStore` — 生成任务队列、进度、结果
- `useStyleStore` — 风格种子列表、当前选中风格
- `useWebSocket` — WebSocket 连接管理 (自定义 hook)