feat: refine wooden fish runtime generation

2026-05-22 03:49:35 +08:00
parent d81cc49549
commit 5f1128540e
30 changed files with 804 additions and 126 deletions
--- a/docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md
+++ b/docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md
@@ -74,7 +74,14 @@ WF-*
  - 写回字段：`hitObjectAsset`
  - 是否允许历史图：允许
  - 是否允许 AI 重绘：允许；上传图只作为 image2 参考，最终运行态只消费 image2 生成图
- 系列素材槽位：无；首版只有单图敲击物，不生成图集
+  - `slotId=background`
+  - `slotType=background-image`
+  - `slotName=背景环境图`
+  - 提示词来源：第一步生成的敲击物图案与用户原始题材关键词 / 参考图主题
+  - 写回字段：`backgroundAsset`
+  - 是否允许历史图：不单独选择；由敲击物图案生成链路派生
+  - 是否允许 AI 重绘：允许；随敲击物图案一起重生成
+- 系列素材槽位：无；首版只有敲击物图案与背景环境图两个单图资产，不生成图集
 - 音频资产槽位：
  - `slotId=hit-sound`
  - `slotType=hit-sound-audio`
@@ -135,13 +142,39 @@ WF-*

 ## 6. 生成规则

-### 6.1 敲击物图案
+### 6.1 敲击物图案与背景环境图

-默认模板在用户未自定义关键词且未上传参考图时，`compile-draft` 使用内置透明 PNG `/wooden-fish/default-hit-object.png` 写回 `hitObjectAsset`，`generationProvider="bundled-default"`。这张图来自 image2 对原始参考图的卡通风格化重绘，固定为模板默认资源，避免默认关键词在每次生成时改变造型。
+默认模板在用户未自定义关键词且未上传参考图时，`compile-draft` 使用内置透明 PNG `/wooden-fish/default-hit-object.png` 写回 `hitObjectAsset`，`generationProvider="bundled-default"`。这张图来自 image2 对原始参考图的卡通风格化重绘，固定为模板默认资源，避免默认关键词在每次生成时改变造型。即使使用内置默认敲击物，首版仍需要生成 `backgroundAsset`，背景环境图使用默认敲击物作为主题和画风参考。

-用户输入自定义关键词、上传参考图，或在结果页主动重生成敲击物时，`compile-draft` 与 `regenerate-hit-object` 必须为敲击物图案生成 image2 单图资产，并由 `api-server` 注入写回 `hitObjectAsset`。前端 action 请求不得自带 `hitObjectAsset` 短路生成。如果用户上传参考图，后端只能把该图作为 image2 参考图或编辑输入；运行态不得直接使用上传图。
+用户输入自定义关键词、上传参考图，或在结果页主动重生成敲击物时，`compile-draft` 与 `regenerate-hit-object` 必须先为敲击物图案生成 image2 单图资产，再基于新敲击物图案生成背景环境图，并由 `api-server` 注入写回 `hitObjectAsset` 与 `backgroundAsset`。前端 action 请求不得自带 `hitObjectAsset` 或 `backgroundAsset` 短路生成。如果用户上传参考图，后端只能把该图作为 image2 参考图或主题参考；运行态不得直接使用上传图。

