gen2d 架构设计

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

技术栈

Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 七牛云对象存储 / 可替换 AI 推理模型

文档索引

文档	说明
后端工程	分层结构、管线设计（PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter）、风格模型
前端工程	组件树、状态管理、路由、三栏工作台、自定义标签
API 设计	接口列表、请求/响应示例、错误码、认证
数据存储	SQLite 选型、表结构、ER 关系、对象存储、去重策略
异步任务	任务生命周期、并发控制、重试策略、进度推送
预设风格键	美术风格、色调、线条等风格键分类与可选值
架构图提示词	全局/后端/前端架构图生成提示词，供多模态 AI 生成架构图
实施计划	限流（令牌桶）、协程池、RabbitMQ 异步化的详细设计方案与实施步骤

系统架构

┌─────────────────────────────────────────────────────────┐
│                     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 次，超过后降级输出保证任务不阻塞。

详见后端工程。

风格系统（Style）

风格分为两层：

工程风格（Project Style）：工程级别的 kvPairs，保证同一工程下所有素材风格一致
任务风格覆盖（Task Style Override）：单次生成任务的风格差异，仅覆盖需要变化的键

合并逻辑：finalStyle = merge(projectStyle, taskStyle)，任务同名键覆盖工程风格。

详见后端工程 — 风格模型和预设风格键。

任务系统（Task）

采用"提交-异步执行-轮询/推送"模式。API 同步返回 taskId，后台 goroutine 执行管线，前端通过 HTTP 轮询或 WebSocket 获取实时进度。

详见异步任务。

数据模型

user 1──N project
project 1──1 project_style
project 1──N task
task 1──N asset

详见数据存储。

命令行参考

后端

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            # 代码检查

前端

cd frontend
npm install          # 安装依赖
npm run dev          # 开发服务器
npm run build        # 生产构建
npm run preview      # 预览构建产物
npm run typecheck    # 类型检查

6.7 KiB Executable File Raw Permalink Blame History Unescape Escape