# 抓大鹅草稿素材生成流水线 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，并从缺失的素材阶段继续，不新建第二份草稿。

生成页步骤固定为：

```text
生成游戏名称 -> 生成物品名称 -> 生成素材图 -> 切割独立图片 -> 上传图片资产 -> 生成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. 图片提示词

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

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

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

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

```text
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：

```text
generated-match3d-assets
```

建议对象分组：

```text
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 运行态模型消费

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

```text
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。

草稿架重进路径为：

```text
草稿 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. 验收

建议执行：

```powershell
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`。