From ddf8e2c213c1805f8d609c8edb81665cb5d79097 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Mon, 21 Sep 2026 12:29:40 +0800 Subject: [PATCH] =?UTF-8?q?=E5=90=8C=E6=AD=A5Tripo=E7=94=9F=E6=88=90API?= =?UTF-8?q?=E7=9A=84=E6=96=87=E6=A1=A3=E7=B4=A2=E5=BC=95=E4=B8=8E=E9=A2=86?= =?UTF-8?q?=E5=9F=9F=E6=9C=AF=E8=AF=AD=20-=20docs/README=20=E5=A2=9E?= =?UTF-8?q?=E5=8A=A0=E4=B8=BB=E8=A7=84=E8=8C=83=E4=B8=8E=20ADR=20=E5=85=A5?= =?UTF-8?q?=E5=8F=A3=20-=20CONTEXT.md=20=E8=A1=A5=E5=85=85=203D=20?= =?UTF-8?q?=E6=A8=A1=E5=9E=8B=E7=94=9F=E6=88=90=E6=93=8D=E4=BD=9C=E3=80=81?= =?UTF-8?q?provider=20task=E3=80=81Tripo=20API=20facade=20=E7=AD=89?= =?UTF-8?q?=E6=9C=AF=E8=AF=AD=20-=20provider=20=E4=B8=93=E9=A2=98=E6=8A=8A?= =?UTF-8?q?=E5=BA=94=E7=94=A8=E5=B1=82=E6=8E=A5=E5=85=A5=E6=8C=87=E5=90=91?= =?UTF-8?q?=E6=96=B0=E4=B8=BB=E8=A7=84=E8=8C=83=20-=20=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=94=9F=E5=91=BD=E5=91=A8=E6=9C=9F=E7=B4=A2=E5=BC=95=E6=94=B9?= =?UTF-8?q?=E4=B8=BA=E6=8C=87=E5=90=91=E6=B4=BB=E5=8A=A8=E8=AE=A1=E5=88=92?= =?UTF-8?q?=E7=9B=AE=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTEXT.md | 22 ++++++++++++++++++- docs/README.md | 4 +++- ...方案】Tripo 3D模型Provider集成-2026-09-18.md | 2 +- ...作规范】文档生命周期与现状索引-2026-09-12.md | 2 +- 4 files changed, 26 insertions(+), 4 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index b5c4adc36..75f3160e8 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -53,7 +53,7 @@ _Avoid_: 为每个玩法单独发明素材流水线、把系列素材建模成 ### 3D Model Generation **3D 模型生成操作**: -由文本提示驱动、可异步查询并最终产生模型文件的 provider-neutral 操作；操作状态和产品资源结果分开建模。 +由文本提示或平台图片引用驱动、可异步查询并最终产生模型文件的 provider-neutral 操作；操作状态和产品资源结果分开建模。 _Avoid_: 直接把第三方 provider task 当作产品资源、把模型 URL 当作永久资源地址 **Provider task**: @@ -68,6 +68,26 @@ _Avoid_: 永久 OSS URL、资源 ID 由 text-to-model、image-to-model 或 multiview-to-model 任务产生、待应用层登记和持久化的模型文件结果；provider adapter 只提供可下载结果，不负责生成 resourceId 或 assetId。 _Avoid_: 仅 UI 中展示的模型链接、没有来源任务的静态文件 +**Tripo API facade**: +面向站内已认证调用方的全新 Tripo 3D 生成 API 上下文，负责把 API operation、用户归属、异步状态、产物持久化和正式资源引用连接起来；它独立于历史 Hyper3D adapter，不复用其路由、契约或实现。 +_Avoid_: 把 Tripo API 当成 Hyper3D 的 provider 替换、让 Hyper3D 路由悄悄切换到 Tripo + +**Tripo operation**: +Genarrative 为一次 Tripo 生成请求分配的内部异步操作标识；客户端只看到 operationId，Tripo provider task 只作为服务端 checkpoint 保存，二者不是同一个 ID。 +_Avoid_: 将 Tripo taskId 直接当公开 operationId、把 SDK task 状态模型穿透到 API + +**模型产物持久化**: +Tripo 任务完成后，服务端下载模型与预览、写入受控对象存储并登记资源元数据，成功后才把 Tripo operation 置为 completed；本期按完整字节写入，流式上传是后续目标。 +_Avoid_: 返回临时签名 URL作为永久资源、在 API handler 中把完整模型读成 Vec + +**模型生成落点**: +3D 生成结果要进入的平台容器，调用方必须在工程资源与素材库资产之间显式二选一；工程分支可附带画布占位框回填，素材库分支必须给出目录与标签。 +_Avoid_: 两个都不给就默认落素材库、把落点混进 provider 请求参数 + +**模型输入资源引用**: +image-to-model 请求对平台已有图片的明确 tagged 引用，可指向项目资源或素材库资产；服务端负责 owner 校验和 OSS 对象解析，不接受把多种来源塞进裸 `input` 字符串。 +_Avoid_: 任意远程 URL、data URL、未区分语义的 resourceId/assetId 字符串 + ### Puzzle Clear **拼消消**: diff --git a/docs/README.md b/docs/README.md index 68bec1944..91b6c89cf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,7 +25,8 @@ ## 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 与流式下载边界。 +- [Tripo 3D 生成 API 集成](<./technical/【技术方案】Tripo 3D生成API集成-2026-09-21.md>)：把 text-to-model 与 image-to-model 接成内部 API，复用异步队列与状态查询，产物落 OSS 并登记资源，按显式泥点定价真实扣费。 - [策划 Agent 生产迁移与工作区浏览](./technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)：实施中；以自由协作原型为行为基线，复用生产基建，采用阶段审批与用户工作区文件浏览。无旧 V2 会话的策划入口切换到新设计 Agent。 @@ -77,6 +78,7 @@ ## 后端、运维与测试 - [Tripo SDK 隔离与 Provider DTO 边界 ADR](./adr/【ADR】0001-Tripo%20SDK隔离与Provider%20DTO边界-2026-09-18.md)：固定 SDK 只存在于 `platform-tripo` 内部，provider task 与产品资源结果分层。 +- [Tripo 生成 API 集成边界与提交时定价 ADR](./adr/【ADR】0002-Tripo生成API集成边界与提交时定价-2026-09-21.md)：全新 API 不复用 Hyper3D，at-most-once submit，按提交时定价真实扣费。 - [BgFilter 受限资源调度方案](./technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md) - [Issue225 登录成功 AGC 用户归属修复](./technical/【后端架构】Issue225登录成功AGC用户归属修复方案-2026-09-03.md)：登录 route tracking 的真实用户归属、`daily_login` 幂等边界和实施验收。 diff --git a/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md b/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md index 926bc4c4f..b31234d75 100644 --- a/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md +++ b/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md @@ -8,7 +8,7 @@ ## 非目标 -- 不接入 `api-server`、worker、SpacetimeDB、OSS 或计费；前端查看器已由 `packages/model3d-viewer` 独立实现，本阶段不接任何 UI 链路。 +- 不接入 `api-server`、worker、SpacetimeDB、OSS 或计费；应用层接入由 [`【技术方案】Tripo 3D 生成 API 集成-2026-09-21`](./【技术方案】Tripo%203D生成API集成-2026-09-21.md) 承接，前端查看器已由 `packages/model3d-viewer` 独立实现，本阶段不接任何 UI 链路。 - 不暴露 SDK 的 `wait_for_task`，不在 adapter 内启动后台轮询。 - 不实现后处理、rig、animation、图片生成或其它 SDK endpoint。 diff --git a/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md b/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md index ec52ae65f..e92f793c3 100644 --- a/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md +++ b/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md @@ -79,7 +79,7 @@ - `docs/project-memory/todos/【待评估】UI编辑器字体跨运行时像素一致性-2026-08-19.md` - `docs/project-memory/todos/【已知问题】AppConfig与AppState调试输出敏感配置泄漏-Master遗留-2026-08-07.md` -当前没有活动计划；新任务按 SDD 规则在 `docs/project-memory/plans/` 建立计划，完成、取消或合并后删除。 +活动计划见 `docs/project-memory/plans/`；新任务按 SDD 规则在该目录建立里程碑规范与实现计划，完成、取消或合并后删除。 ## 下一轮复核顺序