Genarrative/docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md

抓大鹅草稿素材生成流水线 2026-05-10

1. 范围

本方案用于改造 生成抓大鹅草稿 的首版生成链路：点击按钮后先进入独立生成过程页，生成结束后自动进入抓大鹅草稿页，并在草稿页 3D素材 Tab 预览本次生成的 3D 模型。

本次只把任意难度都收敛为 3 件物品。后续难度曲线恢复时，再把物品数、网格数和手动 3D 任务数量从配置中放开。

2. 前端流程

入口仍复用 Match3DAgentWorkspace 表单。点击 生成抓大鹅草稿 后：

1. 创建 Match3D session。
2. 后端先用当前题材和本地兜底元信息创建同一个 Match3D 草稿 profile，草稿 Tab 必须立即能看到这份存档。
3. 进入 match3d-generating 生成过程页。
4. 过程页复用拼图生成页的 CustomWorldGenerationView 结构。
5. 生成成功后自动进入 match3d-result。
6. 生成失败时停留在生成过程页，允许重新生成或返回创作中心；重新生成必须复用同一个 session / profile，并从缺失的素材阶段继续，不新建第二份草稿。

生成页步骤固定为：

生成游戏名称 -> 生成物品名称 -> 生成素材图 -> 切割独立图片 -> 上传图片资产 -> 生成3D模型 -> 写入草稿页

生成页只展示题材和物品数量，不展示玩法规则说明。

当前 match3d-generating 进度页不是后端 task 状态订阅页，而是一个覆盖 match3d_compile_draft 长 action 的本地时间进度页：前端每 500ms 以本地时间刷新阶段展示，真正的生成完成仍以 action 返回为准。为避免长 action 未返回时页面完全无感，生成页在 match3d_compile_draft 执行期间每 3 秒旁路读取一次 session 和 work detail，并用 profile 中已写回的 generatedItemAssets 更新 生成3D模型 的完成数量。Hyper3D 控制台中看到 3 个 Rodin 任务已经 Done 后，页面仍可能继续停留在 生成3D模型，此时通常表示后端还在等待下载列表、下载 GLB、转存 OSS 或写回 generated_item_assets_json；若 generatedItemAssets 已出现 model_ready，前端应逐步显示完成数量。排查时应看 api-server 日志中的 抓大鹅 Rodin 状态轮询返回、抓大鹅 Rodin 下载列表轮询返回、抓大鹅 Rodin GLB 下载完成 和 抓大鹅 Rodin GLB 转存 OSS 完成。

3. 后端编排边界

外部模型和 OSS 上传全部由 api-server 编排，不进入 SpacetimeDB reducer。SpacetimeDB 继续只负责 Match3D 会话、草稿和作品 profile 的确定性写入。

match3d_compile_draft action 的后端顺序为：

