1

.hermes/shared-memory/decision-log.md

@@ -16,6 +16,14 @@
 
 ---
 
+## 2026-05-11 拼图与抓大鹅结果页音频资产复用通用创作音频链路
+
+- 背景：拼图和抓大鹅结果页需要接入 Suno 背景音乐，抓大鹅还需要物体点击音效，但当前两类作品没有独立的作品级音频表或 metadata 字段。
+- 决策：新增 `/api/creation/audio/*` 通用创作音频路由，后端统一负责 VectorEngine 音频任务、OSS 转存、`asset_object` 与 `asset_entity_binding` 写入；视觉小说旧路由保留并复用同一持久化逻辑。拼图背景音乐暂存到首关 `levels_json[0].backgroundMusic/background_music`；抓大鹅背景音乐暂存到 `generated_item_assets_json[0].backgroundMusic/background_music`，单物体点击音效存到对应 item 的 `clickSound/click_sound`。本轮不新增 SpacetimeDB 表和字段。
+- 影响范围：拼图结果页、抓大鹅结果页、抓大鹅运行态音频播放、通用创作音频 shared contracts、`api-server` 音频路由和资产绑定。
+- 验证方式：执行拼图/抓大鹅结果页定向测试、`npm run typecheck`、`cargo test -p api-server vector_engine_audio_generation`、`cargo test -p shared-contracts creation_audio`、`cargo check -p api-server`，真实生成需配置 VectorEngine 与 OSS 私密环境。
+- 关联文档：`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md`。
+
 ## 2026-05-10 儿童动作 Demo 视觉资产统一为绘本草地舞台
 
 - 背景：儿童动作 Demo 需要从暗色科技风切换到更适合儿童互动的卡通绘本草地风格，并且要预留 image-2 真实背景图的固定接入位。

.hermes/shared-memory/pitfalls.md

@@ -439,16 +439,16 @@
 
 ## 抓大鹅草稿生成恢复 Rodin 后要并行生成模型、同步长超时和 GLB 私有读取
 
-- 现象：抓大鹅草稿生成重新接回 Rodin 后，前端可能在模型轮询和 GLB 转存完成前超时；或结果页把 `/generated-match3d-assets/.../model.glb` 直接当浏览器 URL 加载导致私有 OSS/CORS 读取失败。
+- 现象：抓大鹅草稿生成重新接回 Rodin 后，前端可能在模型轮询和 GLB 转存完成前超时；或 Hyper3D 控制台显示 3 个任务已完成，但草稿进度页仍停留在 `生成3D模型`；或结果页把 `/generated-match3d-assets/.../model.glb` 直接当浏览器 URL 加载导致私有 OSS/CORS 读取失败。
 - 原因：`match3d_compile_draft` 会完成作品元信息、素材图、切图上传、3 件 Rodin 图生模型、GLB 下载和 OSS 转存，耗时远长于普通 Agent action；如果 3 件 Rodin 模型逐个提交和轮询，等待时间会线性叠加；同时 generated 私有资产不能被 Three.js 直接 `fetch`。
-- 处理：切图和图片入库后，所有 Rodin 图生模型任务必须并行提交、并行轮询、并行下载转存；Match3D creation client 的 `executeAction` 必须给长超时，当前为 20 分钟；生成进度页要包含 `生成3D模型` 阶段；结果页模型预览、场内运行态和备选栏预览都必须通过 `/api/assets/read-bytes` 读取 GLB 字节后交给 Three.js GLTFLoader，不要直接请求裸 generated 路径。
+- 处理：切图和图片入库后，所有 Rodin 图生模型任务必须并行提交、并行轮询、并行下载转存；Match3D creation client 的 `executeAction` 必须给长超时，当前为 20 分钟；生成进度页要包含 `生成3D模型` 阶段，但它不是 Hyper3D task 订阅页，而是在长 action 执行期间旁路轮询 session / work detail，并用 profile 的 `generatedItemAssets` 更新完成数量；控制台看到 Rodin `Done` 后仍需等待下载列表、GLB 下载、OSS 转存和草稿 JSON 写回。结果页模型预览、场内运行态和备选栏预览都必须通过 `/api/assets/read-bytes` 读取 GLB 字节后交给 Three.js GLTFLoader，不要直接请求裸 generated 路径。排查时按同一个 session/profile 查看 api-server 日志：`抓大鹅 Rodin 状态轮询返回`、`抓大鹅 Rodin 下载列表轮询返回`、`抓大鹅 Rodin GLB 下载完成`、`抓大鹅 Rodin GLB 转存 OSS 完成`；同时检查前端 work detail 响应里的 `generatedItemAssets[].status/modelObjectKey/error`。
 - 验证：`npm run test -- src\services\miniGameDraftGenerationProgress.test.ts src\components\match3d-result\Match3DResultView.test.tsx src\components\match3d-runtime\Match3DRuntimeShell.test.tsx`、`npm run typecheck`；真实联调需配置 `VECTOR_ENGINE_API_KEY`、`HYPER3D_API_KEY` 和 OSS 变量。
 - 关联：`src/services/match3d-creation/match3dCreationClient.ts`、`src/services/creation-agent/creationAgentClientFactory.ts`、`src/components/match3d-result/Match3DModelPreview.tsx`、`src/components/match3d-runtime/Match3DPhysicsBoard.tsx`、`server-rs/crates/api-server/src/match3d.rs`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
 
 ## Rodin 完成态后下载列表可能延迟或字段漂移
 
 - 现象：抓大鹅草稿生成时 Rodin 状态已完成，但 `/api/creation/match3d/sessions/{sessionId}/actions` 返回 502，提示 `{物品名} 3D 模型已完成但未返回可下载模型文件：{taskUuid}`。
-- 原因：Hyper3D Rodin 官方示例要求看 `jobs` 列表，只有所有 job 都 `Done` 才能进入下载；旧聚合若只看 root status 或第一个 job，可能在 preview job 完成但模型 job 仍在生成时提前下载。另外任务完成和下载列表文件发布不是强同步的；上游下载结果还可能使用 `fileUrl`、`signedUrl`、`presignedUrl`、`fileName` 等字段别名，旧解析器只识别 `url/downloadUrl/name/file_name/filename` 时会得到空列表。
+- 原因：Hyper3D Rodin 官方 `check-status_reset_v` 示例要求看 `jobs` 列表，只有所有 job 都 `Done` 才能进入下载；`download-results_reset_v` 还明确要求用生成响应顶层 `uuid` 作为 `task_uuid`，不要用 `jobs.uuids` 子任务 uuid。旧聚合若只看 root status 或第一个 job，可能在 preview job 完成但模型 job 仍在生成时提前下载。另外任务完成和下载列表文件发布不是强同步的；上游下载结果还可能使用 `fileUrl`、`signedUrl`、`presignedUrl`、`fileName` 等字段别名，旧解析器只识别 `url/downloadUrl/name/file_name/filename` 时会得到空列表。
 - 处理：`query_task_status` 聚合状态必须以 `jobs` 为准：任一 failed 即 failed，全部 done 才 done；`match3d_compile_draft` 在状态完成后对 `query_downloads` 继续轮询；下载解析兼容常见 URL 和文件名字段别名；模型选择优先 `.glb`，可兜底到非图片下载文件，但只有 preview/png/jpg/webp 这类预览图时必须继续失败，不能伪装成 GLB。
 - 验证：`cargo test -p api-server match3d_model_download --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server extracts_download_files --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server hyper3d --manifest-path server-rs/Cargo.toml`。
 - 关联：`server-rs/crates/api-server/src/match3d.rs`、`server-rs/crates/api-server/src/hyper3d_generation.rs`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
