diff --git a/docs/architecture.md b/docs/architecture.md index e9bcb26..5242009 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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**:纯数据结构,不含业务逻辑。 + --- ## 六、前端集成