From 49b64515483f087e7f4895f23c8c7e655fd54735 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 23:16:02 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85Tripo=E4=B8=8B=E8=BD=BD?= =?UTF-8?q?=E5=99=A8=E8=BF=81=E7=A7=BB=E5=BE=85=E5=8A=9E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 记录Provider侧流式下载与第三方SDK保持原样的边界 增加等待上游SDK原生stream能力后的替换TODO --- ...ADR】0001-Tripo SDK隔离与Provider DTO边界-2026-09-18.md | 2 +- .../【技术方案】Tripo 3D模型Provider集成-2026-09-18.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/adr/【ADR】0001-Tripo SDK隔离与Provider DTO边界-2026-09-18.md b/docs/adr/【ADR】0001-Tripo SDK隔离与Provider DTO边界-2026-09-18.md index 973315c1a..c0210d8f2 100644 --- a/docs/adr/【ADR】0001-Tripo SDK隔离与Provider DTO边界-2026-09-18.md +++ b/docs/adr/【ADR】0001-Tripo SDK隔离与Provider DTO边界-2026-09-18.md @@ -2,7 +2,7 @@ 状态：已接受 -`tripo3d-sdk` 只允许出现在 `platform-tripo` 内部。该 crate 以显式必填配置创建可复用 provider client，只公开自己的 text-to-model、image-to-model、multiview-to-model DTO、通用单次 task 查询、显式模型下载流和结构化错误；不暴露 SDK 类型、`wait_for_task` 或后台轮询。模型下载只逐块消费，不提供完整 `Vec`；未来 OSS 持久化直接承接同一数据流。共享产品契约与 provider task 结果分层，provider adapter 不伪造 `resourceId`/`assetId`；shared-contracts 的 Rust 类型始终通过 ts-rs 生成目录化 TypeScript binding。 +`tripo3d-sdk` 只允许出现在 `platform-tripo` 内部。该 crate 以显式必填配置创建可复用 provider client，只公开自己的 text-to-model、image-to-model、multiview-to-model DTO、通用单次 task 查询、显式模型下载流和结构化错误；不暴露 SDK 类型、`wait_for_task` 或后台轮询。模型下载由 provider 自有 HTTP client 逐块消费，不提供完整 `Vec`；未来 OSS 持久化直接承接同一数据流，第三方 SDK 保持原样。共享产品契约与 provider task 结果分层，provider adapter 不伪造 `resourceId`/`assetId`；shared-contracts 的 Rust 类型始终通过 ts-rs 生成目录化 TypeScript binding。 选择这个边界是为了避免 API 层绑定第三方 SDK 的任务/错误模型，同时让未来的资源持久化、幂等和 provider 替换由应用层负责。请求 enum 以 Tripo API 文档为准；当前 `compress=geometry`、纹理质量 `fast/standard/detailed/extreme` 及纹理版本已经纳入目录化 Rust/TypeScript contracts。文档确认不存在于这三个 endpoint 的 `style` 字段不再保留占位类型，组合约束在 provider 副作用前执行。 diff --git a/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md b/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md index c4e25dc9e..926bc4c4f 100644 --- a/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md +++ b/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md @@ -42,12 +42,14 @@ task 尚未完成时 `output` 为空；完成后 `output` 必须是与 task type `get_task` 按 `TripoTaskHandle` 做单次查询，返回通用 `TripoTaskSnapshot`，由 `task_type` 决定 `output` 的具体 variant；adapter 不做轮询、不阻塞等待。 -`download_model` 接受 `TripoTaskSnapshot`，从严格 endpoint 结果中取得已校验的 `model_url`，调用 SDK 的 `download_url_stream` 返回 provider 自己的 `TripoDownloadedModel` 流包装。包装只公开 `url`、`content_type`、`content_length`、`filename(name)` 和 `next_chunk()`；不提供完整 `Vec`，调用方必须逐块消费。SDK 在流结束时校验实际接收字节数与 `Content-Length`，响应体中断或长度不一致按结构化请求错误失败。smoke example 使用异步文件写入逐块落盘；未来接入 OSS 时应把同一数据流直接送入 OSS 分片上传，不经过完整内存缓冲。 +`download_model` 接受 `TripoTaskSnapshot`，从严格 endpoint 结果中取得已校验的 `model_url`，由 provider 自己的无鉴权 reqwest client 打开签名 URL 并返回 `TripoDownloadedModel` 流包装。包装只公开 `url`、`content_type`、`content_length`、`filename(name)` 和 `next_chunk()`；不提供完整 `Vec`，调用方必须逐块消费。provider 在流结束时校验实际接收字节数与 `Content-Length`，响应体中断或长度不一致按结构化请求错误失败；SDK 保持第三方原样，不承担产物下载。smoke example 使用异步文件写入逐块落盘；未来接入 OSS 时应把同一数据流直接送入 OSS 分片上传，不经过完整内存缓冲。 + +TODO：等待上游 `tripo-rust-sdk` 提供原生 artifact stream API 后，删除 provider-side reqwest 下载器，改由 SDK stream 直接承接。 ## 验收 - `platform-tripo` 不公开 re-export SDK 类型或 `wait_for_task`。 -- 三个 3D 生成入口的 submit、通用 get task、按 endpoint 严格映射的完成结果和显式流式 download API 可编译，且共用同一 client 与同一套 `TripoError`。 +- 三个 3D 生成入口的 submit、通用 get task、按 endpoint 严格映射的完成结果和 provider 自有流式 download API 可编译，且共用同一 client 与同一套 `TripoError`。 - 三个入口的输入校验可拒绝空白 `prompt` / `input`、视图不足两张和空白 `taskId`；组合校验在调用 SDK 前完成。 - provider 错误统一为 adapter 错误类型。 - shared contracts 的 ts-rs binding 无 feature 开关且始终可生成。