gen2d

AI 驱动的 2D 游戏素材生成工具。通过文本提示词或可视化参数，生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧，无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流。

在线体验 http://47.121.181.112:10000

特性

• 多智能体协作管线 — 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 流水线

技术栈

层	技术
后端语言	Go 1.26
HTTP 框架	Gin v1.12
管线编排	Eino v0.8 — compose.Graph + compose.Chain
ORM	GORM + SQLite
认证	JWT (golang-jwt) + bcrypt
配置	Viper + godotenv（环境变量 > config.yml > 默认值）
前端框架	React 18 + TypeScript 5.6
构建工具	Vite 6
状态管理	Zustand 5
路由	react-router-dom v7
样式	CSS Modules + CSS 自定义属性
容器化	Docker 多阶段构建 + nginx 反向代理
CI/CD	Gitee Workflow + deploy.sh

快速开始

后端

cd backend
cp .env.example .env        # 编辑 .env 填入 API key
go mod tidy
go run cmd/main.go

服务默认运行在 http://localhost:8080。

前端

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 的四阶段管线，支持质检重试与降级输出：

START
  │
  ▼
PromptOptimizer          合并工程风格 + 任务风格覆盖，调用 PromptAgent 生成三段式提示词
  │                      （Eino Chain: formatMetaPrompt → llmRefine → 三段式规范提示词）
  ▼
AssetGenerator           调用文生图 API 生成素材
  │
  ▼
QualitySupervisor ─────────┬─────────────────────────────┐
  │                        │ pass                        │ fail (retry < 3)
  ▼                        │                             ▼
FormatAdapter              │                     回到 PromptOptimizer 重试
  │                        │                             │
  ▼                        │                             ▼ (retry >= 3)
END                        └───────────────────── FormatAdapter (降级输出)

提示词优化链路

用户输入 (标签 + 原始 Prompt + 素材类型)
    │
    ▼
formatMetaPrompt (Lambda)         构建元提示词：角色设定 + 输出格式要求 + 用户输入
    │
    ▼
llmRefine (Lambda → ChatModel)    调用 OpenAI 兼容 Chat Completions API
    │                              支持流式 (SSE) 与非流式响应
    │                              无 API key 时自动回退到模板生成
    ▼
三段式规范提示词（【主题】【风格】【技术】）

预设风格键

分类	键名	可选值示例
美术风格	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

详细架构说明见 docs/_index.md。

API

接口统一前缀 /api/v1/，统一响应格式：

{ "code": 0, "message": "ok", "data": {} }

除健康检查和注册登录外，所有接口需通过 Authorization: Bearer <token> 认证。

已实现

方法	路径	说明
GET	/api/v1/health	健康检查
POST	/auth/register	用户注册
POST	/auth/login	用户登录（返回 JWT Token）
POST	/api/v1/prompt/optimize	提示词优化

规划中

方法	路径	说明
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。

部署

Docker Compose

cd backend
cp .env.example .env        # 编辑填入 API key
cd ..
docker compose up -d --build

• 后端：Go 多阶段构建，暴露 8080 端口
• 前端：Node 构建 + nginx 反向代理，默认映射到宿主机 10000 端口
• 数据持久化：backend-data 卷挂载 SQLite 数据库与生成素材

一键脚本

bash deploy.sh

自动完成仓库克隆/拉取、环境检查、.env 模板复制、docker compose up。

项目结构

gen2d/
├── 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 前端
│   └── src/
│       ├── api/                # HTTP 客户端与类型定义
│       ├── 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 流水线

参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

License

MIT