1. 读取 session config。
2. 将本次 MVP 的 clearCount 固定为 3，并同步用于草稿编译。
3. 先调用 SpacetimeDB compile procedure 写入草稿。首次执行使用新 profileId；重试时复用 session draft / work profile 中已有 profileId。这一步不能等待 LLM、图片、OSS 或 Rodin 成功后才执行。
4. 基于入口页题材设定文本调用文本模型生成作品元信息。模型固定请求 gpt-4o，只返回 JSON，其中 gameName 为 4 到 12 个中文字符的游戏名称，tags 为 3 到 6 个中文短标签；summary 首版必须保持空字符串，结果页 作品描述 默认留给用户填写。文本模型不可用时保留第 3 步的本地兜底，不阻断草稿。
5. 调用文本模型生成 3 个题材下的短物品名称。
6. 调用项目当前图片链路 VectorEngine gpt-image-2-all 生成一张 1:1 素材图，提示词必须合入入口页选择的 assetStylePrompt。历史 nanobanana2 图片选项当前按项目统一决策回落到 VectorEngine，不重新接入 APIMart 图片网关。
7. 将素材图按 n*n 网格切割成独立图片。当前 3 件物品使用 2*2 网格，取前 3 格。
8. 将素材图和每张独立图片上传到 OSS，其中独立图片作为草稿页素材预览和 Rodin 图生模型参考图；每次获得可恢复的图片资产后，都要回写 match3d_work_profile.generated_item_assets_json。
9. 使用每张独立图片作为参考图，并行调用 Hyper3D Rodin 图生模型；所有 3D 模型任务必须在同一阶段同时提交、同时轮询状态、同时下载并转存 OSS，禁止逐个物品串行等待模型完成。每个任务按官方 check-status_reset_v / download-results_reset_v 文档轮询状态和下载：状态查询使用 subscription_key，整体完成态以 jobs[] 聚合为准；下载查询使用生成响应顶层 uuid 作为 task_uuid，不能使用 jobs.uuids 子任务 uuid。只有 jobs 全部进入 Done 才能视为任务完成，任一 job Failed 则失败。完成后选择 .glb 下载文件，并把 GLB 转存到 OSS。Rodin 的 subscriptionKey 是上游 opaque token，不做 256 字符这类短文本长度限制。Rodin 任务状态进入完成态后，下载列表仍可能延迟发布；后端必须对下载列表继续轮询，并兼容 url、downloadUrl、fileUrl、signedUrl 等下载字段别名，只有预览图而没有模型文件时不能伪装成 GLB 成功。
10. Rodin 每批完成后继续回写 generated_item_assets_json。成功素材状态为 model_ready；失败素材保留图片引用并记录 error，下次 match3d_compile_draft 只继续缺失模型的素材，不重复生成已完成的 GLB。
11. 在 HTTP 返回的 draft/profile DTO 中附带本次生成的素材资产预览信息；后续重进草稿页时从 work profile 的持久化 generatedItemAssets 恢复同一批素材。

若文本模型不可用或返回无法解析，后端必须降级为 {themeText}抓大鹅 与本地标签兜底，不阻断素材生成；但描述仍保持空字符串。

草稿生成阶段会调用 Hyper3D Rodin 并等待 GLB 下载完成；前端 match3d_compile_draft action 请求超时必须覆盖该长耗时链路，当前 Match3D client 使用 20 分钟超时。Rodin 单模型状态轮询预算为 10 分钟，下载列表发布轮询预算为 5 分钟；GLB 下载和 OSS PutObject 各自设置 3 分钟 HTTP 超时，避免上游下载或转存连接长期悬挂。由于 3 个模型并行生成，总耗时按最慢模型计算，不能按模型数量线性叠加。结果页 3D素材 Tab 直接加载已生成模型；用户点击 重新生成 时再复用 Rodin 安全代理，首版重新生成只更新当前页面内预览状态，后续正式资产绑定以独立技术方案为准。

4. 图片提示词

素材图提示词必须显式包含：

生成一张1:1图片
生成2*2网格素材图
整体画风遵循：...
只绘制这些物品：...
不要出现文字、水印、UI、边框

包含若干个物品名称 在落地中解释为“按生成出的物品名称绘制对应主体”，不要求图片上写出物品名称。这样可以避免文字渲染污染切图和后续手动 3D 模型参考。

入口页内置风格参考图通过同一 VectorEngine gpt-image-2-all 能力生成，保存路径固定为：

public/match3d-style-references/clay-toy.png
public/match3d-style-references/low-poly.png
public/match3d-style-references/toy-plastic.png
public/match3d-style-references/wood-carved.png
public/match3d-style-references/voxel-block.png
public/match3d-style-references/metal-mecha.png

这些图片只作为入口页风格选择的视觉参考，不进入用户草稿资产，不替代生成时的物品素材图。

5. OSS 路径

新增 generated legacy prefix：

generated-match3d-assets

建议对象分组：

generated-match3d-assets/{sessionId}/{profileId}/material-sheet/{taskId}/sheet.png
generated-match3d-assets/{sessionId}/{profileId}/items/{itemSlug}/image/image.png
generated-match3d-assets/{sessionId}/{profileId}/items/{itemSlug}/model/{taskUuid}/model.glb

