docs: 拆分架构设计文档为多篇专项文档

2026-05-23 18:49:50 +08:00
parent e63165f898
commit 4f3598c521
8 changed files with 447 additions and 278 deletions
@@ -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) — 接口列表、请求/响应示例、实现状态
@@ -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` | 批量清除缓存 |
@@ -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)
@@ -0,0 +1,3 @@
+# 异步任务
+
+> 待补充：任务队列设计、状态机、并发控制、失败重试策略。
@@ -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 在生成提示词时执行合并。
@@ -0,0 +1,3 @@
+# 数据存储
+
+> 待补充：数据库选型、表结构设计、素材文件存储方案。
@@ -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 | 任务结果页，预览素材、下载 |
+
+## 组件树
+
+```
+<App>
+  <Router>
+    <ProjectPage>
+      <StyleSelector />          # 工程风格编辑
+      <TaskList />               # 历史任务列表
+    </ProjectPage>
+    <GeneratePage>
+      <GenerateForm>
+        <AssetTypePicker />      # sprite / background / UI / animation
+        <StyleSelector />        # 任务风格覆盖（基于工程风格，高亮差异）
+        <PromptEditor />         # 三段式提示词预览 & 编辑
+        <ParamsForm />           # 分辨率、帧数等技术参数
+      </GenerateForm>
+      <ProgressBar />            # 提交后显示管线进度
+    </GeneratePage>
+    <ResultPage>
+      <AssetPreview />           # 素材预览
+      <MetadataPanel />          # 元数据展示
+      <DownloadButton />         # 下载素材
+    </ResultPage>
+  </Router>
+</App>
+```
+
+## 核心交互流程
+
+### 生成流程
+
+```
+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<string, string>;  // kvPairs
+  loading: boolean;
+  loadStyle: (projectId: string) => Promise<void>;
+  updateStyle: (kvPairs: Record<string, string>) => void;
+  saveStyle: () => Promise<void>;
+}
+```
+
+**task store** — 任务草稿
+
+```typescript
+interface TaskStore {
+  prompt: string;
+  assetType: 'sprite' | 'background' | 'ui' | 'animation';
+  taskStyle: Record<string, string>;  // 仅覆盖的键
+  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<TaskStore['params']>) => 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<void>;
+  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）：基于工程风格展示，高亮已覆盖的键，仅记录差异
@@ -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 |
+
+（具体键值后续可扩展，这里是初始集合）