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-generating 生成过程页。
3. 过程页复用拼图生成页的 CustomWorldGenerationView 结构。
4. 生成成功后自动进入 match3d-result。
5. 生成失败时停留在生成过程页，允许重新生成或返回创作中心。

生成页步骤固定为：

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

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

3. 后端编排边界

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

match3d_compile_draft action 的后端顺序为：

1. 读取 session config。
2. 将本次 MVP 的 clearCount 固定为 3，并同步用于草稿编译。
3. 基于入口页题材设定文本调用文本模型生成作品元信息。模型固定请求 gpt-4o，只返回 JSON，其中 gameName 为 4 到 12 个中文字符的游戏名称，tags 为 3 到 6 个中文短标签；summary 首版必须保持空字符串，结果页 作品描述 默认留给用户填写。
4. 调用文本模型生成 3 个题材下的短物品名称。
5. 调用项目当前图片链路 VectorEngine gpt-image-2-all 生成一张 1:1 素材图，提示词必须合入入口页选择的 assetStylePrompt。历史 nanobanana2 图片选项当前按项目统一决策回落到 VectorEngine，不重新接入 APIMart 图片网关。
6. 将素材图按 n*n 网格切割成独立图片。当前 3 件物品使用 2*2 网格，取前 3 格。
7. 将素材图和每张独立图片上传到 OSS，其中独立图片作为草稿页素材预览和后续 Rodin 图生模型参考图。
8. 调用现有 SpacetimeDB compile procedure 写入草稿，并把本次生成的独立物品图片列表序列化写入 match3d_work_profile.generated_item_assets_json。这一步对标拼图的 save_puzzle_generated_images：生成资产不能只挂在本次 HTTP response 上，否则退出结果页后从草稿架读取 getMatch3DWorkDetail 会丢失素材列表。
9. 在 HTTP 返回的 draft/profile DTO 中附带本次生成的素材资产预览信息，独立图片状态为 image_ready，模型字段保持为空；后续重进草稿页时从 work profile 的持久化 generatedItemAssets 恢复同一批素材。

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

草稿生成阶段不调用 Hyper3D Rodin，不等待 subscriptionKey，也不下载模型文件；Rodin 生成只在结果页 3D素材 Tab 由用户手动触发。手动生成得到的上游下载 URL 仍不得直接写入 Match3D profile，后续正式资产绑定以独立技术方案为准。

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

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

HTTP DTO 同时返回 imageSrc、imageObjectKey、空的 modelSrc、空的 modelObjectKey 和 status = image_ready。前端预览图片继续走 ResolvedAssetImage 换签；后续手动生成的模型文件也必须通过 useResolvedAssetReadUrl / /api/assets/read-url 换签后打开，不直接请求裸 /generated-match3d-assets/... 路径。

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 素材占位。

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

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

3D素材 详情页只保留：

1. 模型预览区：优先加载 modelSrc 对应 GLB，支持拖动旋转；没有模型时展示空预览。
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 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 和 OSS 访问变量；HYPER3D_API_KEY 只在结果页手动生成 3D 模型时需要。后端改动后使用 npm run api-server 启动，并检查 /healthz。