gen2d/docs/architecture.md

gen2d 多智能体架构设计

概述

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

整体架构

┌─────────────────────────────────────────────────────────────────┐
│                         Orchestrator                            │
│                    (生成任务编排主控 Agent)                        │
└─────────────────────────────────────────────────────────────────┘
         │                    │                    │
    ┌────▼────┐          ┌────▼────┐          ┌────▼────┐
    │ 预处理   │          │ 生成执行  │          │ 后处理   │
    │ Agents  │          │ Agents  │          │ Agents  │
    └─────────┘          └─────────┘          └─────────┘

---

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

1.1 PromptRewriter Agent

• 职责：将用户输入的简短/模糊提示词改写为高质量生成提示词
• 输入：用户原始文本 + 素材类型标签（sprite/tilemap/ui/background/effect）
• 输出：结构化生成提示词（含主体描述、风格描述、技术参数、负向提示词）
• 策略：
  • 补全缺失细节（如未指定视角则根据素材类型推断默认视角）
  • 注入游戏美术专用术语（pixel art / hand-drawn / vector flat 等）
  • 添加质量关键词（"masterpiece", "clean edges", "game-ready"）

1.2 StyleInjector Agent

• 职责：将风格种子参数注入提示词，确保跨批次一致性
• 输入：改写后的提示词 + StyleSeed 对象
• 输出：带有风格约束的最终提示词
• StyleSeed 数据结构：
  • palette: 主色调 + 辅助色 + 高光/阴影色
  • lineWeight: 线条粗细等级
  • styleRef: 参考图特征向量（可选，来自用户上传的参考图）
  • resolution: 目标分辨率 (16/32/48/64/128/256)
  • artStyle: 美术风格枚举 (pixel/cartoon/hand-drawn/vector/flat)

1.3 TagInjector Agent

• 职责：注入管线兼容性标签和技术参数
• 注入内容：
  • 分辨率标签：--ar 1:1 --res 64x64（根据素材类型自动选择）
  • 格式标签：--format png --alpha
  • 引擎兼容标签：--spritesheet-ready, --tileable（瓦片类素材）
  • 命名标签：{category}_{name} 前缀

---

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

2.1 Orchestrator（主控 Agent）

• 职责：接收预处理后的任务，拆分子任务，调度生成 Agent，收集结果
• 核心流程：
  1. 解析用户请求，确定素材类型和数量（如"角色的8方向行走动画 × 4帧" → 32个子任务）
  2. 查询缓存（相同提示词+参数 → 直接返回）
  3. 将子任务入队，按优先级调度生成 Agent
  4. 返回 jobId，前端通过轮询/WebSocket 获取进度
  5. 所有子任务完成后触发后处理流程

2.2 生成 Agent 类型

每种素材类型对应一个专精 Agent：

Agent	职责	特殊约束
SpriteGenerator	角色精灵、多帧动画序列	帧间一致性、锚点对齐
TilemapGenerator	无缝地形瓦片	边缘无缝拼接验证
UIGenerator	按钮、血条、对话框、图标	UI 安全区、九宫格切片
BackgroundGenerator	横版/俯视场景背景	视差层支持、滚动连续性
EffectGenerator	火焰/烟雾/魔法粒子帧	帧动画循环、透明度渐变

2.3 两阶段生成机制

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

---

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

3.1 QualitySupervisor Agent

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

3.2 FormatAdapter Agent

• 职责：将原始生成结果转换为游戏引擎可用的格式
• 功能：
  • SpriteSheet 打包：将单帧图片合并为 spritesheet，生成 JSON/CSV 元数据（帧位置、尺寸、锚点、碰撞框）
  • 元数据生成：

    {
      "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/，统一响应格式：

{ "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)：

{
  "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	批量清除缓存

---

五、后端 Service 层结构

backend/internal/
├── handler/              # HTTP handlers (薄层)
│   ├── generate.go       # 生成相关接口
│   ├── style.go          # 风格种子接口
│   ├── cache.go          # 缓存管理接口
│   └── health.go         # [已有] 健康检查
├── service/              # 业务逻辑层
│   ├── orchestrator.go   # 主控 Agent：任务编排与调度
│   ├── preprocess.go     # 预处理：PromptRewriter + StyleInjector + TagInjector
│   ├── generator.go      # 生成器注册与调度
│   ├── postprocess.go    # 后处理：QualitySupervisor + FormatAdapter
│   ├── style.go          # 风格种子管理 & 特征提取
│   └── inference.go      # AI 模型调用封装
├── model/                # 数据模型
│   ├── response.go       # [已有] 统一响应
│   ├── task.go           # 生成任务模型
│   ├── style.go          # 风格种子模型
│   └── asset.go          # 素材模型
├── middleware/            # 中间件
│   ├── cors.go
│   ├── logger.go
│   └── ratelimit.go
├── config/               # [已有] 配置
│   └── config.go
├── queue/                # 异步任务队列
│   └── jobqueue.go
└── cache/                # 缓存层
    └── cache.go

---

六、前端集成

核心交互流程

用户输入提示词 → 选择风格种子 → 配置参数 → 提交生成
   → 轮询/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)