@@ -469,6 +469,14 @@
 - 验证：`cargo test -p spacetime-client match3d --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`。
 - 关联：`server-rs/crates/spacetime-module/src/match3d/*`、`server-rs/crates/spacetime-client/src/mapper.rs`、`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-result/Match3DResultView.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
 
+## 抓大鹅试玩和正式运行态不要只读草稿页本地模型预览
+
+- 现象：历史草稿页 `3D素材` Tab 能看到水果模型，但点击试玩或从推荐 / 公开作品进入正式抓大鹅时，局内仍显示默认积木素材。
+- 原因：结果页手动 `重新生成` 曾只更新本地 `assetDrafts.downloads`，没有把新的 GLB 写回 `generatedItemAssets`；历史数据还可能只有 `modelObjectKey` 而没有 `modelSrc`；推荐流内嵌运行态若只读卡片摘要，卡片缺素材时会把已持久化 profile 模型丢掉；本次生成 response 的 draft 也可能比 profile 旧，只带图片而不带模型。
+- 处理：结果页模型预览和运行态都按 `modelSrc || modelObjectKey` 读取；手动重新生成成功后把素材草稿重新序列化并写回作品 profile；`Match3DResultView` 合并同 `itemId` 的 draft/profile 素材，用 profile 已有模型补齐旧 draft；推荐流内嵌运行态启动前若卡片摘要没有生成素材，补读 `getMatch3DWorkDetail(profileId)` 并把详情资产传给 `Match3DRuntimeShell`。
+- 验证：执行 `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`，并检查历史草稿和公开 M3 作品的 Network 响应里 `generatedItemAssets[].modelSrc/modelObjectKey`。
+- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/match3d-runtime/Match3DPhysicsBoard.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
 ## 抓大鹅标签清洗不要把 `3D素材` 当编号剥掉
 
 - 现象：AI 或兜底生成的 `3D素材` 标签在后端规范化后变成 `D素材`。

docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md

@@ -18,7 +18,7 @@
 
 ```text
 标题：10分钟创作一个精品互动玩法
-模板 Tab：拼图 / 抓大鹅 / 视觉小说 / AIRP
+模板 Tab：拼图 / 抓大鹅 / 视觉小说（敬请期待）/ AIRP
 默认内容：拼图创作表单
 ```
 
@@ -34,7 +34,7 @@
 1. 打开“创作”一级 Tab 时默认停留在拼图 Tab，不主动创建拼图 session。
 2. 点击拼图表单“生成草稿”后，才创建拼图 session 并执行 `compile_puzzle_draft`。
 3. 拼图表单内的模板按钮使用 `tablist / tab` 语义，点击后只填充画面描述。
-4. 点击非拼图且已开放的模板 Tab 时，进入该玩法既有工作台；未开放模板保持禁用。
+4. 点击非拼图且已开放的模板 Tab 时，进入该玩法既有工作台；视觉小说与 AIRP 当前保持敬请期待禁用态。
 5. `creative-agent` 不出现在模板 Tab 和选择弹层中，不再作为创作 Tab 首屏入口。
 6. 方洞挑战暂时从创作页完全隐藏，不出现在模板 Tab、旧选择弹层和创作 Hub 卡片中；既有作品链路继续保留。
 

docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md

@@ -114,3 +114,13 @@
 - 未登录用户点击推荐页封面时，再次打开同一个登录弹窗；登录成功后由既有受保护动作继续进入作品详情或玩法入口。
 - 未登录状态下点击“下一个”只切换下一张推荐封面，不触发登录弹窗，也不启动玩法。
 - 已登录用户继续沿用推荐页内嵌运行态、上下滑切换和底部“下一个”行为。
+
+## 10. 2026-05-11 草稿生成中与新完成标记
+
+草稿生成过程页允许用户直接返回创作中心并自由使用平台其它功能：
+
+- 点击生成过程页的返回按钮时，当前生成任务继续在后台执行，页面回到创作中心，不清空生成状态。
+- 用户再进入草稿 Tab 并点击同一草稿时，若生成仍未完成，进入对应生成过程页查看最新进度；若已完成，直接进入对应结果页。
+- 草稿作品卡在生成中展示“生成中”状态标记；新生成完成且用户尚未查看的草稿在卡片右上角展示红点。
+- 底部一级“草稿”Tab 在存在未查看新完成草稿时展示红点；用户点击查看带红点的作品后，该作品红点消失。若草稿页已无任何带红点作品，底部“草稿”Tab 红点同步消失。
+- 生成完成时如果用户仍停留在对应生成过程页，可自动进入结果页；如果用户已经回到创作中心或其它功能页，不打断当前操作。

docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md

@@ -69,7 +69,7 @@
 
 ### 3.1 必须完成的模板闭环
 
-1. 平台创作中心展示 `视觉小说` 入口，并在实现完成后从 `open: false` 改为 `open: true`。
+1. 平台创作中心展示 `视觉小说` 入口；2026-05-11 起当前运营状态回退为 `open: false`，入口显示敬请期待，不允许创建新视觉小说草稿。
 2. 创作者可选择 `idea`、`document`、`blank` 三种起点创建视觉小说底稿。
 3. Agent 或表单工作台生成 / 编辑同一份 `VisualNovelResultDraft`。
 4. 结果页可编辑世界观、角色、场景、剧情阶段、资产和运行时配置。
@@ -692,27 +692,27 @@ GET  /api/runtime/profile/save-archives
 
 ### 11.1 入口配置
 
-当前 `src/config/newWorkEntryConfig.ts` 已存在：
+入口配置事实源已经迁移到 SpacetimeDB 的 `creation_entry_type_config` 表，默认种子位于 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs`。2026-05-11 起视觉小说当前默认状态为：
 
 ```ts
 {
   id: 'visual-novel',
   title: '视觉小说',
-  subtitle: '敬请期待',
+  subtitle: '分支叙事体验',
   badge: '敬请期待',
   visible: true,
   open: false,
 }
 ```
 
