1

2026-05-14 01:11:58 +08:00
parent b13870f71b
commit 5a55180b78
61 changed files with 5050 additions and 1057 deletions
--- a/.hermes/shared-memory/pitfalls.md
+++ b/.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` 变量，或者层级低于登录遮罩导致不可见。