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

1. 范围

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

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

2. 前端流程

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

创建 Match3D session。
进入 match3d-generating 生成过程页。
过程页复用拼图生成页的 CustomWorldGenerationView 结构。
生成成功后自动进入 match3d-result。
生成失败时停留在生成过程页，允许重新生成或返回创作中心。

生成页步骤固定为：

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

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

3. 后端编排边界

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

match3d_compile_draft action 的后端顺序为：

读取 session config。
将本次 MVP 的 clearCount 固定为 3，并同步用于草稿编译。
调用文本模型生成 3 个题材下的短物品名称。
调用项目当前图片链路 VectorEngine gpt-image-2-all 生成一张 1:1 素材图，提示词必须合入入口页选择的 assetStylePrompt。历史 nanobanana2 图片选项当前按项目统一决策回落到 VectorEngine，不重新接入 APIMart 图片网关。
将素材图按 n*n 网格切割成独立图片。当前 3 件物品使用 2*2 网格，取前 3 格。
将素材图和每张独立图片上传到 OSS，其中独立图片作为 Rodin 图生模型参考图。
对每张独立图片调用 Hyper3D Rodin Gen-2 图生模型，等待任务完成，读取 GLB 下载文件并转存到 generated-match3d-assets。
调用现有 SpacetimeDB compile procedure 写入草稿，并把本次生成的独立物品图片与模型文件引用序列化写入 match3d_work_profile.generated_item_assets_json。这一步对标拼图的 save_puzzle_generated_images：生成资产不能只挂在本次 HTTP response 上，否则退出结果页后从草稿架读取 getMatch3DWorkDetail 会丢失素材列表。
在 HTTP 返回的 draft/profile DTO 中附带本次生成的素材资产预览信息，模型生成成功时状态为 model_ready；后续重进草稿页时从 work profile 的持久化 generatedItemAssets 恢复同一批素材。

草稿生成阶段会调用 Hyper3D Rodin，并等待 GLB 模型文件可下载；不得把上游下载 URL 直接写入 Match3D profile，必须先转存 OSS，再保存 /generated-match3d-assets/... 引用。结果页 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.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 = model_ready。前端模型预览不得直接请求裸 /generated-match3d-assets/... 路径；需要通过 /api/assets/read-bytes 读取模型字节，转成 Blob URL 后交给 Three.js GLTFLoader 加载，以绕开私有 bucket CORS。

6. 自动保存与草稿恢复

抓大鹅结果页的基础信息自动保存继续调用 PUT /api/runtime/match3d/works/{profileId} 更新名称、题材、描述、标签、封面、消除数和难度；该保存不得清空 generated_item_assets_json。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；从草稿架重进没有 draft 时，用 profile.generatedItemAssets；两者都没有才回退到默认 3D 素材占位。

3D素材 详情页只保留：

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

详情页不再展示参考图、用途、提示词、文生/图生切换、状态查询、下载列表、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 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。

7.2 KiB Raw Blame History Unescape Escape