feat: 完善敲木鱼玩法模板链路

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

@@ -16,14 +16,38 @@
 
 ---
 
-## 2026-05-22 敲木鱼图片创作采用双图 image2 链路
+## 2026-05-23 寓教于乐玩法入口收敛为马路街区式横向延展
 
-- 背景：敲木鱼自定义题材只生成中央敲击物时，运行态缺少与新主题匹配的竖屏背景；若直接让背景 prompt 自由发挥，又容易把敲击物或木槌画进背景里。
-- 决策：敲木鱼 `compile-draft` / `regenerate-hit-object` 图片链路固定为两步 image2 edits。第一步调用 VectorEngine `/v1/images/edits` + `gpt-image-2`，以默认木鱼图作为结构和画风参考，用户上传参考图只作为同次请求的新主题参考，结合用户题材关键词或参考图主题生成 `1:1` 透明底新敲击物并写回 `hitObjectAsset`；第二步以新敲击物图作为主题和画风参考，结合用户原始题材生成 `9:16` 背景环境图并写回 `backgroundAsset`。两步 prompt 使用 PRD 中固定隐藏关键词，不追加额外 negative prompt；背景图不得包含敲击物本体或木槌互动物品。
-- 影响范围：`api-server` 木鱼图片生成编排、`wooden_fish_work_profile.background_asset_json`、shared contracts、前端结果页 / 运行态背景展示、敲木鱼 PRD 和平台链路文档。
+- 背景：参考图和视频表明，寓教于乐板块的图形化入口更接近 Toca Life World 式的“中央马路串联主题小建筑群街区”，而不是乐园分区、环形岛屿或世界球体结构。
+- 决策：后续寓教于乐入口概念图统一采用“横屏 16:9、中央灰蓝色马路贯穿、建筑群沿路两侧聚集、左右边缘持续出画可接下一屏”的结构；马路必须带车道线、斑马线、路口和小汽车，区域通过水果店、画笔工坊、运动馆、音乐剧场、树屋温室等主题小建筑群暗示，不再使用乐园式分区组织。
+- 影响范围：寓教于乐入口概念图、image2 prompt 生成脚本、设计文档、后续横向世界地图探索稿。
+- 验证方式：新生成概念图必须满足“马路是主脊线、建筑群成街区聚合、左右边缘可延展、无品牌乐园元素”四项约束；若图面再跑回环形乐园或漂浮岛，需要重新收敛 prompt。
+- 关联文档：`docs/design/【前端体验】寓教于乐Toca式横向世界地图入口概念图-2026-05-23.md`、`scripts/generate-edutainment-road-town-map-concepts.mjs`、`output/imagegen/edutainment-road-town-map-concepts-20260523/`。
+
+## 2026-05-22 敲木鱼图片创作采用三图 image2 链路
+
+- 背景：敲木鱼自定义题材只生成中央敲击物时，运行态缺少与新主题匹配的竖屏背景和主题化返回按钮；若直接让背景 prompt 自由发挥，又容易把敲击物或木槌画进背景里。
+- 决策：敲木鱼 `compile-draft` / `regenerate-hit-object` 图片链路固定为三步 image2 edits。第一步调用 VectorEngine `/v1/images/edits` + `gpt-image-2`，以默认木鱼图作为结构和画风参考，用户上传参考图只作为同次请求的新主题参考，结合用户题材关键词或参考图主题生成 `1:1` 绿色背景主体图；`api-server` 先对这张绿幕图执行去绿背景处理并写回 `hitObjectAsset`。第二步必须以第一步抠图完成后的透明敲击物图作为参考，结合用户原始题材生成 `9:16` 背景环境图并写回 `backgroundAsset`，避免背景图继承绿幕或纯绿色画布。第三步必须以去绿后的敲击物主体图和背景环境图为参考，生成 `1:1` 绿色背景返回按钮图，服务端去绿后写回 `backButtonAsset`。三步 prompt 使用 PRD 中固定隐藏关键词，不追加额外 negative prompt；返回按钮只允许参考图约束圆形底色和箭头配色，不允许继承复杂造型、花纹、浮雕边、异形外框或装饰图案；背景图不得包含敲击物本体或木槌互动物品，返回按钮图不得包含文字、数字、水印或额外 UI 面板。
+- 影响范围：`api-server` 木鱼图片生成编排、`wooden_fish_work_profile.background_asset_json`、`wooden_fish_work_profile.back_button_asset_json`、shared contracts、前端结果页 / 运行态背景与返回按钮展示、敲木鱼 PRD 和平台链路文档。
 - 验证方式：执行 `cargo test -p api-server wooden_fish --manifest-path server-rs/Cargo.toml`、`cargo test -p spacetime-client wooden_fish --manifest-path server-rs/Cargo.toml`、`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run typecheck`。
 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 2026-05-22 敲木鱼敲击物暂不做服务端抠图后处理
