# 系统全链路开发文档（基于当前项目）

> 项目：`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`