-实现完成后更新为：
+重新开放创建时再通过后台入口开关或默认种子更新为：
 
 ```ts
 {
   id: 'visual-novel',
   title: '视觉小说',
-  subtitle: 'AI 生成可玩的视觉小说',
-  badge: '新玩法',
+  subtitle: '分支叙事体验',
+  badge: '可创建',
   visible: true,
   open: true,
 }
@@ -1754,7 +1754,7 @@ VN-11 从 Batch 1 开始持续运行，最终阻塞发布。
 
 ### 17.1 正向验收
 
-1. `visual-novel` 入口可见并可点击创建。
+1. `visual-novel` 入口当前可见但处于敬请期待禁用态；重新开放 `open=true` 后，再验收点击创建闭环。
 2. 一句话创建能生成可编辑底稿。
 3. 文档创建能读取平台文档资产并生成底稿。
 4. 空白创建能进入结果页。

docs/technical/ADMIN_CREATION_ENTRY_SWITCH_CONFIG_2026-05-11.md

@@ -65,7 +65,7 @@ Admin Web
   -> spacetime-module creation_entry_type_config 表
 ```
 
-`visible=false` 会让创作中心不展示对应入口；`open=false` 会让前端展示锁定态，并让 api-server 熔断对应玩法 API。隐藏入口但仍保留既有作品号、广场详情或试玩链路时，应只关闭 `visible`，不要关闭 `open`。
+`visible=false` 会让创作中心不展示对应入口；`open=false` 会让前端展示锁定态，并让 api-server 熔断对应玩法创作 / 运行态 API。隐藏入口但仍保留既有作品号、广场详情或试玩链路时，应只关闭 `visible`，不要关闭 `open`。
 
 ## 注意
 

docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md

@@ -13,6 +13,8 @@
 - `https://developer.hyper3d.ai/api-specification/rodin-generation-gen2`
 - `https://developer.hyper3d.ai/api-specification/check-status`
 - `https://developer.hyper3d.ai/api-specification/download-results`
+- `https://developer.hyper3d.ai/api-specification/check-status_reset_v`
+- `https://developer.hyper3d.ai/api-specification/download-results_reset_v`
 
 上游接口：
 
@@ -24,6 +26,11 @@ POST https://api.hyper3d.com/api/v2/download
 
 Rodin Gen-2 提交接口必须使用 `multipart/form-data`。文本生成时提交 `prompt`；图片生成时提交一个或多个 `images` 文件，可选 `prompt` 作为辅助描述。两种模式均固定提交 `tier=Gen-2`。
 
+官方 `*_reset_v` 文档对状态和下载有两个关键约束：
+
+1. 生成接口返回的顶层 `uuid` 是后续下载接口的 `task_uuid`，不要使用 `jobs.uuids` 中的子任务 uuid 作为下载参数。
+2. 状态接口使用 `subscription_key` 查询，并返回 `jobs[]`；只有所有 job 的 `status` 都为 `Done` 才能进入下载，任一 job `Failed` 都应视为任务失败。
+
 ## 3. 环境变量
 
 ```text
@@ -111,7 +118,7 @@ RODIN_MODEL_REQUEST_TIMEOUT_MS
 }
 ```
 
-状态查询会把上游 `Waiting / Generating / Done / Failed` 归一化为 `waiting / generating / done / failed / unknown`。下载接口只返回上游 `list.name` 与 `list.url`，不在后端转存文件。
+状态查询会把上游 `Waiting / Generating / Done / Failed` 归一化为 `waiting / generating / done / failed / unknown`，整体状态必须以 `jobs[]` 聚合结果为准。下载接口只返回上游 `list.name` 与 `list.url`，不在 Hyper3D 代理路由中转存文件；具体玩法若需要持久化模型，应在玩法编排层等待 `Done` 后再下载并转存。
 
 ## 7. 验收
 

docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md

@@ -11,10 +11,11 @@
 入口仍复用 `Match3DAgentWorkspace` 表单。点击 `生成抓大鹅草稿` 后：
 
 1. 创建 Match3D session。
-2. 进入 `match3d-generating` 生成过程页。
-3. 过程页复用拼图生成页的 `CustomWorldGenerationView` 结构。
-4. 生成成功后自动进入 `match3d-result`。
-5. 生成失败时停留在生成过程页，允许重新生成或返回创作中心。
+2. 后端先用当前题材和本地兜底元信息创建同一个 Match3D 草稿 profile，草稿 Tab 必须立即能看到这份存档。
+3. 进入 `match3d-generating` 生成过程页。
+4. 过程页复用拼图生成页的 `CustomWorldGenerationView` 结构。
+5. 生成成功后自动进入 `match3d-result`。
+6. 生成失败时停留在生成过程页，允许重新生成或返回创作中心；重新生成必须复用同一个 session / profile，并从缺失的素材阶段继续，不新建第二份草稿。
 
 生成页步骤固定为：
 
@@ -24,6 +25,8 @@
 
 生成页只展示题材和物品数量，不展示玩法规则说明。
 
+当前 `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 的确定性写入。
@@ -32,18 +35,19 @@
 
 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. 使用每张独立图片作为参考图，并行调用 Hyper3D Rodin 图生模型；所有 3D 模型任务必须在同一阶段同时提交、同时轮询状态、同时下载并转存 OSS，禁止逐个物品串行等待模型完成。每个任务按官方 minimal example 轮询状态；只有 `jobs` 全部进入 `Done` 才能视为任务完成，任一 job `Failed` 则失败。完成后选择 `.glb` 下载文件，并把 GLB 转存到 OSS。Rodin 的 `subscriptionKey` 是上游 opaque token，不做 256 字符这类短文本长度限制。Rodin 任务状态进入完成态后，下载列表仍可能延迟发布；后端必须对下载列表继续轮询，并兼容 `url`、`downloadUrl`、`fileUrl`、`signedUrl` 等下载字段别名，只有预览图而没有模型文件时不能伪装成 GLB 成功。
-9. 调用现有 SpacetimeDB compile procedure 写入草稿，并把本次生成的独立物品图片和模型列表序列化写入 `match3d_work_profile.generated_item_assets_json`。这一步对标拼图的 `save_puzzle_generated_images`：生成资产不能只挂在本次 HTTP response 上，否则退出结果页后从草稿架读取 `getMatch3DWorkDetail` 会丢失素材列表。
-10. 在 HTTP 返回的 draft/profile DTO 中附带本次生成的素材资产预览信息，模型生成成功的素材状态为 `model_ready`；后续重进草稿页时从 work profile 的持久化 `generatedItemAssets` 恢复同一批素材。
+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 分钟；由于 3 个模型并行生成，总耗时按最慢模型计算，不能按模型数量线性叠加。结果页 `3D素材` Tab 直接加载已生成模型；用户点击 `重新生成` 时再复用 Rodin 安全代理，首版重新生成只更新当前页面内预览状态，后续正式资产绑定以独立技术方案为准。
+草稿生成阶段会调用 Hyper3D Rodin 并等待 GLB 下载完成；前端 `match3d_compile_draft` action 请求超时必须覆盖该长耗时链路，当前 Match3D client 使用 20 分钟超时。Rodin 单模型状态轮询预算为 10 分钟，下载列表发布轮询预算为 5 分钟；GLB 下载和 OSS PutObject 各自设置 3 分钟 HTTP 超时，避免上游下载或转存连接长期悬挂。由于 3 个模型并行生成，总耗时按最慢模型计算，不能按模型数量线性叠加。结果页 `3D素材` Tab 直接加载已生成模型；用户点击 `重新生成` 时再复用 Rodin 安全代理，首版重新生成只更新当前页面内预览状态，后续正式资产绑定以独立技术方案为准。
 
 ## 4. 图片提示词
 
@@ -113,9 +117,18 @@ Match3DWorkProfile / PlatformMatch3DGalleryCard
 5. 物理碰撞和边界仍沿用现有 `visualKey` 的程序化几何，生成 GLB 只替换视觉模型，不承接规则真相。
 6. 模型缺失、读取失败或 WebGL 回退时，继续使用默认积木素材，不能阻断开局、点击、入槽或结算。
 
+结果页点击 `试玩` 时，前端必须把当前结果页可见的 `generatedItemAssets` 带入运行态启动入参。`PUT /api/runtime/match3d/works/{profileId}` 若因为并发或旧快照返回了缺少素材的 profile，`Match3DResultView` 需要把当前 draft / profile 的素材重新合并到 `onStartTestRun(profile)`；若历史草稿同时存在旧 `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. 自动保存与草稿恢复
 
