# gen2d

AI 驱动的 2D 游戏素材生成工具
文本描述 + 风格参数 → 风格一致、管线友好的 Sprite、背景、UI 与动画帧
无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流

Go Gin Eino React TypeScript Vite License

在线体验  |  文档  |  快速开始  |  API

> 🎈 **哔哩哔哩视频**：【七牛云 XEngineer 暑期实训营 | 2D 游戏素材 | 团体作品演示】 https://www.bilibili.com/video/BV1jAGo6DEbC > 🔥 **在线体验**：http://47.121.181.112:10000/ > 详细架构说明见 [docs/_index.md](docs/_index.md)。 ![全局架构](assets/global-architecture.png) ![后端架构](assets/backend-architecture.png) ![前端架构](assets/frontend-architecture.png) --- ## 目录 - [特性](#特性) - [快速开始](#快速开始) - [配置](#配置) - [架构](#架构) - [生成管线](#生成管线) - [提示词优化链路](#提示词优化链路) - [预设风格键](#预设风格键) - [API](#api) - [技术栈](#技术栈) - [项目结构](#项目结构) - [部署](#部署) - [文档](#文档) - [路线图](#路线图) - [参与贡献](#参与贡献) - [参考链接](#参考链接) - [License](#license) ## 特性 - **多智能体协作管线** — PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter，基于 Eino `compose.Graph` 编排，支持质检重试与降级输出 - **提示词优化** — Eino Chain 驱动的 PromptAgent，支持任意 OpenAI 兼容 API，无 key 时自动回退模板生成 - **风格系统** — 预设美术风格、色调、线条、场景、光照、情绪等维度，支持工程级与任务级风格覆盖 - **实时进度** — WebSocket 推送管线各阶段状态、进度与质检重试信息 - **异步任务** — goroutine 模型，支持并发控制、失败重试（最多 3 次）与降级输出 - **请求去重** — 相同 `prompt + assetType + params` 的并发请求自动合并，返回已有 taskId - **暗色主题** — 前端支持 Light / Dark 双主题，CSS 自定义属性驱动 - **一键部署** — Docker Compose 双容器架构 + `deploy.sh` 脚本 ## 快速开始 ### 环境要求 - Go 1.26+ - Node.js 20+ - Docker & Docker Compose（部署用） ### 后端 ```bash cd backend cp .env.example .env # 编辑 .env 填入 API key go mod tidy go run cmd/main.go ``` 服务默认运行在 `http://localhost:8080`。 ### 前端 ```bash cd frontend npm install npm run dev ``` 开发服务器运行在 `http://localhost:5173`，通过 Vite proxy 转发 `/api` 和 `/auth` 请求到后端。 ## 配置 配置通过 Viper 读取，优先级从高到低： | 优先级 | 来源 | 说明 | |:---:|------|------| | 1 | 环境变量 | 适合 Docker / CI，敏感字段推荐使用 | | 2 | `.env` 文件 | 位于 `backend/.env`，通过 godotenv 加载 | | 3 | `config.yml` | 位于 `backend/internal/config/config.yml`，存放非敏感默认值 | | 4 | 代码默认值 | 无需任何配置文件即可启动 | ### 大语言模型 | 环境变量 | YAML 路径 | 默认值 | 说明 | |----------|-----------|--------|------| | `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_MODEL` | `llm.model` | `deepseek-v4-pro` | 模型名称 | | `GEN2D_LLM_TEMPERATURE` | `llm.temperature` | `0.7` | 生成温度 (0-2) | | `GEN2D_LLM_MAX_TOKENS` | `llm.max_tokens` | `2048` | 最大输出 token 数 | ### 文生图 | 环境变量 | YAML 路径 | 默认值 | 说明 | |----------|-----------|--------|------| | `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_MODEL` | `image_gen.model` | `stable-diffusion-xl` | 模型名称 | | `GEN2D_IMAGE_WIDTH` | `image_gen.width` | `1024` | 生成图片宽度 | | `GEN2D_IMAGE_HEIGHT` | `image_gen.height` | `1024` | 生成图片高度 | | `GEN2D_IMAGE_NUM_IMAGES` | `image_gen.num_images` | `1` | 每次生成图片数量 | | `GEN2D_IMAGE_STEPS` | `image_gen.steps` | `30` | 扩散步数 | | `GEN2D_IMAGE_CFG_SCALE` | `image_gen.cfg_scale` | `7.0` | CFG 引导强度 | ### 服务基础 | 环境变量 | YAML 路径 | 默认值 | 说明 | |----------|-----------|--------|------| | `GEN2D_PORT` | `server.port` | `8080` | HTTP 监听端口 | | `GEN2D_MODE` | `server.mode` | `debug` | Gin 运行模式 (`debug` / `release`) | | `GEN2D_DSN` | `database.dsn` | `data/gen2d.db` | SQLite 数据库路径 | | `GEN2D_JWT_SECRET` | `jwt.secret` | `gen2d-dev-secret` | JWT 签名密钥 | | `GEN2D_JWT_EXPIRE` | `jwt.expire` | `7200` | JWT 过期时间（秒） | ## 架构 ### 生成管线 基于 Eino `compose.Graph` 的四阶段管线，支持质检重试与降级输出： ```mermaid graph TD START(( )) --> PromptOptimizer PromptOptimizer["PromptOptimizer
合并工程风格 + 任务风格覆盖
调用 PromptAgent 生成三段式提示词"] PromptOptimizer --> AssetGenerator AssetGenerator["AssetGenerator
调用文生图 API 生成素材"] AssetGenerator --> QualitySupervisor QualitySupervisor{"QualitySupervisor
质检通过？"} QualitySupervisor -->|pass| FormatAdapter QualitySupervisor -->|fail, retry < 3| PromptOptimizer QualitySupervisor -->|fail, retry ≥ 3| FormatAdapter FormatAdapter["FormatAdapter
组装输出素材与元数据"] FormatAdapter --> END(( )) ``` ### 提示词优化链路 ```mermaid graph TD A["用户输入
标签 + 原始 Prompt + 素材类型"] --> B["formatMetaPrompt
构建元提示词：角色设定 + 输出格式 + 用户输入"] B --> C["llmRefine
调用 OpenAI 兼容 Chat API
支持 SSE 流式 / 非流式
无 key 自动回退模板"] C --> D["三段式规范提示词
【主题】【风格】【技术】"] ``` ### 预设风格键 | 分类 | 键名 | 可选值示例 | |------|------|-----------| | 美术风格 | `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 | ## API 接口统一前缀 `/api/v1/`，统一响应格式： ```json { "code": 0, "message": "ok", "data": {} } ``` 除健康检查和注册登录外，所有接口需通过 `Authorization: Bearer ` 认证。 ### 已实现 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/v1/health` | 健康检查 | | POST | `/auth/register` | 用户注册 | | POST | `/auth/login` | 用户登录（返回 JWT Token） | | POST | `/api/v1/prompt/optimize` | 提示词优化 | | GET/POST | `/api/v1/projects` | 工程列表 / 创建工程 | | GET/PUT/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` | 生成结果素材列表 | | GET | `/api/v1/assets/download` | 下载素材（重定向到 CDN） | ### 规划中 | 方法 | 路径 | 说明 | |------|------|------| | WS | `/api/v1/tasks/:id/ws` | WebSocket 实时进度推送 | | GET | `/api/v1/auth/me` | 获取当前用户信息 | | PUT | `/api/v1/auth/password` | 修改密码 | 完整 API 文档见 [docs/api.md](docs/api.md)。 ## 技术栈 | 层 | 技术 | 说明 | |---|------|------| | 后端语言 | Go 1.26 | — | | HTTP 框架 | Gin v1.12 | 路由、中间件、JSON 绑定 | | 管线编排 | [Eino](https://github.com/cloudwego/eino) v0.8 | `compose.Graph` + `compose.Chain` | | ORM | GORM + SQLite | 零配置数据库 | | 认证 | JWT (golang-jwt) + bcrypt | 无状态认证 | | 配置 | Viper + godotenv | 多层配置优先级 | | 对象存储 | 七牛云 Kodo | CDN 加速、私有 Bucket 签名访问 | | 前端框架 | React 18 + TypeScript 5.6 | 函数组件 + Hooks | | 构建工具 | Vite 6 | HMR 开发体验 | | 状态管理 | Zustand 5 | 轻量、不可变状态 | | 路由 | react-router-dom v7 | SPA 路由 | | 样式 | CSS Modules + CSS 自定义属性 | 主题切换 | | 容器化 | Docker 多阶段构建 | nginx 反向代理 | | CI/CD | Gitee Workflow | 自动构建部署 | ## 项目结构 ``` gen2d/ ├── backend/ # Go + Gin API 服务 │ ├── cmd/main.go # 入口：加载配置 → 初始化 DB → 注册路由 → 启动 │ ├── internal/ │ │ ├── config/ # Viper 配置加载 + config.yml │ │ ├── db/ # SQLite + GORM 初始化 │ │ ├── handler/ # HTTP 处理器（health, prompt, auth, generate, storage） │ │ ├── model/ # 数据模型（User, Response） │ │ ├── mildware/ # 中间件（JWT 认证、日志、恢复） │ │ ├── logger/ # 日志包（基于 log/slog） │ │ └── service/ # 业务逻辑 │ │ ├── pipeline.go # Eino Graph 四阶段管线编排 │ │ ├── prompt_agent.go # Eino Chain 提示词优化 │ │ ├── nodes.go # 管线节点实现 │ │ ├── inference.go # 文生图推理 │ │ ├── auth.go # 注册 / 登录 / JWT │ │ └── storage.go # 七牛云对象存储 │ └── pkg/splitsprite/ # 精灵表拆分工具 ├── frontend/ # Vite + React 前端 │ └── src/ │ ├── api/ # HTTP 客户端与类型定义 │ ├── components/ # UI 组件 │ ├── pages/ # 页面（Login, Register, Home, Project, Result） │ ├── stores/ # Zustand 状态管理 │ ├── hooks/ # 自定义 Hooks │ ├── router/ # 路由配置 │ ├── utils/ # 工具函数 │ └── 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/ # CI/CD 流水线配置 ``` ## 部署 ### 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`。 ## 文档 详细设计文档见 [docs/](docs/) 目录： | 文档 | 说明 | |------|------| | [docs/_index.md](docs/_index.md) | 文档索引与架构概述 | | [docs/api.md](docs/api.md) | API 接口设计、请求/响应示例、错误码 | | [docs/backend.md](docs/backend.md) | 后端分层结构、管线设计、风格模型、缓存层 | | [docs/frontend.md](docs/frontend.md) | 前端组件树、状态管理、路由、交互流程 | | [docs/database.md](docs/database.md) | SQLite 选型、表结构、ER 关系、对象存储、去重策略 | | [docs/async-tasks.md](docs/async-tasks.md) | 任务生命周期、并发控制、重试策略、进度推送 | | [docs/style-keys.md](docs/style-keys.md) | 预设风格键分类与可选值 | ## 路线图 - [x] 提示词优化 Agent（Eino Chain） - [x] 多智能体生成管线（Eino Graph） - [x] 工程风格系统 + 任务级覆盖 - [x] 用户认证（JWT + bcrypt） - [x] 异步任务 + 实时进度推送 - [x] 素材帧预览、GIF 动画与导出 - [x] 自定义标签 - [ ] WebSocket 实时进度推送（待完成） - [ ] 批量生成与队列调度 - [ ] 文生图多模型适配（DALL-E, Midjourney） - [ ] 素材版本管理与历史记录 ## 参与贡献 1. Fork 本仓库 2. 新建 `Feat_xxx` 分支 3. 提交代码 4. 新建 Pull Request ## 参考链接 ### 后端 - [Go](https://go.dev/) — 编程语言 - [Gin](https://gin-gonic.com/) — HTTP 框架 - [Eino](https://github.com/cloudwego/eino) — AI 管线编排框架 - [GORM](https://gorm.io/) — Go ORM - [golang-jwt](https://github.com/golang-jwt/jwt) — JWT 库 - [Viper](https://github.com/spf13/viper) — 配置管理 ### 前端 - [React](https://react.dev/) — UI 框架 - [TypeScript](https://www.typescriptlang.org/) — 类型安全 - [Vite](https://vite.dev/) — 构建工具 - [Zustand](https://github.com/pmndrs/zustand) — 状态管理 - [react-router](https://reactrouter.com/) — 路由 ### AI / 模型 - [DeepSeek API](https://platform.deepseek.com/) — 默认 LLM - [Stability AI](https://platform.stability.ai/) — 默认文生图 - [OpenAI API](https://platform.openai.com/) — 兼容接口 ### 游戏引擎 - [Unity 2D](https://unity.com/solutions/2d) — 支持精灵图集导入 - [Godot Engine](https://godotengine.org/) — 开源 2D/3D 引擎 ### 基础设施 - [Docker](https://www.docker.com/) — 容器化 - [SQLite](https://www.sqlite.org/) — 嵌入式数据库 - [七牛云 Kodo](https://www.qiniu.com/products/kodo) — 对象存储 ## License [MIT](LICENSE)