+
+- 背景：gpt-image-2 偶尔会把木鱼图直接回成带黑底或其它实底背景的 PNG，但服务端抠图后处理在玉米等主题上误伤过主体像素。
+- 决策：敲木鱼 hit object 落盘前暂不做服务端抠图后处理，当前只通过 prompt 强约束真实透明 alpha PNG、透明底、禁止黑底 / 白底 / 棋盘格 / 实底背景。后续若重启后处理，必须先有可验证的保守策略，只能清理画布边缘连通背景，不能抠掉主体内部深色结构或主题细节。
+- 影响范围：`server-rs/crates/api-server/src/wooden_fish.rs`、敲木鱼 PRD、平台链路文档、后续同类 image2 单图资产落盘策略。
+- 验证方式：`cargo test -p api-server wooden_fish --manifest-path server-rs/Cargo.toml`，并在试玩阶段确认主体像素未被后处理误删。
+- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-22 敲木鱼背景中央禁主体要写成硬约束
+
+- 背景：苹果等主题在试玩时，背景图中央仍可能残留主题主体，说明“外围设计”这种软描述不够。
+- 决策：敲木鱼背景 prompt 必须显式要求中央主体预留区保持干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子、重复元素或主题主体碎片；主题元素只允许出现在外围氛围。
+- 影响范围：`server-rs/crates/api-server/src/wooden_fish.rs`、敲木鱼 PRD、平台链路文档、后续 image2 背景类玩法 prompt。
+- 验证方式：背景 prompt 单测应包含中央禁区硬约束，试玩图中央不再出现苹果或其它主题主体。
+- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 2026-05-21 外部 API 失败必须 OTLP 上报并落库
 
 - 背景：图片生成等外部供应商调用失败时，仅返回 502/504 或普通日志无法支持后续按 provider、阶段和重试属性聚合排障。
@@ -165,12 +189,12 @@
 - 验证方式：执行敲木鱼契约 / module / facade / runtime model / platform entry 定向测试、`npm run typecheck`、`npm run check:encoding`、`npm run check:spacetime-schema`、`cargo check -p api-server --manifest-path server-rs\Cargo.toml`，本地 smoke 使用 mock 短信配置后检查 `/healthz`。
 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
 
-## 2026-05-21 敲木鱼敲击音效复用通用 Vidu 音效链路
+## 2026-05-21 敲木鱼敲击音效当前只接受上传、录音或默认音
 