-抓大鹅结果页的基础信息自动保存继续调用 `PUT /api/runtime/match3d/works/{profileId}` 更新名称、题材、描述、标签、封面、消除数和难度；该保存不得清空 `generated_item_assets_json`。SpacetimeDB `update_match3d_work` / `publish_match3d_work` 必须保留当前行的生成素材 JSON。
+点击 `生成抓大鹅草稿` 后，草稿存档创建与素材生成解耦：
+
+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。
 
 草稿架重进路径为：
 
@@ -123,7 +136,7 @@ Match3DWorkProfile / PlatformMatch3DGalleryCard
 草稿 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 素材占位。
+因此 `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 字段命名对齐拼图草稿：
 
@@ -134,7 +147,7 @@ Match3DWorkProfile / PlatformMatch3DGalleryCard
 
 `3D素材` 详情页只保留：
 
-1. 模型预览区：优先加载 `modelSrc` 对应 GLB，支持拖动旋转；没有模型时展示空预览。
+1. 模型预览区：优先加载 `modelSrc` 对应 GLB，缺失时加载 `modelObjectKey`，支持拖动旋转；没有模型时展示空预览。
 2. 素材名称输入。
 3. `重新生成` 按钮。
 
@@ -148,6 +161,8 @@ Match3DWorkProfile / PlatformMatch3DGalleryCard
 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

docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md

@@ -8,7 +8,7 @@
 
 1. 新建作品入口配置统一存放在 SpacetimeDB 的 `creation_entry_config` / `creation_entry_type_config` 表；默认种子位于 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs`。
 2. `visible` 控制玩法是否展示在创作 Tab 模板入口、新建作品入口和创作类型弹层中。
-3. `open` 控制玩法是否允许点击创建以及对应 runtime/API 路由是否放行；`open: false` 时入口保持展示但禁用，并由 `api-server` 熔断对应玩法 API。
+3. `open` 控制玩法是否允许点击创建以及对应创作 / runtime API 路由是否放行；`open: false` 时入口保持展示但禁用，并由 `api-server` 熔断对应玩法 API。
 4. `title`、`subtitle`、`badge` 控制玩法卡片文案。
 5. `startCard` 控制旧创作中心顶部新建作品模块的标题、辅助文案和移动端角标文案；当前创作 Tab 首屏标题固定在 `PlatformEntryFlowShellImpl.tsx`，不再由 `startCard` 控制。
 6. `typeModal` 控制平台创作类型弹层标题和描述。
@@ -26,7 +26,7 @@
 | 抓大鹅 | 是 | 是 | 点击后进入抓大鹅 Match3D Agent 共创工作台 |
 | 方洞挑战 | 否 | 是 | 创作页入口暂时完全隐藏，既有草稿、结果页、发布、试玩、作品架与广场链路保留 |
 | AIRP | 是 | 否 | 保留入口，显示敬请期待 |
-| 视觉小说 | 是 | 是 | 点击后进入视觉小说创作工作台 |
+| 视觉小说 | 是 | 否 | 保留入口，显示敬请期待，暂不允许创建视觉小说草稿 |
 | 智能创作 | 否 | 是 | 入口隐藏，既有 `creative-agent` 链路保留 |
 
 ## 验收

docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md

@@ -0,0 +1,89 @@
+# 拼图与抓大鹅结果页音乐 Tab 2026-05-11
+
+## 1. 范围
+
+本方案把 VectorEngine 音频生成能力从视觉小说结果页扩展到拼图与抓大鹅结果页：
+
+1. 拼图结果页新增 `音乐` Tab，支持通过 Suno 生成作品背景音乐。
+2. 抓大鹅结果页新增 `音乐` Tab，支持通过 Suno 生成作品背景音乐。
+3. 抓大鹅 `3D素材` Tab 支持为每个生成物体通过 Vidu 生成点击音效。
+
+本轮不新增 SpacetimeDB 表，不修改表字段，不把供应商密钥下发到前端。
+
+## 2. 通用音频接口
+
+后端在既有视觉小说音频路由外新增通用创作音频路由：
+
+| 方法 | 路由 | 用途 |
+| --- | --- | --- |
+| `POST` | `/api/creation/audio/background-music` | 提交 Suno 背景音乐任务 |
+| `POST` | `/api/creation/audio/background-music/{task_id}/asset` | 查询并转存 Suno 音频资产 |
+| `POST` | `/api/creation/audio/sound-effect` | 提交 Vidu 音效任务 |
+| `POST` | `/api/creation/audio/sound-effect/{task_id}/asset` | 查询并转存 Vidu 音效资产 |
+
+通用转存请求由前端传入 `entityKind`、`entityId`、`slot`、`assetKind`、`profileId`。后端仍负责：
+
+1. 校验 VectorEngine 与 OSS 环境变量。
+2. 轮询供应商任务结果。
+3. 下载音频字节。
+4. 写入 OSS 私有对象。
+5. 确认 `asset_object` 并绑定 `asset_entity_binding`。
+
+视觉小说原路由保持兼容，内部继续复用同一套提交、轮询、转存逻辑。
+
+## 3. 数据落点
+
+### 3.1 拼图
+
+拼图作品没有独立作品级 metadata 字段。背景音乐随 `levels_json` 保存到首个 `PuzzleDraftLevel.backgroundMusic`：
+
+```json
+{
+  "levelId": "puzzle-level-1",
+  "backgroundMusic": {
+    "taskId": "suno-task",
+    "provider": "vector-engine-suno",
+    "assetObjectId": "assetobj_1",
+    "assetKind": "puzzle_background_music",
+    "audioSrc": "/generated-puzzle-assets/..."
+  }
+}
+```
+
+运行态后续可从当前关卡快照或作品详情读取该字段作为背景音乐源；若字段为空，继续使用现有程序化背景音乐兜底。
+
+### 3.2 抓大鹅
+
+抓大鹅作品级音频与物体点击音效复用 `generated_item_assets_json` 数组保存，不新增表字段：
+
+1. 作品背景音乐暂存到第一个 `Match3DGeneratedItemAsset.backgroundMusic`，表示当前 work profile 的作品级背景音乐。
+2. 单个物体点击音效保存到对应 `Match3DGeneratedItemAsset.clickSound`。
+
+这是一个兼容性折中：当前 Match3D work profile 没有 work-level metadata 字段，而 `generated_item_assets_json` 已经随作品详情、草稿架、运行态入口稳定传递。后续若新增正式作品 metadata 表达，应迁移 `backgroundMusic` 到作品级字段。
+
+## 4. 前端交互
+
+结果页 UI 保持轻量：
+
+1. `音乐` Tab 只展示必要输入、生成按钮、状态与音频预览，不展示供应商规则说明。
+2. 生成完成后立即写回本地草稿状态，并触发既有保存链路或专用保存接口。
+3. 抓大鹅每个物体音效生成入口放在对应素材详情面板内，不在列表下方展开大段配置。
+
+## 5. 验收
+
+建议执行：
+
+```powershell
+npm run check:encoding
+npm run test -- src\components\puzzle-result\PuzzleResultView.test.tsx
+npm run test -- src\components\match3d-result\Match3DResultView.test.tsx
+npm run typecheck
+cargo test -p shared-contracts creation_audio --manifest-path server-rs\Cargo.toml
+cargo test -p shared-contracts puzzle --manifest-path server-rs\Cargo.toml
+cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml
+cargo test -p api-server vector_engine_audio_generation --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
+```
+
+真实生成 smoke 需要本地私密环境配置 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 与 OSS 变量。后端改动后使用 `npm run api-server` 启动，并确认 `/healthz`。

