120 lines
6.6 KiB
Markdown
Executable File
120 lines
6.6 KiB
Markdown
Executable File
# gen2d 架构设计
|
||
|
||
gen2d — AI 驱动的 2D 游戏素材生成工具。通过文本提示词生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧，无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流。
|
||
|
||
## 技术栈
|
||
|
||
Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 七牛云对象存储 / 可替换 AI 推理模型
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [后端工程](backend.md) | 分层结构、管线设计（PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter）、风格模型 |
|
||
| [前端工程](frontend.md) | 组件树、状态管理、路由、三栏工作台、自定义标签 |
|
||
| [API 设计](api.md) | 接口列表、请求/响应示例、错误码、认证 |
|
||
| [数据存储](database.md) | SQLite 选型、表结构、ER 关系、对象存储、去重策略 |
|
||
| [异步任务](async-tasks.md) | 任务生命周期、并发控制、重试策略、进度推送 |
|
||
| [预设风格键](style-keys.md) | 美术风格、色调、线条等风格键分类与可选值 |
|
||
| [架构图提示词](prompts/) | 全局/后端/前端架构图生成提示词，供多模态 AI 生成架构图 |
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Frontend (Vite + React) │
|
||
│ ┌─────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ │
|
||
│ │ 画廊页 │ │ 三栏工作台 │ │ 结果预览页 │ │ 登录注册 │ │
|
||
│ └─────────┘ └──────────┘ └────────────┘ └──────────┘ │
|
||
│ │ HTTP / WebSocket │
|
||
└──────────────────────┼──────────────────────────────────┘
|
||
│
|
||
┌──────────────────────┼──────────────────────────────────┐
|
||
│ Backend (Go + Gin + Eino) │
|
||
│ │ │
|
||
│ ┌───────────────────▼──────────────────────────────┐ │
|
||
│ │ Eino compose.Graph │ │
|
||
│ │ ┌──────────────┐ ┌──────────────┐ │ │
|
||
│ │ │PromptOptimizer│─▶│AssetGenerator│ │ │
|
||
│ │ └──────────────┘ └──────────────┘ │ │
|
||
│ │ ▲ │ │ │
|
||
│ │ │ ┌────────────▼──────────┐ │ │
|
||
│ │ │ │ QualitySupervisor │ │ │
|
||
│ │ │ └────────────┬──────────┘ │ │
|
||
│ │ │ pass │ fail (retry < 3) │ │
|
||
│ │ └────────────────┘ │ │
|
||
│ │ fail, retry ≥ 3 │ │
|
||
│ │ │ ┌──────────────┐ │ │
|
||
│ │ └─▶│FormatAdapter │ │ │
|
||
│ │ └──────────────┘ │ │
|
||
│ └────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────┼────────────┐ │
|
||
│ │ │ │ │
|
||
│ ┌────▼───┐ ┌─────▼────┐ ┌───▼──────┐ │
|
||
│ │ SQLite │ │ 七牛云 Kodo│ │ LLM API │ │
|
||
│ └────────┘ └──────────┘ └──────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 核心概念
|
||
|
||
### 生成管线（Pipeline）
|
||
|
||
基于 Eino `compose.Graph` 的四阶段管线。每个阶段是一个 Lambda 节点，通过 `StatePreHandler` / `StatePostHandler` 读写全局状态。质检不通过时，Graph 分支自动触发重优化，最多重试 3 次，超过后降级输出保证任务不阻塞。
|
||
|
||
详见 [后端工程](backend.md#多阶段生成管线)。
|
||
|
||
### 风格系统（Style）
|
||
|
||
风格分为两层：
|
||
|
||
- **工程风格（Project Style）**：工程级别的 kvPairs，保证同一工程下所有素材风格一致
|
||
- **任务风格覆盖（Task Style Override）**：单次生成任务的风格差异，仅覆盖需要变化的键
|
||
|
||
合并逻辑：`finalStyle = merge(projectStyle, taskStyle)`，任务同名键覆盖工程风格。
|
||
|
||
详见 [后端工程 — 风格模型](backend.md#风格模型) 和 [预设风格键](style-keys.md)。
|
||
|
||
### 任务系统（Task）
|
||
|
||
采用"提交-异步执行-轮询/推送"模式。API 同步返回 taskId，后台 goroutine 执行管线，前端通过 HTTP 轮询或 WebSocket 获取实时进度。
|
||
|
||
详见 [异步任务](async-tasks.md)。
|
||
|
||
### 数据模型
|
||
|
||
```
|
||
user 1──N project
|
||
project 1──1 project_style
|
||
project 1──N task
|
||
task 1──N asset
|
||
```
|
||
|
||
详见 [数据存储](database.md#er-关系)。
|
||
|
||
## 命令行参考
|
||
|
||
### 后端
|
||
|
||
```bash
|
||
cd backend
|
||
go mod tidy # 安装依赖
|
||
go run cmd/main.go # 开发服务器
|
||
go build -o bin/gen2d cmd/main.go # 构建
|
||
go test ./... # 全部测试
|
||
go test -run TestX ./internal/service/ # 单测
|
||
golangci-lint run # 代码检查
|
||
```
|
||
|
||
### 前端
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install # 安装依赖
|
||
npm run dev # 开发服务器
|
||
npm run build # 生产构建
|
||
npm run preview # 预览构建产物
|
||
npm run typecheck # 类型检查
|
||
```
|