itemSlug 必须带 itemId 前缀，例如 match3d-item-1-item。中文物品名清洗后可能都退回 item，不能只用物品名做路径，否则多张切割图会写到同一个 object key，导致草稿页预览图全部一致。

HTTP DTO 同时返回 imageSrc、imageObjectKey、modelSrc、modelObjectKey、modelFileName、taskUuid、subscriptionKey 和 status。模型生成成功后 status = model_ready；若后续允许部分模型失败降级，失败素材必须带 error，且不能伪装成可预览模型。前端模型预览必须通过 /api/assets/read-bytes 读取私有 GLB 字节并转成 Blob URL 后交给 Three.js，不直接请求裸 /generated-match3d-assets/... 路径。

5.1 运行态模型消费

生成模型不仅用于结果页预览，也必须进入游戏运行态。运行态入口的传递链路为：

Match3DWorkProfile / PlatformMatch3DGalleryCard
-> Match3DRuntimeShell(generatedItemAssets)
-> Match3DPhysicsBoard / Match3DTrayPreviewBoard

Match3DPhysicsBoard 与 Match3DTrayPreviewBoard 按运行快照中的 itemTypeId 稳定排序后，把生成出的模型顺序映射到对应类型。当前 MVP 固定 clearCount = 3，因此 match3d-type-01/02/03 分别对应生成列表的第 1/2/3 个模型；后续恢复更多物品生成时，后端必须继续保证 generatedItemAssets 顺序与类型编号一致。

前端加载规则：

1. 优先读取 modelSrc；为空时使用 modelObjectKey。
2. 通过 readAssetBytes 调用 /api/assets/read-bytes，由同源后端读取 OSS 私有对象字节。
3. 使用 Three.js GLTFLoader.parseAsync 解析 GLB 字节，并按物品类型缓存模板。
4. 场内每个物品和备选栏预览都从模板 clone 独立对象，点击命中继续写入 itemInstanceId。
5. 物理碰撞和边界仍沿用现有 visualKey 的程序化几何，生成 GLB 只替换视觉模型，不承接规则真相。
6. 模型缺失、读取失败或 WebGL 回退时，继续使用默认积木素材，不能阻断开局、点击、入槽或结算；调试模式下需要输出加载失败的 itemTypeId、模型来源和错误信息，便于区分“资产没有传入”和“GLB 字节读取或解析失败”。

结果页点击 试玩 时，前端必须把当前结果页可见的 generatedItemAssets 带入运行态启动入参。PUT /api/runtime/match3d/works/{profileId} 若因为并发或旧快照返回了缺少素材的 profile，Match3DResultView 需要把当前 draft / profile 的素材重新合并到运行态 profile，并在启动试玩前调用生成素材保存接口把当前可见的 generatedItemAssets 写回作品 profile；不能只在内存里把素材补到 onStartTestRun(profile)。发布同理必须先落库当前素材，再调用 publish_match3d_work，否则公开推荐流和正式运行态只能读到旧 profile 快照，历史草稿尤其容易表现为结果页有 3D 模型、正式游戏仍是默认积木。若历史草稿同时存在旧 draft.generatedItemAssets 和较新的 profile.generatedItemAssets，同 itemId 下以 profile 中已有的 modelSrc / modelObjectKey 补齐 draft，不能让旧 draft 把模型状态覆盖回 image_ready。PlatformEntryFlowShellImpl 在渲染 match3d-runtime 时按 run.profileId 优先使用当前 match3dProfile.generatedItemAssets，只有 profileId 不匹配时才读取 selectedPublicWorkDetail.generatedItemAssets。推荐流内嵌正式运行态也必须走同一解析器；当推荐卡片摘要缺少素材时，启动前补读 getMatch3DWorkDetail(profileId)，把详情里的生成模型写入 match3dProfile 后再传给运行态。这样可以避免从公开详情页残留状态或推荐卡片旧摘要进入试玩 / 正式游戏时，把已生成草稿的 3D 模型覆盖成空列表。

