1

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

@@ -16,10 +16,42 @@
 
 ---
 
+## 2026-05-14 抓大鹅草稿计划同时产出作品信息和默认封面
+
+- 背景：抓大鹅草稿生成原本重点在物品名称和素材生成，作品名称、作品描述、作品标签和封面容易在结果页保持空值或只靠用户手动补齐。
+- 决策：`match3d_compile_draft` 的作品生成计划必须同时返回 `gameName`、`summary`、`tags`、背景音乐、背景提示词和物品计划。后端先把 `gameName` 与 `summary` 写入 `match3d_work_profile`，再基于题材、作品名和描述自动调用作品标签生成器；标签生成失败时才合并计划 tags 与本地兜底。若作品尚无用户封面，草稿生成完成后默认使用生成的抓大鹅容器 UI 图作为 `coverImageSrc`，容器图缺失时才回退到纯背景图。
+- 影响范围：`server-rs/crates/api-server/src/match3d.rs`、Match3D works shared contracts、`Match3DResultView` 手动标签生成、抓大鹅草稿素材生成流水线文档。
+- 验证方式：执行 `cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml`、`cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml`、`npm run test -- src\components\match3d-result\Match3DResultView.test.tsx`、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
+## 2026-05-13 抓大鹅草稿生成固定 10 光点且入口不生成点击音效
+
+- 背景：抓大鹅入口草稿生成需要有明确、稳定的光点成本，且入口不再把点击音效作为草稿生成选项暴露，避免一次草稿生成混入额外音效任务与扣费。
+- 决策：`match3d_compile_draft` 草稿生成固定预扣 `10` 光点，失败时按钱包流水退款；创作页按钮展示 `消耗10光点`，不展示 `生成音效` Toggle，入口表单和重试均固定传 `generateClickSound = false`。物品点击音效只保留在结果页 `素材配置 > 物品` 详情面板手动生成，并按独立音效任务扣费。
+- 影响范围：`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-creation/Match3DAgentWorkspace.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、抓大鹅 PRD、F1 入口文档、素材生成流水线文档和音频 Tab 文档。
+- 验证方式：执行 `npm run test -- src\components\match3d-creation\Match3DAgentWorkspace.interaction.test.tsx`、`npm run typecheck`、`cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml`、`cargo check -p api-server --manifest-path server-rs\Cargo.toml`、`npm run check:encoding`。
+
+## 2026-05-13 抓大鹅 5x5 物品素材固定绿幕生成并本地转透明
+
+- 背景：抓大鹅 2D 五视角素材如果继续让上游自由生成白底、灰底、纹理底或透明感背景，切割后的物品图会带底色块，运行态叠加到中心容器时观感不稳定。
+- 决策：抓大鹅物品素材 sheet 的 VectorEngine prompt 固定要求每格使用统一纯绿色绿幕背景；`api-server` 在按 5x5 切割前先对整张素材图执行绿幕 alpha 处理，再做格内前景边界校准和 PNG 上传。物品本体不得使用与绿幕相同的纯绿色，天然绿色物品需要用描边和不同绿相区分。
+- 影响范围：`server-rs/crates/api-server/src/match3d.rs`、抓大鹅素材生成 prompt、5x5 切图、OSS 视角图上传和 Match3D 素材生成技术文档。
+- 验证方式：`cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml` 覆盖 prompt 中的绿幕约束、绿幕转透明和主体保留；执行 `npm run check:encoding`。
+- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
+## 2026-05-13 拼图和抓大鹅 UI 生图拆分为纯背景与运行态默认 UI
+
+- 背景：拼图和抓大鹅此前的 UI 背景生成容易把拼图槽、锅状竞技区或其它 UI 元素烘进背景图，导致运行态默认 UI、真实物品和生成图层重复。
+- 决策：拼图只生成 `9:16` 纯题材背景图，不携带拼图槽、棋盘框、按钮、HUD、文字或物品，拼图槽继续使用运行态默认样式。抓大鹅生成 `9:16` 纯背景图和一张独立 `1:1` 中心容器 UI 图；纯背景不得包含锅/圆盘/托盘/物品槽/HUD/文字/物品，容器图单独贴合题材设定并覆盖运行态中心容器，底部备选栏继续使用默认 UI。
+- 影响范围：拼图 UI 背景 prompt、抓大鹅 `backgroundAsset` JSON、Match3D shared contracts、运行态背景/容器渲染、生成进度工作量和对应 PRD/技术文档。
+- 验证方式：检查 VectorEngine 请求 prompt 不要求背景图生成锅或槽位；运行态有 `containerImageSrc/containerImageObjectKey` 时使用容器图，否则默认容器兜底；执行拼图/抓大鹅定向测试、`npm run typecheck` 和 `npm run check:encoding`。
+- 关联文档：`docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`、`docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md`。
+
 ## 2026-05-12 抓大鹅入口素材风格改为 2D 常见素材风格
 
 - 背景：抓大鹅草稿素材生成已经收敛为多视角 2D 图片素材，但入口页和旧参考图仍沿用黏土、低多边形、塑料、木雕、体素、金属等偏 3D 素材语言，容易让后续生成链路和用户预期继续漂移。
-- 决策：抓大鹅创作入口 `2D素材风格` 固定为 `扁平图标 / 赛璐璐卡通 / 像素复古 / 手绘水彩 / 贴纸描边 / 厚涂图标 / 自定义`；默认风格为 `flat-icon`。入口参考图统一由 `npm run assets:match3d-style-references -- --live` 调用 VectorEngine `gpt-image-2-all` 生成，输出到 `public/match3d-style-references/`。旧 3D 风格参考图不再保留为入口资产。
+- 决策：抓大鹅创作入口 `2D素材风格` 固定为 `扁平图标 / 赛璐璐卡通 / 像素复古 / 手绘水彩 / 贴纸描边 / 厚涂图标 / 自定义`；默认风格为 `flat-icon`。入口参考图统一由 `npm run assets:match3d-style-references -- --live` 调用 VectorEngine `gpt-image-2-all` 生成，输出到 `public/match3d-style-references/`。2026-05-13 起，入口参考图固定只展示 `1` 个完整独立物品，不能展示 `5` 个物品样张或多物品散点图。旧 3D 风格参考图不再保留为入口资产。
+- 2026-05-13 补充：`像素复古` 不能只写“复古像素”或“有限色板”；前端、参考图脚本和后端素材图 prompt 必须要求约 `64x64` 低分辨率像素块、整数倍放大、硬边方块像素、`12-24` 色有限色板，并禁止抗锯齿、柔焦、平滑渐变、真实 3D 渲染、PBR 材质和摄影光照。后端收到 `assetStyleId = pixel-retro` 或 `assetStyleLabel = 像素复古` 时必须兜底补齐这些约束。
 - 影响范围：`Match3DAgentWorkspace`、抓大鹅入口交互测试、Match3D PRD、素材生成流水线技术文档、F1 入口文档和 `public/match3d-style-references/` 静态资产。
 - 验证方式：执行 `npm run test -- src\components\match3d-creation\Match3DAgentWorkspace.interaction.test.tsx`、`cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml`、`npm run typecheck`、`npm run check:encoding`，并人工抽查 `.tmp/match3d-style-preview.png`。
 - 关联文档：`docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`、`docs/technical/MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md`。

.hermes/shared-memory/pitfalls.md

@@ -25,9 +25,9 @@
 ## generated 音频路径进运行态前要先换签
 
 - 现象：草稿页 audio 控件能播放背景音乐，但拼图或抓大鹅运行态开局后背景音乐不响，Network 可能出现裸 `/generated-*-assets/...mp3` 私有路径 403。
-- 原因：生成音乐转存到 OSS 私有对象后，`audioSrc` 是 generated legacy path；浏览器 `<audio>` 不能像公开静态资源一样直接请求裸路径。
-- 处理：运行态隐藏 `<audio>` 设置 `src` 前，先通过 `useResolvedAssetReadUrl` 或 `resolveAssetReadUrl` 换签；播放失败只静默兜底，不阻断局内交互。拼图读取 `currentLevel.backgroundMusic.audioSrc`，抓大鹅读取 `generatedItemAssets[].backgroundMusic.audioSrc`。
-- 验证：运行态开局后 `<audio loop>` 的 `src` 为签名 URL 或公开 URL；`npm run typecheck` 不报契约字段缺失，后端 run response 带 `backgroundMusic`。
+- 原因：生成音乐转存到 OSS 私有对象后，`audioSrc` 是 generated legacy path；浏览器 `<audio>` 不能像公开静态资源一样直接请求裸路径。另一个常见误判是浏览器拒绝自动播放，资源已经进入运行态但开局第一次 `audio.play()` 被拦截。
+- 处理：结果页试听控件和运行态隐藏 `<audio>` 设置 `src` 前，都先通过 `useResolvedAssetReadUrl` 或 `resolveAssetReadUrl` 换签；签名未就绪时不要回退请求裸 generated 路径。运行态自动播放失败只静默兜底，但玩家首次按下拼图块或点击抓大鹅物品时要重试同一个背景音乐播放函数。拼图读取 `currentLevel.backgroundMusic.audioSrc`，抓大鹅读取 `generatedItemAssets[].backgroundMusic.audioSrc`。
+- 验证：结果页试听和运行态 `<audio loop>` 的 `src` 为签名 URL 或公开 URL；拼图/抓大鹅运行态首次局内交互后会再次尝试播放背景音乐；`npm run typecheck` 不报契约字段缺失，后端 run response 带 `backgroundMusic`。
 - 关联：`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md`。
 
 ## 中文乱码与编码风险
@@ -51,6 +51,14 @@
 - 验证：执行 `cargo test -p module-auth password --manifest-path server-rs/Cargo.toml` 与 `cargo test -p api-server password --manifest-path server-rs/Cargo.toml`；手测时重设密码后旧密码应失败，新密码应成功，重启后仍应保持。
 - 关联：`server-rs/crates/api-server/src/password_management.rs`、`server-rs/crates/api-server/src/state.rs`、`docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md`。
 
+## 抓大鹅生成页只显示服务暂不可用先查 reason 和外部服务配置
+
+- 现象：点击生成抓大鹅草稿后，页面只提示“服务暂不可用”，或者本地 `npm run api-server` 看似启动但生成接口不可用。
+- 原因：配置缺失类错误通常在后端 `error.details.reason` 中给出具体缺项，前端如果只读 `details.message` 会吞掉原因；本地只配置 `ALIYUN_OSS_BUCKET` / `ALIYUN_OSS_ENDPOINT` 时，旧逻辑还会在启动期构造空 AccessKey 的 OSS 客户端并失败。抓大鹅新链路仍是 2D 生图切割，不需要也不应回退 Rodin/GLB。
+- 处理：前端 API 错误展示读取 `details.message` 后继续读取 `details.reason`；`api-server` 只有在 OSS 四件套齐全时初始化 OSS 客户端，部分缺失只记 warning 并让具体 generated 上传/换签接口返回 `OSS 未完成环境变量配置`。抓大鹅素材、封面和背景生成在调用 VectorEngine 前先预检 OSS，并通过 `details.missingEnv` 列出缺项；真实生成需补齐 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和完整 `ALIYUN_OSS_*` 四件套。抓大鹅 `5*5` 素材图提示词还必须要求相邻物体主体至少保留 `1/4` 单格宽度空白间距，避免切割后相邻格内容污染。
+- 验证：`npm run test -- src/services/apiClient.test.ts` 覆盖 `details.reason`；`cargo test -p api-server state --manifest-path server-rs/Cargo.toml` 覆盖半配置 OSS 不阻断启动；`npm run api-server` 后按实际 `GENARRATIVE_API_PORT` 请求 `/healthz`，不要默认打 `3100`。
+- 关联：`packages/shared/src/http.ts`、`server-rs/crates/api-server/src/state.rs`、`docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md`、`docs/technical/AUTH_SNAPSHOT_AND_MATCH3D_LOCAL_DEV_FIX_2026-05-01.md`。
+
 ## `.hermes` 只放共享内容，不放个人 Hermes 配置
 
 - 现象：团队成员误把个人 Hermes 配置、会话或密钥复制进仓库。
@@ -124,6 +132,30 @@
 - 验证：后端单测应覆盖 `images/edits` 路由、`b64_json` 响应解码和参考图强提示；真实联调先看日志里是否命中 `拼图 VectorEngine 图片编辑 HTTP 返回`。
 - 关联：`server-rs/crates/api-server/src/puzzle.rs`、`src/services/puzzleReferenceImage.ts`、`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`。
 
+## 拼图 edits 报 error sending request 先看网络分类
+
+- 现象：拼图有参考图时返回 `拼图图片生成失败：创建拼图 VectorEngine 图片编辑任务失败：error sending request for url (https://api.vectorengine.ai/v1/images/edits)`，后端没有 `拼图 VectorEngine 图片编辑 HTTP 返回` 日志。
+- 原因：这是 `reqwest` 在 `send()` 阶段失败，尚未收到 VectorEngine HTTP 响应；常见原因是服务器网络 / DNS / 防火墙 / 代理问题，或上游网关中断 multipart 连接。
+- 处理：查看错误响应 `details.reason/source/connect/body/timeout/endpoint` 和 `拼图 VectorEngine 请求发送失败` 日志。拼图图片客户端已强制 HTTP/1.1，降低 multipart HTTP/2 兼容风险；若 `connect=true` 先查网络出口，若 `body=true` 先查参考图大小和 multipart 发送。
+- 验证：`curl -i -X POST https://api.vectorengine.ai/v1/images/edits -H "Authorization: Bearer invalid" -F "model=gpt-image-2-all" -F "prompt=test" -F "n=1" -F "size=1024x1024"` 至少应返回 HTTP `401`，说明域名、TLS 和路径可达；执行 `cargo test -p api-server puzzle_vector_engine --manifest-path server-rs/Cargo.toml`。
+- 关联：`server-rs/crates/api-server/src/puzzle.rs`、`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`、`docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md`。
+
+## 拼图自动试玩缺 UI 背景先查本地运行态字段继承
+
+- 现象：拼图草稿生成完成后，草稿数据里已有首关 `uiBackgroundImageSrc`，结果页素材配置也能看到背景图，但自动试玩或结果页“试玩”进入局内仍只显示封面模糊背景，甚至看不到 UI 背景。
+- 原因：生成完成后的自动试玩走前端 `startLocalPuzzleRun(...)` 本地运行态兜底，不经过后端 `start_puzzle_run`；如果本地 run 只把 `coverImageSrc` 带入 `currentLevel`，就会丢掉 `levels[].uiBackgroundImageSrc` 和 `levels[].backgroundMusic`。
+- 处理：`startLocalPuzzleRun` 与本地下一关 handoff 都要从关卡 `levels[]` 复制 `uiBackgroundImageSrc`、`backgroundMusic` 到 `currentLevel`；`PuzzleRuntimeShell` 继续读取 `currentLevel.uiBackgroundImageSrc` 渲染全屏背景。
+- 验证：`npm run test -- src/services/puzzle-runtime/puzzleLocalRuntime.test.ts src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`。
+- 关联：`src/services/puzzle-runtime/puzzleLocalRuntime.ts`、`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md`。
+
+## 拼图草稿生成 180 秒后 502/504 先查 VectorEngine 超时与前端重试
+
+- 现象：点击“生成拼图游戏草稿”后，`POST /api/runtime/puzzle/agent/sessions/{sessionId}/actions` 等待约 180 秒返回 `502 Bad Gateway` 或 `504 Gateway Timeout`；钱包流水里同一 session 可能出现连续两组 `puzzle_initial_image` 扣费后退款。
+- 原因：首图生成走 VectorEngine `gpt-image-2-all`，默认 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=180000`；若上游在该窗口内未返回，后端退款并返回超时错误。旧前端 action 写请求会对 502/503/504 自动重试一次，导致同一次点击重复触发生图与扣退费。
+- 处理：拼图/创作 Agent 的 `executeAction` 默认不做前端自动重试；后端将 VectorEngine / 图片请求超时映射为 `504 Gateway Timeout`，`error.details.provider=vector-engine` 且 `timeout=true`。真实排障按日志同一 `session_id` 查 `拼图 VectorEngine 图片生成 HTTP 返回` 是否缺失，以及钱包流水扣费到退款的时间差是否接近 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`。
+- 验证：运行 `npm run test -- src/services/creation-agent/creationAgentClientFactory.test.ts src/services/apiClient.test.ts`、`cargo test -p api-server puzzle_vector_engine --manifest-path server-rs/Cargo.toml`，真实联调重启 `npm run api-server` 后检查 `/healthz`。
+- 关联：`src/services/creation-agent/creationAgentClientFactory.ts`、`server-rs/crates/api-server/src/puzzle.rs`、`docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md`。
+
 ## 旧后端路线文档造成判断漂移
 
 - 现象：开发时参考到 Express、Node、PostgreSQL 或 Go 方向旧文档，导致接口、数据真相或部署路径与当前主线不一致。
@@ -228,6 +260,13 @@
 - 验证：本地加入临时测试后，`HYPER3D_API_KEY` 应能被 `.env.secrets.local` 覆盖，且 shell 变量仍然最高优先级。
 - 关联：`scripts/api-server-dev.mjs`、`server-rs/crates/api-server/src/hyper3d_generation.rs`、`docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md`。
 
+## OSS 密钥键名不要把字母 O 写成数字 0
+
+- 现象：`.env.secrets.local` 看起来已经配置 OSS AccessKey Secret，但拼图或抓大鹅生成仍返回 `OSS 未完成环境变量配置`。
+- 原因：后端只读取 `ALIYUN_OSS_ACCESS_KEY_SECRET`。如果写成 `ALIYUN_0SS_ACCESS_KEY_SECRET`，中间是数字 `0`，配置合并检查会显示正确键缺失，`api-server` 不会初始化 OSS 客户端。另一个常见原因是外层 shell / IDE 预置了空的 `ALIYUN_OSS_*`，旧启动脚本会把空值当作最高优先级，导致 `.env.local` 或 `.env.secrets.local` 的真实值被跳过。
+- 处理：只改键名为 `ALIYUN_OSS_ACCESS_KEY_SECRET`，保留原值；不要在日志、文档或对话里输出密钥内容。本地启动脚本应只保护非空外层环境变量，空字符串或全空白值不得遮蔽本地 env 文件。
+- 验证：运行 `npm run check:api-server-env`，确认 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY`、`ALIYUN_OSS_BUCKET`、`ALIYUN_OSS_ENDPOINT`、`ALIYUN_OSS_ACCESS_KEY_ID`、`ALIYUN_OSS_ACCESS_KEY_SECRET` 都是 `present`，再重启 `npm run api-server` 或 `npm run dev`。
+
 ## 拼图图片生成 98% 后报 OSS V4 签名时间格式化失败
 
 - 现象：拼图创作表单生成进度卡在 98%，`POST /api/runtime/puzzle/agent/sessions/{sessionId}/actions` 返回 `502 Bad Gateway`，前端提示 `拼图图片生成失败：OSS V4 签名时间格式化失败`。
@@ -482,7 +521,7 @@
 
 - 现象：修改抓大鹅素材时容易沿用旧 Rodin/GLB 方案，导致新草稿生成耗时变长、进度停在模型阶段，或运行态等待不存在的 GLB。
 - 原因：仓库里保留了 Hyper3D 通用代理和历史模型字段，旧文档也曾要求草稿阶段同步生成 GLB。当前产品口径已经改为 2D 多视角素材。
-- 处理：新 `match3d_compile_draft` 与批量新增只生成 2D 图片：每个物品 5 个视角，单张 1K 素材图固定 5x5 切割，一行对应一个物品，超过 5 个物品自动分批并行生图。`generatedItemAssets[].status` 使用 `image_ready`，发布校验看 `imageViews[]` 或首图引用。`generated-models` 仅用于历史外部模型链接转存，不能作为新生产链路。
+- 处理：新 `match3d_compile_draft` 与批量新增只生成 2D 图片：每个物品 5 个视角，单张 1K 素材图固定 5x5，最多承载 5 个物品，一行对应一个物品，不足 5 个物品也补齐到完整 5 行；超过 5 个物品自动分批并行生图。素材图 prompt 固定要求纯绿色绿幕背景，切割前先把绿幕处理为透明 alpha，再做格内内容前景边界校准并带留白，避免固定内缩切掉贴近格线的主体。`generatedItemAssets[].status` 使用 `image_ready`，发布校验看 `imageViews[]` 或首图引用。`generated-models` 仅用于历史外部模型链接转存，不能作为新生产链路。
 - 验证：`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`npm run test -- src\services\miniGameDraftGenerationProgress.test.ts src\components\match3d-result\Match3DResultView.test.tsx src\components\match3d-runtime\Match3DRuntimeShell.test.tsx`。
 - 关联：`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
 
@@ -506,10 +545,18 @@
 
 - 现象：结果页能看到生成的物品图片，但点击试玩或从推荐 / 公开作品进入正式抓大鹅时，局内仍显示默认积木素材。
 - 原因：结果页本地 `assetDrafts` 和作品 profile 的 `generatedItemAssets` 可能不同步；推荐流内嵌运行态若只读卡片摘要，卡片缺素材时会把已持久化 profile 素材丢掉；点击试玩时 React state 异步更新也可能让运行态第一帧读取旧 `match3dProfile`。
-- 处理：删除、批量新增、音效生成或封面引用物品素材后，都把当前 `generatedItemAssets` 写回作品 profile；`Match3DResultView` 合并同 `itemId` 的 draft/profile 素材，用 profile 已有 `imageViews[]` 或首图引用补齐旧 draft；点击试玩前把试玩可用物品种类通过 `itemTypeCountOverride` 降到已生成 2D 素材数量；推荐流内嵌运行态启动前若卡片摘要没有生成素材，补读 `getMatch3DWorkDetail(profileId)` 并把详情资产传给 `Match3DRuntimeShell`。`PlatformEntryFlowShellImpl` 需要维护 `match3dRuntimeProfile`，在 `startMatch3DRunFromProfile` 创建 run 后立即锁定本次完整 profile，runtime 渲染时优先按 `run.profileId` 使用这份 profile，而不是等待普通 `match3dProfile` state 下一轮刷新。
+- 处理：删除、批量新增、音效生成或封面引用物品素材后，都把当前 `generatedItemAssets` 写回作品 profile；`Match3DResultView` 合并同 `itemId` 的 draft/profile 素材，用 profile 已有 `imageViews[]`、首图引用、`backgroundMusic` 或 `backgroundAsset` 补齐旧 draft；点击试玩前把试玩可用物品种类通过 `itemTypeCountOverride` 降到已生成 2D 素材数量；推荐流内嵌运行态启动前若卡片摘要没有物品图片素材，补读 `getMatch3DWorkDetail(profileId)` 并把详情资产传给 `Match3DRuntimeShell`。`PlatformEntryFlowShellImpl` 需要维护 `match3dRuntimeProfile`，在 `startMatch3DRunFromProfile` 创建 run 后立即锁定本次完整 profile，runtime 渲染时优先按 `run.profileId` 使用这份 profile，而不是等待普通 `match3dProfile` state 下一轮刷新。同 profile 下已有 `generatedItemAssets` 时不能因为图片完整性判断失败就覆盖为空数组。判断是否需要补读详情时只看 `imageViews[]` 或 `imageSrc/imageObjectKey`；背景、音乐、容器 UI 是附属运行态资产，不能单独证明物品素材已完整。
 - 验证：执行 `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[].imageViews/imageSrc/imageObjectKey`。
 - 关联：`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`。
 
+## 抓大鹅结果页音频试听也要先换签
+
+- 现象：抓大鹅草稿生成完成后，背景音乐已写在 `generatedItemAssets[0].backgroundMusic.audioSrc`，但 `素材配置 > 背景音乐` 或物品详情音效 `<audio>` 不能播放，Network 可能请求裸 `/generated-match3d-assets/...mp3` 并返回 403。
+- 原因：结果页试听控件和运行态一样运行在浏览器里，不能直接读取 generated 私有对象；只在运行态换签会造成“运行态可能有声，结果页不能预览”的割裂。
+- 处理：结果页音频控件统一通过 `useResolvedAssetReadUrl` / `/api/assets/read-url` 取得签名 URL 后再传给 `<audio>`；换签失败时只显示“音频已绑定”，不要回退请求裸 generated path。
+- 验证：`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx` 覆盖背景音乐和点击音效试听使用签名 URL。
+- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/services/assetReadUrlService.ts`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
 ## 法律文档弹窗通过 portal 挂载时要显式带平台主题
 
 - 现象：登录弹窗内点击协议链接打开法律文档时，弹窗可能继承不到 `platform-theme--light/dark` 变量，或者层级低于登录遮罩导致不可见。