packages/shared/src/contracts/creationAudio.ts

@@ -0,0 +1,53 @@
+export type CreationAudioGenerationKind =
+  | 'background_music'
+  | 'sound_effect';
+
+export interface CreationAudioAsset {
+  taskId: string;
+  provider: string;
+  assetObjectId?: string | null;
+  assetKind?: string | null;
+  audioSrc: string;
+  prompt?: string | null;
+  title?: string | null;
+  updatedAt?: string | null;
+}
+
+export interface CreateBackgroundMusicRequest {
+  prompt: string;
+  title: string;
+  tags?: string | null;
+  model?: string | null;
+}
+
+export interface CreateSoundEffectRequest {
+  prompt: string;
+  duration?: number | null;
+  seed?: number | null;
+}
+
+export interface AudioGenerationTaskResponse {
+  kind: CreationAudioGenerationKind;
+  taskId: string;
+  provider: string;
+  status: string;
+}
+
+export interface PublishGeneratedAudioAssetRequest {
+  entityKind: string;
+  entityId: string;
+  slot: string;
+  assetKind: string;
+  profileId?: string | null;
+  storagePrefix?: 'puzzle_assets' | 'match3d_assets' | 'custom_world_scenes' | null;
+}
+
+export interface GeneratedAudioAssetResponse {
+  kind: CreationAudioGenerationKind;
+  taskId: string;
+  provider: string;
+  status: string;
+  assetObjectId?: string | null;
+  assetKind?: string | null;
+  audioSrc?: string | null;
+}

packages/shared/src/contracts/index.ts

@@ -1,4 +1,5 @@
 export type * from './creativeAgent';
+export type * from './creationAudio';
 export type * from './hyper3d';
 export type * from './puzzleCreativeTemplate';
 export type * from './visualNovel';

packages/shared/src/contracts/match3dWorks.ts

@@ -2,6 +2,8 @@
  * 抓大鹅 Match3D 作品读写共享契约。
  * 首版作品发布必须补齐游戏名称、标签、封面、题材、消除次数和难度。
  */
+import type { CreationAudioAsset } from './creationAudio';
+
 export type Match3DWorkPublicationStatus = 'draft' | 'published' | string;
 
 export type Match3DGeneratedItemAssetStatus =
@@ -22,10 +24,16 @@ export interface Match3DGeneratedItemAsset {
   modelFileName?: string | null;
   taskUuid?: string | null;
   subscriptionKey?: string | null;
+  backgroundMusic?: CreationAudioAsset | null;
+  clickSound?: CreationAudioAsset | null;
   status: Match3DGeneratedItemAssetStatus;
   error?: string | null;
 }
 
