docs: 后端采用 Eino 框架编排管线，完善前后端文档对齐
- 后端管线从手写编排改为 Eino compose.Graph，含质检重试分支 - 移除 CORS 中间件 - api.md 补充工程管理接口、任务状态机、管线阶段、WebSocket 消息示例 - frontend.md 组件树和交互流程改用 mermaid 图，stores 对齐 PipelineInput/Output - CLAUDE.md 修复死链，技术栈补充 Eino
This commit is contained in:
+214
-18
@@ -19,35 +19,64 @@
|
||||
|------|------|------|------|
|
||||
| [x] | GET | `/api/v1/health` | 健康检查 |
|
||||
|
||||
## 素材生成
|
||||
## 工程管理
|
||||
|
||||
| 状态 | 方法 | 路径 | 说明 |
|
||||
|------|------|------|------|
|
||||
| [ ] | POST | `/api/v1/generate` | 提交生成任务，返回 jobId |
|
||||
| [ ] | GET | `/api/v1/generate/:jobId` | 查询任务状态与进度 |
|
||||
| [ ] | GET | `/api/v1/generate/:jobId/result` | 获取生成结果（素材 URL + 元数据） |
|
||||
| [ ] | WS | `/api/v1/generate/:jobId/ws` | WebSocket 实时进度推送 |
|
||||
| [ ] | POST | `/api/v1/projects` | 创建工程 |
|
||||
| [ ] | GET | `/api/v1/projects/:projectId` | 获取工程信息 |
|
||||
| [ ] | GET | `/api/v1/projects/:projectId/tasks` | 获取工程下的任务列表 |
|
||||
|
||||
请求体示例 (POST /api/v1/generate)：
|
||||
### POST /api/v1/projects
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "一个拿剑的小人",
|
||||
"assetType": "sprite",
|
||||
"taskStyle": {
|
||||
"scene": "dungeon",
|
||||
"mood": "dark"
|
||||
},
|
||||
"params": {
|
||||
"resolution": 64,
|
||||
"frames": { "directions": 8, "framesPerDirection": 4 },
|
||||
"format": "spritesheet"
|
||||
"name": "我的像素游戏"
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"id": "proj_abc123",
|
||||
"name": "我的像素游戏",
|
||||
"style": { "kvPairs": {} },
|
||||
"createdAt": "2026-05-24T10:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `prompt`：用户原始文本，后端 PromptBuilder 负责三段式重写
|
||||
- `taskStyle`：可选，任务级别风格覆盖（同名键覆盖工程风格）
|
||||
### GET /api/v1/projects/:projectId/tasks
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `page` | int | 页码，默认 1 |
|
||||
| `pageSize` | int | 每页条数，默认 20 |
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"total": 42,
|
||||
"tasks": [
|
||||
{
|
||||
"id": "task_xyz789",
|
||||
"prompt": "一个拿剑的小人",
|
||||
"assetType": "sprite",
|
||||
"status": "completed",
|
||||
"createdAt": "2026-05-24T10:05:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 工程风格
|
||||
|
||||
@@ -69,6 +98,173 @@
|
||||
}
|
||||
```
|
||||
|
||||
## 素材生成
|
||||
|
||||
| 状态 | 方法 | 路径 | 说明 |
|
||||
|------|------|------|------|
|
||||
| [ ] | POST | `/api/v1/generate` | 提交生成任务，返回 taskId |
|
||||
| [ ] | GET | `/api/v1/tasks/:taskId` | 查询任务状态与进度 |
|
||||
| [ ] | GET | `/api/v1/tasks/:taskId/assets` | 获取生成结果（素材列表 + 元数据） |
|
||||
| [ ] | WS | `/api/v1/tasks/:taskId/ws` | WebSocket 实时进度推送 |
|
||||
|
||||
### POST /api/v1/generate
|
||||
|
||||
请求体对应后端 `PipelineInput`：
|
||||
|
||||
```json
|
||||
{
|
||||
"projectId": "proj_abc123",
|
||||
"prompt": "一个拿剑的小人",
|
||||
"assetType": "sprite",
|
||||
"taskStyle": {
|
||||
"scene": "dungeon",
|
||||
"mood": "dark"
|
||||
},
|
||||
"params": {
|
||||
"resolution": 64,
|
||||
"frames": { "directions": 8, "framesPerDirection": 4 },
|
||||
"format": "spritesheet"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `projectId` | string | 是 | 工程 ID，用于获取工程风格 |
|
||||
| `prompt` | string | 是 | 用户原始文本，后端 PromptBuilder 负责三段式重写 |
|
||||
| `assetType` | string | 是 | 素材类型：`sprite` / `background` / `ui` / `animation` |
|
||||
| `taskStyle` | object | 否 | 任务级别风格覆盖（同名键覆盖工程风格） |
|
||||
| `params.resolution` | int | 否 | 分辨率，默认 64 |
|
||||
| `params.frames` | object | 否 | 帧参数（仅 sprite/animation） |
|
||||
| `params.frames.directions` | int | 否 | 方向数，默认 4 |
|
||||
| `params.frames.framesPerDirection` | int | 否 | 每方向帧数，默认 4 |
|
||||
| `params.format` | string | 否 | 输出格式：`spritesheet` / `individual`，默认 `spritesheet` |
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"taskId": "task_xyz789",
|
||||
"status": "pending"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/tasks/:taskId
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"taskId": "task_xyz789",
|
||||
"projectId": "proj_abc123",
|
||||
"prompt": "一个拿剑的小人",
|
||||
"assetType": "sprite",
|
||||
"status": "running",
|
||||
"stage": "asset_generator",
|
||||
"progress": 45,
|
||||
"retryCount": 0,
|
||||
"createdAt": "2026-05-24T10:05:00Z",
|
||||
"updatedAt": "2026-05-24T10:05:30Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
任务状态机：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> pending
|
||||
pending --> running : 管线开始执行
|
||||
running --> completed : 四阶段全部通过
|
||||
running --> failed : 节点执行失败 / 超过重试次数
|
||||
completed --> [*]
|
||||
failed --> [*]
|
||||
```
|
||||
|
||||
管线阶段（对应 Eino Graph 节点）：
|
||||
|
||||
| 阶段 | 说明 |
|
||||
|------|------|
|
||||
| `prompt_builder` | 合并风格，生成三段式提示词 |
|
||||
| `asset_generator` | 调用 AI 推理 API 出图 |
|
||||
| `quality_supervisor` | 视觉模型质检（可能触发重试回到 prompt_builder） |
|
||||
| `format_adapter` | 格式转换、spritesheet 打包 |
|
||||
|
||||
### GET /api/v1/tasks/:taskId/assets
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"assets": [
|
||||
{
|
||||
"id": "asset_001",
|
||||
"url": "/files/tasks/task_xyz789/spritesheet.png",
|
||||
"format": "png",
|
||||
"width": 256,
|
||||
"height": 64,
|
||||
"metadata": {
|
||||
"frameWidth": 64,
|
||||
"frameHeight": 64,
|
||||
"frameCount": 4,
|
||||
"directions": 1
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### WebSocket 消息格式
|
||||
|
||||
连接路径：`ws://host/api/v1/tasks/:taskId/ws`
|
||||
|
||||
```typescript
|
||||
interface PipelineProgress {
|
||||
stage: 'prompt_builder' | 'asset_generator' | 'quality_supervisor' | 'format_adapter';
|
||||
status: 'running' | 'completed' | 'failed';
|
||||
progress: number; // 0-100
|
||||
message?: string; // 阶段描述
|
||||
retryCount?: number; // 质检重试次数（仅 quality_supervisor 阶段）
|
||||
rejectReason?: string; // 质检不通过原因（仅 quality_supervisor fail 时）
|
||||
result?: { // 仅在 format_adapter completed 时返回
|
||||
assets: Asset[];
|
||||
};
|
||||
error?: string; // 仅在 failed 时返回
|
||||
}
|
||||
```
|
||||
|
||||
消息示例（正常流程）：
|
||||
|
||||
```json
|
||||
{"stage":"prompt_builder","status":"running","progress":0}
|
||||
{"stage":"prompt_builder","status":"completed","progress":100}
|
||||
{"stage":"asset_generator","status":"running","progress":0}
|
||||
{"stage":"asset_generator","status":"completed","progress":100}
|
||||
{"stage":"quality_supervisor","status":"completed","progress":100}
|
||||
{"stage":"format_adapter","status":"running","progress":0}
|
||||
{"stage":"format_adapter","status":"completed","progress":100,"result":{"assets":[...]}}
|
||||
```
|
||||
|
||||
消息示例（质检重试）：
|
||||
|
||||
```json
|
||||
{"stage":"quality_supervisor","status":"running","progress":0}
|
||||
{"stage":"quality_supervisor","status":"failed","progress":100,"retryCount":1,"rejectReason":"风格不一致"}
|
||||
{"stage":"prompt_builder","status":"running","progress":0}
|
||||
{"stage":"asset_generator","status":"running","progress":0}
|
||||
{"stage":"quality_supervisor","status":"completed","progress":100}
|
||||
{"stage":"format_adapter","status":"completed","progress":100,"result":{"assets":[...]}}
|
||||
```
|
||||
|
||||
## 缓存管理
|
||||
|
||||
| 状态 | 方法 | 路径 | 说明 |
|
||||
|
||||
Reference in New Issue
Block a user