gen2d

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

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

---

目录

• 特性
• 快速开始
• 配置
• 架构
  • 生成管线
  • 提示词优化链路
  • 预设风格键
• API
• 技术栈
• 项目结构
• 部署
• 文档
• 路线图
• 参与贡献
• 参考链接
• 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（部署用）

后端

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

graph TD
    START(( )) --> PromptOptimizer
    PromptOptimizer["PromptOptimizer<br/>合并工程风格 + 任务风格覆盖<br/>调用 PromptAgent 生成三段式提示词"]
    PromptOptimizer --> AssetGenerator
    AssetGenerator["AssetGenerator<br/>调用文生图 API 生成素材"]
    AssetGenerator --> QualitySupervisor
    QualitySupervisor{"QualitySupervisor<br/>质检通过？"}
    QualitySupervisor -->|pass| FormatAdapter
    QualitySupervisor -->|fail, retry < 3| PromptOptimizer
    QualitySupervisor -->|fail, retry ≥ 3| FormatAdapter
    FormatAdapter["FormatAdapter<br/>组装输出素材与元数据"]
    FormatAdapter --> END(( ))

提示词优化链路

graph TD
    A["用户输入<br/>标签 + 原始 Prompt + 素材类型"] --> B["formatMetaPrompt<br/>构建元提示词：角色设定 + 输出格式 + 用户输入"]
    B --> C["llmRefine<br/>调用 OpenAI 兼容 Chat API<br/>支持 SSE 流式 / 非流式<br/>无 key 自动回退模板"]
    C --> D["三段式规范提示词<br/>【主题】【风格】【技术】"]

预设风格键

分类	键名	可选值示例
美术风格	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/，统一响应格式：

{ "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/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。

技术栈

层	技术	说明
后端语言	Go 1.26	—
HTTP 框架	Gin v1.12	路由、中间件、JSON 绑定
管线编排	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

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。

文档

详细设计文档见 docs/ 目录：

文档	说明
docs/_index.md	文档索引与架构概述
docs/api.md	API 接口设计、请求/响应示例、错误码
docs/backend.md	后端分层结构、管线设计、风格模型、缓存层
docs/frontend.md	前端组件树、状态管理、路由、交互流程
docs/database.md	SQLite 选型、表结构、ER 关系、对象存储、去重策略
docs/async-tasks.md	任务生命周期、并发控制、重试策略、进度推送
docs/style-keys.md	预设风格键分类与可选值

路线图

• 提示词优化 Agent（Eino Chain）
• 多智能体生成管线（Eino Graph）
• 工程风格系统 + 任务级覆盖
• 用户认证（JWT + bcrypt）
• 异步任务 + 实时进度推送
• 素材帧预览、GIF 动画与导出
• 自定义标签
• WebSocket 实时进度推送（待完成）
• 批量生成与队列调度
• 文生图多模型适配（DALL-E, Midjourney）
• 素材版本管理与历史记录

参与贡献

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

参考链接

后端

• Go — 编程语言
• Gin — HTTP 框架
• Eino — AI 管线编排框架
• GORM — Go ORM
• golang-jwt — JWT 库
• Viper — 配置管理

前端

• React — UI 框架
• TypeScript — 类型安全
• Vite — 构建工具
• Zustand — 状态管理
• react-router — 路由

AI / 模型

• DeepSeek API — 默认 LLM
• Stability AI — 默认文生图
• OpenAI API — 兼容接口

游戏引擎

• Unity 2D — 支持精灵图集导入
• Godot Engine — 开源 2D/3D 引擎

基础设施

• Docker — 容器化
• SQLite — 嵌入式数据库
• 七牛云 Kodo — 对象存储

License

MIT