-落库链路固定为：`api-server` 调用 VectorEngine `gpt-image-2-all` -> 服务端上传 OSS 私有对象 -> `confirm_asset_object` 登记资产对象 -> `bind_asset_object_to_entity` 绑定到 `entityKind='wooden_fish_work'`、`slot='hit_object'`、`assetKind='wooden_fish_hit_object'` -> 把 `legacyPublicPath` 写入 `hitObjectAsset.imageSrc`。不得只拼 `/generated-wooden-fish-assets/...` 占位路径；前端会对 generated legacy path 走 `/api/assets/read-url` 换签，OSS 中没有真实对象时图片无法显示。
+敲击物图案生成流程固定为：
+
+1. 调用 VectorEngine `/v1/images/edits`，模型固定为 `gpt-image-2`；
+2. multipart 参考图固定包含默认木鱼图 `/wooden-fish/default-hit-object.png`，作为基础结构和画风参考；
+3. 若用户上传参考图，该图只作为新主题参考追加到同一次 image2 edits 请求，不直接进入运行态；
+4. 尺寸固定 `1:1`，透明底；
+5. 提示词严格使用：
+
+```text
+生成敲木鱼新样式，要求结构，画风与参考图保持高度一致，新样式颜色搭配使用新主题对应的颜色。
+新主题为：（用户提供参考图或用户输入关键词）
+```
+
+背景环境图生成流程固定为：
+
+1. 调用 VectorEngine `/v1/images/edits`，模型固定为 `gpt-image-2`；
+2. multipart 参考图固定为第一步新生成的敲击物图案；默认未生成新敲击物时使用内置默认敲击物图案；
+3. 尺寸固定竖屏 `9:16`；
+4. 背景环境图只适配新敲击物主题和画风，背景中不得包含新敲击物本体，也不得增加木槌互动物品；
+5. 提示词严格使用：
+
+```text
+生成敲木鱼背景，要求主题，画风与参考图保持高度一致，背景元素和颜色搭配与主题对应，木鱼预设在屏幕中央位置，木鱼主体周围元素保持干净，背景氛围围绕外围设计，背景环境图中不包含新木鱼物品，背景氛围中不增加木槌互动物品。
+主题为：（用户提供参考图或用户输入关键词）
+```
+
+落库链路固定为：`api-server` 调用 VectorEngine `/v1/images/edits` -> 服务端上传 OSS 私有对象 -> `confirm_asset_object` 登记资产对象 -> `bind_asset_object_to_entity` 绑定到 `entityKind='wooden_fish_work'`。敲击物绑定 `slot='hit_object'`、`assetKind='wooden_fish_hit_object'`，背景绑定 `slot='background'`、`assetKind='wooden_fish_background'`。写回时把 `legacyPublicPath` 分别写入 `hitObjectAsset.imageSrc` 与 `backgroundAsset.imageSrc`。不得只拼 `/generated-wooden-fish-assets/...` 占位路径；前端会对 generated legacy path 走 `/api/assets/read-url` 换签，OSS 中没有真实对象时图片无法显示。

 默认图案要求：

@@ -166,7 +199,7 @@ WF-*

 ### 6.3 封面

-首版封面使用 `hitObjectAsset.imageSrc` 作为 `coverImageSrc`。不单独新增第三次图片生成。
+首版封面使用 `hitObjectAsset.imageSrc` 作为 `coverImageSrc`。背景环境图不作为封面图，不单独新增第三次图片生成。

 ## 7. 契约草案

@@ -183,9 +216,10 @@ WF-*
 9. `hitSoundPrompt`；
 10. `floatingWords[]`；
 11. `hitObjectAsset`；
-12. `hitSoundAsset`；
-13. `coverImageSrc`；
-14. `generationStatus`。
+12. `backgroundAsset`；
+13. `hitSoundAsset`；
+14. `coverImageSrc`；
+15. `generationStatus`。

 `WoodenFishImageAsset` 至少包含：

@@ -260,7 +294,7 @@ finish
 新增表：

 1. `wooden_fish_agent_session`；
-2. `wooden_fish_work_profile`；
+2. `wooden_fish_work_profile`，其中 `background_asset_json` 保存背景环境图资产快照；
 3. `wooden_fish_runtime_run`；
 4. `wooden_fish_event`。

@@ -276,13 +310,14 @@ finish
 结果页必须展示：

 1. 作品标题和简介；
-2. 敲击物图案；
-3. 敲击音效试听；
-4. 祝福词配置；
-5. 标签；
-6. 试玩；
-7. 发布；
-8. 返回编辑。
+2. 竖屏背景环境图预览；
+3. 敲击物图案；
+4. 敲击音效试听；
+5. 祝福词配置；
+6. 标签；
+7. 试玩；
+8. 发布；
+9. 返回编辑。

 结果页必须支持：

@@ -333,16 +368,17 @@ finish

 1. 创作入口能看到 `敲木鱼` 模板；
 2. 工作台可以填写敲击物描述、上传参考图、配置音效和祝福词；
