diff --git a/README.md b/README.md index ab566ea..6121f3e 100755 --- a/README.md +++ b/README.md @@ -1,48 +1,71 @@ # gen2d -AI 驱动的 2D 游戏素材生成工具。通过文本提示词或可视化参数，生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧，无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流。 +

+ 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) +

+ Go + Gin + Eino + React + TypeScript + Vite + License +

-### **[在线体验 http://47.121.181.112:10000](http://47.121.181.112:10000)** +

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

+ +--- + +## 目录 + +- [特性](#特性) +- [快速开始](#快速开始) +- [配置](#配置) +- [架构](#架构) + - [生成管线](#生成管线) + - [提示词优化链路](#提示词优化链路) + - [预设风格键](#预设风格键) +- [API](#api) +- [技术栈](#技术栈) +- [项目结构](#项目结构) +- [部署](#部署) +- [文档](#文档) +- [路线图](#路线图) +- [参与贡献](#参与贡献) +- [参考链接](#参考链接) +- [License](#license) ## 特性 -- **多智能体协作管线** — PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter，基于 Eino `compose.Graph` 编排 +- **多智能体协作管线** — PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter，基于 Eino `compose.Graph` 编排，支持质检重试与降级输出 - **提示词优化** — Eino Chain 驱动的 PromptAgent，支持任意 OpenAI 兼容 API，无 key 时自动回退模板生成 - **风格系统** — 预设美术风格、色调、线条、场景、光照、情绪等维度，支持工程级与任务级风格覆盖 - **实时进度** — WebSocket 推送管线各阶段状态、进度与质检重试信息 -- **异步任务** — 内存队列 + 通道模型，支持并发控制、失败重试（最多 3 次）与降级输出 -- **请求去重** — 相同 `prompt + assetType + params` 的并发请求自动合并 +- **异步任务** — goroutine 模型，支持并发控制、失败重试（最多 3 次）与降级输出 +- **请求去重** — 相同 `prompt + assetType + params` 的并发请求自动合并，返回已有 taskId - **暗色主题** — 前端支持 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 | +- **一键部署** — Docker Compose 双容器架构 + `deploy.sh` 脚本 ## 快速开始 +### 环境要求 + +- Go 1.26+ +- Node.js 20+ +- Docker & Docker Compose（部署用） + ### 后端 ```bash @@ -62,14 +85,14 @@ npm install npm run dev ``` -开发服务器默认运行在 `http://localhost:5173`，通过 Vite proxy 转发 `/api` 和 `/auth` 请求到后端。 +开发服务器运行在 `http://localhost:5173`，通过 Vite proxy 转发 `/api` 和 `/auth` 请求到后端。 ## 配置 配置通过 Viper 读取，优先级从高到低： | 优先级 | 来源 | 说明 | -|--------|------|------| +|:---:|------|------| | 1 | 环境变量 | 适合 Docker / CI，敏感字段推荐使用 | | 2 | `.env` 文件 | 位于 `backend/.env`，通过 godotenv 加载 | | 3 | `config.yml` | 位于 `backend/internal/config/config.yml`，存放非敏感默认值 | @@ -80,7 +103,7 @@ npm run dev | 环境变量 | 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_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 数 | @@ -90,7 +113,7 @@ npm run dev | 环境变量 | 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` | 生成图片高度 | @@ -149,8 +172,6 @@ graph TD | 光照 | `lighting` | bright, dim, dramatic, ambient, neon | | 情绪 | `mood` | cheerful, dark, mysterious, epic, calm | -详细架构说明见 [docs/_index.md](docs/_index.md)。 - ## API 接口统一前缀 `/api/v1/`，统一响应格式： @@ -169,21 +190,87 @@ graph TD | 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） | ### 规划中 | 方法 | 路径 | 说明 | |------|------|------| -| 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 实时进度推送 | +| GET | `/api/v1/auth/me` | 获取当前用户信息 | +| PUT | `/api/v1/auth/password` | 修改密码 | 完整 API 文档见 [docs/api.md](docs/api.md)。 +## 技术栈 + +| 层 | 技术 | 说明 | +|---|------|------| +| 后端语言 | Go 1.26 | — | +| HTTP 框架 | Gin v1.12 | 路由、中间件、JSON 绑定 | +| 管线编排 | [Eino](https://github.com/cloudwego/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 @@ -196,7 +283,7 @@ docker compose up -d --build ``` - 后端：Go 多阶段构建，暴露 8080 端口 -- 前端：Node 构建 + nginx 反向代理，默认映射到宿主机 10000 端口 +- 前端：Node 构建 + nginx 反向代理，默认映射宿主机 10000 端口 - 数据持久化：`backend-data` 卷挂载 SQLite 数据库与生成素材 ### 一键脚本 @@ -207,45 +294,33 @@ 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 流水线 -``` +详细设计文档见 [docs/](docs/) 目录： + +| 文档 | 说明 | +|------|------| +| [docs/_index.md](docs/_index.md) | 文档索引与架构概述 | +| [docs/api.md](docs/api.md) | API 接口设计、请求/响应示例、错误码 | +| [docs/backend.md](docs/backend.md) | 后端分层结构、管线设计、风格模型、缓存层 | +| [docs/frontend.md](docs/frontend.md) | 前端组件树、状态管理、路由、交互流程 | +| [docs/database.md](docs/database.md) | SQLite 选型、表结构、ER 关系、对象存储、去重策略 | +| [docs/async-tasks.md](docs/async-tasks.md) | 任务生命周期、并发控制、重试策略、进度推送 | +| [docs/style-keys.md](docs/style-keys.md) | 预设风格键分类与可选值 | + +## 路线图 + +- [x] 提示词优化 Agent（Eino Chain） +- [x] 多智能体生成管线（Eino Graph） +- [x] 工程风格系统 + 任务级覆盖 +- [x] 用户认证（JWT + bcrypt） +- [x] 异步任务 + 实时进度推送 +- [x] 素材帧预览、GIF 动画与导出 +- [x] 自定义标签 +- [ ] WebSocket 实时进度推送（待完成） +- [ ] 批量生成与队列调度 +- [ ] 文生图多模型适配（DALL-E, Midjourney） +- [ ] 素材版本管理与历史记录 ## 参与贡献 @@ -254,6 +329,42 @@ gen2d/ 3. 提交代码 4. 新建 Pull Request +## 参考链接 + +### 后端 + +- [Go](https://go.dev/) — 编程语言 +- [Gin](https://gin-gonic.com/) — HTTP 框架 +- [Eino](https://github.com/cloudwego/eino) — AI 管线编排框架 +- [GORM](https://gorm.io/) — Go ORM +- [golang-jwt](https://github.com/golang-jwt/jwt) — JWT 库 +- [Viper](https://github.com/spf13/viper) — 配置管理 + +### 前端 + +- [React](https://react.dev/) — UI 框架 +- [TypeScript](https://www.typescriptlang.org/) — 类型安全 +- [Vite](https://vite.dev/) — 构建工具 +- [Zustand](https://github.com/pmndrs/zustand) — 状态管理 +- [react-router](https://reactrouter.com/) — 路由 + +### AI / 模型 + +- [DeepSeek API](https://platform.deepseek.com/) — 默认 LLM +- [Stability AI](https://platform.stability.ai/) — 默认文生图 +- [OpenAI API](https://platform.openai.com/) — 兼容接口 + +### 游戏引擎 + +- [Unity 2D](https://unity.com/solutions/2d) — 支持精灵图集导入 +- [Godot Engine](https://godotengine.org/) — 开源 2D/3D 引擎 + +### 基础设施 + +- [Docker](https://www.docker.com/) — 容器化 +- [SQLite](https://www.sqlite.org/) — 嵌入式数据库 +- [七牛云 Kodo](https://www.qiniu.com/products/kodo) — 对象存储 + ## License [MIT](LICENSE) diff --git a/docs/_index.md b/docs/_index.md index 5fc8745..92b7960 100755 --- a/docs/_index.md +++ b/docs/_index.md @@ -8,9 +8,111 @@ Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 七牛云对象 ## 文档索引 -- [后端工程](backend.md) — 分层结构、管线设计（PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter）、风格模型 -- [前端工程](frontend.md) — 组件树、状态管理、路由、三栏工作台、自定义标签 -- [异步任务](async-tasks.md) — 任务队列、状态机、并发控制、失败重试 -- [数据存储](database.md) — SQLite 选型、表结构、七牛云对象存储 -- [API 设计](api.md) — 接口列表、请求/响应示例、实现状态 -- [预设风格键](style-keys.md) — 美术风格、色调、线条等风格键分类与可选值 +| 文档 | 说明 | +|------|------| +| [后端工程](backend.md) | 分层结构、管线设计（PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter）、风格模型 | +| [前端工程](frontend.md) | 组件树、状态管理、路由、三栏工作台、自定义标签 | +| [API 设计](api.md) | 接口列表、请求/响应示例、错误码、认证 | +| [数据存储](database.md) | SQLite 选型、表结构、ER 关系、对象存储、去重策略 | +| [异步任务](async-tasks.md) | 任务生命周期、并发控制、重试策略、进度推送 | +| [预设风格键](style-keys.md) | 美术风格、色调、线条等风格键分类与可选值 | + +## 系统架构 + +``` +┌─────────────────────────────────────────────────────────┐ +│ Frontend (Vite + React) │ +│ ┌─────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ │ +│ │ 画廊页 │ │ 三栏工作台 │ │ 结果预览页 │ │ 登录注册 │ │ +│ └─────────┘ └──────────┘ └────────────┘ └──────────┘ │ +│ │ HTTP / WebSocket │ +└──────────────────────┼──────────────────────────────────┘ + │ +┌──────────────────────┼──────────────────────────────────┐ +│ Backend (Go + Gin + Eino) │ +│ │ │ +│ ┌───────────────────▼──────────────────────────────┐ │ +│ │ Eino compose.Graph │ │ +│ │ ┌──────────────┐ ┌──────────────┐ │ │ +│ │ │PromptOptimizer│─▶│AssetGenerator│ │ │ +│ │ └──────────────┘ └──────────────┘ │ │ +│ │ ▲ │ │ │ +│ │ │ ┌────────────▼──────────┐ │ │ +│ │ │ │ QualitySupervisor │ │ │ +│ │ │ └────────────┬──────────┘ │ │ +│ │ │ pass │ fail (retry < 3) │ │ +│ │ └────────────────┘ │ │ +│ │ fail, retry ≥ 3 │ │ +│ │ │ ┌──────────────┐ │ │ +│ │ └─▶│FormatAdapter │ │ │ +│ │ └──────────────┘ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌────────────┼────────────┐ │ +│ │ │ │ │ +│ ┌────▼───┐ ┌─────▼────┐ ┌───▼──────┐ │ +│ │ SQLite │ │ 七牛云 Kodo│ │ LLM API │ │ +│ └────────┘ └──────────┘ └──────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +## 核心概念 + +### 生成管线（Pipeline） + +基于 Eino `compose.Graph` 的四阶段管线。每个阶段是一个 Lambda 节点，通过 `StatePreHandler` / `StatePostHandler` 读写全局状态。质检不通过时，Graph 分支自动触发重优化，最多重试 3 次，超过后降级输出保证任务不阻塞。 + +详见 [后端工程](backend.md#多阶段生成管线)。 + +### 风格系统（Style） + +风格分为两层： + +- **工程风格（Project Style）**：工程级别的 kvPairs，保证同一工程下所有素材风格一致 +- **任务风格覆盖（Task Style Override）**：单次生成任务的风格差异，仅覆盖需要变化的键 + +合并逻辑：`finalStyle = merge(projectStyle, taskStyle)`，任务同名键覆盖工程风格。 + +详见 [后端工程 — 风格模型](backend.md#风格模型) 和 [预设风格键](style-keys.md)。 + +### 任务系统（Task） + +采用"提交-异步执行-轮询/推送"模式。API 同步返回 taskId，后台 goroutine 执行管线，前端通过 HTTP 轮询或 WebSocket 获取实时进度。 + +详见 [异步任务](async-tasks.md)。 + +### 数据模型 + +``` +user 1──N project +project 1──1 project_style +project 1──N task +task 1──N asset +``` + +详见 [数据存储](database.md#er-关系)。 + +## 命令行参考 + +### 后端 + +```bash +cd backend +go mod tidy # 安装依赖 +go run cmd/main.go # 开发服务器 +go build -o bin/gen2d cmd/main.go # 构建 +go test ./... # 全部测试 +go test -run TestX ./internal/service/ # 单测 +golangci-lint run # 代码检查 +``` + +### 前端 + +```bash +cd frontend +npm install # 安装依赖 +npm run dev # 开发服务器 +npm run build # 生产构建 +npm run preview # 预览构建产物 +npm run typecheck # 类型检查 +```