diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..e9bcb26 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,254 @@ +# 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 元数据（帧位置、尺寸、锚点、碰撞框） + - **元数据生成**： + ```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` | 批量清除缓存 | + +--- + +## 五、后端 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)