From 092bca744483b3ce559031d9d3f01c987dcd8823 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Sat, 19 Sep 2026 16:19:05 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0Tripo=203D=E6=A8=A1=E5=9E=8BP?= =?UTF-8?q?rovider=E9=9B=86=E6=88=90=E6=96=87=E6=A1=A3=E8=A6=86=E7=9B=96?= =?UTF-8?q?=E4=B8=89=E4=B8=AA=E7=94=9F=E6=88=90=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 文档改名为「Tripo 3D模型Provider集成」，H1 同步去掉“文本到”前缀，并更新 docs/README.md 链接 目标段改为三个入口共用 TripoProviderClient，列明 submit / submit_image_to_model / submit_multiview_to_model 新增「三个入口的输入」小节，记录 prompt 长度上限、image input 裸字符串引用、multiview views 与 taskId 二选一及视图数量要求 新增「任务查询与下载」小节，记录 TripoTaskSnapshot、TripoDownloadedModel 与必须重复取 task 的原因 补充契约分层说明：产品级结果契约目前只服务 text-to-model，image 与 multiview 结果仍在 provider 层 非目标标注前端查看器由 packages/model3d-viewer 独立实现、本阶段不接 UI 链路，验收补上输入校验与 smoke 行为 --- docs/README.md | 2 +- ... => 【技术方案】Tripo 3D模型Provider集成-2026-09-18.md} | 27 +++++++++++++++---- 2 files changed, 23 insertions(+), 6 deletions(-) rename docs/technical/{【技术方案】Tripo文本到3D模型Provider集成-2026-09-18.md => 【技术方案】Tripo 3D模型Provider集成-2026-09-18.md} (58%) diff --git a/docs/README.md b/docs/README.md index c845863ee..68bec1944 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,7 +25,7 @@ ## AI 游戏创作与 Agent Runtime -- [Tripo 3D 模型 Provider 集成](./technical/【技术方案】Tripo文本到3D模型Provider集成-2026-09-18.md)：实现 text-to-model、image-to-model、multiview-to-model 的 Rust provider adapter，暂不接入 api-server。 +- [Tripo 3D 模型 Provider 集成](<./technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md>)：实现 text-to-model、image-to-model、multiview-to-model 的 Rust provider adapter，暂不接入 api-server。 - [策划 Agent 生产迁移与工作区浏览](./technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)：实施中；以自由协作原型为行为基线，复用生产基建，采用阶段审批与用户工作区文件浏览。无旧 V2 会话的策划入口切换到新设计 Agent。 diff --git a/docs/technical/【技术方案】Tripo文本到3D模型Provider集成-2026-09-18.md b/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md similarity index 58% rename from docs/technical/【技术方案】Tripo文本到3D模型Provider集成-2026-09-18.md rename to docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md index 7f51d4b62..de56cab48 100644 --- a/docs/technical/【技术方案】Tripo文本到3D模型Provider集成-2026-09-18.md +++ b/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md @@ -1,14 +1,14 @@ -# 【技术方案】Tripo文本到3D模型 Provider 集成-2026-09-18 +# 【技术方案】Tripo 3D模型 Provider 集成-2026-09-18 ## 目标 -本阶段在 `server-rs/crates/platform-tripo` 内接入固定 revision 的 `tripo3d-sdk`，完成 text-to-model、image-to-model 和 multiview-to-model 三个 3D 生成入口的 Rust provider adapter。adapter 提供显式配置、提交、单次通用 task 查询和模型下载能力；共享产品契约继续由 `shared-contracts` 管理，并始终生成目录化 ts-rs TypeScript binding。 +本阶段在 `server-rs/crates/platform-tripo` 内接入固定 revision 的 `tripo3d-sdk`，完成 text-to-model、image-to-model 和 multiview-to-model 三个 3D 生成入口的 Rust provider adapter。三个入口共用同一个 `TripoProviderClient`，分别通过 `submit`、`submit_image_to_model`、`submit_multiview_to_model` 提交；client 另提供显式配置、通用单次 task 查询和模型下载能力。共享产品契约继续由 `shared-contracts` 管理，并始终生成目录化 ts-rs TypeScript binding。 代码按 API 目录组织：公共 SDK 配置、client、任务映射、错误、下载类型和 task 生命周期 DTO 位于 `platform-tripo/src/common/`；三个生成 API 各自拥有独立目录和结果类型。Rust 与 TypeScript contracts 按 `common/`、`text_to_model/`、`image_to_model/`、`multiview_to_model/` 分目录生成。 ## 非目标 -- 不接入 `api-server`、worker、SpacetimeDB、OSS、计费或 UI。 +- 不接入 `api-server`、worker、SpacetimeDB、OSS 或计费；前端查看器已由 `packages/model3d-viewer` 独立实现，本阶段不接任何 UI 链路。 - 不暴露 SDK 的 `wait_for_task`，不在 adapter 内启动后台轮询。 - 不实现后处理、rig、animation、图片生成或其它 SDK endpoint。 @@ -22,16 +22,33 @@ task 尚未完成时 `output` 为空；完成后 `output` 必须是与 task type 生成结果 DTO 中的 `poll_after_ms`、`updated_at_micros` 与 `size_bytes` 以 TypeScript `number` 导出：毫秒级轮询间隔与几十 MB 的产物字节数远低于 2^53，微秒时间戳在 2^53 内也可精确表示（约到公元 2255 年），因此不做 `bigint`/`string` 特殊处理；若将来出现超过 2^53 的取值再评估。 +## 三个入口的输入 + +- text-to-model：`prompt` 必填，上限 1024 字符；`negative_prompt` 上限 255 字符。空白 prompt 在提交前拒绝。 +- image-to-model：`input` 是单张参考图引用，序列化为裸字符串并由服务端推断是公开 URL 还是 `file_token`；空白 `input` 在提交前拒绝。 +- multiview-to-model：`inputs` 是带 `kind` 的 tagged enum，二选一——`views { front, left, back, right }` 或复用已有结果的 `taskId`。`views` 下 `front` 必填，其余视图至少再提供一张（少于两张视图直接拒绝）；左/后/右视图为空白字符串时按未提供处理，不会上传空文件。`taskId` 走统一的 task id 校验。 + +三个入口的 `model` 都必填，其余生成参数可选。SDK params 未命名的 `texture_version` 与 `delight`，由 image-to-model 和 multiview-to-model 通过 extra 字段透传。 + ## 请求与类型 三个生成请求使用官方文档已确认的 enum：模型版本、纹理版本、纹理质量（含 `fast`）、几何质量、纹理对齐、输入方向、导出方向和压缩类型（`geometry`）。文档未将 `style` 列为这三个 endpoint 的请求字段，因此不再保留占位 enum。`model` 在三个请求中都是必填字段（缺失或取值非法时在反序列化阶段即拒绝）；除它以外的参数可选，在 Rust 侧为 `Option`，TypeScript 绑定对应 `field?: T | null`，调用方既可省略字段也可显式传 `null`。TypeScript 绑定仍按目录生成到 `packages/shared/src/contracts/model3d/`，并由该目录的 `index.ts` 与 `packages/shared` 的 barrel 统一再导出；生成命令 `npm run contracts:model3d:generate` 写入的是未格式化的 ts-rs 输出，需再执行 `prettier --write packages/shared/src/contracts/model3d` 后提交。 提交前由 provider 统一执行组合校验：模型版本决定 family；`fast` 必须配 `v3.5-20260815`；几何质量 / 压缩 / 自动尺寸 / P 系列与 H 系列能力按模型版本限制；`quad`、`generate_parts`、`smart_low_poly` 和 `texture/pbr` 组合按文档的互斥关系拒绝；`face_limit` 按模型、quad 和 smart-low-poly 模式检查范围。SDK 返回的参数错误仍统一归一为 `TripoError`。 +契约分层：三个入口都导出 request 契约，`common/` 导出共享 enum；产品级结果契约（`Model3dGenerationSubmission`、`Model3dGenerationJob`、`Model3dGenerationResult`、`Model3dArtifact`）目前只服务 text-to-model。image-to-model 与 multiview-to-model 的完成结果仍停在 provider 层的 `TripoImageToModelResult`、`TripoMultiviewToModelResult`，等应用层真正做资源持久化时再决定是否提升为产品契约。 + +## 任务查询与下载 + +`get_task` 按 `TripoTaskHandle` 做单次查询，返回通用 `TripoTaskSnapshot`，由 `task_type` 决定 `output` 的具体 variant；adapter 不做轮询、不阻塞等待。 + +`download_model` 接受 `TripoTaskSnapshot`，返回 `TripoDownloadedModel { url, content_type, data }`，并由 `filename(name)` 从 URL 末段推断扩展名（推断不出时回落 `glb`）。SDK 只公开 `download_model(&Task)`，因此实现会按 handle 再取一次 task（已留 TODO）；若将来 SDK 支持按 URL 下载，可直接用 snapshot 里的模型 URL 省掉这次请求。 + ## 验收 - `platform-tripo` 不公开 re-export SDK 类型或 `wait_for_task`。 -- 三个 3D 生成入口的 submit、通用 get task、按 endpoint 严格映射的完成结果和显式 download API 可编译。 +- 三个 3D 生成入口的 submit、通用 get task、按 endpoint 严格映射的完成结果和显式 download API 可编译，且共用同一 client 与同一套 `TripoError`。 +- 三个入口的输入校验可拒绝空白 `prompt` / `input`、视图不足两张和空白 `taskId`；组合校验在调用 SDK 前完成。 - provider 错误统一为 adapter 错误类型。 - shared contracts 的 ts-rs binding 无 feature 开关且始终可生成。 -- 真实 Provider smoke 已覆盖三个入口；example 保留脱敏后的结果结构和下载产物信息。 +- 真实 Provider smoke 已覆盖三个入口；example 在任务未完成时跳过下载并继续跑后续入口，只打印脱敏后的结果结构和下载产物信息。