lunanting/ai-chatbot

Fork 0

Your Name d272bd5ee8

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

Details

Playwright Tests / test (push) Has been cancelled

Details

feat(canvas): add Tripo3D generation workspace and provider config

2026-02-28 21:57:51 +08:00

13 KiB

Raw Permalink Blame History

无限画布 3D 生成（Tripo3D）开发文档

0. 文档信息

文档版本：v1.0（开发方案）
编写日期：2026-02-28
适用项目：ai-chatbot-main（Next.js + 无限画布）
目标：在无限画布左侧工具栏新增「3D生成」入口，并新增独立 3D 生成页面，接入 Tripo3D OpenAPI，实现文生3D/图生3D并回流到画布节点

1. 背景与目标

当前无限画布已支持图片、视频、文本、实时画布等工作流，但缺少 3D 资产生产能力。新增 3D 生成能力后，用户可在同一工作空间内完成：

文案到 3D（Text to 3D）
图片到 3D（Image to 3D）
3D 资产预览、格式转换、导入画布、下载复用

本次先完成「文档先行」：明确 API、架构、页面、数据流、错误处理、安全与验收标准，为后续编码提供统一基线。

2. Tripo3D API 研究结论（用于接入实现）

2.1 基础信息

Base URL：https://api.tripo3d.ai/v2/openapi
鉴权：Authorization: Bearer <TRIPO_API_KEY>
通用响应结构：
- 成功：{ code: 0, data: ... }
- 失败：{ code: 非0, message, suggestion }
响应头可包含追踪字段：X-Tripo-Trace-ID

2.2 本项目相关接口

能力	方法	路径	用途
创建任务	POST	`/task`	发起 text_to_model / image_to_model / convert_model 等任务
查询任务	GET	`/task/{task_id}`	轮询任务状态与输出
上传图片（STS）	POST	`/upload/sts`	图生3D前上传参考图并获取 token
STS Token	POST	`/upload/sts/token`	进阶上传流程（S3 直传）
查询余额	GET	`/user/balance`	展示可用额度

2.3 任务类型（本期聚焦）

text_to_model（MVP 必做）
image_to_model（MVP 必做）
convert_model（MVP 建议做：统一为 GLB/GLTF）
refine_model（V1.1）
multiview_to_model（V1.1）

2.4 任务状态

进行中：queued、running
结束态：success、failed、banned、expired、cancelled、unknown

建议前端状态映射：

queued/running -> generating
success -> completed
其他结束态 -> failed

2.5 输出字段（按可用性优先级）

任务成功后输出可能在以下字段出现：

pbr_model
model
base_model
generated_image（预览图）
rendered_image（预览图）

建议导入画布时优先选择：pbr_model > model > base_model。

2.6 已确认可选模型版本（写入产品文案与参数面板）

可用版本示例（官方文档中出现）：

Turbo-v1.0-20250506（建议默认）
v3.1-20260211
v3.0-20250812
v2.5-20250123
v2.0-20240919
v1.4-20240625（部分可能已废弃）

说明：模型版本可能变更，运行时应允许后台动态配置默认值与可选列表。

2.7 关键约束

速率与并发（文档值）：
- Refine 并发上限：5
- 其他任务并发上限：10
- 图片上传：10 QPS
图片输入：
- 格式：webp | jpeg | png
- 尺寸：20~6000px（建议 >256px）
输出 URL 可能短时有效（文档提到默认较短有效期），不能只在前端缓存，建议尽快回存到自有存储

2.8 典型错误码（需做前端友好映射）

1002：鉴权失败
1004：参数错误
1007：触发限流
2000：超出限制
2001：任务不存在
2002：任务类型不支持
2004：文件类型不支持
2008：内容策略拦截
2010：余额不足
2015：模型版本废弃
2017：模型版本无效

3. 业务范围定义

3.1 MVP（本期上线）

无限画布左侧工具栏新增 3D生成 按钮
新增页面：/canvas/[id]/model3d
支持文生3D、图生3D
支持任务轮询、结果预览、一键导入画布
支持下载 3D 文件（至少 GLB/GLTF）
错误态、超时态、重试机制可用

3.2 V1.1（增强）

refine_model 二次精修
批量任务队列与历史检索
多格式导出（USDZ/FBX/OBJ/STL/3MF）
3D 资产库与复用

4. 现有系统接入点（基于当前代码）

已确认关键文件：

