lunanting/ai-chatbot

Fork 0

Your Name ec988be30a

Lint / build (20) (push) Has been cancelled

Details

Playwright Tests / test (push) Has been cancelled

Details

Update agent workflow and video task handling

2026-03-13 11:21:42 +08:00

18 KiB

Raw Blame History

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

项目：ai-chatbot-main
文档目标：沉淀当前系统已实现能力，并给出“RUXA 视频九宫格 + Agent 技能化”完整可开发方案
适用范围：聊天页、无限画布、3D 生成、AI 详情、视频生成、存储迁移、后台模型配置

1. 项目定位与能力边界

本系统是一个多模态 AI 创作平台，核心能力覆盖：

文本/图片/视频对话式生成（统一在聊天链路）
无限画布创作与多节点编排（图片、视频、文本、3D）
Agent 智能路由与智能参数推荐
AI 详情生成（电商详情页自动分镜 + 质检回修）
多供应商模型治理（后台可配置 provider/model）
多存储后端（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

主流程：

鉴权 + 请求去重（同 chatId:messageId 防重入）
自动模式判定（selectedChatModel === "auto" 或固定视觉模型 + deepThinking）
历史图片补全（当前无图时回溯最近生成图/上传图）
调用 LangGraph Agent：
- 意图识别（图编/图生/视频/问答）
- 友好回复
- 提示词优化
- 推荐图片/视频参数
- 路由到最佳模型
按 provider 分支执行（文本、图片、视频）
流式返回 + 消息持久化 + 积分/配额扣减

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

核心能力：

电商详情 brief 结构化输入
分屏规划（传统生图 / agent_layout 可编辑文字层）
逐屏生成 + 质检 + 二次修图
存档回放（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 迁移降本

现状策略（已上线）：

上传优先走可用存储配置（支持 OSS 作为入口桶）
记录迁移任务（StorageMigrationTask）
定时任务将 OSS 图片转存到默认桶
回写数据库 URL（消息、画布、详情存档）
到期清理 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 视频 时：

Agent 判断用户上传图是否为九宫格
若是九宫格，切成 9 张图
用户脚本格式不固定，先由 Agent 归一为 9 镜头脚本
切图后尺寸偏小，后台预留“图片变清晰”调用链路（默认关闭，待测试后再开启）
每张图按对应脚本生成视频，串行发送，间隔 10 秒
失败自动重试；超限/失败可降级到其它视频模型
全流程可追踪进度，可回放任务结果

6.2 合理性评估结论

该需求合理，且与现有架构兼容；但需工程化约束：

超分能力先预留不启用，通过配置开关控制，默认 false
九宫格检测需置信度门槛，低置信度不自动切片
串行队列必须持久化到 DB，避免重启丢任务

7. 九宫格技能链设计（建议实现）

采用“技能链（Skill Chain）”封装，而不是把全部逻辑塞进 chat/route.ts。

实施约束：当前阶段仅输出方案文档，不改动业务代码；开发时必须按“技能封装”方式落地。

7.1 技能模块划分

script-normalizer-skill
输入任意脚本文本，输出标准 JSON（9 段）
nine-grid-detector-skill
判断是否九宫格 + 透视校正 + 切片 + 质量评分
tile-upscale-skill
对小图按阈值走增强（复用现有 enhance 能力，先预留默认关闭）
storyboard-mapper-skill
将 9 图与 9 段脚本一一映射，生成每段视频 prompt
video-sequencer-skill
串行调度（10s）+ 重试 + 降级模型 + 状态更新

7.2 技能触发规则（必须）

仅在满足以下条件时触发九宫格技能链：

当前模式为视频生成，且选中模型 provider 为 ruxa-video
用户消息包含至少 1 张图片
nine-grid-detector-skill 识别结果 isNineGrid=true
confidence >= minGridConfidence（默认 0.85）

触发后的流程：

进入 script-normalizer-skill
再进入 nine-grid-detector-skill 切片
按开关决定是否进入 tile-upscale-skill
进入 storyboard-mapper-skill
最后进入 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 或 3:3 拼图常见比例；分辨率 > 最低阈值
网格线检测：行列投影 + 边缘峰值，识别 2 条纵线 + 2 条横线
几何校正：若轻微透视，先矫正再切片
切后复检：每格清晰度、边界截断、相邻差异、主体完整度评分

8.2 判定阈值建议

grid_confidence >= 0.85：自动进入九宫格流程
0.65 ~ 0.85：进入“待确认”状态（Agent 提示用户确认）
< 0.65：走普通单图视频流程

