docs: 全面优化 README.md

基于仓库代码与 docs/ 文档综合重写 README:
- 新增特性概览、技术栈表格、架构管线图、风格系统、部署说明
- 补充 Eino / License 徽章,修正版本号
- 配置表默认值与 config.yml 实际值对齐(DeepSeek)
- 项目结构树反映实际目录与关键文件
- API 部分区分已实现与规划中,补充 WebSocket 说明
This commit is contained in:
2026-05-25 11:18:23 +08:00
parent 6254433728
commit 6932b20152
+174 -115
View File
@@ -1,49 +1,45 @@
# gen2d # gen2d
AI 驱动的 2D 游戏素材生成工具。通过文本提示词或可视化参数,快速生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧。支持 Unity / Godot 一键集成。 AI 驱动的 2D 游戏素材生成工具。通过文本提示词或可视化参数,生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧,无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流。
[![Go](https://img.shields.io/badge/Go-00ADD8?logo=go&logoColor=white)](https://go.dev/) [![Go](https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white)](https://go.dev/)
[![Gin](https://img.shields.io/badge/Gin-008ECF?logo=gin&logoColor=white)](https://gin-gonic.com/) [![Gin](https://img.shields.io/badge/Gin-1.12-008ECF?logo=gin&logoColor=white)](https://gin-gonic.com/)
[![React](https://img.shields.io/badge/React-61DAFB?logo=react&logoColor=black)](https://react.dev/) [![Eino](https://img.shields.io/badge/Eino-0.8-blue)](https://github.com/cloudwego/eino)
[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![React](https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=black)](https://react.dev/)
[![Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white)](https://vite.dev/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Vite](https://img.shields.io/badge/Vite-6-646CFF?logo=vite&logoColor=white)](https://vite.dev/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
### **[在线体验 http://47.121.181.112:10000](http://47.121.181.112:10000)** ### **[在线体验 http://47.121.181.112:10000](http://47.121.181.112:10000)**
架构采用多智能体协作管线(PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter),详见 [docs/backend.md](docs/backend.md)。 ## 特性
## 提示词优化链路 - **多智能体协作管线** — PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter,基于 Eino `compose.Graph` 编排
- **提示词优化** — Eino Chain 驱动的 PromptAgent,支持任意 OpenAI 兼容 API,无 key 时自动回退模板生成
- **风格系统** — 预设美术风格、色调、线条、场景、光照、情绪等维度,支持工程级与任务级风格覆盖
- **实时进度** — WebSocket 推送管线各阶段状态、进度与质检重试信息
- **异步任务** — 内存队列 + 通道模型,支持并发控制、失败重试(最多 3 次)与降级输出
- **请求去重** — 相同 `prompt + assetType + params` 的并发请求自动合并
- **暗色主题** — 前端支持 Light / Dark 双主题,CSS 自定义属性驱动
- **一键部署** — Docker Compose 双容器架构 + `deploy.sh` 脚本 + Gitee CI/CD 流水线
前端用户输入标签和原始描述后,后端通过 Eino 驱动的 PromptAgent 调用 LLM 进行提示词优化,最终生成规范的三段式提示词(【主题】【风格】【技术】)。 ## 技术栈
### 优化管线 | 层 | 技术 |
|---|------|
``` | 后端语言 | Go 1.26 |
用户输入 (标签 + 原始Prompt + 素材类型) | HTTP 框架 | Gin v1.12 |
│ | 管线编排 | [Eino](https://github.com/cloudwego/eino) v0.8 — `compose.Graph` + `compose.Chain` |
▼ | ORM | GORM + SQLite |
formatMetaPrompt (Lambda) | 认证 | JWT (golang-jwt) + bcrypt |
│ 构建元提示词:角色设定 + 输出格式要求 + 用户输入 | 配置 | Viper + godotenv(环境变量 > config.yml > 默认值) |
▼ | 前端框架 | React 18 + TypeScript 5.6 |
llmRefine (Lambda → ChatModel API) | 构建工具 | Vite 6 |
│ 调用 OpenAI 兼容的 Chat Completions API | 状态管理 | Zustand 5 |
│ 支持流式 (SSE) 与非流式响应 | 路由 | react-router-dom v7 |
│ 无 API key 时自动回退到模板生成 | 样式 | CSS Modules + CSS 自定义属性 |
▼ | 容器化 | Docker 多阶段构建 + nginx 反向代理 |
三段式规范提示词(【主题】【风格】【技术】) | CI/CD | Gitee Workflow + deploy.sh |
│
▼
PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter(生成管线)
```
### 特性
- **Eino Chain 编排**:`START → formatMetaPrompt → llmRefine → END`
- **OpenAI 兼容 API**:支持任意兼容 OpenAI 接口的 LLM 服务(OpenAI / DeepSeek / 本地模型等)
- **SSE 流式解析**:自动识别 `text/event-stream` 响应并拼接完整内容
- **优雅降级**:API 调用失败或未配置 key 时回退到模板生成,不阻塞管线
详见下方 [提示词优化 API](#提示词优化-api)。
## 快速开始 ## 快速开始
@@ -51,6 +47,7 @@ PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter(生
```bash ```bash
cd backend cd backend
cp .env.example .env # 编辑 .env 填入 API key
go mod tidy go mod tidy
go run cmd/main.go go run cmd/main.go
``` ```
@@ -65,36 +62,35 @@ npm install
npm run dev npm run dev
``` ```
开发服务器默认运行在 `http://localhost:5173`,通过 Vite proxy 转发 API 请求到后端。 开发服务器默认运行在 `http://localhost:5173`,通过 Vite proxy 转发 `/api` 和 `/auth` 请求到后端。
## 配置 ## 配置
配置通过 Viper 读取,分为三个优先级(高→低): 配置通过 Viper 读取,优先级从高到低:
| 优先级 | 来源 | 说明 | | 优先级 | 来源 | 说明 |
|--------|------|------| |--------|------|------|
| 1 | 环境变量 | 适合 Docker / CI,敏感字段推荐使用 | | 1 | 环境变量 | 适合 Docker / CI,敏感字段推荐使用 |
| 2 | `config.yml` | 文件位于 `backend/internal/config/config.yml`,存放非敏感默认值 | | 2 | `.env` 文件 | 位于 `backend/.env`,通过 godotenv 加载 |
| 3 | 默认值 | 代码内置,无需任何配置文件即可启动 | | 3 | `config.yml` | 位于 `backend/internal/config/config.yml`,存放非敏感默认值 |
| 4 | 代码默认值 | 无需任何配置文件即可启动 |
**环境变量会覆盖 YAML 文件中的同名配置。** ### 大语言模型
### 大语言模型配置
| 环境变量 | YAML 路径 | 默认值 | 说明 | | 环境变量 | YAML 路径 | 默认值 | 说明 |
|----------|-----------|--------|------| |----------|-----------|--------|------|
| `GEN2D_LLM_BASE_URL` | `llm.base_url` | `https://api.openai.com/v1` | LLM API 地址(兼容 OpenAI 接口) | | `GEN2D_LLM_BASE_URL` | `llm.base_url` | `https://api.deepseek.com/v1` | LLM API 地址(兼容 OpenAI 接口) |
| `GEN2D_LLM_API_KEY` | `llm.api_key` | (空) | API 密钥,**请通过环境变量设置** | | `GEN2D_LLM_API_KEY` | `llm.api_key` | (空) | API 密钥,请通过环境变量设置 |
| `GEN2D_LLM_MODEL` | `llm.model` | `gpt-4o` | 模型名称 | | `GEN2D_LLM_MODEL` | `llm.model` | `deepseek-v4-pro` | 模型名称 |
| `GEN2D_LLM_TEMPERATURE` | `llm.temperature` | `0.7` | 生成温度 (0–2) | | `GEN2D_LLM_TEMPERATURE` | `llm.temperature` | `0.7` | 生成温度 (0-2) |
| `GEN2D_LLM_MAX_TOKENS` | `llm.max_tokens` | `2048` | 最大输出 token 数 | | `GEN2D_LLM_MAX_TOKENS` | `llm.max_tokens` | `2048` | 最大输出 token 数 |
### 文生图配置 ### 文生图
| 环境变量 | YAML 路径 | 默认值 | 说明 | | 环境变量 | YAML 路径 | 默认值 | 说明 |
|----------|-----------|--------|------| |----------|-----------|--------|------|
| `GEN2D_IMAGE_BASE_URL` | `image_gen.base_url` | `https://api.stability.ai/v1` | 文生图 API 地址 | | `GEN2D_IMAGE_BASE_URL` | `image_gen.base_url` | `https://api.stability.ai/v1` | 文生图 API 地址 |
| `GEN2D_IMAGE_API_KEY` | `image_gen.api_key` | (空) | API 密钥,**请通过环境变量设置** | | `GEN2D_IMAGE_API_KEY` | `image_gen.api_key` | (空) | API 密钥,请通过环境变量设置 |
| `GEN2D_IMAGE_MODEL` | `image_gen.model` | `stable-diffusion-xl` | 模型名称 | | `GEN2D_IMAGE_MODEL` | `image_gen.model` | `stable-diffusion-xl` | 模型名称 |
| `GEN2D_IMAGE_WIDTH` | `image_gen.width` | `1024` | 生成图片宽度 | | `GEN2D_IMAGE_WIDTH` | `image_gen.width` | `1024` | 生成图片宽度 |
| `GEN2D_IMAGE_HEIGHT` | `image_gen.height` | `1024` | 生成图片高度 | | `GEN2D_IMAGE_HEIGHT` | `image_gen.height` | `1024` | 生成图片高度 |
@@ -102,7 +98,7 @@ npm run dev
| `GEN2D_IMAGE_STEPS` | `image_gen.steps` | `30` | 扩散步数 | | `GEN2D_IMAGE_STEPS` | `image_gen.steps` | `30` | 扩散步数 |
| `GEN2D_IMAGE_CFG_SCALE` | `image_gen.cfg_scale` | `7.0` | CFG 引导强度 | | `GEN2D_IMAGE_CFG_SCALE` | `image_gen.cfg_scale` | `7.0` | CFG 引导强度 |
### 服务基础配置 ### 服务基础
| 环境变量 | YAML 路径 | 默认值 | 说明 | | 环境变量 | YAML 路径 | 默认值 | 说明 |
|----------|-----------|--------|------| |----------|-----------|--------|------|
@@ -112,100 +108,163 @@ npm run dev
| `GEN2D_JWT_SECRET` | `jwt.secret` | `gen2d-dev-secret` | JWT 签名密钥 | | `GEN2D_JWT_SECRET` | `jwt.secret` | `gen2d-dev-secret` | JWT 签名密钥 |
| `GEN2D_JWT_EXPIRE` | `jwt.expire` | `7200` | JWT 过期时间(秒) | | `GEN2D_JWT_EXPIRE` | `jwt.expire` | `7200` | JWT 过期时间(秒) |
### 快速配置示例 ## 架构
**方式一:直接使用环境变量** ### 生成管线
```bash 基于 Eino `compose.Graph` 的四阶段管线,支持质检重试与降级输出:
export GEN2D_LLM_API_KEY=sk-your-openai-key
export GEN2D_IMAGE_API_KEY=sk-your-stability-key ```
go run cmd/main.go START
│
▼
PromptOptimizer 合并工程风格 + 任务风格覆盖,调用 PromptAgent 生成三段式提示词
│ (Eino Chain: formatMetaPrompt → llmRefine → 三段式规范提示词)
▼
AssetGenerator 调用文生图 API 生成素材
│
▼
QualitySupervisor ─────────┬─────────────────────────────┐
│ │ pass │ fail (retry < 3)
▼ │ ▼
FormatAdapter │ 回到 PromptOptimizer 重试
│ │ │
▼ │ ▼ (retry >= 3)
END └───────────────────── FormatAdapter (降级输出)
``` ```
**方式二:使用 `.env` 文件** ### 提示词优化链路
```bash ```
# backend/.env 用户输入 (标签 + 原始 Prompt + 素材类型)
GEN2D_LLM_API_KEY=sk-your-openai-key │
GEN2D_IMAGE_API_KEY=sk-your-stability-key ▼
formatMetaPrompt (Lambda) 构建元提示词:角色设定 + 输出格式要求 + 用户输入
│
▼
llmRefine (Lambda → ChatModel) 调用 OpenAI 兼容 Chat Completions API
│ 支持流式 (SSE) 与非流式响应
│ 无 API key 时自动回退到模板生成
▼
三段式规范提示词(【主题】【风格】【技术】)
``` ```
**方式三:修改 `config.yml`(仅非敏感字段)** ### 预设风格键
```yaml | 分类 | 键名 | 可选值示例 |
# backend/internal/config/config.yml |------|------|-----------|
llm: | 美术风格 | `artStyle` | pixel, cartoon, hand-drawn, vector, flat |
base_url: "https://api.openai.com/v1" | 色调 | `palette` | warm, cool, neutral, vibrant, muted, monochrome |
model: "gpt-4o" | 线条 | `lineWeight` | none, thin, medium, thick |
image_gen: | 场景 | `scene` | forest, dungeon, city, space, underwater, desert |
width: 512 | 光照 | `lighting` | bright, dim, dramatic, ambient, neon |
height: 512 | 情绪 | `mood` | cheerful, dark, mysterious, epic, calm |
```
## 提示词优化 API 详细架构说明见 [docs/_index.md](docs/_index.md)。
### POST /api/v1/prompt/optimize ## API
接收用户标签和原始描述,调用 LLM 生成规范化的三段式提示词。 接口统一前缀 `/api/v1/`,统一响应格式:
**请求体:**
```json ```json
{ { "code": 0, "message": "ok", "data": {} }
"tags": ["像素", "战士"],
"assetType": "sprite",
"prompt": "我要一个拿着大剑的战士角色",
"userNote": "需要发光特效"
}
``` ```
| 字段 | 类型 | 必填 | 说明 | 除健康检查和注册登录外,所有接口需通过 `Authorization: Bearer <token>` 认证。
|------|------|------|------|
| `tags` | string[] | 是 | 用户选择的风格标签,至少 1 个 |
| `assetType` | string | 是 | 素材类型:`sprite` / `background` / `ui` / `animation` |
| `prompt` | string | 否 | 用户输入的原始提示词描述 |
| `userNote` | string | 否 | 额外补充说明 |
**响应:** ### 已实现
```json | 方法 | 路径 | 说明 |
{
"code": 0,
"message": "ok",
"data": {
"prompt": "【主题】一个融合像素、战士元素的游戏角色精灵图...\n【风格】色彩鲜明;像素风格...\n【技术】输出格式: spritesheet;分辨率: 64x64...",
"rawText": "【主题】一个融合像素...\n【风格】色彩鲜明..."
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------| |------|------|------|
| `data.prompt` | string | 优化后的三段式提示词,可直接传入生成管线 | | GET | `/api/v1/health` | 健康检查 |
| `data.rawText` | string | LLM 原始返回文本 | | POST | `/auth/register` | 用户注册 |
| POST | `/auth/login` | 用户登录(返回 JWT Token) |
| POST | `/api/v1/prompt/optimize` | 提示词优化 |
接入真实 LLM 后(配置 `GEN2D_LLM_API_KEY`),LLM 会根据标签+原始描述+素材类型生成高质量、可执行的提示词。未配置 API key 时自动回退到模板生成。 ### 规划中
| 方法 | 路径 | 说明 |
|------|------|------|
| GET/POST | `/api/v1/projects` | 工程列表 / 创建工程 |
| GET/DELETE | `/api/v1/projects/:id` | 工程详情 / 删除工程 |
| GET/PUT | `/api/v1/projects/:id/style` | 工程风格读写 |
| POST | `/api/v1/generate` | 提交生成任务 |
| GET | `/api/v1/tasks/:id` | 任务状态与进度 |
| GET | `/api/v1/tasks/:id/assets` | 生成结果素材列表 |
| WS | `/api/v1/tasks/:id/ws` | WebSocket 实时进度推送 |
完整 API 文档见 [docs/api.md](docs/api.md)。
## 部署
### Docker Compose
```bash
cd backend
cp .env.example .env # 编辑填入 API key
cd ..
docker compose up -d --build
```
- 后端:Go 多阶段构建,暴露 8080 端口
- 前端:Node 构建 + nginx 反向代理,默认映射到宿主机 10000 端口
- 数据持久化:`backend-data` 卷挂载 SQLite 数据库与生成素材
### 一键脚本
```bash
bash deploy.sh
```
自动完成仓库克隆/拉取、环境检查、`.env` 模板复制、`docker compose up`。
## 项目结构 ## 项目结构
``` ```
gen2d/ gen2d/
├── backend/ # Go + Gin API 服务 ├── backend/ # Go + Gin API 服务
│ ├── cmd/main.go # 入口:加载配置 → 初始化 DB → 注册路由 → 启动
│ ├── internal/
│ │ ├── config/ # Viper 配置加载 + config.yml
│ │ ├── db/ # SQLite + GORM 初始化
│ │ ├── handler/ # HTTP 处理器(health, prompt, auth)
│ │ ├── model/ # 数据模型(User, Response)
│ │ └── service/ # 业务逻辑
│ │ ├── pipeline.go # Eino Graph 四阶段管线
│ │ ├── prompt_agent.go # Eino Chain 提示词优化
│ │ ├── nodes.go # 管线节点实现
│ │ ├── inference.go # 文生图推理(Mock)
│ │ └── auth.go # 注册 / 登录 / JWT
│ └── pkg/splitsprite/ # 精灵表拆分工具
├── frontend/ # Vite + React 前端 ├── frontend/ # Vite + React 前端
└── docs/ # 项目文档 │ └── src/
├── architecture.md # 架构设计 │ ├── api/ # HTTP 客户端与类型定义
└── api.md # API 文档 │ ├── components/ # UI 组件(StyleSelector, PromptEditor, GenerateForm...)
│ ├── pages/ # 页面(Login, Register, Project, Generate, Result)
│ ├── stores/ # Zustand 状态管理
│ ├── hooks/ # 自定义 Hooks
│ ├── router/ # 路由配置
│ └── styles/ # 全局样式与主题变量
├── docs/ # 项目文档
│ ├── _index.md # 文档索引
│ ├── api.md # API 设计
│ ├── backend.md # 后端工程
│ ├── frontend.md # 前端工程
│ ├── database.md # 数据存储
│ ├── async-tasks.md # 异步任务
│ └── style-keys.md # 预设风格键
├── docker-compose.yml # 容器编排
├── deploy.sh # 一键部署脚本
└── .workflow/deploy.yml # Gitee CI/CD 流水线
``` ```
详细架构说明见 [docs/architecture.md](docs/architecture.md)。
## API
接口统一前缀 `/api/v1/`,详见 [docs/api.md](docs/api.md)。
## 参与贡献 ## 参与贡献
1. Fork 本仓库 1. Fork 本仓库
2. 新建 Feat_xxx 分支 2. 新建 `Feat_xxx` 分支
3. 提交代码 3. 提交代码
4. 新建 Pull Request 4. 新建 Pull Request
## License
[MIT](LICENSE)