画布主页面：/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
节点类型定义：/Users/lanmu/Desktop/ai-chatbot-main/types/canvas/index.ts
现有独立功能页范式（实时画布）：/Users/lanmu/Desktop/ai-chatbot-main/app/canvas/[id]/realtime/page.tsx
全局设计 Token：/Users/lanmu/Desktop/ai-chatbot-main/app/globals.css

当前节点类型暂不含 3D，需扩展：

现状：message | image | video | text | scene-fusion
新增：model3d

项目已具备 3D 渲染依赖（无需新增核心依赖）：

three
@react-three/fiber
@react-three/drei

5. 页面与交互设计（参考图布局 + 站内 UI 规范）

5.1 页面路由

新页面：/canvas/[id]/model3d
从画布侧栏按钮进入；关闭后返回 /canvas/[id]

5.2 结构分区（桌面端）

顶部：轻量标题栏（返回、项目名、余额、帮助）
左侧参数区（约 320px）：
- 生成模式切换：文生3D / 图生3D
- Prompt 输入
- 参考图上传（图生3D）
- 高级参数折叠（模型版本、面数、贴图、PBR、seed）
- 主按钮：开始生成
中央预览区（主视觉）：
- 3D Viewer（OrbitControls）
- 状态覆盖层（排队中/生成中/失败）
- 结果操作（导入画布、下载、重新生成）
右侧任务区（约 300px）：
- 当前任务状态卡
- 最近任务历史（可重开结果）
- 输出资源信息（格式、大小、创建时间）

5.3 视觉规范（必须遵循站内风格）

使用现有 Token，不复制参考图配色：

背景：bg-background
卡片：bg-card border
主色：bg-primary text-primary-foreground
辅助文本：text-muted-foreground
圆角：与现有画布一致（rounded-xl/2xl）
毛玻璃与阴影：沿用 backdrop-blur + shadow-sm/2xl

5.4 移动端策略

左右栏折叠为抽屉（参数抽屉 + 任务抽屉）
中央 Viewer 全宽
关键操作固定底栏（生成 / 导入画布）

6. 系统架构设计

flowchart LR
  A["Canvas Sidebar: 3D生成"] --> B["/canvas/[id]/model3d 页面"]
  B --> C["Next.js API: /api/canvas/3d/*"]
  C --> D["Tripo OpenAPI"]
  D --> C
  C --> E["任务状态返回前端"]
  E --> B
  B --> F["导入画布 model3d 节点"]
  F --> G["CanvasStore + CanvasProject.canvasData"]

6.1 前端层

新建页面组件：app/canvas/[id]/model3d/page.tsx
新建 3D 业务组件（建议）：
- components/canvas/Model3DStudio.tsx
- components/canvas/model3d/Model3DViewer.tsx
- components/canvas/model3d/TaskHistoryPanel.tsx
在 app/canvas/[id]/page.tsx 左侧工具栏新增入口按钮（图标建议 Box）

6.2 后端 API 代理层

新增接口（同域代理，隐藏 Tripo Key）：

POST /api/canvas/3d/upload-image
POST /api/canvas/3d/tasks
GET /api/canvas/3d/tasks/[taskId]
GET /api/canvas/3d/balance
POST /api/canvas/3d/import（可选，做导入封装）

6.3 Tripo 适配层

新增服务层（建议）：

lib/tripo/client.ts：底层请求、鉴权头、trace-id 提取
lib/tripo/types.ts：请求/响应类型
lib/tripo/mappers.ts：错误码与状态映射

7. 详细数据流

7.1 文生3D流程

前端提交 prompt + modelVersion + params
后端 POST /task（type=text_to_model）
返回 taskId
前端轮询 GET /api/canvas/3d/tasks/[taskId]
成功后拿到模型 URL（优先 pbr_model）
预览通过后点击「导入画布」
生成 model3d 节点并持久化画布

7.2 图生3D流程

上传参考图到后端
后端调用 Tripo POST /upload/sts，拿到 image token
后端 POST /task（type=image_to_model）
后续轮询与导入同上

7.3 轮询策略

初始间隔：2s
单任务最大时长：8~10 分钟（可配置）
超时处理：标记失败并提示可重试
页面离开后自动停止轮询

8. 内部 API 合同（建议定稿）

8.1 `POST /api/canvas/3d/upload-image`

请求：multipart/form-data（file）

响应：

{
  "success": true,
  "data": {
    "imageToken": "xxxx",
    "source": "tripo-sts"
  }
}

8.2 `POST /api/canvas/3d/tasks`

请求（文生）：

{
  "taskType": "text_to_model",
  "prompt": "a cute toy robot",
  "modelVersion": "Turbo-v1.0-20250506",
  "faceLimit": 120000,
  "texture": true,
  "pbr": true
}

