docs: 修改架构设计文档
This commit is contained in:
+44
-64
@@ -7,77 +7,55 @@ gen2d 是一个 AI 驱动的 2D 游戏素材生成工具。核心思路是采用
|
||||
## 整体架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Orchestrator │
|
||||
│ (生成任务编排主控 Agent) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│ │ │
|
||||
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
|
||||
│ 预处理 │ │ 生成执行 │ │ 后处理 │
|
||||
│ Agents │ │ Agents │ │ Agents │
|
||||
└─────────┘ └─────────┘ └─────────┘
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ PromptBuilder │ ──▶ │ AssetGenerator │ ──▶ │ PostProcess │
|
||||
│ (提示词工程) │ │ (AI 出图) │ │ (质检+格式适配) │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
三个 Agent 顺序执行，无需主控编排——上一步的输出即是下一步的输入。
|
||||
|
||||
---
|
||||
|
||||
## 一、处理前 — 提示词工程 & 风格注入
|
||||
|
||||
### 1.1 PromptRewriter Agent
|
||||
### 1.1 PromptBuilder Agent
|
||||
|
||||
- **职责**：将用户输入的简短/模糊提示词改写为高质量生成提示词
|
||||
- **输入**：用户原始文本 + 素材类型标签（sprite/tilemap/ui/background/effect）
|
||||
- **输出**：结构化生成提示词（含主体描述、风格描述、技术参数、负向提示词）
|
||||
- **策略**：
|
||||
- 补全缺失细节（如未指定视角则根据素材类型推断默认视角）
|
||||
将用户输入一次性加工为最终生成提示词，合并了原本分散在多个步骤中的提示词改写、风格注入、管线标签拼接。
|
||||
|
||||
- **输入**：用户原始文本 + 素材类型标签 + StyleSeed 对象 + 技术参数
|
||||
- **输出**：直接可用于 `AssetGenerator` 的完整提示词
|
||||
- **处理逻辑**：
|
||||
- 补全缺失细节（根据素材类型推断默认视角、构图等）
|
||||
- 注入游戏美术专用术语（pixel art / hand-drawn / vector flat 等）
|
||||
- 添加质量关键词（"masterpiece", "clean edges", "game-ready"）
|
||||
- 注入 StyleSeed 风格参数（色板、线条粗细、参考图特征向量）
|
||||
- 拼接管线兼容性标签（`--ar 1:1 --res 64x64 --format png --alpha` 等）
|
||||
- 添加质量关键词和负向提示词
|
||||
|
||||
### 1.2 StyleInjector Agent
|
||||
|
||||
- **职责**：将风格种子参数注入提示词，确保跨批次一致性
|
||||
- **输入**：改写后的提示词 + StyleSeed 对象
|
||||
- **输出**：带有风格约束的最终提示词
|
||||
- **StyleSeed 数据结构**：
|
||||
**StyleSeed 数据结构**（前端维护，透传至 PromptBuilder）：
|
||||
- `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）
|
||||
### 2.1 AssetGenerator（统一生成 Agent）
|
||||
|
||||
- **职责**：接收预处理后的任务，拆分子任务，调度生成 Agent，收集结果
|
||||
- **核心流程**：
|
||||
1. 解析用户请求，确定素材类型和数量（如"角色的8方向行走动画 × 4帧" → 32个子任务）
|
||||
2. 查询缓存（相同提示词+参数 → 直接返回）
|
||||
3. 将子任务入队，按优先级调度生成 Agent
|
||||
4. 返回 jobId，前端通过轮询/WebSocket 获取进度
|
||||
5. 所有子任务完成后触发后处理流程
|
||||
所有素材类型共用同一个生成 Agent，调用底层 AI 推理 API 出图。不同素材类型的差异化需求已在预处理阶段由 `PromptBuilder` 按 `assetType` 注入到提示词中，不体现在生成阶段。
|
||||
|
||||
### 2.2 生成 Agent 类型
|
||||
原本归属在"生成 Agent"上的特殊约束（帧间一致性、边缘拼接、UI 安全区、视差层、帧循环等），本质上是**后处理阶段**的验证和适配工作，应下沉到 `QualitySupervisor` 和 `FormatAdapter` 中按 `assetType` 做策略分发。
|
||||
|
||||
每种素材类型对应一个专精 Agent：
|
||||
### 2.2 序列帧生成策略
|
||||
|
||||
| Agent | 职责 | 特殊约束 |
|
||||
|-------|------|---------|
|
||||
| SpriteGenerator | 角色精灵、多帧动画序列 | 帧间一致性、锚点对齐 |
|
||||
| TilemapGenerator | 无缝地形瓦片 | 边缘无缝拼接验证 |
|
||||
| UIGenerator | 按钮、血条、对话框、图标 | UI 安全区、九宫格切片 |
|
||||
| BackgroundGenerator | 横版/俯视场景背景 | 视差层支持、滚动连续性 |
|
||||
| EffectGenerator | 火焰/烟雾/魔法粒子帧 | 帧动画循环、透明度渐变 |
|
||||
对于多帧动画（角色行走、特效等），逐帧独立生成容易出现帧间外观不一致。采用 **版图生成法**：
|
||||
|
||||
- AI 生成一张包含完整动作序列的大图（action plate），帧按网格排列
|
||||
- 后处理阶段由 `FormatAdapter` 按网格坐标切分为单帧
|
||||
- 一张版图内的角色外观、光影、比例天然一致
|
||||
|
||||
### 2.3 两阶段生成机制
|
||||
|
||||
@@ -106,6 +84,7 @@ gen2d 是一个 AI 驱动的 2D 游戏素材生成工具。核心思路是采用
|
||||
|
||||
- **职责**：将原始生成结果转换为游戏引擎可用的格式
|
||||
- **功能**：
|
||||
- **版图拆分**：将序列帧版图按网格切分为单帧（配合 2.2 版图生成法）
|
||||
- **SpriteSheet 打包**：将单帧图片合并为 spritesheet，生成 JSON/CSV 元数据（帧位置、尺寸、锚点、碰撞框）
|
||||
- **元数据生成**：
|
||||
```json
|
||||
@@ -183,27 +162,22 @@ gen2d 是一个 AI 驱动的 2D 游戏素材生成工具。核心思路是采用
|
||||
|
||||
---
|
||||
|
||||
## 五、后端 Service 层结构
|
||||
## 五、后端分层结构
|
||||
|
||||
```
|
||||
backend/internal/
|
||||
├── handler/ # HTTP handlers (薄层)
|
||||
│ ├── generate.go # 生成相关接口
|
||||
│ ├── style.go # 风格种子接口
|
||||
│ ├── cache.go # 缓存管理接口
|
||||
├── handler/ # HTTP handlers（薄层，只做参数绑定 + 调用 service）
|
||||
│ ├── generate.go # 生成任务提交 / 查询 / WebSocket
|
||||
│ ├── style.go # 风格种子 CRUD + 特征提取
|
||||
│ └── health.go # [已有] 健康检查
|
||||
├── service/ # 业务逻辑层
|
||||
│ ├── orchestrator.go # 主控 Agent：任务编排与调度
|
||||
│ ├── preprocess.go # 预处理：PromptRewriter + StyleInjector + TagInjector
|
||||
│ ├── generator.go # 生成器注册与调度
|
||||
│ ├── postprocess.go # 后处理：QualitySupervisor + FormatAdapter
|
||||
│ ├── style.go # 风格种子管理 & 特征提取
|
||||
│ └── inference.go # AI 模型调用封装
|
||||
├── model/ # 数据模型
|
||||
│ ├── pipeline.go # 核心管线：接收请求 → PromptBuilder → AssetGenerator → QualitySupervisor → FormatAdapter
|
||||
│ ├── inference.go # AI 推理 API 调用封装（可替换模型提供商）
|
||||
│ └── style.go # 风格种子管理 & 参考图特征提取
|
||||
├── model/ # 数据模型 / DTO
|
||||
│ ├── response.go # [已有] 统一响应
|
||||
│ ├── task.go # 生成任务模型
|
||||
│ ├── style.go # 风格种子模型
|
||||
│ └── asset.go # 素材模型
|
||||
│ ├── task.go # 生成任务 & 素材
|
||||
│ └── style.go # 风格种子
|
||||
├── middleware/ # 中间件
|
||||
│ ├── cors.go
|
||||
│ ├── logger.go
|
||||
@@ -212,10 +186,16 @@ backend/internal/
|
||||
│ └── config.go
|
||||
├── queue/ # 异步任务队列
|
||||
│ └── jobqueue.go
|
||||
└── cache/ # 缓存层
|
||||
└── cache/ # 缓存层（请求去重 + 结果缓存）
|
||||
└── cache.go
|
||||
```
|
||||
|
||||
### 分层原则
|
||||
|
||||
- **handler**：只做参数绑定、校验、调用 service、返回响应。一个 handler 对应一组 API 路由。
|
||||
- **service**：承载所有业务逻辑。`pipeline.go` 是唯一编排入口，不再拆分成 orchestrator/preprocess/generator/postprocess 四个文件——这些是同一根管线的顺序步骤，拆开反而增加耦合面。
|
||||
- **model**：纯数据结构，不含业务逻辑。
|
||||
|
||||
---
|
||||
|
||||
## 六、前端集成
|
||||
|
||||
Reference in New Issue
Block a user