gen2d/README.md

gen2d

AI 驱动的 2D 游戏素材生成工具。通过文本提示词或可视化参数，快速生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧。支持 Unity / Godot 一键集成。

在线体验 http://47.121.181.112:10000

架构采用多智能体协作管线（PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter），详见 docs/backend.md。

提示词优化链路

前端用户输入标签和原始描述后，后端通过 Eino 驱动的 PromptAgent 调用 LLM 进行提示词优化，最终生成规范的三段式提示词（【主题】【风格】【技术】）。

优化管线

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

特性

• Eino Chain 编排：START → formatMetaPrompt → llmRefine → END
• OpenAI 兼容 API：支持任意兼容 OpenAI 接口的 LLM 服务（OpenAI / DeepSeek / 本地模型等）
• SSE 流式解析：自动识别 text/event-stream 响应并拼接完整内容
• 优雅降级：API 调用失败或未配置 key 时回退到模板生成，不阻塞管线

详见下方 提示词优化 API。

快速开始

后端

cd backend
go mod tidy
go run cmd/main.go

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

前端

cd frontend
npm install
npm run dev

开发服务器默认运行在 http://localhost:5173，通过 Vite proxy 转发 API 请求到后端。

配置

配置通过 Viper 读取，分为三个优先级（高→低）：

优先级	来源	说明
1	环境变量	适合 Docker / CI，敏感字段推荐使用
2	config.yml	文件位于 backend/internal/config/config.yml，存放非敏感默认值
3	默认值	代码内置，无需任何配置文件即可启动

环境变量会覆盖 YAML 文件中的同名配置。

大语言模型配置

环境变量	YAML 路径	默认值	说明
GEN2D_LLM_BASE_URL	llm.base_url	https://api.openai.com/v1	LLM API 地址（兼容 OpenAI 接口）
GEN2D_LLM_API_KEY	llm.api_key	(空)	API 密钥，请通过环境变量设置
GEN2D_LLM_MODEL	llm.model	gpt-4o	模型名称
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 过期时间（秒）

快速配置示例

方式一：直接使用环境变量

export GEN2D_LLM_API_KEY=sk-your-openai-key
export GEN2D_IMAGE_API_KEY=sk-your-stability-key
go run cmd/main.go

方式二：使用 .env 文件

# backend/.env
GEN2D_LLM_API_KEY=sk-your-openai-key
GEN2D_IMAGE_API_KEY=sk-your-stability-key

方式三：修改 config.yml（仅非敏感字段）

# backend/internal/config/config.yml
llm:
  base_url: "https://api.openai.com/v1"
  model: "gpt-4o"
image_gen:
  width: 512
  height: 512

提示词优化 API

POST /api/v1/prompt/optimize

接收用户标签和原始描述，调用 LLM 生成规范化的三段式提示词。

请求体：

{
  "tags":      ["像素", "战士"],
  "assetType": "sprite",
  "prompt":    "我要一个拿着大剑的战士角色",
  "userNote":  "需要发光特效"
}

字段	类型	必填	说明
tags	string[]	是	用户选择的风格标签，至少 1 个
assetType	string	是	素材类型：sprite / background / ui / animation
prompt	string	否	用户输入的原始提示词描述
userNote	string	否	额外补充说明

响应：

{
  "code": 0,
  "message": "ok",
  "data": {
    "prompt":  "【主题】一个融合像素、战士元素的游戏角色精灵图...\n【风格】色彩鲜明；像素风格...\n【技术】输出格式: spritesheet；分辨率: 64x64...",
    "rawText": "【主题】一个融合像素...\n【风格】色彩鲜明..."
  }
}

字段	类型	说明
data.prompt	string	优化后的三段式提示词，可直接传入生成管线
data.rawText	string	LLM 原始返回文本

接入真实 LLM 后（配置 GEN2D_LLM_API_KEY），LLM 会根据标签+原始描述+素材类型生成高质量、可执行的提示词。未配置 API key 时自动回退到模板生成。

项目结构

gen2d/
├── backend/          # Go + Gin API 服务
├── frontend/         # Vite + React 前端
└── docs/             # 项目文档
    ├── architecture.md  # 架构设计
    └── api.md           # API 文档

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

API

接口统一前缀 /api/v1/，详见 docs/api.md。

参与贡献

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