请求（图生）：

{
  "taskType": "image_to_model",
  "imageToken": "xxxx",
  "modelVersion": "Turbo-v1.0-20250506",
  "faceLimit": 120000,
  "texture": true,
  "pbr": true
}

响应：

{
  "success": true,
  "data": {
    "taskId": "task_xxx",
    "status": "queued"
  }
}

8.3 `GET /api/canvas/3d/tasks/[taskId]`

响应（成功）：

{
  "success": true,
  "data": {
    "taskId": "task_xxx",
    "status": "success",
    "outputs": {
      "modelUrl": "https://...",
      "previewImageUrl": "https://..."
    },
    "raw": {}
  }
}

响应（失败）：

{
  "success": false,
  "error": "余额不足",
  "code": 2010,
  "retryable": false
}

8.4 `GET /api/canvas/3d/balance`

{
  "success": true,
  "data": {
    "balance": 123.45,
    "unit": "credits"
  }
}

9. 无限画布节点扩展方案

9.1 类型定义

更新 types/canvas/index.ts：

NodeType 新增 model3d
新增 Model3DNodeData：
- src（模型地址）
- previewImage?
- format（glb/gltf/usdz/fbx/obj...）
- prompt?
- modelVersion?
- status
- metadata（faceLimit、texture、seed、taskId、traceId 等）

9.2 组件渲染

新增：components/canvas/nodes/Model3DNode.tsx
更新：components/canvas/CanvasWorkspace.tsx 渲染分支
节点交互：
- 预览缩略图
- 下载
- 复制链接
- 删除
- 在新窗口查看 3D

9.3 数据持久化

MVP 可不加新表，直接利用现有 CanvasProject.canvasData JSON 存储节点。

V1.1 如需任务历史和统计，可新增 Canvas3DTask 表。

10. 后端安全与配置

10.1 鉴权与密钥

Tripo API Key 仅保留在服务端（TRIPO_API_KEY）
前端严禁直连 Tripo API
所有 /api/canvas/3d/* 必须校验登录态

10.2 输入约束

上传文件白名单：image/png, image/jpeg, image/webp
文件大小上限建议：10MB（可配置）
prompt 长度限制（例如 500）

10.3 审计日志

每次调用记录：

userId
taskId
taskType
modelVersion
tripo code / message
X-Tripo-Trace-ID

11. 错误处理与降级策略

场景	检测	前端提示	系统动作
API Key 无效	code=1002	服务配置异常	终止任务并告警
速率限制	code=1007	请求过于频繁，请稍后	指数退避重试
余额不足	code=2010	余额不足，请充值	终止任务
模型版本失效	code=2015/2017	当前模型不可用，已切换默认版本	自动回退默认模型
内容审核拦截	code=2008	内容不符合规范	终止任务
任务超时	本地计时超阈值	生成超时，请重试	标记失败，可重提

12. 性能与可观测性

12.1 性能

限制单用户并发任务数（建议 2~3）
轮询仅对活跃任务执行
3D 预览默认启用轻量灯光与压缩纹理，避免页面卡顿

12.2 可观测性

API 耗时埋点：upload/create/poll/import
失败率指标：按任务类型、模型版本、错误码聚合
成功耗时 P50/P90/P99

13. 研发排期（建议）

阶段 A（1~2 天）：后端通路

Tripo client + API 代理路由
上传、创建任务、轮询、余额接口
错误映射和日志

阶段 B（1~2 天）：前端页面与交互

新建 /canvas/[id]/model3d
三栏式页面 + 3D Viewer
任务状态与结果操作

阶段 C（1 天）：画布集成与验收

左侧工具栏新增 3D 入口
model3d 节点落盘与展示
全链路联调 + 回归测试

14. 验收标准（Definition of Done）

用户可从无限画布一键进入 3D 生成页
文生3D与图生3D至少各成功 10 次，成功率 >= 95%（测试环境）
生成成功后 1 次点击可导入画布，并在刷新后仍保留节点
失败场景提示清晰，不出现无响应状态
页面风格符合站内 UI 规范（Token、按钮、间距、圆角、暗黑模式）

15. 参考文档

Tripo 文档入口：https://platform.tripo3d.ai/docs/introduction
Tripo OpenAPI Base：https://api.tripo3d.ai/v2/openapi

备注：Tripo 文档为动态站点，模型版本与限制可能变化；实现时应将默认版本、可选版本与限额做成后台可配置项，而不是硬编码。

13 KiB Raw Permalink Blame History Unescape Escape