diff --git a/README.md b/README.md index d018005..f02745b 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,45 @@ # gen2d -AI 驱动的 2D 游戏素材生成工具。通过文本提示词或可视化参数，快速生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧。支持 Unity / Godot 一键集成。 +AI 驱动的 2D 游戏素材生成工具。通过文本提示词或可视化参数，生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧，无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流。 -[![Go](https://img.shields.io/badge/Go-00ADD8?logo=go&logoColor=white)](https://go.dev/) -[![Gin](https://img.shields.io/badge/Gin-008ECF?logo=gin&logoColor=white)](https://gin-gonic.com/) -[![React](https://img.shields.io/badge/React-61DAFB?logo=react&logoColor=black)](https://react.dev/) -[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) -[![Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white)](https://vite.dev/) +[![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），详见 [docs/backend.md](docs/backend.md)。 +## 特性 -## 提示词优化链路 +- **多智能体协作管线** — 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 流水线 -前端用户输入标签和原始描述后，后端通过 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](#提示词优化-api)。 +| 层 | 技术 | +|---|------| +| 后端语言 | 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 | ## 快速开始 @@ -51,6 +47,7 @@ PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter（生 ```bash cd backend +cp .env.example .env # 编辑 .env 填入 API key go mod tidy go run cmd/main.go ``` @@ -65,36 +62,35 @@ npm install npm run dev ``` -开发服务器默认运行在 `http://localhost:5173`，通过 Vite proxy 转发 API 请求到后端。 +开发服务器默认运行在 `http://localhost:5173`，通过 Vite proxy 转发 `/api` 和 `/auth` 请求到后端。 ## 配置 -配置通过 Viper 读取，分为三个优先级（高→低）： +配置通过 Viper 读取，优先级从高到低： | 优先级 | 来源 | 说明 | |--------|------|------| | 1 | 环境变量 | 适合 Docker / CI，敏感字段推荐使用 | -| 2 | `config.yml` | 文件位于 `backend/internal/config/config.yml`，存放非敏感默认值 | -| 3 | 默认值 | 代码内置，无需任何配置文件即可启动 | +| 2 | `.env` 文件 | 位于 `backend/.env`，通过 godotenv 加载 | +| 3 | `config.yml` | 位于 `backend/internal/config/config.yml`，存放非敏感默认值 | +| 4 | 代码默认值 | 无需任何配置文件即可启动 | -**环境变量会覆盖 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_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_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` | 生成图片高度 | @@ -102,7 +98,7 @@ npm run dev | `GEN2D_IMAGE_STEPS` | `image_gen.steps` | `30` | 扩散步数 | | `GEN2D_IMAGE_CFG_SCALE` | `image_gen.cfg_scale` | `7.0` | CFG 引导强度 | -### 服务基础配置 +### 服务基础 | 环境变量 | YAML 路径 | 默认值 | 说明 | |----------|-----------|--------|------| @@ -112,100 +108,163 @@ npm run dev | `GEN2D_JWT_SECRET` | `jwt.secret` | `gen2d-dev-secret` | JWT 签名密钥 | | `GEN2D_JWT_EXPIRE` | `jwt.expire` | `7200` | JWT 过期时间（秒） | -### 快速配置示例 +## 架构 -**方式一：直接使用环境变量** +### 生成管线 -```bash -export GEN2D_LLM_API_KEY=sk-your-openai-key -export GEN2D_IMAGE_API_KEY=sk-your-stability-key -go run cmd/main.go +基于 Eino `compose.Graph` 的四阶段管线，支持质检重试与降级输出： + +``` +START + │ + ▼ +PromptOptimizer 合并工程风格 + 任务风格覆盖，调用 PromptAgent 生成三段式提示词 + │ （Eino Chain: formatMetaPrompt → llmRefine → 三段式规范提示词） + ▼ +AssetGenerator 调用文生图 API 生成素材 + │ + ▼ +QualitySupervisor ─────────┬─────────────────────────────┐ + │ │ pass │ fail (retry < 3) + ▼ │ ▼ +FormatAdapter │ 回到 PromptOptimizer 重试 + │ │ │ + ▼ │ ▼ (retry >= 3) +END └───────────────────── FormatAdapter (降级输出) ``` -**方式二：使用 `.env` 文件** +### 提示词优化链路 -```bash -# backend/.env -GEN2D_LLM_API_KEY=sk-your-openai-key -GEN2D_IMAGE_API_KEY=sk-your-stability-key +``` +用户输入 (标签 + 原始 Prompt + 素材类型) + │ + ▼ +formatMetaPrompt (Lambda) 构建元提示词：角色设定 + 输出格式要求 + 用户输入 + │ + ▼ +llmRefine (Lambda → ChatModel) 调用 OpenAI 兼容 Chat Completions API + │ 支持流式 (SSE) 与非流式响应 + │ 无 API key 时自动回退到模板生成 + ▼ +三段式规范提示词（【主题】【风格】【技术】） ``` -**方式三：修改 `config.yml`（仅非敏感字段）** +### 预设风格键 -```yaml -# backend/internal/config/config.yml -llm: - base_url: "https://api.openai.com/v1" - model: "gpt-4o" -image_gen: - width: 512 - height: 512 -``` +| 分类 | 键名 | 可选值示例 | +|------|------|-----------| +| 美术风格 | `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 +详细架构说明见 [docs/_index.md](docs/_index.md)。 -### POST /api/v1/prompt/optimize +## API -接收用户标签和原始描述，调用 LLM 生成规范化的三段式提示词。 - -**请求体：** +接口统一前缀 `/api/v1/`，统一响应格式： ```json -{ - "tags": ["像素", "战士"], - "assetType": "sprite", - "prompt": "我要一个拿着大剑的战士角色", - "userNote": "需要发光特效" -} +{ "code": 0, "message": "ok", "data": {} } ``` -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `tags` | string[] | 是 | 用户选择的风格标签，至少 1 个 | -| `assetType` | string | 是 | 素材类型：`sprite` / `background` / `ui` / `animation` | -| `prompt` | string | 否 | 用户输入的原始提示词描述 | -| `userNote` | string | 否 | 额外补充说明 | +除健康检查和注册登录外，所有接口需通过 `Authorization: Bearer ` 认证。 -**响应：** +### 已实现 -```json -{ - "code": 0, - "message": "ok", - "data": { - "prompt": "【主题】一个融合像素、战士元素的游戏角色精灵图...\n【风格】色彩鲜明；像素风格...\n【技术】输出格式: spritesheet；分辨率: 64x64...", - "rawText": "【主题】一个融合像素...\n【风格】色彩鲜明..." - } -} -``` - -| 字段 | 类型 | 说明 | +| 方法 | 路径 | 说明 | |------|------|------| -| `data.prompt` | string | 优化后的三段式提示词，可直接传入生成管线 | -| `data.rawText` | string | LLM 原始返回文本 | +| GET | `/api/v1/health` | 健康检查 | +| POST | `/auth/register` | 用户注册 | +| POST | `/auth/login` | 用户登录（返回 JWT Token） | +| POST | `/api/v1/prompt/optimize` | 提示词优化 | -接入真实 LLM 后（配置 `GEN2D_LLM_API_KEY`），LLM 会根据标签+原始描述+素材类型生成高质量、可执行的提示词。未配置 API key 时自动回退到模板生成。 +### 规划中 + +| 方法 | 路径 | 说明 | +|------|------|------| +| 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 服务 -├── frontend/ # Vite + React 前端 -└── docs/ # 项目文档 - ├── architecture.md # 架构设计 - └── api.md # API 文档 +├── 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 流水线 ``` -详细架构说明见 [docs/architecture.md](docs/architecture.md)。 - -## API - -接口统一前缀 `/api/v1/`，详见 [docs/api.md](docs/api.md)。 - ## 参与贡献 1. Fork 本仓库 -2. 新建 Feat_xxx 分支 +2. 新建 `Feat_xxx` 分支 3. 提交代码 4. 新建 Pull Request + +## License + +[MIT](LICENSE)