-- 背景：敲木鱼创作需要通过“敲击音效”描述生成真实短音频，不能继续由 `spacetime-client` 合成 `/generated-wooden-fish-assets/...` 假路径；同时拼图和抓大鹅音频生成入口仍需保持关闭。
-- 决策：通用 `/api/creation/audio/sound-effect` 提交 Vidu 音效任务；`/api/creation/audio/sound-effect/{task_id}/asset` 只对木鱼 `hit_sound` 目标开放，完成查询、下载、OSS 私有对象、`asset_object` 和 entity binding 写入。木鱼 `compile-draft` / `generate-hit-sound` 在 `api-server` 内复用同一 helper 生成并注入 `hitSoundAsset`，`spacetime-client` 缺少真实 `hitSoundAsset` 时拒绝编译。拼图和抓大鹅相关目标继续返回 `410 Gone`。
+- 背景：敲木鱼按关键词生成的敲击音效约束不够稳定；当前创作阶段需要先关闭提示词生成音效，避免生成结果不符合敲击体验。
+- 决策：通用 `/api/creation/audio/sound-effect` 对木鱼 `hit_sound` 目标也返回 `410 Gone`。木鱼工作台只支持上传或麦克风录制音频；若用户未提供音频，`api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。`hitSoundPrompt` 只作为历史兼容字段保留，当前创作流程不使用；`spacetime-client` 不得合成 `/generated-wooden-fish-assets/...` 假路径。
 - 影响范围：`server-rs/crates/api-server/src/vector_engine_audio_generation.rs`、`server-rs/crates/api-server/src/wooden_fish.rs`、`server-rs/crates/spacetime-client/src/wooden_fish.rs`、`shared-contracts` / `packages/shared` 的 `creationAudio` 契约、敲木鱼 PRD 与平台链路文档。
-- 验证方式：执行 `cargo test -p shared-contracts creation_audio --manifest-path server-rs\Cargo.toml`、`cargo test -p spacetime-client wooden_fish --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server wooden_fish --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server disabled_creation_audio_targets_return_gone_except_wooden_fish_sound_effects --manifest-path server-rs\Cargo.toml`、`npm run typecheck`、`npm run check:encoding`，本地 smoke 检查 `/healthz`；真实生成需同时配置 VectorEngine 与 OSS AccessKey。
+- 验证方式：执行 `cargo test -p shared-contracts creation_audio --manifest-path server-rs\Cargo.toml`、`cargo test -p spacetime-client wooden_fish --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server wooden_fish --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server disabled_creation_audio_targets_return_gone_including_wooden_fish_sound_effects --manifest-path server-rs\Cargo.toml`、`npm run typecheck`、`npm run check:encoding`，本地 smoke 检查 `/healthz`。
 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
 
 ## 2026-05-21 敲木鱼默认敲击物使用内置透明 PNG
@@ -181,6 +205,14 @@
 - 验证方式：默认 `compile-draft` 返回的 `hitObjectAsset.generationProvider` 应为 `bundled-default` 且 `imageSrc=/wooden-fish/default-hit-object.png`；自定义关键词或参考图仍走 image2；前端静态资源可通过 Vite 直接访问。
 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 2026-05-23 敲木鱼创作请求需要独立长超时
+
+- 背景：敲木鱼 `createSession` 和 `executeAction` 都会串行等待多段 image2 生成、去绿背景处理和 OSS 落库；共享创作工厂默认 15 秒对这条链路太短，容易让前端先报 `请求超时：15000ms`。
+- 决策：敲木鱼 client 单独配置长等待窗口，同时覆盖会话创建和执行动作请求，不修改共享工厂默认值，避免影响其它轻量创作玩法。
+- 影响范围：`src/services/wooden-fish/woodenFishClient.ts`、`src/services/creation-agent/creationAgentClientFactory.ts`、敲木鱼工作台与生成页请求行为。
+- 验证方式：`npm test -- src/services/wooden-fish/woodenFishClient.test.ts`，并在本地敲木鱼创作时不再提前触发 15 秒超时。
+- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 2026-05-21 RPG publish_world 设定文本以后端草稿真相派生
 
 - 背景：RPG 结果页发布动作只保证提交 `{ action: 'publish_world' }`；旧 agent 会话可能没有 `seed_text`，但 `draft_profile_json` 已经通过 `publish_gate` 并可发布。