6. 自动保存与草稿恢复

点击 生成抓大鹅草稿 后，草稿存档创建与素材生成解耦：

1. 首次 compile 必须先写 match3d_work_profile 草稿行，即使后续卡在文本模型、图片生成、OSS 上传、Rodin 生成或下载转存任意阶段。
2. 失败态前端要重新读取 session / work detail，并刷新草稿作品架，保证用户离开生成页后仍能在草稿 Tab 找到这份作品。
3. 重新生成时优先使用当前 session 的 draft.profileId 或 publishedProfileId，不得重新创建 session；后端读取同一 profile 的 generated_item_assets_json 后，只补齐缺失图片或缺失模型的阶段。
4. 已有 status = model_ready 且带 modelSrc / modelObjectKey 的素材视为完成，不再重复调用 Rodin。

抓大鹅结果页的基础信息自动保存继续调用 PUT /api/runtime/match3d/works/{profileId} 更新名称、题材、描述、标签、封面、消除数和难度；该保存不得清空 generated_item_assets_json。结果页 3D素材 Tab 手动点击 重新生成 并拿到 GLB 下载文件后，必须把当前素材草稿重新序列化成 generatedItemAssets 并写回作品 profile；否则页面内预览会显示新模型，但试玩、发布和重进草稿仍会读取旧的空模型快照。SpacetimeDB update_match3d_work / publish_match3d_work 必须保留当前行的生成素材 JSON。

草稿架重进路径为：

草稿 Tab -> getMatch3DWorkDetail(profileId) -> Match3DResultView(profile.generatedItemAssets)

因此 map_match3d_work_summary_response / map_match3d_work_profile_response 需要从 work profile snapshot 反序列化 generated_item_assets_json 并输出 generatedItemAssets。前端 Match3DResultView 的读取顺序为：有 draft.generatedItemAssets 时先用 draft 保留本次生成顺序和图片；同 itemId 在 profile.generatedItemAssets 中已有模型字段时，用 profile 模型字段补齐 draft；从草稿架重进没有 draft 时，用 profile.generatedItemAssets；两者都没有才回退到默认 3D 素材占位。

结果页 作品信息 Tab 字段命名对齐拼图草稿：

1. 作品名称 对应 Match3D gameName。
2. 作品描述 对应 Match3D summary，草稿生成默认空。
3. 作品标签 对应 Match3D tags，可由 AI 首次生成并允许用户继续编辑。
4. 封面图与作品名称不再拆成左右两个大模块；封面只作为同一 Tab 内的可选上传入口，避免和作品基础信息割裂。

3D素材 详情页只保留：

1. 模型预览区：优先加载 modelSrc 对应 GLB，缺失时加载 modelObjectKey，支持拖动旋转；没有模型时展示空预览。
2. 素材名称输入。
3. 重新生成 按钮。

详情页不再展示参考图、用途、提示词、文生/图生切换、状态查询、下载列表、taskUuid 或 subscriptionKey。

7. 验收

建议执行：

npm run check:encoding
npm run test -- src\services\miniGameDraftGenerationProgress.test.ts
npm run test -- src\components\match3d-result\Match3DResultView.test.tsx
npm run test -- src\components\match3d-runtime\Match3DRuntimeShell.test.tsx
npm run test -- src\components\rpg-entry\RpgEntryFlowShell.agent.interaction.test.tsx
npm run typecheck
cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml
cargo test -p spacetime-client match3d --manifest-path server-rs\Cargo.toml
cargo test -p platform-oss --manifest-path server-rs\Cargo.toml
cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml
cargo check -p api-server --manifest-path server-rs\Cargo.toml
cargo check -p spacetime-client --manifest-path server-rs\Cargo.toml
cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml

真实草稿生成需要本地私密环境配置 VECTOR_ENGINE_API_KEY、HYPER3D_API_KEY 和 OSS 访问变量。后端改动后使用 npm run api-server 启动，并检查 /healthz。