-3. 提交后生成 image2 敲击物图案；
-4. 上传图不会直接进入运行态；
-5. 用户上传或录制音效时跳过音效生成并持久化该资产；
-6. 结果页能看到图案、试听音效、编辑祝福词并试玩；
-7. 运行态功能区点击不触发敲击；
-8. 非功能区点击会计数、播放音效、播放敲击动画并飘字；
-9. 顶部计数器只在词条首次出现时创建；
-10. 连点不丢计数；
-11. `checkpoint` 和 `finish` 只保存单次 run 摘要；
-12. 作品可以发布、进入公开列表和公开详情；
-13. `WF-*` 公开作品号能进入分享和运行态；
-14. `npm run check:encoding` 通过；
-15. schema 变更后 `npm run check:spacetime-schema` 通过。
+3. 提交后按默认木鱼参考图生成 image2 敲击物图案；
+4. 提交后按新敲击物图案参考图生成 9:16 背景环境图；
+5. 上传图不会直接进入运行态；
+6. 用户上传或录制音效时跳过音效生成并持久化该资产；
+7. 结果页能看到背景、图案、试听音效、编辑祝福词并试玩；
+8. 运行态功能区点击不触发敲击；
+9. 非功能区点击会计数、播放音效、播放敲击动画并飘字；
+10. 顶部计数器只在词条首次出现时创建；
+11. 连点不丢计数；
+12. `checkpoint` 和 `finish` 只保存单次 run 摘要；
+13. 作品可以发布、进入公开列表和公开详情；
+14. `WF-*` 公开作品号能进入分享和运行态；
+15. `npm run check:encoding` 通过；
+16. schema 变更后 `npm run check:spacetime-schema` 通过。
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -160,6 +160,7 @@ npm run check:server-rs-ddd
 - Match3D 物品 sheet：VectorEngine Gemini `gemini-3-pro-image-preview` 原生 `generateContent`；图集 prompt、切图、透明化和切片持久化走 `generated_asset_sheets` 通用模块，Match3D 只补题材 / 风格 / 五视角设定和字段映射。
 - Match3D 封面和 9:16 纯背景：VectorEngine `/v1/images/generations`。
 - Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。
+- 敲木鱼敲击物和背景环境图：VectorEngine `/v1/images/edits`，模型固定 `gpt-image-2`。敲击物支持 multipart 多参考图，第一张固定为后端内嵌默认木鱼图，用户上传图只作为新主题参考；背景环境图只使用新敲击物图作为参考。
 - Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；新 Match3D 草稿和批量新增不再生成 GLB。
 - 音频：视觉小说专用音频路由保留；拼图和抓大鹅生成入口暂时关闭，通用 `/api/creation/audio/*` 对相关目标返回 `410 Gone`；敲木鱼 `hit_sound` 目标例外开放，复用 VectorEngine Vidu 音效生成、OSS 私有对象、`asset_object` 和 entity binding 链路，目标字段固定为 `entityKind='wooden_fish_work'`、`slot='hit_sound'`、`assetKind='wooden_fish_hit_sound'`、`storagePrefix='wooden_fish_assets'`。
 - OSS：私有 generated legacy path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。
@@ -421,6 +422,7 @@ npm run check:server-rs-ddd

 - Rust 结构体：`WoodenFishWorkProfileRow`
 - 源码：`server-rs/crates/spacetime-module/src/wooden_fish/tables.rs`
+- 说明：敲木鱼作品 profile 真相，包含敲击物图案、背景环境图、敲击音效、飘字配置、发布状态和公开计数；`background_asset_json` 是后加入字段，保存 image2 生成的 9:16 背景环境图资产快照，旧迁移数据按 `None` 兼容。

 ### SpacetimeDB view：`wooden_fish_gallery_card_view`

--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -169,6 +169,7 @@ UI 相关修改要重点验证：
 4. 身份问题先查 `spacetime login show`、`spacetime server list` 和目标库权限，不通过切回旧 Node / PostgreSQL 绕过。
 5. 旧库迁移或 private 表数据保留走 `migration.rs` 的 JSON 导入导出和分片导入思路。
 6. Jenkins 数据库导入 / 导出流水线会先加载 `scripts/jenkins-prepare-toolchain-env.sh`，显式补齐 Jenkins 用户的 Node、Cargo、SpacetimeDB 工具链目录；如果目标机器安装路径不同，用 `GENARRATIVE_JENKINS_TOOL_PATHS` 传入额外 `bin` 目录。
