604 lines
18 KiB
Markdown
604 lines
18 KiB
Markdown
# 系统全链路开发文档（基于当前项目）
|
||
|
||
> 项目：`ai-chatbot-main`
|
||
> 文档目标：沉淀当前系统已实现能力，并给出“RUXA 视频九宫格 + Agent 技能化”完整可开发方案
|
||
> 适用范围：聊天页、无限画布、3D 生成、AI 详情、视频生成、存储迁移、后台模型配置
|
||
|
||
---
|
||
|
||
## 1. 项目定位与能力边界
|
||
|
||
本系统是一个多模态 AI 创作平台，核心能力覆盖：
|
||
|
||
1. 文本/图片/视频对话式生成（统一在聊天链路）
|
||
2. 无限画布创作与多节点编排（图片、视频、文本、3D）
|
||
3. Agent 智能路由与智能参数推荐
|
||
4. AI 详情生成（电商详情页自动分镜 + 质检回修）
|
||
5. 多供应商模型治理（后台可配置 provider/model）
|
||
6. 多存储后端（S3/MinIO/OSS）与 OSS 降本迁移任务
|
||
|
||
---
|
||
|
||
## 2. 技术架构总览
|
||
|
||
## 2.1 技术栈
|
||
|
||
- 前端：Next.js 16 + React 19 + Tailwind + shadcn/ui
|
||
- 后端：Next.js Route Handlers（Node Runtime）
|
||
- AI 编排：`ai` SDK + LangGraph（Agent 流程）
|
||
- 数据库：PostgreSQL + Drizzle ORM
|
||
- 存储：S3 兼容存储 / Aliyun OSS / Vercel Blob（兼容）
|
||
- 图像处理：`sharp`
|
||
- 状态管理：Zustand（画布）
|
||
|
||
## 2.2 关键目录
|
||
|
||
- 聊天主链路：`/Users/lanmu/Desktop/ai-chatbot-main/app/(chat)/api/chat/route.ts`
|
||
- 模型动态加载：`/Users/lanmu/Desktop/ai-chatbot-main/lib/ai/dynamic-provider.ts`
|
||
- Agent 编排：`/Users/lanmu/Desktop/ai-chatbot-main/lib/ai/auto-agent-graph.ts`
|
||
- 智能分析：`/Users/lanmu/Desktop/ai-chatbot-main/lib/ai/smart-analyzer.ts`
|
||
- 无限画布页面：`/Users/lanmu/Desktop/ai-chatbot-main/app/canvas/[id]/page.tsx`
|
||
- 画布聊天面板：`/Users/lanmu/Desktop/ai-chatbot-main/components/canvas/CanvasChatPanel.tsx`
|
||
- 3D 页面：`/Users/lanmu/Desktop/ai-chatbot-main/app/canvas/[id]/model3d/page.tsx`
|
||
- 3D API：`/Users/lanmu/Desktop/ai-chatbot-main/app/api/canvas/3d/tasks/route.ts`
|
||
- 后台设置：`/Users/lanmu/Desktop/ai-chatbot-main/app/(admin)/settings/admin-settings-client.tsx`
|
||
- 数据模型：`/Users/lanmu/Desktop/ai-chatbot-main/lib/db/schema.ts`
|
||
- 存储迁移任务：`/Users/lanmu/Desktop/ai-chatbot-main/lib/jobs/oss-image-migration-job.ts`
|
||
|
||
---
|
||
|
||
## 3. 当前模型与供应商体系（已实现）
|
||
|
||
## 3.1 Provider 类型（后台可配置）
|
||
|
||
已接入的 provider 类型（数据库 + 后台一致）：
|
||
|
||
- `alibaba`、`openai`、`custom`、`local`
|
||
- `gemini`、`huanke-gemini`
|
||
- `alibaba-image`、`ruxa-image`、`fal-image`、`volcano-vision`
|
||
- `qianwen-video`、`doubao-video`、`fal-video`、`ruxa-video`、`volcano-video`
|
||
- `tripo-3d`
|
||
- 扩展兼容：`zhipu`、`volcano-multimodal`（由 `custom` 映射识别）
|
||
|
||
参考实现：
|
||
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/app/api/admin/ai-providers/route.ts`
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/lib/ai/provider-defaults.ts`
|
||
|
||
## 3.2 视频模型与模式能力（代码内置）
|
||
|
||
视频能力模型通过 `capabilities + videoToolCapability` 驱动前端 UI 与参数限制：
|
||
|
||
- RUXA：仅 `first-frame`（图生视频），比例 `16:9/9:16/1:1`，时长 `5/10`
|
||
- Qianwen：`first-frame`
|
||
- FAL：`first-frame/first-last-frame`
|
||
- Volcano/Doubao：支持文生/首帧/首尾帧/多参考图（按模型能力动态裁剪）
|
||
|
||
参考实现：
|
||
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/lib/ai/video-tool-capability.ts`
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/components/video-params-bar.tsx`
|
||
|
||
## 3.3 代码中已出现的具体模型名称（非运行态 DB 全量）
|
||
|
||
- RUXA 视频：`veo3.1`（后台模型可配置）
|
||
- 实时画布默认模型：`fal-ai/flux-2/klein/realtime`
|
||
- 火山预设模型族：
|
||
- `doubao-seedance-1-0-pro-250528`
|
||
- `doubao-seedance-1-0-pro-fast-251015`
|
||
- `doubao-seedance-1-0-lite-t2v-250428`
|
||
- `doubao-seedance-1-0-lite-i2v-250428`
|
||
- Tripo3D 版本选项：
|
||
- `Turbo-v1.0-20250506`
|
||
- `v3.1-20260211`
|
||
- `v3.0-20250812`
|
||
- `v2.5-20250123`
|
||
- `v2.0-20240919`
|
||
- `v1.4-20240625`
|
||
|
||
说明：系统最终“在用模型清单”来自数据库 `AiModel`，由后台“AI模型/本地AI模型”动态配置。
|
||
|
||
---
|
||
|
||
## 4. 核心链路说明（已实现）
|
||
|
||
## 4.1 聊天与 Agent 模式
|
||
|
||
入口：`POST /api/chat`
|
||
实现：`/Users/lanmu/Desktop/ai-chatbot-main/app/(chat)/api/chat/route.ts`
|
||
|
||
主流程：
|
||
|
||
1. 鉴权 + 请求去重（同 `chatId:messageId` 防重入）
|
||
2. 自动模式判定（`selectedChatModel === "auto"` 或固定视觉模型 + deepThinking）
|
||
3. 历史图片补全（当前无图时回溯最近生成图/上传图）
|
||
4. 调用 LangGraph Agent：
|
||
- 意图识别（图编/图生/视频/问答）
|
||
- 友好回复
|
||
- 提示词优化
|
||
- 推荐图片/视频参数
|
||
- 路由到最佳模型
|
||
5. 按 provider 分支执行（文本、图片、视频）
|
||
6. 流式返回 + 消息持久化 + 积分/配额扣减
|
||
|
||
## 4.2 无限画布
|
||
|
||
页面：`/canvas/[id]`
|
||
实现：
|
||
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/app/canvas/[id]/page.tsx`
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/components/canvas/CanvasWorkspace.tsx`
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/store/canvas/index.ts`
|
||
|
||
能力：
|
||
|
||
- 节点类型：`message/image/video/text/scene-fusion/model3d`
|
||
- 自动保存 + 节流重试（429 后重试）
|
||
- 节点操作：拖拽、缩放、撤销/重做、多选
|
||
- 画布与聊天联动（图片可回注对话）
|
||
|
||
## 4.3 AI 详情生成
|
||
|
||
核心接口：
|
||
|
||
- `POST /api/canvas/detail-plan`
|
||
- `POST /api/canvas/detail-review`
|
||
- `GET|POST|PATCH|DELETE /api/canvas/[id]/detail-archives`
|
||
|
||
核心能力：
|
||
|
||
1. 电商详情 brief 结构化输入
|
||
2. 分屏规划（传统生图 / `agent_layout` 可编辑文字层）
|
||
3. 逐屏生成 + 质检 + 二次修图
|
||
4. 存档回放（`canvasDetailArchive`）
|
||
|
||
主要实现：
|
||
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/components/canvas/CanvasChatPanel.tsx`
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/app/api/canvas/detail-plan/route.ts`
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/app/api/canvas/detail-review/route.ts`
|
||
|
||
## 4.4 3D 生成（Tripo3D）
|
||
|
||
页面：`/canvas/[id]/model3d`
|
||
API：
|
||
|
||
- `POST /api/canvas/3d/upload-image`
|
||
- `POST /api/canvas/3d/tasks`
|
||
- `GET /api/canvas/3d/tasks/[taskId]`
|
||
- `GET /api/canvas/3d/balance`
|
||
|
||
后端关键点：
|
||
|
||
- 从 `AiProvider(type="tripo-3d")` 读取 key/baseUrl
|
||
- 对 API key 做隐藏字符清洗（解决 ByteString 8232 问题）
|
||
- 统一 Tripo 错误结构返回（含 traceId）
|
||
|
||
主要实现：
|
||
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/lib/tripo/server.ts`
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/lib/tripo/client.ts`
|
||
|
||
## 4.5 存储与 OSS 迁移降本
|
||
|
||
现状策略（已上线）：
|
||
|
||
1. 上传优先走可用存储配置（支持 OSS 作为入口桶）
|
||
2. 记录迁移任务（`StorageMigrationTask`）
|
||
3. 定时任务将 OSS 图片转存到默认桶
|
||
4. 回写数据库 URL（消息、画布、详情存档）
|
||
5. 到期清理 OSS 源对象
|
||
|
||
接口：
|
||
|
||
- `POST /api/jobs/migrate-oss-images`
|
||
- `GET /api/jobs/migrate-oss-images`
|
||
|
||
主要实现：
|
||
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/lib/storage/service.ts`
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/lib/jobs/oss-image-migration-job.ts`
|
||
- `/Users/lanmu/Desktop/ai-chatbot-main/app/api/jobs/migrate-oss-images/route.ts`
|
||
|
||
---
|
||
|
||
## 5. 数据库核心表（当前）
|
||
|
||
主要业务表：
|
||
|
||
- `AiProvider`：供应商配置
|
||
- `AiModel`：模型配置、能力、故障迁移字段
|
||
- `StorageConfig`：存储桶配置
|
||
- `StorageMigrationTask`：OSS 迁移任务
|
||
- `SiteSettings` + `SystemSettings`：站点与功能开关
|
||
- `Message`：消息主表（含视频存储元数据）
|
||
- `GeneratedImage`：图片记录
|
||
- `CanvasProject`、`CanvasNode`、`CanvasImageTask`
|
||
- `CanvasDetailArchive`：AI详情归档
|
||
|
||
定义文件：`/Users/lanmu/Desktop/ai-chatbot-main/lib/db/schema.ts`
|
||
|
||
---
|
||
|
||
## 6. 新需求：RUXA 视频九宫格 + Agent 技能化（待开发）
|
||
|
||
> 2026-03-12 补充需求：多宫格（4/6/9）标准切片、切片后先生成高清镜头图、用户确认分镜后才允许开始生视频。
|
||
> 需求详见：`docs/多宫格分镜视频需求补充-2026-03-12.md`
|
||
> 开发清单详见：`docs/多宫格分镜视频开发清单-2026-03-12.md`
|
||
|
||
## 6.1 需求归纳
|
||
|
||
当用户在视频模式选中 `RUXA 视频` 时：
|
||
|
||
1. Agent 判断用户上传图是否为九宫格
|
||
2. 若是九宫格，切成 9 张图
|
||
3. 用户脚本格式不固定，先由 Agent 归一为 9 镜头脚本
|
||
4. 切图后尺寸偏小，后台预留“图片变清晰”调用链路（默认关闭，待测试后再开启）
|
||
5. 每张图按对应脚本生成视频，串行发送，间隔 10 秒
|
||
6. 失败自动重试；超限/失败可降级到其它视频模型
|
||
7. 全流程可追踪进度，可回放任务结果
|
||
|
||
## 6.2 合理性评估结论
|
||
|
||
该需求合理，且与现有架构兼容；但需工程化约束：
|
||
|
||
- 超分能力先预留不启用，通过配置开关控制，默认 `false`
|
||
- 九宫格检测需置信度门槛，低置信度不自动切片
|
||
- 串行队列必须持久化到 DB，避免重启丢任务
|
||
|
||
---
|
||
|
||
## 7. 九宫格技能链设计（建议实现）
|
||
|
||
采用“技能链（Skill Chain）”封装，而不是把全部逻辑塞进 `chat/route.ts`。
|
||
|
||
> 实施约束：当前阶段仅输出方案文档，不改动业务代码；开发时必须按“技能封装”方式落地。
|
||
|
||
## 7.1 技能模块划分
|
||
|
||
1. `script-normalizer-skill`
|
||
输入任意脚本文本，输出标准 JSON（9 段）
|
||
|
||
2. `nine-grid-detector-skill`
|
||
判断是否九宫格 + 透视校正 + 切片 + 质量评分
|
||
|
||
3. `tile-upscale-skill`
|
||
对小图按阈值走增强（复用现有 enhance 能力，先预留默认关闭）
|
||
|
||
4. `storyboard-mapper-skill`
|
||
将 9 图与 9 段脚本一一映射，生成每段视频 prompt
|
||
|
||
5. `video-sequencer-skill`
|
||
串行调度（10s）+ 重试 + 降级模型 + 状态更新
|
||
|
||
## 7.2 技能触发规则（必须）
|
||
|
||
仅在满足以下条件时触发九宫格技能链：
|
||
|
||
1. 当前模式为视频生成，且选中模型 provider 为 `ruxa-video`
|
||
2. 用户消息包含至少 1 张图片
|
||
3. `nine-grid-detector-skill` 识别结果 `isNineGrid=true`
|
||
4. `confidence >= minGridConfidence`（默认 0.85）
|
||
|
||
触发后的流程：
|
||
|
||
1. 进入 `script-normalizer-skill`
|
||
2. 再进入 `nine-grid-detector-skill` 切片
|
||
3. 按开关决定是否进入 `tile-upscale-skill`
|
||
4. 进入 `storyboard-mapper-skill`
|
||
5. 最后进入 `video-sequencer-skill`
|
||
|
||
未触发时（任一条件不满足）：
|
||
|
||
- 直接走现有普通视频链路，不进入九宫格技能链
|
||
|
||
## 7.3 建议代码落点
|
||
|
||
- `lib/video-agent/skills/script-normalizer.ts`
|
||
- `lib/video-agent/skills/nine-grid-detector.ts`
|
||
- `lib/video-agent/skills/tile-upscaler.ts`
|
||
- `lib/video-agent/skills/storyboard-mapper.ts`
|
||
- `lib/video-agent/skills/video-sequencer.ts`
|
||
- `lib/video-agent/pipeline/ruxa-nine-grid-pipeline.ts`
|
||
|
||
聊天主链路只做路由：
|
||
|
||
- 修改 `/Users/lanmu/Desktop/ai-chatbot-main/app/(chat)/api/chat/route.ts`
|
||
- 当 provider=`ruxa-video` 且满足“技能触发规则”时调用 pipeline
|
||
|
||
---
|
||
|
||
## 8. 防切错设计（重点）
|
||
|
||
## 8.1 检测流程（四段式）
|
||
|
||
1. **预检**：宽高比接近 1:1 或 3:3 拼图常见比例；分辨率 > 最低阈值
|
||
2. **网格线检测**：行列投影 + 边缘峰值，识别 2 条纵线 + 2 条横线
|
||
3. **几何校正**：若轻微透视，先矫正再切片
|
||
4. **切后复检**：每格清晰度、边界截断、相邻差异、主体完整度评分
|
||
|
||
## 8.2 判定阈值建议
|
||
|
||
- `grid_confidence >= 0.85`：自动进入九宫格流程
|
||
- `0.65 ~ 0.85`：进入“待确认”状态（Agent 提示用户确认）
|
||
- `< 0.65`：走普通单图视频流程
|
||
|
||
## 8.3 输出结构建议
|
||
|
||
```json
|
||
{
|
||
"isNineGrid": true,
|
||
"confidence": 0.92,
|
||
"cropBoxes": [
|
||
{"index": 1, "x": 0, "y": 0, "w": 342, "h": 342}
|
||
],
|
||
"qualityScore": 0.88
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 脚本归一化与分镜映射
|
||
|
||
## 9.1 脚本标准 JSON
|
||
|
||
```json
|
||
{
|
||
"language": "zh",
|
||
"globalStyle": "写实电影感",
|
||
"shots": [
|
||
{
|
||
"index": 1,
|
||
"durationSec": 3,
|
||
"action": "角色抬头看向镜头",
|
||
"camera": "轻微推进",
|
||
"mood": "期待",
|
||
"negativePrompt": "抖动,畸变,低清"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 9.2 映射策略
|
||
|
||
- 默认 `shot[i] -> tile[i]`
|
||
- 若脚本中有显式编号（如“第3镜头”）优先按编号映射
|
||
- 脚本不足 9 段：补全占位镜头（继承全局风格）
|
||
- 脚本超过 9 段：截断并告知用户
|
||
|
||
---
|
||
|
||
## 10. 超分链路设计（复用现有能力）
|
||
|
||
当前已有增强接口：`POST /api/enhance`
|
||
|
||
建议：
|
||
|
||
1. 抽出服务层（如 `lib/image/enhance-service.ts`），避免服务端内部再走 HTTP
|
||
2. 增加特性开关 `enableTileUpscale`，默认 `false`（预留不启用）
|
||
3. 仅当 `enableTileUpscale=true` 时，切片后按阈值触发超分（短边 < 768）
|
||
4. 超分失败降级：保留原切片继续后续流程
|
||
5. 记录 `enhanceApplied/enhanceProvider/enhanceLatencyMs`
|
||
|
||
---
|
||
|
||
## 11. 调度、重试、降级
|
||
|
||
## 11.1 串行调度规则
|
||
|
||
- 一次任务 9 段，严格串行
|
||
- 相邻请求间隔 10 秒
|
||
- 任一段失败：指数退避（10s/20s/40s），最多 3 次
|
||
|
||
## 11.2 降级模型规则
|
||
|
||
从后台 `AiModel` 读取，不硬编码：
|
||
|
||
1. 先用当前选中模型
|
||
2. 失败后按 `fallbackModelId1 -> fallbackModelId2`
|
||
3. 若仍失败，按同 provider 可用模型池挑选
|
||
|
||
---
|
||
|
||
## 12. 数据库扩展设计（建议新增）
|
||
|
||
新增任务主表：`VideoStoryboardTask`
|
||
|
||
- `id`
|
||
- `userId`
|
||
- `chatId`
|
||
- `providerType`（默认 `ruxa-video`）
|
||
- `sourceImageUrl`
|
||
- `isNineGrid`
|
||
- `detectionConfidence`
|
||
- `normalizedScript` (jsonb)
|
||
- `status`（pending/running/partial_success/succeeded/failed/cancelled）
|
||
- `currentShot`
|
||
- `totalShots`（固定 9）
|
||
- `createdAt/updatedAt/completedAt`
|
||
|
||
新增子任务表：`VideoStoryboardShotTask`
|
||
|
||
- `id`
|
||
- `parentTaskId`
|
||
- `shotIndex`
|
||
- `tileImageUrl`
|
||
- `upscaledImageUrl`
|
||
- `prompt`
|
||
- `modelId`
|
||
- `fallbackChain` (jsonb)
|
||
- `attemptCount`
|
||
- `status`
|
||
- `videoUrl`
|
||
- `errorCode/errorMessage`
|
||
- `startedAt/completedAt`
|
||
|
||
---
|
||
|
||
## 13. API 设计（建议新增）
|
||
|
||
1. `POST /api/video/storyboard/create`
|
||
创建九宫格视频任务，返回 `taskId`
|
||
|
||
2. `GET /api/video/storyboard/tasks/:taskId`
|
||
获取任务与每段进度
|
||
|
||
3. `POST /api/video/storyboard/tasks/:taskId/cancel`
|
||
取消任务
|
||
|
||
4. `POST /api/jobs/video-storyboard-dispatch`
|
||
调度器轮询（可由 cron/pm2 定时触发）
|
||
|
||
---
|
||
|
||
## 14. 与现有聊天链路集成方式
|
||
|
||
在 `/api/chat` 增加分支：
|
||
|
||
1. 当前 provider 是否 `ruxa-video`
|
||
2. 用户是否上传图片
|
||
3. 是否触发九宫格识别（可由配置开关控制）
|
||
|
||
若命中：
|
||
|
||
- 先回 SSE 占位消息（“正在识别九宫格与解析分镜...”）
|
||
- 创建 storyboard 任务
|
||
- 前端按 taskId 轮询并展示 9 段进度
|
||
- 最终输出 9 条视频或合并汇总消息
|
||
|
||
---
|
||
|
||
## 15. 前端改造点（建议）
|
||
|
||
- `components/video-params-bar.tsx`
|
||
- 新增“九宫格自动分镜”开关（RUXA 模式显示）
|
||
- `components/messages.tsx`
|
||
- 支持展示分段进度条（1/9 ~ 9/9）
|
||
- `components/chat.tsx` / `components/canvas/CanvasChatPanel.tsx`
|
||
- 扩展任务状态卡片（处理中、重试中、降级中）
|
||
|
||
---
|
||
|
||
## 16. 配置项设计（系统设置）
|
||
|
||
在系统设置新增 `video_storyboard_config`：
|
||
|
||
- `enabled`：是否启用九宫格流程
|
||
- `providerWhitelist`：默认仅 `ruxa-video`
|
||
- `minGridConfidence`：默认 0.85
|
||
- `enableTileUpscale`：是否启用切片超分（默认 false，预留）
|
||
- `sliceUpscaleMinEdge`：默认 768
|
||
- `dispatchIntervalSec`：默认 10
|
||
- `maxRetry`：默认 3
|
||
- `enableFallback`：默认 true
|
||
|
||
存储位置：`SystemSettings`
|
||
|
||
---
|
||
|
||
## 17. 监控与告警
|
||
|
||
建议埋点：
|
||
|
||
- `nine_grid_detect_success_rate`
|
||
- `nine_grid_misdetect_rate`
|
||
- `script_normalize_success_rate`
|
||
- `shot_retry_rate`
|
||
- `fallback_trigger_rate`
|
||
- `storyboard_task_success_rate`
|
||
- `avg_storyboard_total_latency`
|
||
|
||
日志关键词建议统一：
|
||
|
||
- `[VideoStoryboard]`
|
||
- `[NineGridDetector]`
|
||
- `[ScriptNormalizer]`
|
||
- `[TileUpscaler]`
|
||
- `[VideoSequencer]`
|
||
|
||
---
|
||
|
||
## 18. 测试与验收
|
||
|
||
## 18.1 单元测试
|
||
|
||
- 九宫格检测：标准图、弱网格图、非九宫格图
|
||
- 脚本归一：口语化、表格化、混合语言
|
||
- 映射规则：缺段/超段/乱序编号
|
||
- 重试降级：模拟 429、余额不足、超时
|
||
|
||
## 18.2 集成测试
|
||
|
||
1. 上传九宫格 + 9段脚本 -> 全部成功
|
||
2. 上传九宫格 + 混乱脚本 -> 归一成功
|
||
3. 部分失败 -> 自动重试 + 降级成功
|
||
4. 非九宫格 -> 正常走单图视频
|
||
|
||
## 18.3 验收标准
|
||
|
||
- 切片正确率 ≥ 95%
|
||
- 9 段任务可追踪、可重试、可取消
|
||
- 不出现并发超限（严格 10 秒间隔）
|
||
- 失败可降级且不丢任务状态
|
||
|
||
---
|
||
|
||
## 19. 发布计划（建议）
|
||
|
||
1. Phase 1：先上“检测 + 归一 + 任务表 + 状态查询”
|
||
2. Phase 2：接入“超分能力预留 + 串行调度”（超分开关保持关闭）
|
||
3. Phase 3：接入降级链路与前端进度 UI
|
||
4. Phase 4：灰度开关 + 指标监控 + 回归优化
|
||
|
||
---
|
||
|
||
## 20. 风险与规避
|
||
|
||
1. **误判九宫格**：加入置信度阈值与人工确认分支
|
||
2. **成本过高**：超分默认关闭，待效果验证后灰度开启
|
||
3. **任务堆积**：DB 队列 + 限流 + 可取消机制
|
||
4. **外部 API 不稳定**：重试 + fallback + 错误分级
|
||
5. **多机部署一致性**：调度基于 DB 状态机，不依赖内存队列
|
||
|
||
---
|
||
|
||
## 21. 当前实施状态标记
|
||
|
||
- 聊天/画布/3D/AI详情/OSS迁移：**已实现并在代码中可见**
|
||
- RUXA 九宫格视频技能链：**本文档为待开发方案（尚未落地代码）**
|
||
|
||
---
|
||
|
||
## 22. 运维与发布命令（项目现状）
|
||
|
||
- 安装依赖：`pnpm install --no-frozen-lockfile`
|
||
- 数据库迁移：`pnpm db:migrate`
|
||
- 构建：`pnpm build`
|
||
- 启动：`pnpm start`
|
||
- PM2 重启：`pm2 restart ai-chatbot || pm2 restart all`
|
||
|
||
---
|
||
|
||
## 23. 附：本方案主要影响文件清单（开发阶段）
|
||
|
||
新增（建议）：
|
||
|
||
- `lib/video-agent/pipeline/ruxa-nine-grid-pipeline.ts`
|
||
- `lib/video-agent/skills/script-normalizer.ts`
|
||
- `lib/video-agent/skills/nine-grid-detector.ts`
|
||
- `lib/video-agent/skills/tile-upscaler.ts`
|
||
- `lib/video-agent/skills/storyboard-mapper.ts`
|
||
- `lib/video-agent/skills/video-sequencer.ts`
|
||
- `app/api/video/storyboard/create/route.ts`
|
||
- `app/api/video/storyboard/tasks/[taskId]/route.ts`
|
||
- `app/api/jobs/video-storyboard-dispatch/route.ts`
|
||
- `lib/db/migrations/00xx_add_video_storyboard_tasks.sql`
|
||
|
||
修改（建议）：
|
||
|
||
- `app/(chat)/api/chat/route.ts`
|
||
- `lib/ai/providers/ruxa-video.ts`
|
||
- `app/(admin)/settings/admin-settings-client.tsx`
|
||
- `lib/db/schema.ts`
|
||
- `lib/db/queries.ts`
|