gen2d/README.md

# gen2d

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

[![Go](https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white)](https://go.dev/)
[![Gin](https://img.shields.io/badge/Gin-1.12-008ECF?logo=gin&logoColor=white)](https://gin-gonic.com/)
[![Eino](https://img.shields.io/badge/Eino-0.8-blue)](https://github.com/cloudwego/eino)
[![React](https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=black)](https://react.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)**

## 特性

- **多智能体协作管线** — 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](https://github.com/cloudwego/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 |

## 快速开始

### 后端

```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 过期时间（秒） |

## 架构

![全局架构](assets/global-architecture.png)

### 生成管线

基于 Eino `compose.Graph` 的四阶段管线，支持质检重试与降级输出：

```mermaid
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(( ))
```

### 提示词优化链路

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

![后端架构](assets/backend-architecture.png)

### 预设风格键

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

![前端架构](assets/frontend-architecture.png)

详细架构说明见 [docs/_index.md](docs/_index.md)。

## API

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

```json
{ "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](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/
├── 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](LICENSE)