docs: 适配单机场景，简化存储与认证方案
- 数据库：MySQL → SQLite，去掉连接池配置和 golang-migrate - 文件存储：OSS 对象存储 → 本地文件系统，统一 Gin 静态文件服务 - ID 生成：Sonyflake → 前缀+随机字符串 - 认证：Bearer Token → httpOnly Cookie，WebSocket 同步改为 Cookie 认证 - 质检重试：PromptBuilder 重试时注入 RejectReason 改进提示词 - 合并 multi-agent-pipeline.md 到 backend.md，消除文档重复 - 移除缓存管理 API（暴露内部实现细节）
This commit is contained in:
+75
-10
@@ -30,13 +30,13 @@ backend/internal/
|
||||
│ └── style.go # 工程风格 & 任务风格覆盖
|
||||
├── middleware/ # 中间件
|
||||
│ ├── logger.go
|
||||
│ ├── auth.go # JWT 认证中间件
|
||||
│ ├── auth.go # JWT 认证中间件（从 Cookie 读取 Token）
|
||||
│ └── ratelimit.go
|
||||
├── config/ # [已有] 配置
|
||||
│ └── config.go
|
||||
├── queue/ # 异步任务队列
|
||||
│ └── jobqueue.go
|
||||
└── cache/ # 缓存层（请求去重 + 结果缓存）
|
||||
└── cache/ # 缓存层（请求去重）
|
||||
└── cache.go
|
||||
```
|
||||
|
||||
@@ -46,17 +46,71 @@ backend/internal/
|
||||
- **service**：承载所有业务逻辑。`pipeline.go` 通过 Eino `compose.Graph` 编排四个节点；`nodes.go` 实现各节点逻辑；`types.go` 定义显式状态结构体。
|
||||
- **model**：纯数据结构，不含业务逻辑。
|
||||
|
||||
## 管线设计（Eino compose.Graph）
|
||||
## 多阶段生成管线
|
||||
|
||||
四阶段管线，含质检不通过时的重生成分支：
|
||||
gen2d 的核心生成流程采用 Eino `compose.Graph` 编排的四阶段管线，含质检不通过时的重生成分支。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
START --> PromptBuilder --> AssetGenerator --> QualitySupervisor
|
||||
QualitySupervisor -- pass --> FormatAdapter --> END
|
||||
QualitySupervisor -- fail --> PromptBuilder
|
||||
A["PromptBuilder\n(提示词工程)"] --> B["AssetGenerator\n(AI 出图)"]
|
||||
B --> C["QualitySupervisor\n(质检)"]
|
||||
C -- pass --> D["FormatAdapter\n(格式适配)"]
|
||||
C -- fail --> A
|
||||
```
|
||||
|
||||
### 各阶段职责
|
||||
|
||||
#### 1. PromptBuilder
|
||||
|
||||
- **输入**：用户文本 + 素材类型标签 + 工程风格 + 任务风格覆盖 + 技术参数
|
||||
- **输出**：三段式完整生成提示词
|
||||
- **职责**：
|
||||
1. 解析用户文本，提取核心内容作为【主题】
|
||||
2. 合并工程风格与任务风格覆盖（任务同名键覆盖工程），生成【约束】（含负面提示词）
|
||||
3. 注入素材类型、分辨率等技术参数作为【内容】
|
||||
4. 拼接为最终提示词
|
||||
5. **重试时**：将上次质检的 RejectReason 注入【约束】段，指导 AI 修正问题
|
||||
|
||||
**风格合并**：
|
||||
|
||||
```go
|
||||
finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
|
||||
```
|
||||
|
||||
工程风格保证同一工程下所有素材风格一致；任务风格仅覆盖需要差异化的键。
|
||||
|
||||
**三段式提示词结构**：
|
||||
|
||||
```
|
||||
【主题】用户的原始描述核心内容
|
||||
【约束】风格键值对生成的约束条件 + 负面提示词 + [重试时] 上次质检问题：{rejectReason}
|
||||
【内容】素材类型、分辨率、帧数等技术参数
|
||||
```
|
||||
|
||||
#### 2. AssetGenerator
|
||||
|
||||
- **输入**：PromptBuilder 的输出
|
||||
- **输出**：原始生成图片（单张或多张）
|
||||
- **职责**：调用 AI 推理 API 出图。不同素材类型的差异化需求已在上一步注入提示词中。
|
||||
- **接口规范**：统一采用 OpenAI 兼容的 `/v1/images/generations` 格式。多张生成通过 `n` 参数请求，实际支持数量取决于后端模型（如 DALL-E 3 仅支持 `n=1`，需多次调用模拟多张）。
|
||||
|
||||
#### 3. QualitySupervisor
|
||||
|
||||
- **输入**：原始生成图片 + 风格配置
|
||||
- **输出**：通过 / 不通过 + 不通过的原因
|
||||
- **职责**：通过视觉模型检查素材是否符合提示词要求与风格约束。不通过时，Graph 分支将 RejectReason 回填到 PipelineState，路由回 PromptBuilder 重新生成（最多 3 次，超过则降级输出）。
|
||||
|
||||
#### 4. FormatAdapter
|
||||
|
||||
- **输入**：通过质检的图片 + 素材类型
|
||||
- **输出**：游戏引擎可用的素材文件 + 元数据
|
||||
- **职责**：格式转换、spritesheet 打包、元数据生成。
|
||||
- **示例**：输入 4 张 64×64 的角色行走帧 PNG → 输出一张 256×64 的 spritesheet + JSON 元数据（帧尺寸、帧数、锚点偏移），可直接拖入 Unity 2D Animation 使用。
|
||||
|
||||
---
|
||||
|
||||
## 管线设计（Eino compose.Graph）
|
||||
|
||||
### 类型定义（types.go）
|
||||
|
||||
```go
|
||||
@@ -105,6 +159,7 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {
|
||||
|
||||
// 添加节点
|
||||
_ = g.AddLambdaNode(nodePromptBuilder, promptBuilderNode,
|
||||
compose.WithStatePreHandler(promptBuilderPreHandler), // 重试时注入 RejectReason
|
||||
compose.WithStatePostHandler(promptBuilderPostHandler))
|
||||
_ = g.AddLambdaNode(nodeAssetGenerator, assetGeneratorNode,
|
||||
compose.WithStatePostHandler(assetGeneratorPostHandler))
|
||||
@@ -142,7 +197,7 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {
|
||||
|
||||
| 节点 | Lambda 输入→输出 | State 交互 | 职责 |
|
||||
|------|-----------------|-----------|------|
|
||||
| PromptBuilder | `PipelineInput → string` | PostHandler 写入 FinalPrompt | 合并风格 → 生成三段式提示词 |
|
||||
| PromptBuilder | `PipelineInput → string` | PreHandler 读取 RejectReason，PostHandler 写入 FinalPrompt | 合并风格 → 生成三段式提示词（重试时注入质检问题） |
|
||||
| AssetGenerator | `string → []GeneratedImage` | PostHandler 写入 RawImages | 调用 AI 推理 API 出图 |
|
||||
| QualitySupervisor | `[]GeneratedImage → bool` | PostHandler 写入 PassQuality + RejectReason + RetryCount | 视觉模型质检 |
|
||||
| FormatAdapter | `[]GeneratedImage → PipelineOutput` | 无 | 格式转换、spritesheet 打包 |
|
||||
@@ -150,10 +205,18 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {
|
||||
```go
|
||||
// PromptBuilder 节点：接收输入，输出提示词
|
||||
var promptBuilderNode = compose.InvokableLambda(func(ctx context.Context, in PipelineInput) (string, error) {
|
||||
// 合并 projectStyle + taskStyle，生成三段式提示词
|
||||
return buildPrompt(in), nil
|
||||
})
|
||||
|
||||
// StatePreHandler：重试时将 RejectReason 注入输入
|
||||
func promptBuilderPreHandler(ctx context.Context, in PipelineInput, state *PipelineState) (PipelineInput, error) {
|
||||
if state.RetryCount > 0 && state.RejectReason != "" {
|
||||
// 将上次质检问题附加到输入中，供 buildPrompt 注入【约束】段
|
||||
in.RejectReason = state.RejectReason
|
||||
}
|
||||
return in, nil
|
||||
}
|
||||
|
||||
// StatePostHandler：将提示词写入全局状态
|
||||
func promptBuilderPostHandler(ctx context.Context, out string, state *PipelineState) (string, error) {
|
||||
state.FinalPrompt = out
|
||||
@@ -189,6 +252,8 @@ func RunPipeline(ctx context.Context, in PipelineInput) (*PipelineOutput, error)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键实体
|
||||
|
||||
| 实体 | 说明 | 关系 |
|
||||
@@ -242,4 +307,4 @@ finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
|
||||
- **数据结构**：`sync.Map`，key 为 `hash(prompt + assetType + params)`，value 为 taskId
|
||||
- **生命周期**：任务提交时写入，任务完成或失败后清除；可设置 TTL 过期兜底
|
||||
- **作用域**：单实例内存，不跨实例共享
|
||||
- **接口**：提供 `Get`/`Set`/`Delete`/`Clear` 方法，同时供 handler 层（缓存管理 API）和 service 层（去重检查）调用
|
||||
- **接口**：提供 `Get`/`Set`/`Delete`/`Clear` 方法，供 service 层（去重检查）调用
|
||||
|
||||
Reference in New Issue
Block a user