From 4f3598c521833bdcf879668a937884001e696ea3 Mon Sep 17 00:00:00 2001 From: wonder Date: Sat, 23 May 2026 18:49:50 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8B=86=E5=88=86=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3=E4=B8=BA=E5=A4=9A=E7=AF=87?= =?UTF-8?q?=E4=B8=93=E9=A1=B9=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/_index.md | 16 +++ docs/api.md | 103 ++++++++------- docs/architecture.md | 234 ----------------------------------- docs/async-tasks.md | 3 + docs/backend.md | 85 +++++++++++++ docs/database.md | 3 + docs/frontend.md | 208 +++++++++++++++++++++++++++++++ docs/multi-agent-pipeline.md | 73 +++++++++++ 8 files changed, 447 insertions(+), 278 deletions(-) create mode 100644 docs/_index.md delete mode 100644 docs/architecture.md create mode 100644 docs/async-tasks.md create mode 100644 docs/backend.md create mode 100644 docs/database.md create mode 100644 docs/frontend.md create mode 100644 docs/multi-agent-pipeline.md diff --git a/docs/_index.md b/docs/_index.md new file mode 100644 index 0000000..5e243e0 --- /dev/null +++ b/docs/_index.md @@ -0,0 +1,16 @@ +# gen2d 架构设计 + +gen2d — AI 驱动的 2D 游戏素材生成工具。通过文本提示词生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧，无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流。 + +## 技术栈 + +Go + Gin / Vite + React + TypeScript + zustand / 可替换 AI 推理模型 + +## 文档索引 + +- [多智能体生成管线](multi-agent-pipeline.md) — PromptBuilder → AssetGenerator → QualitySupervisor → FormatAdapter 三阶段流水线 +- [后端工程](backend.md) — 分层结构、目录组织、分层原则 +- [前端工程](frontend.md) — 组件树、状态管理、路由、WebSocket 通信 +- [异步任务](async-tasks.md) — 任务队列、状态机、并发控制、失败重试 +- [数据存储](database.md) — 数据库选型、表结构、素材文件存储 +- [API 设计](api.md) — 接口列表、请求/响应示例、实现状态 diff --git a/docs/api.md b/docs/api.md index 6d238fb..1b8b30c 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,62 +1,77 @@ -# gen2d API 文档 +# gen2d API 设计 -Base URL: `http://localhost:8080` - -## 统一响应格式 - -所有接口均返回以下 JSON 结构： +所有接口统一前缀 `/api/v1/`，统一响应格式： ```json -{ - "code": 0, - "message": "ok", - "data": {} -} +{ "code": 0, "message": "ok", "data": {} } ``` -| 字段 | 类型 | 说明 | -| --------- | ------ | -------------------------------------- | -| `code` | int | 业务状态码。`0` 表示成功，非零为错误码 | -| `message` | string | 状态描述 | -| `data` | any | 响应数据，错误时可能不返回此字段 | +## 状态说明 -### 成功响应 - -```json -{ - "code": 0, - "message": "ok", - "data": { ... } -} -``` - -### 错误响应 - -```json -{ - "code": 400, - "message": "error description" -} -``` +- [x] 已完成 +- [ ] 规划中 --- -## 接口列表 +## 基础设施 -### 健康检查 +| 状态 | 方法 | 路径 | 说明 | +|------|------|------|------| +| [x] | GET | `/api/v1/health` | 健康检查 | -``` -GET /api/v1/health -``` +## 素材生成 -**响应示例** +| 状态 | 方法 | 路径 | 说明 | +|------|------|------|------| +| [ ] | 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 { - "code": 0, - "message": "ok", - "data": { - "status": "healthy" + "prompt": "一个拿剑的小人", + "assetType": "sprite", + "taskStyle": { + "scene": "dungeon", + "mood": "dark" + }, + "params": { + "resolution": 64, + "frames": { "directions": 8, "framesPerDirection": 4 }, + "format": "spritesheet" } } ``` + +- `prompt`：用户原始文本，后端 PromptBuilder 负责三段式重写 +- `taskStyle`：可选，任务级别风格覆盖（同名键覆盖工程风格） + +## 工程风格 + +| 状态 | 方法 | 路径 | 说明 | +|------|------|------|------| +| [ ] | GET | `/api/v1/projects/:projectId/style` | 获取工程风格 | +| [ ] | PUT | `/api/v1/projects/:projectId/style` | 更新工程风格 | + +请求体示例 (PUT /api/v1/projects/:projectId/style)： + +```json +{ + "kvPairs": { + "artStyle": "pixel", + "palette": "warm", + "lineWeight": "thin", + "lighting": "bright" + } +} +``` + +## 缓存管理 + +| 状态 | 方法 | 路径 | 说明 | +|------|------|------|------| +| [ ] | DELETE | `/api/v1/cache/:key` | 清除特定缓存 | +| [ ] | POST | `/api/v1/cache/clear` | 批量清除缓存 | diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index 5242009..0000000 --- a/docs/architecture.md +++ /dev/null @@ -1,234 +0,0 @@ -# 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) diff --git a/docs/async-tasks.md b/docs/async-tasks.md new file mode 100644 index 0000000..a110dec --- /dev/null +++ b/docs/async-tasks.md @@ -0,0 +1,3 @@ +# 异步任务 + +> 待补充：任务队列设计、状态机、并发控制、失败重试策略。 diff --git a/docs/backend.md b/docs/backend.md new file mode 100644 index 0000000..518374e --- /dev/null +++ b/docs/backend.md @@ -0,0 +1,85 @@ +# 后端工程 + +## 分层结构 + +``` +backend/internal/ +├── handler/ # HTTP handlers（薄层，只做参数绑定 + 调用 service） +│ ├── generate.go # 生成任务提交 / 查询 / WebSocket +│ ├── project_style.go # 工程风格 CRUD +│ └── health.go # [已有] 健康检查 +├── service/ # 业务逻辑层 +│ ├── pipeline.go # 核心管线：接收请求 → PromptBuilder → AssetGenerator → QualitySupervisor → FormatAdapter +│ ├── inference.go # AI 推理 API 调用封装（可替换模型提供商） +│ └── project_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**：纯数据结构，不含业务逻辑。 + +## 关键实体 + +| 实体 | 说明 | 关系 | +|------|------|------| +| Project | 顶层容器，用户创建的项目 | 1──1 ProjectStyle, 1──N Task | +| ProjectStyle | 工程级键值对风格配置，保证同一工程下所有素材风格一致 | 属于 Project | +| Task | 工程下的单次生成请求，包含用户文本、素材类型、任务风格覆盖、技术参数、状态、结果 | 属于 Project, 1──N Asset | +| Prompt | PromptBuilder 输出的三段式提示词（主题+约束+内容），管线中间产物，不持久化 | 由 Task 生成 | +| Asset | 生成结果素材，关联到任务，包含 URL、元数据（分辨率、帧数、格式） | 属于 Task | + +``` +Project 1──1 ProjectStyle +Project 1──N Task +Task 1──N Asset +``` + +## 风格模型 + +### 工程风格（Project Style） + +工程级别，保证同一工程下所有素材风格一致： + +```go +type ProjectStyle struct { + ID string `json:"id"` + ProjectID string `json:"projectId"` + KVPairs map[string]string `json:"kvPairs"` // 如 {"artStyle":"pixel","palette":"warm"} + CreatedAt time.Time `json:"createdAt"` + UpdatedAt time.Time `json:"updatedAt"` +} +``` + +### 任务风格覆盖（Task Style Override） + +任务级别，仅覆盖需要差异化的键： + +```go +type TaskStyle struct { + KVPairs map[string]string `json:"kvPairs"` // 仅记录与工程风格不同的部分 +} +``` + +### 合并逻辑 + +``` +finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs) +``` + +任务同名键覆盖工程风格，由 PromptBuilder 在生成提示词时执行合并。 diff --git a/docs/database.md b/docs/database.md new file mode 100644 index 0000000..250c686 --- /dev/null +++ b/docs/database.md @@ -0,0 +1,3 @@ +# 数据存储 + +> 待补充：数据库选型、表结构设计、素材文件存储方案。 diff --git a/docs/frontend.md b/docs/frontend.md new file mode 100644 index 0000000..7229fa2 --- /dev/null +++ b/docs/frontend.md @@ -0,0 +1,208 @@ +# 前端工程 + +## 技术栈 + +Vite 6 + React 18 + TypeScript + zustand + react-router-dom + +| 类别 | 选型 | 说明 | +|------|------|------| +| 构建 | Vite 6 | 开发服务器端口 3000，`/api` 代理到 `localhost:8080` | +| UI 框架 | React 18 | 函数组件 + Hooks | +| 状态管理 | zustand | 轻量，支持 devtools 中间件 | +| 路由 | react-router-dom v6 | SPA 模式 | +| 实时通信 | 原生 WebSocket | 连接后端 `/api/v1/generate/:jobId/ws` | +| HTTP 请求 | fetch + 封装层 | 统一错误处理、响应解包 | + +## 目录结构 + +``` +frontend/src/ +├── main.tsx # 入口 +├── App.tsx # 根组件 + 路由配置 +├── api/ # API 封装层 +│ ├── client.ts # fetch 封装：baseURL、统一错误处理、响应解包 +│ ├── generate.ts # POST /generate、GET /generate/:jobId、GET /generate/:jobId/result +│ ├── project.ts # GET/PUT /projects/:projectId/style +│ └── types.ts # API 请求/响应类型定义（Task、Asset、Style、JobStatus 等） +├── stores/ # zustand stores +│ ├── project.ts # 工程风格（从 API 加载 + 本地编辑 + 持久化回写） +│ ├── task.ts # 当前任务草稿（用户文本、素材类型、任务风格覆盖、技术参数） +│ └── generation.ts # 生成状态（jobId、进度、阶段、结果、错误） +├── pages/ # 页面级组件 +│ ├── ProjectPage.tsx # 工程首页：工程风格配置 + 任务列表 +│ ├── GeneratePage.tsx # 生成页：提示词构建 + 提交 +│ └── ResultPage.tsx # 结果页：素材预览 + 下载 + 元数据 +├── components/ # 可复用组件 +│ ├── StyleSelector.tsx # 风格选择器 +│ ├── PromptEditor.tsx # 三段式提示词编辑器 +│ ├── GenerateForm.tsx # 生成表单 +│ ├── ProgressBar.tsx # 管线进度条（显示当前阶段） +│ └── AssetPreview.tsx # 素材预览（spritesheet 预览、单帧预览） +├── hooks/ # 自定义 Hooks +│ ├── useGenerate.ts # 提交生成任务 + WebSocket 订阅进度 +│ └── useProjectStyle.ts # 工程风格加载/保存 +├── router/ # 路由定义 +│ └── index.tsx +└── utils/ # 工具函数 + └── style.ts # 风格合并逻辑（与后端保持一致的 merge 算法） +``` + +## 路由规划 + +| 路径 | 页面 | 说明 | +|------|------|------| +| `/` | — | 重定向到默认工程 | +| `/projects/:projectId` | ProjectPage | 工程首页，配置工程风格，查看历史任务 | +| `/projects/:projectId/generate` | GeneratePage | 提示词构建 + 提交生成 | +| `/projects/:projectId/tasks/:taskId` | ResultPage | 任务结果页，预览素材、下载 | + +## 组件树 + +``` + + + + # 工程风格编辑 + # 历史任务列表 + + + + # sprite / background / UI / animation + # 任务风格覆盖（基于工程风格，高亮差异） + # 三段式提示词预览 & 编辑 + # 分辨率、帧数等技术参数 + + # 提交后显示管线进度 + + + # 素材预览 + # 元数据展示 + # 下载素材 + + + +``` + +## 核心交互流程 + +### 生成流程 + +``` +1. 用户进入 GeneratePage +2. 填写文本描述（prompt） +3. 选择素材类型（sprite / background / UI / animation） +4. StyleSelector 展示工程风格，用户可点选覆盖（任务风格） +5. PromptEditor 实时预览三段式提示词： + - 【主题】从用户文本提取 + - 【约束】从风格选择自动生成（含负面提示词） + - 【内容】从素材类型 + 技术参数生成 +6. 用户确认后提交 +7. 前端 POST /api/v1/generate → 获取 jobId +8. 建立 WebSocket 连接 /api/v1/generate/:jobId/ws +9. ProgressBar 实时显示管线阶段：PromptBuilder → AssetGenerator → QualitySupervisor → FormatAdapter +10. 管线完成后跳转 ResultPage +``` + +### WebSocket 消息格式 + +```typescript +interface PipelineProgress { + stage: 'prompt_builder' | 'asset_generator' | 'quality_supervisor' | 'format_adapter'; + status: 'running' | 'completed' | 'failed'; + progress: number; // 0-100 + message?: string; // 阶段描述 + result?: { // 仅在 format_adapter completed 时返回 + assets: Asset[]; + }; + error?: string; // 仅在 failed 时返回 +} +``` + +### 风格编辑流程 + +``` +1. 用户进入 ProjectPage +2. StyleSelector 从 API 加载工程风格（GET /projects/:id/style） +3. 用户按分类点选风格键值对（美术风格、色调、线条、场景、光照、情绪） +4. 实时展示当前风格配置 +5. 保存 → PUT /projects/:id/style +6. 工程风格持久化到后端，后续生成任务自动继承 +``` + +## 状态管理 + +### zustand stores + +**project store** — 工程风格 + +```typescript +interface ProjectStore { + projectId: string; + style: Record; // kvPairs + loading: boolean; + loadStyle: (projectId: string) => Promise; + updateStyle: (kvPairs: Record) => void; + saveStyle: () => Promise; +} +``` + +**task store** — 任务草稿 + +```typescript +interface TaskStore { + prompt: string; + assetType: 'sprite' | 'background' | 'ui' | 'animation'; + taskStyle: Record; // 仅覆盖的键 + params: { + resolution: number; + frames?: { directions: number; framesPerDirection: number }; + format: string; + }; + setPrompt: (text: string) => void; + setAssetType: (type: string) => void; + toggleTaskStyle: (key: string, value: string) => void; + setParams: (params: Partial) => void; + reset: () => void; +} +``` + +**generation store** — 生成状态 + +```typescript +interface GenerationStore { + jobId: string | null; + stage: PipelineProgress['stage'] | null; + progress: number; + status: 'idle' | 'submitting' | 'running' | 'completed' | 'failed'; + assets: Asset[]; + error: string | null; + submit: (projectId: string, task: TaskStore) => Promise; + reset: () => void; +} +``` + +## API 封装 + +`api/client.ts` 统一封装： + +- baseURL 从环境变量读取，开发模式默认 `/api/v1` +- 所有响应按 `{ code, message, data }` 解包，`code !== 0` 时抛错 +- 统一 401/403/500 错误处理 +- WebSocket 连接封装为 `createJobSocket(jobId)` 返回可订阅对象 + +## 预设风格键分类 + +前端 StyleSelector 以分类标签组织，用户点选： + +| 分类 | 键名 | 可选值 | +|------|------|--------| +| 美术风格 | `artStyle` | pixel, cartoon, hand-drawn, vector, flat | +| 色调 | `palette` | warm, cool, neutral, vibrant, muted, monochrome | +| 线条 | `lineWeight` | none, thin, medium, thick | +| 场景 | `scene` | forest, dungeon, city, space, underwater, desert | +| 光照 | `lighting` | bright, dim, dramatic, ambient, neon | +| 情绪 | `mood` | cheerful, dark, mysterious, epic, calm | + +StyleSelector 两种使用场景： +1. **工程风格**（ProjectPage）：全量编辑，保存到后端 +2. **任务覆盖**（GeneratePage）：基于工程风格展示，高亮已覆盖的键，仅记录差异 diff --git a/docs/multi-agent-pipeline.md b/docs/multi-agent-pipeline.md new file mode 100644 index 0000000..c5355de --- /dev/null +++ b/docs/multi-agent-pipeline.md @@ -0,0 +1,73 @@ +# 多阶段生成管线 + +gen2d 的核心生成流程采用四阶段顺序管线，上一步输出即下一步输入，无需编排。 + +```mermaid +flowchart LR + A["PromptBuilder\n(提示词工程)"] --> B["AssetGenerator\n(AI 出图)"] + B --> C["QualitySupervisor\n(质检)"] + C --> D["FormatAdapter\n(格式适配)"] +``` + +--- + +## 1. PromptBuilder + +- **输入**：用户文本 + 素材类型标签 + 工程风格 + 任务风格覆盖 + 技术参数 +- **输出**：三段式完整生成提示词 +- **职责**： + 1. 解析用户文本，提取核心内容作为【主题】 + 2. 合并工程风格与任务风格覆盖（任务同名键覆盖工程），生成【约束】（含负面提示词） + 3. 注入素材类型、分辨率等技术参数作为【内容】 + 4. 拼接为最终提示词 + +### 风格合并 + +```go +finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs) +``` + +工程风格保证同一工程下所有素材风格一致；任务风格仅覆盖需要差异化的键。 + +### 三段式提示词结构 + +``` +【主题】用户的原始描述核心内容 +【约束】风格键值对生成的约束条件 + 负面提示词 +【内容】素材类型、分辨率、帧数等技术参数 +``` + +## 2. AssetGenerator + +- **输入**：PromptBuilder 的输出 +- **输出**：原始生成图片（单张或多张） +- **职责**：调用 AI 推理 API 出图。不同素材类型的差异化需求已在上一步注入提示词中。 + +## 3. QualitySupervisor + +- **输入**：原始生成图片 + 风格配置 +- **输出**：质量评分 + 是否通过 +- **职责**：评估素材质量，不通过则触发重新生成（最多 3 次）。 + +## 4. FormatAdapter + +- **输入**：通过质检的图片 + 素材类型 +- **输出**：游戏引擎可用的素材文件 + 元数据 +- **职责**：格式转换、spritesheet 打包、元数据生成。 + +--- + +## 预设风格键分类 + +前端以分类标签组织，用户点选： + +| 分类 | 键名 | 可选值示例 | +|------|------|-----------| +| 美术风格 | `artStyle` | pixel, cartoon, hand-drawn, vector, flat | +| 色调 | `palette` | warm, cool, neutral, vibrant, muted, monochrome | +| 线条 | `lineWeight` | none, thin, medium, thick | +| 场景 | `scene` | forest, dungeon, city, space, underwater, desert | +| 光照 | `lighting` | bright, dim, dramatic, ambient, neon | +| 情绪 | `mood` | cheerful, dark, mysterious, epic, calm | + +（具体键值后续可扩展，这里是初始集合）