+export interface PutMatch3DAudioAssetsRequest {
+  generatedItemAssets: Match3DGeneratedItemAsset[];
+}
+
 export interface PutMatch3DWorkRequest {
   gameName: string;
   themeText?: string;

packages/shared/src/contracts/puzzleAgentDraft.ts

@@ -1,4 +1,5 @@
 import type { JsonObject } from './common';
+import type { CreationAudioAsset } from './creationAudio';
 
 export type PuzzleAnchorStatus =
   | 'missing'
@@ -47,6 +48,7 @@ export interface PuzzleDraftLevel {
   levelName: string;
   pictureDescription: string;
   pictureReference?: string | null;
+  backgroundMusic?: CreationAudioAsset | null;
   candidates: PuzzleGeneratedImageCandidate[];
   selectedCandidateId: string | null;
   coverImageSrc: string | null;

packages/shared/src/index.ts

@@ -3,6 +3,7 @@ export * from './contracts/auth';
 export type * from './contracts/bigFish';
 export * from './contracts/common';
 export type * from './contracts/creationAgentDocumentInput';
+export type * from './contracts/creationAudio';
 export type * from './contracts/creativeAgent';
 export type * from './contracts/customWorldAgent';
 export type * from './contracts/hyper3d';

server-rs/crates/api-server/src/app.rs

@@ -5,7 +5,7 @@ use axum::{
     http::Request,
     middleware,
     response::Response,
-    routing::{delete, get, post},
+    routing::{delete, get, post, put},
 };
 use tower_http::{
     classify::ServerErrorsFailureClass,
@@ -92,8 +92,8 @@ use crate::{
         delete_match3d_work, execute_match3d_agent_action, finish_match3d_time_up,
         generate_match3d_work_tags, get_match3d_agent_session, get_match3d_run,
         get_match3d_work_detail, get_match3d_works, list_match3d_gallery, publish_match3d_work,
-        put_match3d_work, restart_match3d_run, start_match3d_run, stop_match3d_run,
-        stream_match3d_agent_message, submit_match3d_agent_message,
+        put_match3d_audio_assets, put_match3d_work, restart_match3d_run, start_match3d_run,
+        stop_match3d_run, stream_match3d_agent_message, submit_match3d_agent_message,
     },
     password_entry::password_entry,
     password_management::{change_password, reset_password},
@@ -156,7 +156,9 @@ use crate::{
     },
     tracking::record_route_tracking_event_after_success,
     vector_engine_audio_generation::{
+        create_background_music_task, create_sound_effect_task,
         create_visual_novel_background_music_task, create_visual_novel_sound_effect_task,
+        publish_background_music_asset, publish_sound_effect_asset,
         publish_visual_novel_background_music_asset, publish_visual_novel_sound_effect_asset,
     },
     visual_novel::{
@@ -942,6 +944,13 @@ pub fn build_router(state: AppState) -> Router {
                     require_bearer_auth,
                 )),
         )
+        .route(
+            "/api/creation/match3d/works/{profile_id}/audio-assets",
+            put(put_match3d_audio_assets).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
         .route(
             "/api/creation/match3d/works/{profile_id}/publish",
             post(publish_match3d_work).route_layer(middleware::from_fn_with_state(
@@ -1517,7 +1526,7 @@ pub fn build_router(state: AppState) -> Router {
             )),
         )
         .route("/api/auth/password/reset", post(reset_password))
-        // 后端 runtime/API 路由只按 open 做熔断；visible 仅控制创作页入口展示。
+        // 后端创作/运行态 API 路由只按 open 做熔断；visible 仅控制创作页入口展示。
         .layer(middleware::from_fn_with_state(
             state.clone(),
             require_creation_entry_route_enabled,
@@ -1770,6 +1779,34 @@ fn visual_novel_router(state: AppState) -> Router<AppState> {
                 middleware::from_fn_with_state(state.clone(), require_bearer_auth),
             ),
         )
+        .route(
+            "/api/creation/audio/background-music",
+            post(create_background_music_task).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/audio/background-music/{task_id}/asset",
+            post(publish_background_music_asset).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/audio/sound-effect",
+            post(create_sound_effect_task).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/audio/sound-effect/{task_id}/asset",
+            post(publish_sound_effect_asset).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
         .route(
             "/api/runtime/visual-novel/gallery",
             get(list_visual_novel_gallery),
@@ -2007,6 +2044,38 @@ mod tests {
         assert_eq!(body["error"]["details"]["creationTypeId"], "puzzle");
     }
 
+    #[tokio::test]
+    async fn disabled_visual_novel_creation_route_returns_service_unavailable() {
+        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/creation/visual-novel/sessions")
+                    .header("content-type", "application/json")
+                    .body(Body::from(
+                        serde_json::json!({
+                            "sourceMode": "idea",
+                            "seedText": "雨夜书店",
+                            "sourceAssetIds": []
+                        })
+                        .to_string(),
+                    ))
+                    .expect("request should build"),
+            )
+            .await
+            .expect("request should succeed");
+
+        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+        let body = read_json_response(response).await;
+        assert_eq!(
+            body["error"]["details"]["reason"],
+            "creation_entry_disabled"
+        );
+        assert_eq!(body["error"]["details"]["creationTypeId"], "visual-novel");
+    }
+
     #[tokio::test]
     async fn healthz_returns_standard_envelope_when_requested() {
         let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
@@ -4693,7 +4762,9 @@ mod tests {
 
     #[tokio::test]
     async fn visual_novel_creation_route_requires_authentication() {
-        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        state.set_test_creation_entry_route_enabled("visual-novel", true);
+        let app = build_router(state);
 
         let response = app
             .oneshot(

server-rs/crates/api-server/src/creation_entry_config.rs

@@ -34,7 +34,7 @@ pub async fn get_creation_entry_config_handler(
     Ok(json_success_body(Some(&request_context), config))
 }
 
-/// 中文注释：api-server 路由熔断只拦运行态/API 请求，不改变前端入口展示规则。
+/// 中文注释：api-server 路由熔断只拦创作/运行态 API 请求，不改变前端入口展示规则。
 pub async fn require_creation_entry_route_enabled(
     State(state): State<AppState>,
     request: Request<Body>,
@@ -87,6 +87,9 @@ pub fn resolve_creation_entry_route_id(path: &str) -> Option<&'static str> {
     if normalized.starts_with("/api/runtime/visual-novel") {
         return Some("visual-novel");
     }
+    if normalized.starts_with("/api/creation/visual-novel") {
+        return Some("visual-novel");
+    }
     None
 }
 
@@ -115,7 +118,7 @@ pub(crate) fn test_creation_entry_config_response()
             test_creation_type("puzzle", true, true, 30),
             test_creation_type("match3d", true, true, 40),
             test_creation_type("square-hole", false, true, 50),
-            test_creation_type("visual-novel", true, true, 60),
+            test_creation_type("visual-novel", true, false, 60),
             test_creation_type("airp", true, false, 70),
             test_creation_type("creative-agent", false, true, 80),
         ],
@@ -165,6 +168,10 @@ mod tests {
             resolve_creation_entry_route_id("/api/runtime/visual-novel/works"),
             Some("visual-novel"),
         );
+        assert_eq!(
+            resolve_creation_entry_route_id("/api/creation/visual-novel/sessions"),
+            Some("visual-novel"),
+        );
         assert_eq!(resolve_creation_entry_route_id("/healthz"), None);
     }
 }

server-rs/crates/api-server/src/http_error.rs

@@ -89,6 +89,14 @@ impl IntoResponse for AppError {
     }
 }
 
+impl std::fmt::Display for AppError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(self.body_text().as_str())
+    }
+}
+
+impl std::error::Error for AppError {}
+
 impl From<AppError> for Response {
     fn from(error: AppError) -> Self {
         error.into_response()

server-rs/crates/api-server/src/hyper3d_generation.rs

@@ -563,11 +563,9 @@ fn resolve_hyper3d_overall_status(
 
 fn extract_job_uuids(payload: &Value) -> Vec<String> {
     let mut job_uuids = Vec::new();
-    if let Some(jobs) = find_first_array_by_keys(payload, &["jobs"]) {
-        for job in jobs {
-            if let Some(uuid) = find_first_string_by_keys(job, &["uuid", "task_uuid", "taskUuid"])
-                && !job_uuids.contains(&uuid)
-            {
+    if let Some(jobs) = payload.get("jobs") {
+        for uuid in collect_strings_by_keys(jobs, &["uuid", "task_uuid", "taskUuid", "uuids"]) {
+            if !job_uuids.contains(&uuid) {
                 job_uuids.push(uuid);
             }
         }
@@ -1076,8 +1074,10 @@ mod tests {
             contract::Hyper3dGenerationMode::TextToModel,
             json!({
                 "uuid": "task-1",
-                "subscription_key": "sub-1",
-                "jobs": [{ "uuid": "job-1" }],
+                "jobs": {
+                    "uuids": ["job-1", "job-2"],
+                    "subscription_key": "sub-1"
+                },
                 "message": "submitted"
             }),
         )
@@ -1085,7 +1085,7 @@ mod tests {
 
         assert_eq!(response.task_uuid, "task-1");
         assert_eq!(response.subscription_key, "sub-1");
-        assert_eq!(response.job_uuids, vec!["job-1"]);
+        assert_eq!(response.job_uuids, vec!["job-1", "job-2"]);
     }
 
     #[test]

server-rs/crates/api-server/src/puzzle.rs

@@ -26,6 +26,7 @@ use platform_oss::{
 };
 use serde_json::{Map, Value, json};
 use shared_contracts::{
+    creation_audio::CreationAudioAsset,
     puzzle_agent::{
         CreatePuzzleAgentSessionRequest, ExecutePuzzleAgentActionRequest,
         PuzzleAgentActionResponse, PuzzleAgentMessageResponse, PuzzleAgentOperationResponse,
@@ -56,7 +57,7 @@ use spacetime_client::{
     PuzzleAgentMessageRecord, PuzzleAgentMessageSubmitRecordInput,
     PuzzleAgentSessionCreateRecordInput, PuzzleAgentSessionRecord,
     PuzzleAgentSuggestedActionRecord, PuzzleAnchorItemRecord, PuzzleAnchorPackRecord,
-    PuzzleCreatorIntentRecord, PuzzleDraftLevelRecord, PuzzleFormDraftRecord,
+    PuzzleAudioAssetRecord, PuzzleCreatorIntentRecord, PuzzleDraftLevelRecord, PuzzleFormDraftRecord,
     PuzzleFormDraftSaveRecordInput, PuzzleGeneratedImageCandidateRecord,
     PuzzleGeneratedImagesSaveRecordInput, PuzzleLeaderboardEntryRecord,
     PuzzleLeaderboardSubmitRecordInput, PuzzlePublishRecordInput, PuzzleRecommendedNextWorkRecord,
@@ -228,6 +229,7 @@ pub async fn generate_puzzle_onboarding_work(
         level_name: level_name.clone(),
         picture_description: prompt_text.clone(),
         picture_reference: None,
+        background_music: None,
         candidates,
         selected_candidate_id: Some(selected.candidate_id.clone()),
         cover_image_src: Some(selected.image_src.clone()),
@@ -2059,6 +2061,7 @@ fn map_puzzle_draft_level_response(level: PuzzleDraftLevelRecord) -> PuzzleDraft
         level_name: level.level_name,
         picture_description: level.picture_description,
         picture_reference: level.picture_reference,
+        background_music: level.background_music.map(map_puzzle_audio_asset_record_response),
         candidates: level
             .candidates
             .into_iter()
@@ -2071,6 +2074,70 @@ fn map_puzzle_draft_level_response(level: PuzzleDraftLevelRecord) -> PuzzleDraft
     }
 }
 
+fn map_puzzle_audio_asset_record_response(asset: PuzzleAudioAssetRecord) -> CreationAudioAsset {
+    CreationAudioAsset {
+        task_id: asset.task_id,
+        provider: asset.provider,
+        asset_object_id: asset.asset_object_id,
+        asset_kind: asset.asset_kind,
+        audio_src: asset.audio_src,
+        prompt: asset.prompt,
+        title: asset.title,
+        updated_at: asset.updated_at,
+    }
+}
+
+fn map_puzzle_audio_asset_domain_record(
+    asset: module_puzzle::PuzzleAudioAsset,
+) -> PuzzleAudioAssetRecord {
+    PuzzleAudioAssetRecord {
+        task_id: asset.task_id,
+        provider: asset.provider,
+        asset_object_id: asset.asset_object_id,
+        asset_kind: asset.asset_kind,
+        audio_src: asset.audio_src,
+        prompt: asset.prompt,
+        title: asset.title,
+        updated_at: asset.updated_at,
+    }
+}
+
+fn puzzle_audio_asset_response_module_json(asset: &Option<CreationAudioAsset>) -> Value {
+    asset
+        .as_ref()
+        .map(|asset| {
+            json!({
+                "task_id": asset.task_id,
+                "provider": asset.provider,
+                "asset_object_id": asset.asset_object_id,
+                "asset_kind": asset.asset_kind,
+                "audio_src": asset.audio_src,
+                "prompt": asset.prompt,
+                "title": asset.title,
+                "updated_at": asset.updated_at,
+            })
+        })
+        .unwrap_or(Value::Null)
+}
+
+fn puzzle_audio_asset_record_module_json(asset: &Option<PuzzleAudioAssetRecord>) -> Value {
+    asset
+        .as_ref()
+        .map(|asset| {
+            json!({
+                "task_id": asset.task_id,
+                "provider": asset.provider,
+                "asset_object_id": asset.asset_object_id,
+                "asset_kind": asset.asset_kind,
+                "audio_src": asset.audio_src,
+                "prompt": asset.prompt,
+                "title": asset.title,
+                "updated_at": asset.updated_at,
+            })
+        })
+        .unwrap_or(Value::Null)
+}
+
 fn map_puzzle_creator_intent_response(
     intent: PuzzleCreatorIntentRecord,
 ) -> PuzzleCreatorIntentResponse {
@@ -2600,6 +2667,7 @@ fn parse_puzzle_level_records_from_module_json(
             level_name: level.level_name,
             picture_description: level.picture_description,
             picture_reference: level.picture_reference,
+            background_music: level.background_music.map(map_puzzle_audio_asset_domain_record),
             candidates: level
                 .candidates
                 .into_iter()
@@ -2767,6 +2835,7 @@ fn serialize_puzzle_levels_response(
                 "level_name": level.level_name,
                 "picture_description": level.picture_description,
                 "picture_reference": level.picture_reference,
+                "background_music": puzzle_audio_asset_response_module_json(&level.background_music),
                 "candidates": level
                     .candidates
                     .iter()
@@ -2815,6 +2884,7 @@ fn normalize_puzzle_levels_json_for_module(value: Option<&str>) -> Result<Option
                 "level_name": level.level_name,
                 "picture_description": level.picture_description,
                 "picture_reference": level.picture_reference,
+                "background_music": puzzle_audio_asset_response_module_json(&level.background_music),
                 "candidates": level
                     .candidates
                     .iter()
@@ -3806,6 +3876,8 @@ fn serialize_puzzle_level_records_for_module(
                 "level_id": level.level_id,
                 "level_name": level.level_name,
                 "picture_description": level.picture_description,
+                "picture_reference": level.picture_reference,
+                "background_music": puzzle_audio_asset_record_module_json(&level.background_music),
                 "candidates": level
                     .candidates
                     .iter()
@@ -4504,6 +4576,65 @@ mod tests {
         assert_eq!(draft.levels[0].level_name, "雨夜猫街");
     }
 
+    #[test]
+    fn puzzle_level_audio_asset_roundtrips_between_response_and_module_json() {
+        let level = PuzzleDraftLevelResponse {
+            level_id: "puzzle-level-1".to_string(),
+            level_name: "雨夜猫街".to_string(),
+            picture_description: "一只猫在雨夜灯牌下回头。".to_string(),
+            picture_reference: None,
+            background_music: Some(CreationAudioAsset {
+                task_id: "suno-task-1".to_string(),
+                provider: "vector-engine-suno".to_string(),
+                asset_object_id: Some("assetobj_1".to_string()),
+                asset_kind: Some("puzzle_background_music".to_string()),
+                audio_src: "/generated-puzzle-assets/audio.mp3".to_string(),
+                prompt: Some("轻快拼图音乐".to_string()),
+                title: Some("雨夜猫街背景音乐".to_string()),
+                updated_at: Some("2026-05-11T00:00:00Z".to_string()),
+            }),
+            candidates: vec![],
+            selected_candidate_id: None,
+            cover_image_src: None,
+            cover_asset_id: None,
+            generation_status: "ready".to_string(),
+        };
+        let request_context = RequestContext::new(
+            "test-request".to_string(),
+            "PUT /api/runtime/puzzle/works/test".to_string(),
+            Duration::ZERO,
+            false,
+        );
+
+        let levels_json = serialize_puzzle_levels_response(&request_context, &[level])
+            .expect("levels should serialize");
+        let payload: Value =
+            serde_json::from_str(&levels_json).expect("levels json should parse");
+        assert_eq!(
+            payload[0]["background_music"]["audio_src"],
+            Value::String("/generated-puzzle-assets/audio.mp3".to_string())
+        );
+        assert!(payload[0]["background_music"].get("audioSrc").is_none());
+
+        let records = parse_puzzle_level_records_from_module_json(&levels_json)
+            .expect("levels should map back into records");
+        let music = records[0]
+            .background_music
+            .as_ref()
+            .expect("background music should exist");
+        assert_eq!(music.audio_src, "/generated-puzzle-assets/audio.mp3");
+        assert_eq!(music.asset_kind.as_deref(), Some("puzzle_background_music"));
+
+        let response = map_puzzle_draft_level_response(records[0].clone());
+        assert_eq!(
+            response
+                .background_music
+                .as_ref()
+                .map(|asset| asset.audio_src.as_str()),
+            Some("/generated-puzzle-assets/audio.mp3")
+        );
+    }
+
     fn test_puzzle_anchor_pack_record() -> PuzzleAnchorPackRecord {
         let item = PuzzleAnchorItemRecord {
             key: "visualSubject".to_string(),
@@ -4542,6 +4673,7 @@ mod tests {
                 level_name: "猫画面".to_string(),
                 picture_description: "一只猫在雨夜灯牌下回头。".to_string(),
                 picture_reference: None,
+                background_music: None,
                 candidates: vec![],
                 selected_candidate_id: None,
                 cover_image_src: None,

server-rs/crates/module-puzzle/src/application.rs

@@ -186,6 +186,7 @@ pub fn compile_result_draft_from_seed(
         level_name: level_name.clone(),
         picture_description,
         picture_reference: None,
+        background_music: None,
         candidates: Vec::new(),
         selected_candidate_id: None,
         cover_image_src: None,
@@ -242,6 +243,7 @@ pub fn build_form_draft_from_parts(
         level_name: String::new(),
         picture_description: picture_description.clone().unwrap_or_default(),
         picture_reference: None,
+        background_music: None,
         candidates: Vec::new(),
         selected_candidate_id: None,
         cover_image_src: None,
@@ -347,6 +349,7 @@ pub fn normalize_puzzle_draft(mut draft: PuzzleResultDraft) -> PuzzleResultDraft
                 &draft.summary,
             ),
             picture_reference: None,
+            background_music: None,
             candidates: draft.candidates.clone(),
             selected_candidate_id: draft.selected_candidate_id.clone(),
             cover_image_src: draft.cover_image_src.clone(),
@@ -433,6 +436,7 @@ pub fn append_blank_puzzle_level(draft: &PuzzleResultDraft) -> PuzzleResultDraft
         ),
         picture_description,
         picture_reference: None,
+        background_music: None,
         candidates: Vec::new(),
         selected_candidate_id: None,
         cover_image_src: None,
@@ -2798,6 +2802,7 @@ mod tests {
                 level_name: format!("{profile_id} 关"),
                 picture_description: "summary".to_string(),
                 picture_reference: None,
+                background_music: None,
                 candidates: Vec::new(),
                 selected_candidate_id: None,
                 cover_image_src: Some("/cover.png".to_string()),
@@ -3012,6 +3017,7 @@ mod tests {
                 level_name: "第一关".to_string(),
                 picture_description: "第一关画面".to_string(),
                 picture_reference: None,
+                background_music: None,
                 candidates: Vec::new(),
                 selected_candidate_id: None,
                 cover_image_src: Some("/level-1.png".to_string()),
@@ -3023,6 +3029,7 @@ mod tests {
                 level_name: "第二关".to_string(),
                 picture_description: "第二关画面".to_string(),
                 picture_reference: None,
+                background_music: None,
                 candidates: Vec::new(),
                 selected_candidate_id: None,
                 cover_image_src: Some("/level-2.png".to_string()),

server-rs/crates/module-puzzle/src/creative_tools.rs

@@ -169,6 +169,7 @@ pub fn build_puzzle_draft_from_creative_fields(
                     .unwrap_or_else(|| format!("第{}关", index + 1)),
                 picture_description,
                 picture_reference: level.picture_reference.and_then(normalize_required_string),
+                background_music: None,
                 candidates: Vec::new(),
                 selected_candidate_id: None,
                 cover_image_src: None,

server-rs/crates/module-puzzle/src/domain.rs

@@ -131,6 +131,8 @@ pub struct PuzzleDraftLevel {
     pub picture_description: String,
     #[serde(default)]
     pub picture_reference: Option<String>,
+    #[serde(default)]
+    pub background_music: Option<PuzzleAudioAsset>,
     pub candidates: Vec<PuzzleGeneratedImageCandidate>,
     pub selected_candidate_id: Option<String>,
     pub cover_image_src: Option<String>,
@@ -138,6 +140,24 @@ pub struct PuzzleDraftLevel {
     pub generation_status: String,
 }
 
+#[cfg_attr(feature = "spacetime-types", derive(SpacetimeType))]
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PuzzleAudioAsset {
+    pub task_id: String,
+    pub provider: String,
+    #[serde(default)]
+    pub asset_object_id: Option<String>,
+    #[serde(default)]
+    pub asset_kind: Option<String>,
+    pub audio_src: String,
+    #[serde(default)]
+    pub prompt: Option<String>,
+    #[serde(default)]
+    pub title: Option<String>,
+    #[serde(default)]
+    pub updated_at: Option<String>,
+}
+
 #[cfg_attr(feature = "spacetime-types", derive(SpacetimeType))]
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
 pub struct PuzzleResultDraft {