+7. 本地 `npm run dev` / `npm run dev:api-server` 若没有显式 `GENARRATIVE_SPACETIME_TOKEN`，会在 SpacetimeDB 就绪后调用 `/v1/identity` 创建当前进程专用 Web API identity token，并只注入本次 `api-server` 环境，不写回 `.env.local`。启动日志只打印 identity 前缀，禁止打印 token 明文；若仍出现 `subscribe ... 401 Unauthorized`，先确认是否绕过了项目 dev 脚本或是否连接到非本次启动的 SpacetimeDB server。

 ## 生产运维

--- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
+++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
@@ -99,10 +99,12 @@

 创作输入固定为：

-1. `敲什么`：单图资产槽位。默认模板使用内置透明 PNG `/wooden-fish/default-hit-object.png` 作为 `bundled-default` 敲击物资产，避免默认关键词被重新语义化改形；用户输入自定义关键词或上传参考图时，后端必须使用 image2 生成最终敲击物图案，上传图只作为参考，不直接进入运行态。自定义 `compile-draft` / `regenerate-hit-object` 必须完成 image2 -> OSS 私有对象 -> asset object 登记和绑定后，再由 `api-server` 注入真实 `hitObjectAsset.imageSrc`，不能只写 `/generated-wooden-fish-assets/...` 占位路径，也不能接受前端请求自带的 `hitObjectAsset` 短路生成。
+1. `敲什么`：敲击物单图资产槽位。默认模板使用内置透明 PNG `/wooden-fish/default-hit-object.png` 作为 `bundled-default` 敲击物资产，避免默认关键词被重新语义化改形；用户输入自定义关键词或上传参考图时，后端必须以默认木鱼图作为基础结构和画风参考，使用 image2 生成最终敲击物图案，上传图只作为新主题参考，不直接进入运行态。自定义 `compile-draft` / `regenerate-hit-object` 必须完成 image2 -> OSS 私有对象 -> asset object 登记和绑定后，再由 `api-server` 注入真实 `hitObjectAsset.imageSrc`，不能只写 `/generated-wooden-fish-assets/...` 占位路径，也不能接受前端请求自带的 `hitObjectAsset` 短路生成。
 2. `敲击音效`：音频资产槽位，支持描述生成、上传和麦克风录制，统一写回 `hitSoundAsset`。描述生成复用通用 `/api/creation/audio/sound-effect` 的 VectorEngine Vidu 音效生成、下载、OSS 私有对象、asset object 登记和 entity binding 链路；木鱼目标固定为 `entityKind='wooden_fish_work'`、`slot='hit_sound'`、`assetKind='wooden_fish_hit_sound'`、`storagePrefix='wooden_fish_assets'`，不得再返回 `410 Gone`，也不得由 `spacetime-client` 合成假音频路径。
 3. `功德有什么`：最多 8 条飘字，默认 `幸运、健康、财富、姻缘、幸福、事业、成功、功德`；创作态只保存词条名，运行态飘字展示时再追加 `+1`。

+图片生成链路固定为双图 image2 流程：第一步用默认木鱼图作为结构和画风参考，按用户题材关键词或参考图主题生成 `1:1` 透明底新敲击物；第二步用新敲击物作为主题和画风参考生成 `9:16` 背景环境图，背景图只适配主题和画风，不能包含新敲击物本体，也不能增加木槌互动物品。两个资产分别写回 `hitObjectAsset` 与 `backgroundAsset`，并绑定到 `wooden_fish_work` 的 `hit_object` / `background` 槽位。运行态和结果页消费 `backgroundAsset` 做竖屏背景，中央再叠加 `hitObjectAsset`。
+
 运行态规则真相以后端 run 摘要为准，前端只做点击低延迟表现、敲击动画、音频播放和飘字渲染。每次非功能区点击在当前 run 内累计 `totalTapCount` 和 `wordCounters`；计数不进入账号长期账本，不做排行榜。顶部计数器仅在词条首次出现时创建，后续同词条继续累加。

 平台首页推荐、精选、最新、公开详情、搜索、已玩作品和公开试玩统一按 `sourceType='wooden-fish'` 与 `WF-*` 公开作品号识别敲木鱼作品；公开列表应走 `wooden_fish_gallery_card_view` 订阅缓存，公开详情或运行态启动时卡片摘要不足则补读完整 work profile。