8.3 输出结构建议

{
  "isNineGrid": true,
  "confidence": 0.92,
  "cropBoxes": [
    {"index": 1, "x": 0, "y": 0, "w": 342, "h": 342}
  ],
  "qualityScore": 0.88
}

9. 脚本归一化与分镜映射

9.1 脚本标准 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

建议：

抽出服务层（如 lib/image/enhance-service.ts），避免服务端内部再走 HTTP
增加特性开关 enableTileUpscale，默认 false（预留不启用）
仅当 enableTileUpscale=true 时，切片后按阈值触发超分（短边 < 768）
超分失败降级：保留原切片继续后续流程
记录 enhanceApplied/enhanceProvider/enhanceLatencyMs

11. 调度、重试、降级

11.1 串行调度规则

一次任务 9 段，严格串行
相邻请求间隔 10 秒
任一段失败：指数退避（10s/20s/40s），最多 3 次

11.2 降级模型规则

从后台 AiModel 读取，不硬编码：

先用当前选中模型
失败后按 fallbackModelId1 -> fallbackModelId2
若仍失败，按同 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 设计（建议新增）

POST /api/video/storyboard/create
创建九宫格视频任务，返回 taskId
GET /api/video/storyboard/tasks/:taskId
获取任务与每段进度
POST /api/video/storyboard/tasks/:taskId/cancel
取消任务
POST /api/jobs/video-storyboard-dispatch
调度器轮询（可由 cron/pm2 定时触发）

14. 与现有聊天链路集成方式

在 /api/chat 增加分支：

当前 provider 是否 ruxa-video
用户是否上传图片
是否触发九宫格识别（可由配置开关控制）

若命中：

先回 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 集成测试

上传九宫格 + 9段脚本 -> 全部成功
上传九宫格 + 混乱脚本 -> 归一成功
部分失败 -> 自动重试 + 降级成功
非九宫格 -> 正常走单图视频

18.3 验收标准

切片正确率 ≥ 95%
9 段任务可追踪、可重试、可取消
不出现并发超限（严格 10 秒间隔）
失败可降级且不丢任务状态

19. 发布计划（建议）

Phase 1：先上“检测 + 归一 + 任务表 + 状态查询”
Phase 2：接入“超分能力预留 + 串行调度”（超分开关保持关闭）
Phase 3：接入降级链路与前端进度 UI
Phase 4：灰度开关 + 指标监控 + 回归优化

20. 风险与规避

误判九宫格：加入置信度阈值与人工确认分支
成本过高：超分默认关闭，待效果验证后灰度开启
任务堆积：DB 队列 + 限流 + 可取消机制
外部 API 不稳定：重试 + fallback + 错误分级
多机部署一致性：调度基于 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

18 KiB Raw Blame History Unescape Escape

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

1. 项目定位与能力边界

2. 技术架构总览

2.1 技术栈

2.2 关键目录

3. 当前模型与供应商体系（已实现）

3.1 Provider 类型（后台可配置）

3.2 视频模型与模式能力（代码内置）

3.3 代码中已出现的具体模型名称（非运行态 DB 全量）

4. 核心链路说明（已实现）

4.1 聊天与 Agent 模式

4.2 无限画布

4.3 AI 详情生成

4.4 3D 生成（Tripo3D）

4.5 存储与 OSS 迁移降本

5. 数据库核心表（当前）

6. 新需求：RUXA 视频九宫格 + Agent 技能化（待开发）

6.1 需求归纳

6.2 合理性评估结论

7. 九宫格技能链设计（建议实现）

7.1 技能模块划分

7.2 技能触发规则（必须）

7.3 建议代码落点

8. 防切错设计（重点）

8.1 检测流程（四段式）

8.2 判定阈值建议

8.3 输出结构建议

9. 脚本归一化与分镜映射

9.1 脚本标准 JSON

9.2 映射策略

10. 超分链路设计（复用现有能力）

11. 调度、重试、降级

11.1 串行调度规则

11.2 降级模型规则

12. 数据库扩展设计（建议新增）

13. API 设计（建议新增）

14. 与现有聊天链路集成方式

15. 前端改造点（建议）

16. 配置项设计（系统设置）

17. 监控与告警

18. 测试与验收

18.1 单元测试

18.2 集成测试

18.3 验收标准

19. 发布计划（建议）

20. 风险与规避

21. 当前实施状态标记

22. 运维与发布命令（项目现状）

23. 附：本方案主要影响文件清单（开发阶段）

18 KiB

Raw Blame History