From 8372e299c17d9b098f57d299d4b3da87ded0ddbd Mon Sep 17 00:00:00 2001 From: wonder Date: Mon, 25 May 2026 20:26:31 +0800 Subject: [PATCH 1/3] =?UTF-8?q?fix:=20=E8=BE=93=E5=87=BA=E6=A0=BC=E5=BC=8F?= =?UTF-8?q?=E6=A0=B9=E6=8D=AE=E7=B4=A0=E6=9D=90=E7=B1=BB=E5=9E=8B=E8=87=AA?= =?UTF-8?q?=E5=8A=A8=E8=AE=BE=E7=BD=AE=E9=BB=98=E8=AE=A4=E5=80=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 精灵/动画默认精灵表，背景/UI默认单帧，用户仍可手动切换。 --- frontend/src/stores/task.ts | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/frontend/src/stores/task.ts b/frontend/src/stores/task.ts index a156691..244a7a2 100755 --- a/frontend/src/stores/task.ts +++ b/frontend/src/stores/task.ts @@ -28,6 +28,13 @@ interface TaskState { reset: () => void } +const DEFAULT_FORMAT: Record = { + sprite: 'spritesheet', + background: 'individual', + ui: 'individual', + animation: 'spritesheet', +} + const DEFAULT_PARAMS: TaskParams = { resolution: 1024, format: 'spritesheet', @@ -44,7 +51,12 @@ export const useTaskStore = create((set, get) => ({ setPrompt: (text) => set({ prompt: text, optimizedPrompt: null }), - setAssetType: (type) => set({ assetType: type, optimizedPrompt: null }), + setAssetType: (type) => + set({ + assetType: type, + params: { ...get().params, format: DEFAULT_FORMAT[type] }, + optimizedPrompt: null, + }), toggleTaskStyle: (key, value) => set(state => { From e8abc41c2a669a12e159e65df6e758dc89602899 Mon Sep 17 00:00:00 2001 From: wonder Date: Mon, 25 May 2026 20:48:50 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20=E4=BC=98=E5=8C=96=20README=20?= =?UTF-8?q?=E4=B8=8E=E6=96=87=E6=A1=A3=E7=B4=A2=E5=BC=95=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README 新增目录导航、参考链接、路线图、文档索引模块 - README 采用居中标题、Badge 行、快速链接栏的顶级开源项目风格 - 技术栈表增加说明列，项目结构细化各模块用途 - API 已实现/规划中拆分展示，合并近期新增接口 - docs/_index 新增 ASCII 系统架构图、核心概念概览、命令行参考 --- README.md | 275 ++++++++++++++++++++++++++++++++++--------------- docs/_index.md | 114 ++++++++++++++++++-- 2 files changed, 301 insertions(+), 88 deletions(-) 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 # 类型检查 +``` From 8ac039ef388dc6ae3f206f2e6f31cc2b3bf68893 Mon Sep 17 00:00:00 2001 From: wonder Date: Mon, 25 May 2026 20:52:59 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=85=A8?= =?UTF-8?q?=E5=B1=80/=E5=90=8E=E7=AB=AF/=E5=89=8D=E7=AB=AF=E6=9E=B6?= =?UTF-8?q?=E6=9E=84=E5=9B=BE=E7=94=9F=E6=88=90=E6=8F=90=E7=A4=BA=E8=AF=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增三个多模态 AI 架构图提示词文件，分别对应全局系统架构、 后端分层与管线、前端组件树与数据流的可视图生成。 --- docs/_index.md | 1 + docs/prompts/backend-architecture-prompt.md | 180 ++++++++++++++++++ docs/prompts/frontend-architecture-prompt.md | 184 +++++++++++++++++++ docs/prompts/global-architecture-prompt.md | 81 ++++++++ 4 files changed, 446 insertions(+) create mode 100644 docs/prompts/backend-architecture-prompt.md create mode 100644 docs/prompts/frontend-architecture-prompt.md create mode 100644 docs/prompts/global-architecture-prompt.md diff --git a/docs/_index.md b/docs/_index.md index 92b7960..bde8805 100755 --- a/docs/_index.md +++ b/docs/_index.md @@ -16,6 +16,7 @@ Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 七牛云对象 | [数据存储](database.md) | SQLite 选型、表结构、ER 关系、对象存储、去重策略 | | [异步任务](async-tasks.md) | 任务生命周期、并发控制、重试策略、进度推送 | | [预设风格键](style-keys.md) | 美术风格、色调、线条等风格键分类与可选值 | +| [架构图提示词](prompts/) | 全局/后端/前端架构图生成提示词，供多模态 AI 生成架构图 | ## 系统架构 diff --git a/docs/prompts/backend-architecture-prompt.md b/docs/prompts/backend-architecture-prompt.md new file mode 100644 index 0000000..2cb8c47 --- /dev/null +++ b/docs/prompts/backend-architecture-prompt.md @@ -0,0 +1,180 @@ +# 后端架构图 — 文生图提示词 + +你是一位技术架构可视化专家。请根据以下描述，生成一张 **gen2d 后端架构详图**，风格：**技术文档风格，白色或浅灰背景，清晰的层次关系和连线**。 + +## 标题 + +gen2d Backend Architecture (Go + Gin + Eino) + +## 整体布局 + +自上而下的分层架构图，共 5 层。 + +--- + +### 第 1 层：入口 (Entry Point) + +``` +cmd/main.go → 初始化 Config → 初始化 Logger → 初始化 DB → 注册路由 → 启动 HTTP Server (:8080) +``` + +用横向箭头串联的流程表示。 + +--- + +### 第 2 层：HTTP 层 (Handler + Middleware) + +分为两个子块并排放置： + +#### 左块：Middlewares (中间件链) + +三个中间件纵向排列，用向下箭头串联： +1. **Logger Middleware** — 生成 X-Request-ID，记录 method/path/status/latency +2. **Auth Middleware** — JWT Bearer Token 校验，注入 UserID 到 context +3. **Recovery Middleware** — Panic 恢复 + 堆栈日志 + +#### 右块：Handlers (路由处理) + +按路由分组展示： + +| 路由前缀 | Handler | 说明 | +|---------|---------|------| +| `/health` | health.go | 健康检查 | +| `/auth/*` | register.go, login.go | 认证（独立路径） | +| `/api/v1/projects/*` | project handlers | 工程 CRUD + 风格管理 | +| `/api/v1/generate` | generate.go | 提交生成任务 | +| `/api/v1/tasks/*` | task handlers | 任务查询 + 素材获取 | +| `/api/v1/prompt/*` | prompt.go | 提示词优化 | +| `/api/v1/assets/*` | storage.go | 素材下载 (302 重定向) | + +在 Handler 块内用小字标注：**"薄层: 仅参数绑定 + 校验 + 调用 Service + 返回统一响应"** + +--- + +### 第 3 层：Service 层 (核心业务逻辑) + +这是整个图的核心区域，占比最大。分为四个子块： + +#### 3a. Pipeline 编排 (pipeline.go) + +用流程图展示 Eino `compose.Graph` 的节点编排： + +``` + ┌─────────────────┐ + │ PipelineInput │ (user prompt + assetType + styles + params) + └────────┬────────┘ + ▼ + ┌──────────────────────┐ + │ ① PromptOptimizer │ 合并工程风格 + 任务风格覆盖 + │ 输出: 三段式提示词 │ 调用 LLM 生成规范化提示词 + └──────────┬───────────┘ + ▼ + ┌──────────────────────┐ + │ ② AssetGenerator │ OpenAI 兼容接口 /v1/images/generations + │ 输出: 原始图片列表 │ 支持多图生成 (n 参数) + └──────────┬───────────┘ + ▼ + ┌──────────────────────┐ + │ ③ QualitySupervisor │ 视觉模型检查风格一致性 + │ 输出: pass / fail │ + └──────┬──────┬────────┘ + │ │ + pass fail (retry < 3) ──→ 回到 ① (RejectReason 回填) + │ │ + │ fail (retry ≥ 3) ──→ 降级输出 ↓ + ▼ │ + ┌──────────────────────┐ │ + │ ④ FormatAdapter │ ◄──────┘ + │ spritesheet 打包 │ + │ 上传七牛云 + 写 DB │ + └──────────┬───────────┘ + ▼ + ┌──────────────────┐ + │ PipelineOutput │ (assets[] + metadata) + └──────────────────┘ +``` + +#### 3b. 节点实现 (nodes.go) + +四个节点用一个表格或四个小卡片展示，每个卡片包含： +- **节点名称** +- Lambda 输入 → 输出 类型签名 +- StatePreHandler / StatePostHandler 交互说明 + +| 节点 | 输入 → 输出 | State 交互 | +|------|-----------|-----------| +| PromptOptimizer | PipelineInput → string | Pre: 注入 RejectReason; Post: 写 FinalPrompt | +| AssetGenerator | string → []Image | Post: 写 RawImages | +| QualitySupervisor | []Image → bool | Post: 写 PassQuality, RejectReason, RetryCount | +| FormatAdapter | []Image → PipelineOutput | 无 State 交互，直接输出 | + +#### 3c. 类型定义 (types.go) + +一个小卡片展示三个核心结构体的字段： +- **PipelineInput**：Prompt, AssetType, ProjectStyle, TaskStyle, Params +- **PipelineState**：Input, FinalPrompt, RawImages, PassQuality, RejectReason, RetryCount +- **PipelineOutput**：Assets[], Metadata + +#### 3d. 辅助 Service + +并排两个小块： +- **auth.go**：注册 / 登录 / JWT 签发 (HS256) / Token 校验 +- **storage.go**：七牛云上传 (token 鉴权) / 下载 URL 生成 / 删除 +- **inference.go**：AI API 调用封装 (文生图 + 图片编辑) +- **prompt_agent.go**：LLM 提示词优化 Agent (OpenAI 兼容 Chat Completions, 含回退模板) + +--- + +### 第 4 层：数据访问层 + +- **db.go**：GORM SQLite 连接初始化 + 自动建表 (CREATE TABLE IF NOT EXISTS) +- **cache.go**：sync.Map 内存缓存，用于请求去重 (hash → taskId) +- **config.go**：环境变量读取 + 配置结构体 + +--- + +### 第 5 层：外部依赖 (底部并排) + +1. **SQLite** (`data/gen2d.db`) + - 5 张表：user, project, project_style, task, asset + - ER: user 1→N project 1→1 project_style, project 1→N task 1→N asset + - 全部 CASCADE 删除 + +2. **七牛云 Kodo** + - Bucket 存储 Key 格式：`users/{uid}/projects/{pid}/tasks/{tid}/output/{file}` + - CDN URL + 签名参数 (默认 3600s 过期) + +3. **LLM API (外部)** + - OpenAI 兼容 `/v1/images/generations` — 文生图 + - OpenAI 兼容 `/v1/chat/completions` — 提示词优化 + - 可替换模型提供商 + +--- + +## 色彩与排版指南 + +- **标题横幅**：深蓝 (#1E3A5F)，白色文字 +- **第 2 层 (Handler)**：浅蓝 (#E8F4FD)，深蓝边框 +- **第 3 层 (Service)**：浅绿 (#E6F7EE)，深绿边框 — 这是核心层，用稍大的面积 +- **管线节点**：用不同深浅绿色区分： + - ① 浅绿 #D1FAE5 + - ② 中绿 #A7F3D0 + - ③ 中绿 #6EE7B7 + - ④ 深绿 #34D399 +- **第 4 层 (Data)**：浅黄 (#FEF3C7)，深黄边框 +- **第 5 层 (External)**：浅灰 (#F3F4F6)，深灰边框 +- **箭头颜色**： + - 正常流程：实线 绿色 + - 重试/回退：虚线 橙色 + - 降级路径：虚线 红色 + +- 文字：sans-serif，英文为主，括号内中文辅助说明 +- 所有框使用圆角 (border-radius: 8px) +- 层与层之间用虚线分隔，标注层名称在左侧 + +## 附加约束 + +- 保持技术文档风格，干净利落 +- 所有组件名称与代码库中的实际命名一致 (pipeline.go, nodes.go, types.go 等) +- 画面比例 3:4 或 A4 竖版比例，适合放入文档 +- 不要使用 3D 效果或过度装饰 diff --git a/docs/prompts/frontend-architecture-prompt.md b/docs/prompts/frontend-architecture-prompt.md new file mode 100644 index 0000000..2b44e99 --- /dev/null +++ b/docs/prompts/frontend-architecture-prompt.md @@ -0,0 +1,184 @@ +# 前端架构图 — 文生图提示词 + +你是一位前端架构可视化专家。请根据以下描述，生成一张 **gen2d 前端架构详图**，风格：**现代前端技术文档风格，深色主题，组件树 + 数据流 + 路由三重展示**。 + +## 标题 + +gen2d Frontend Architecture (Vite + React + TypeScript + zustand) + +## 整体布局 + +分为三个主要区域，从左到右排列： + +--- + +## 左区：路由与页面层 (Router & Pages) + +### Router 入口 +- **react-router-dom v6** (BrowserRouter, SPA 模式) +- **ProtectedRoute** 守卫组件 (检查 token，未登录重定向 /login) + +### 页面路由表 + +用路由匹配图展示： + +``` +/ → HomePage (项目画廊) +/login → LoginPage (登录) +/register → RegisterPage (注册) +/projects/:projectId → ProjectDetailPage (三栏工作台) +/projects/:projectId/tasks/:taskId → ResultPage (素材预览) +``` + +### 页面层级关系 + +``` +App + └─ Layout (Navbar + Outlet + ToastContainer) + ├─ HomePage + │ ├─ ProjectCard (画廊卡片) × N + │ └─ CreateProjectModal (新建弹窗) + ├─ ProjectDetailPage (三栏 CSS Grid) + │ ├─ [左栏 260px] ProjectConfigPanel + │ ├─ [中间 1fr] GenerateForm + ProgressBar + │ └─ [右栏 320px] TaskListPanel + └─ ResultPage + └─ AssetPreview +``` + +--- + +## 中区：状态管理 & 数据流 (State Management) + +### zustand Stores (7 个) + +用 7 个卡片网格展示，每个卡片包含 Store 名称、核心状态字段、主要 Action： + +| Store | 核心 State | 主要 Actions | 消费组件 | +|-------|-----------|-------------|---------| +| **auth** | user, token, isAuthenticated | login, register, logout | Layout, ProtectedRoute, LoginPage | +| **projectList** | projects[], loading | loadProjects, createProject, deleteProject | HomePage | +| **project** | projectId, name, style, draftStyle, draftName, hasUnsavedChanges | loadProject, startEditing, updateDraft, commitDraft, discardDraft | ProjectConfigPanel, ProjectDetailPage | +| **task** | prompt, assetType, taskStyle, params, enableAI, optimizedPrompt | setters, runOptimize, reset | GenerateForm | +| **generation** | taskId, stage, progress, status, retryCount, assets[], error | submit, reset | ProgressBar, GenerateForm, ResultPage | +| **theme** | mode (light/dark) | toggle | Layout (全局主题切换) | +| **toast** | toasts[] | addToast, removeToast | ToastContainer | + +### 数据流方向 + +在组件和 Store 之间画出单向数据流箭头： +- **组件 → Store**：dispatch action (用户交互) +- **Store → 组件**：useStore selector 订阅，自动重渲染 +- **Store → API**：调用 api/ 封装层 +- **API → Store**：响应数据写入 state + +### 风格编辑流程 (Draft/Commit 模式) + +用一个小流程图展示： + +``` +startEditing() → copy style → draftStyle + ↓ +updateDraft(key, value) → draftStyle 变更 → hasUnsavedChanges = true + ↓ +┌─ commitDraft() → PUT /api/v1/projects/:id/style → style = draftStyle → hasUnsavedChanges = false +└─ discardDraft() → draftStyle = style → hasUnsavedChanges = false +``` + +--- + +## 右区：组件树 & 交互流程 (Components & Interactions) + +### 组件依赖树 + +``` +Layout +├── Navbar (logo + 导航 + 用户菜单) +└── ToastContainer + └── ToastItem × N + +HomePage +├── ProjectCard (缩略图 + 名称 + 任务数 + 最近活动) +└── CreateProjectModal + ├── StyleSelector (预设风格 pill 按钮) + └── CustomTagsEditor (添加/删除自定义标签) + +ProjectDetailPage (CSS Grid: 260px 1fr 320px) +├── [左栏] ProjectConfigPanel +│ ├── 工程名 (可编辑 input) +│ ├── StyleSelector (全量风格编辑) +│ ├── CustomTagsEditor +│ └── 保存/取消 按钮 (hasUnsavedChanges 控制) +├── [中间] 生成区域 +│ ├── GenerateForm +│ │ ├── 素材类型选择 (sprite / background / ui / animation) +│ │ ├── StyleSelector (任务覆盖，仅记录差异) +│ │ ├── PromptEditor (文本输入) +│ │ ├── 技术参数 (分辨率 / 帧数 / 格式) +│ │ └── 提交按钮 + AI 优化按钮 +│ └── ProgressBar (提交后显示) +│ └── 四阶段进度条 (prompt_builder → asset_generator → quality_supervisor → format_adapter) +└── [右栏] TaskListPanel + ├── StatusBadge (状态标签: pending/running/completed/failed) + ├── TaskItem × N (点击跳转 ResultPage) + └── 自动刷新 (15s 间隔) + +ResultPage +└── AssetPreview + ├── 图片预览 (带帧信息标注) + ├── 元数据展示 (分辨率/帧数/方向数/格式) + └── 下载按钮 (GET /api/v1/assets/download?key=...) +``` + +### 生成任务交互流程 (时序简化) + +``` +User → GenerateForm (填写 prompt + 选择类型 + 参数) → [提交] + → POST /api/v1/generate → taskId + → generation store: status=running + → ProgressBar 显示 + → 轮询 GET /api/v1/tasks/:taskId (每 1.5s) + → 更新 stage + progress + → status=completed + → GET /api/v1/tasks/:taskId/assets + → 显示 "查看结果" → 跳转 ResultPage +``` + +### API 封装层结构 (api/) + +在底部用一个窄条展示： + +``` +api/ +├── client.ts — fetch 封装 (统一错误处理, JSON 解包, Bearer Token 注入) +├── auth.ts — login(), register() +├── project.ts — listProjects(), createProject(), getProject(), updateProject(), deleteProject() +├── generate.ts — submitGenerate(), getTask(), getTaskAssets() +├── prompt.ts — optimizePrompt(), extractTags() +├── mock.ts — 多工程 Mock 数据 (开发用) +└── types.ts — Project, Task, Asset, User 等类型定义 +``` + +--- + +## 色彩与排版指南 + +- **背景**：深色 (#1a1a2e 或 #0f172a) +- **左区 (Router)**：紫色调 (#8B5CF6 / #7C3AED)，紫色边框 +- **中区 (State)**：青色调 (#06B6D4 / #0891B2)，青色边框 +- **右区 (Components)**：绿色调 (#10B981 / #059669)，绿色边框 +- **API 层**：橙色调 (#F59E0B) +- **组件框**：半透明背景 + 彩色左边框 +- **箭头**：白色或浅灰 (#94A3B8)，实线 = 同步，虚线 = 异步 +- **文字**：白色为主 (#F8FAFC)，次要文字浅灰 (#94A3B8) +- **Store 卡片**：微亮边框，内部字段用等宽字体 +- **所有框使用圆角** (border-radius: 6px) +- **区域标题**用较大的加粗字体 + 左侧色条 + +## 附加约束 + +- 所有组件名、Store 名、文件名与代码库保持一致 +- 中文用于辅助标注（括号内），英文为主要标注 +- 避免拥挤，分区之间留白充分 +- 画面比例 16:9 或更宽，适合横屏展示 +- 不要使用 3D 效果 diff --git a/docs/prompts/global-architecture-prompt.md b/docs/prompts/global-architecture-prompt.md new file mode 100644 index 0000000..3fa18d4 --- /dev/null +++ b/docs/prompts/global-architecture-prompt.md @@ -0,0 +1,81 @@ +# 全局架构图 — 文生图提示词 + +你是一位技术架构可视化专家。请根据以下描述，生成一张 **gen2d 全局系统架构图**，风格：**简洁现代的技术架构图，深色背景，使用清晰的方框和箭头表示组件与数据流**。 + +## 标题 + +gen2d 系统架构总览 + +## 技术栈标注（顶部或底部小字） + +Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 七牛云 Kodo + +## 架构层次（自上而下） + +### 第一层：前端层 (Frontend) + +放置一个圆角矩形框，标题为 **Frontend (Vite + React + TypeScript)**，内部包含： + +- **Pages (页面层)**：Login, Register, HomePage, ProjectDetailPage, ResultPage，以上下文无关方式排列 +- **State & Router (横跨栏)**： + - 左侧标注 **react-router-dom v6** (SPA Routing) + - 右侧标注 **zustand** (7 stores: auth, project, projectList, task, generation, theme, toast) +- **Components (组件层)**：StyleSelector, CustomTagsEditor, PromptEditor, GenerateForm, ProgressBar, AssetPreview + +在 Frontend 框内用水平虚线或分组分隔三个子层（页面 → 路由/状态 → 组件），展示分层关系。 + +### 第二层：通信层 + +在 Frontend 和 Backend 之间画一个横向箭头带，标注： + +- **HTTP REST /api/v1/***（实线） +- **WebSocket /api/v1/tasks/:taskId/ws**（虚线） +- 旁边小字标注 "JWT Bearer Token 认证" + +### 第三层：后端层 (Backend) + +放置一个圆角矩形框，标题为 **Backend (Go + Gin + Eino)**，内部自左向右分三层： + +#### 3a. Handler 层 (最左) +- Gin Router 入口 +- 薄层：参数绑定 + 校验 + 调用 Service +- 关键 Handler：health, auth, project, generate, prompt, storage + +#### 3b. Service 层 (中间，核心) +- 标题：**Eino compose.Graph (管线编排)** +- 四个节点从上到下，箭头连接： + 1. **PromptOptimizer** (提示词优化 + 风格合并) + 2. **AssetGenerator** (AI 推理 API 调用) + 3. **QualitySupervisor** (视觉模型质检) + 4. **FormatAdapter** (格式转换 + spritesheet 打包) +- 在第 3 步右侧标注分支逻辑：pass → FormatAdapter；fail → 回到 PromptOptimizer (最多 3 次) +- 在管线框下方放置 **中间件栏**：Logger (slog), JWT Auth, Panic Recovery + +#### 3c. Model 层 (最右) +- 数据模型：PipelineInput, PipelineState, PipelineOutput + +### 第四层：数据与基础设施层 (底部) + +放置三个并排的框： + +1. **SQLite** — 标注 5 张表：user, project, project_style, task, asset；附带 ER 关系简写 "1→N cascade" +2. **七牛云 Kodo (对象存储)** — 标注存储路径 `${user}/${project}/${task}/output/` 和 CDN URL 签名访问 +3. **LLM API (外部)** — 标注 OpenAI 兼容接口 `/v1/images/generations` 和 Chat Completions + +在前端和后端之间画出与这三个组件的连线，标注数据流方向。 + +## 色彩建议 + +- **Frontend 区域**：蓝紫色调 (#4A90D9 或类似) +- **Backend 区域**：青绿色调 (#00B4AB 或类似) +- **管线节点**：用不同深浅区分四个阶段 +- **数据层**：灰色调 (#6B7280 或类似) +- **外部服务**：橙色 (#F59E0B 或类似) +- **箭头**：实线 = 同步调用，虚线 = 异步/回调 + +## 附加约束 + +- 不要使用过于花哨的 3D 效果或阴影 +- 文字要清晰可读，字体大小不小于图中主体元素的 1/20 +- 请用英文标注组件名称（与代码库一致），中文可用于辅助说明 +- 整体比例适合 16:9 宽屏展示