更新Tripo 3D模型Provider集成文档覆盖三个生成入口

文档改名为「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/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 在任务未完成时跳过下载并继续跑后续入口，只打印脱敏后的结果结构和下载产物信息。