feat: 完善敲木鱼玩法模板链路
This commit is contained in:
48
docs/design/【前端体验】寓教于乐Toca式横向世界地图入口概念图-2026-05-23.md
Normal file
48
docs/design/【前端体验】寓教于乐Toca式横向世界地图入口概念图-2026-05-23.md
Normal file
@@ -0,0 +1,48 @@
|
||||
# 寓教于乐 马路街区式横向世界入口概念图
|
||||
|
||||
更新时间：`2026-05-23`
|
||||
|
||||
## 背景
|
||||
|
||||
寓教于乐板块需要继续探索图形化玩法入口。前一轮“乐园地图 / 世界地图”方向已被证明不够贴近参考图，本轮进一步收敛为“中央马路串联主题小建筑群街区”的结构，让每一屏都像一个可横向滑动的儿童小镇街区。
|
||||
|
||||
## 参考结论
|
||||
|
||||
从参考图和视频里提炼出的关键结构是：
|
||||
|
||||
1. 每一屏都是一组主题小建筑群，不是稀疏乐园点位。
|
||||
2. 中央马路是主路径，汽车沿路通过，边缘继续延伸到下一屏。
|
||||
3. 建筑群贴着道路两侧聚合，形成清晰街区，而不是围绕中央广场或环形路径展开。
|
||||
4. 左右两边都要有明确“可继续探索”的出画感，方便后续做横向滑动世界。
|
||||
|
||||
## 目标
|
||||
|
||||
- 视觉上像可滑动的儿童街区地图。
|
||||
- 每一屏都能作为独立探索单元，并且能自然接到前后相邻屏。
|
||||
- 保持寓教于乐既有的卡通绘本风，不借用真实品牌乐园或现成 IP。
|
||||
- 适合后续叠加入口按钮、焦点框和中文标题。
|
||||
|
||||
## 本次概念方向
|
||||
|
||||
1. 识物认知主街
|
||||
2. 绘画创作工坊街
|
||||
3. 运动音乐街区
|
||||
4. 自然探索实验大道
|
||||
|
||||
## 推荐方向
|
||||
|
||||
优先推荐 `绘画创作工坊街` 与 `运动音乐街区`。这两条在当前批次里最接近“中央马路 + 两侧主题小建筑群 + 左右可延展”的参考结构。
|
||||
|
||||
## 生图脚本
|
||||
|
||||
- 生成脚本：`scripts/generate-edutainment-road-town-map-concepts.mjs`
|
||||
- 输出目录：`output/imagegen/edutainment-road-town-map-concepts-20260523/`
|
||||
- 风格参考：`public/child-motion-demo/picture-book-grass-stage.png`
|
||||
|
||||
## 说明
|
||||
|
||||
本次产物是设计概念稿，不直接进入正式资源目录。后续如果继续收敛，可以以 `城市公园脊` 为母版，向左、向右补相邻屏幕的区域内容。
|
||||
|
||||
## 当前结论
|
||||
|
||||
乐园分区结构可以抛弃，后续所有概念都优先按“马路街区式一屏一屏延展”的结构继续迭代。
|
||||
@@ -14,7 +14,7 @@
|
||||
创作入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态 -> 公开详情/分享
|
||||
```
|
||||
|
||||
首版默认屏幕中央展示内置卡通透明敲击物图案 `/wooden-fish/default-hit-object.png`。玩家点击运行态非功能区时触发一次敲击：播放敲击音效、敲击物图案执行被敲击动画，并在敲击物上方随机飘出一条祝福词。顶部计数器只在某条祝福词首次出现时创建，之后该词每次出现都累加。计数仅属于当前单次 run，不进入账号长期账本。
|
||||
首版默认屏幕中央展示内置卡通透明敲击物图案 `/wooden-fish/default-hit-object.png`。玩家点击运行态非功能区时触发一次敲击：播放敲击音效、敲击物图案执行被敲击动画，并在敲击物上方随机飘出一条祝福词。顶部只展示总数记录；子项计数收纳到总数卡片下方的折叠面板中，总数卡片点击后展开各子项计数，词条在面板中预置显示，未出现时初始值为 0，点击面板外收起。计数仅属于当前单次 run，不进入账号长期账本。
|
||||
|
||||
## 2. 模板定位
|
||||
|
||||
@@ -86,9 +86,9 @@ WF-*
|
||||
- `slotId=hit-sound`
|
||||
- `slotType=hit-sound-audio`
|
||||
- `slotName=敲击音效`
|
||||
- 来源：`hitSoundPrompt` 生成，或上传/麦克风录制音频
|
||||
- 来源：用户上传/麦克风录制音频，或使用默认木鱼音
|
||||
- 写回字段：`hitSoundAsset`
|
||||
- 描述生成能力：复用通用创作音频接口 `/api/creation/audio/sound-effect` 的 VectorEngine Vidu 音效生成与 OSS 持久化链路
|
||||
- 默认兜底：`/wooden-fish/default-hit-sound.mp3`
|
||||
- API 命名空间：
|
||||
- `/api/creation/wooden-fish/...`
|
||||
- `/api/runtime/wooden-fish/...`
|
||||
@@ -122,8 +122,8 @@ WF-*
|
||||
1. `workDescription`：作品简介；
|
||||
2. `themeTags[]`：最多 6 个标签；
|
||||
3. `hitObjectReferenceImageSrc`：上传或历史图引用，只能作为 image2 参考，不可直接进入运行态；
|
||||
4. `hitSoundPrompt`：生成音效描述；
|
||||
5. `hitSoundAsset`：用户上传或录音产生的音频资产。
|
||||
4. `hitSoundPrompt`：历史兼容字段，当前创作流程不再使用；
|
||||
5. `hitSoundAsset`：用户上传、录音或默认音频资产。
|
||||
|
||||
默认祝福词：
|
||||
|
||||
@@ -142,39 +142,54 @@ WF-*
|
||||
|
||||
## 6. 生成规则
|
||||
|
||||
### 6.1 敲击物图案与背景环境图
|
||||
### 6.1 敲击物图案、背景环境图与返回按钮图
|
||||
|
||||
默认模板在用户未自定义关键词且未上传参考图时，`compile-draft` 使用内置透明 PNG `/wooden-fish/default-hit-object.png` 写回 `hitObjectAsset`，`generationProvider="bundled-default"`。这张图来自 image2 对原始参考图的卡通风格化重绘，固定为模板默认资源，避免默认关键词在每次生成时改变造型。即使使用内置默认敲击物，首版仍需要生成 `backgroundAsset`，背景环境图使用默认敲击物作为主题和画风参考。
|
||||
默认模板在用户未自定义关键词且未上传参考图时，`compile-draft` 使用内置透明 PNG `/wooden-fish/default-hit-object.png` 写回 `hitObjectAsset`，`generationProvider="bundled-default"`。这张图来自 image2 对原始参考图的卡通风格化重绘，固定为模板默认资源，避免默认关键词在每次生成时改变造型。即使使用内置默认敲击物，首版仍需要生成 `backgroundAsset` 与 `backButtonAsset`，背景环境图和主题返回按钮图都使用默认敲击物作为主题和画风参考。
|
||||
|
||||
用户输入自定义关键词、上传参考图，或在结果页主动重生成敲击物时，`compile-draft` 与 `regenerate-hit-object` 必须先为敲击物图案生成 image2 单图资产，再基于新敲击物图案生成背景环境图，并由 `api-server` 注入写回 `hitObjectAsset` 与 `backgroundAsset`。前端 action 请求不得自带 `hitObjectAsset` 或 `backgroundAsset` 短路生成。如果用户上传参考图，后端只能把该图作为 image2 参考图或主题参考；运行态不得直接使用上传图。
|
||||
用户输入自定义关键词、上传参考图，或在结果页主动重生成敲击物时，`compile-draft` 与 `regenerate-hit-object` 必须先为敲击物图案生成 image2 单图资产，再基于新敲击物图案生成背景环境图，最后基于去绿后的敲击物主体和背景环境图生成主题返回按钮图，并由 `api-server` 注入写回 `hitObjectAsset`、`backgroundAsset` 与 `backButtonAsset`。前端 action 请求不得自带 `hitObjectAsset`、`backgroundAsset` 或 `backButtonAsset` 短路生成。如果用户上传参考图，后端只能把该图作为 image2 参考图或主题参考；运行态不得直接使用上传图。
|
||||
|
||||
敲击物图案生成流程固定为：
|
||||
|
||||
1. 调用 VectorEngine `/v1/images/edits`，模型固定为 `gpt-image-2`；
|
||||
2. multipart 参考图固定包含默认木鱼图 `/wooden-fish/default-hit-object.png`，作为基础结构和画风参考；
|
||||
3. 若用户上传参考图，该图只作为新主题参考追加到同一次 image2 edits 请求，不直接进入运行态；
|
||||
4. 尺寸固定 `1:1`，透明底；
|
||||
4. 尺寸固定 `1:1`，必须输出绿色背景主体图（纯绿色绿幕），背景为单一纯绿色 `#00FF00`，并显式禁止黑底、白底、棋盘格、纸板底或任何其它实底背景；
|
||||
5. 提示词严格使用：
|
||||
|
||||
```text
|
||||
生成敲木鱼新样式，要求结构，画风与参考图保持高度一致，新样式颜色搭配使用新主题对应的颜色。
|
||||
生成敲木鱼新样式，要求结构，画风与参考图保持高度一致，新样式颜色搭配使用新主题对应的颜色。尺寸1:1，先输出绿色背景主体图（纯绿色绿幕），背景必须是单一纯绿色 #00FF00 且平整无纹理、无渐变、无阴影、无道具，主体完整居中，主体边缘必须干净，不要直接输出透明底。随后由服务端对绿色背景主体图做抠图去除绿色背景。最终结果只保留单个敲击物图案，禁止黑底、白底、棋盘格、纸板底或任何实底背景；主体本身不要使用与绿幕接近的纯绿色，若新主题天然包含绿色，请改用偏深、偏黄或偏蓝的绿色并与绿幕清晰区分。
|
||||
新主题为：（用户提供参考图或用户输入关键词）
|
||||
```
|
||||
|
||||
敲击物图案落盘前，`api-server` 必须只对第一步生成的纯绿色绿幕背景执行去绿处理，把绿色背景转成真实透明 alpha PNG；不得对黑底、白底或其它未知实底执行泛抠图，避免误伤玉米等主体像素。去绿处理必须保留主体内部深色结构和主题细节。
|
||||
|
||||
背景环境图生成流程固定为：
|
||||
|
||||
1. 调用 VectorEngine `/v1/images/edits`，模型固定为 `gpt-image-2`；
|
||||
2. multipart 参考图固定为第一步新生成的敲击物图案；默认未生成新敲击物时使用内置默认敲击物图案；
|
||||
2. multipart 参考图固定为第一步敲击物图案抠图完成后的透明图；默认未生成新敲击物时使用内置默认敲击物图案的透明兜底图；
|
||||
3. 尺寸固定竖屏 `9:16`；
|
||||
4. 背景环境图只适配新敲击物主题和画风，背景中不得包含新敲击物本体，也不得增加木槌互动物品；
|
||||
4. 背景环境图只适配新敲击物主题和画风，背景中不得包含新敲击物本体，也不得增加木槌互动物品；中央主体预留区必须保持干净，画面中央 40% 区域禁止出现主题主体、主体局部特写、主体轮廓影子、重复元素或主题主体的局部碎片；
|
||||
5. 提示词严格使用：
|
||||
|
||||
```text
|
||||
生成敲木鱼背景，要求主题，画风与参考图保持高度一致，背景元素和颜色搭配与主题对应，木鱼预设在屏幕中央位置，木鱼主体周围元素保持干净，背景氛围围绕外围设计，背景环境图中不包含新木鱼物品，背景氛围中不增加木槌互动物品。
|
||||
生成敲木鱼背景，要求主题，画风与参考图保持高度一致，背景元素和颜色搭配与主题对应，木鱼预设在屏幕中央位置，木鱼主体周围元素保持干净，背景氛围围绕外围设计，背景环境图中不包含新木鱼物品，背景氛围中不增加木槌互动物品。尺寸竖屏9:16。参考图必须是第一步敲击物抠图完成后的透明图，不继承任何绿色底色、绿幕底色或纯绿色画布，并要求最终输出完整不透明的背景环境图。中央主体预留区必须保持干净，画面中央 40% 区域禁止出现主题主体、主体局部特写、主体轮廓影子、重复元素或主题主体的局部碎片；主题元素只允许出现在外围氛围，不得把主题物品画在画面中央，也不要把主题物品作为背景中心装饰。
|
||||
主题为：（用户提供参考图或用户输入关键词）
|
||||
```
|
||||
|
||||
落库链路固定为：`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 中没有真实对象时图片无法显示。
|
||||
返回按钮图生成流程固定为：
|
||||
|
||||
1. 调用 VectorEngine `/v1/images/edits`，模型固定为 `gpt-image-2`；
|
||||
2. multipart 参考图固定包含第一步去除绿色背景后的敲击物主体图，以及第二步生成的背景环境图；
|
||||
3. 尺寸固定 `1:1`，必须输出绿色背景主体图（纯绿色绿幕），后端落库前执行同一套去绿背景处理；
|
||||
4. 按主题、画风、材质和配色生成左上角返回按钮图，但参考图只用于约束圆形底色和中央左箭头的颜色搭配，不得借鉴复杂造型、花纹、浮雕边、异形外框或装饰图案；按钮必须始终是标准圆形，中央只保留单个清晰左箭头或返回箭头，不得包含文字、数字、水印、额外 UI 面板、木槌或敲击道具；
|
||||
5. 提示词严格使用：
|
||||
|
||||
```text
|
||||
生成敲木鱼左上角返回按钮图。要求以参考图-去除绿色背景后的敲击物主体和背景环境图为主题、画风、材质和配色参考，但参考图只用来约束圆形底色和中央左箭头的颜色搭配，不要继承复杂造型、花纹、浮雕边、异形外框或装饰图案。按钮必须始终是标准圆形，整体像单个圆形图标，圆心居中，圆形内部只保留一个清晰、简洁、居中的向左返回箭头，不要出现文字、数字、水印、按钮外标签、额外 UI 面板、木槌或敲击道具。尺寸1:1，输出绿色背景主体图（纯绿色绿幕），背景必须是单一纯绿色 #00FF00 且平整无纹理、无渐变、无阴影。按钮主体边缘干净，后续由服务端扣除绿色背景；按钮底色不要使用与绿幕接近的纯绿色，若主题天然包含绿色，请仅在圆形底色上使用偏深、偏黄或偏蓝的主题绿色，并用更高对比的箭头颜色区分。
|
||||
主题为：（用户提供参考图或用户输入关键词）
|
||||
```
|
||||
|
||||
落库链路固定为：`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'`，返回按钮绑定 `slot='back_button'`、`assetKind='wooden_fish_back_button'`。写回时把 `legacyPublicPath` 分别写入 `hitObjectAsset.imageSrc`、`backgroundAsset.imageSrc` 与 `backButtonAsset.imageSrc`。不得只拼 `/generated-wooden-fish-assets/...` 占位路径；前端会对 generated legacy path 走 `/api/assets/read-url` 换签，OSS 中没有真实对象时图片无法显示。
|
||||
|
||||
默认图案要求：
|
||||
|
||||
@@ -188,18 +203,18 @@ WF-*
|
||||
|
||||
音效统一写回 `hitSoundAsset`。
|
||||
|
||||
生成或写回规则：
|
||||
写回规则：
|
||||
|
||||
1. 若 payload 已包含上传/录音音频资产，`compile-draft` 跳过音效生成，直接持久化该资产；
|
||||
2. 若 payload 只包含 `hitSoundPrompt`，`api-server` 复用通用创作音频能力提交 VectorEngine Vidu `sound_effect` 任务，轮询生成结果，下载音频，写入 OSS 私有对象，登记 `asset_object`，并绑定到 `entityKind='wooden_fish_work'`、`slot='hit_sound'`、`assetKind='wooden_fish_hit_sound'`，最后注入 `hitSoundAsset`；
|
||||
3. 若两者都没有，后端生成默认“清脆短促木鱼敲击声”；
|
||||
2. 若 payload 已上传或录制音频，则直接写回 `hitSoundAsset`；
|
||||
3. 若两者都没有，后端写回默认木鱼音 `/wooden-fish/default-hit-sound.mp3`；
|
||||
4. 音效资产必须包含可播放地址、对象键、asset object id、来源和可选时长；
|
||||
5. 通用创作音频接口对 `wooden_fish` 的 `hit_sound` 目标不得返回 `410 Gone`，对应 `storagePrefix='wooden_fish_assets'`；
|
||||
6. `spacetime-client` 不得自行合成 `/generated-wooden-fish-assets/...` 音效占位路径，缺少真实 `hitSoundAsset` 时必须拒绝编译。
|
||||
5. 通用创作音频接口当前对 `wooden_fish` 的 `hit_sound` 目标返回 `410 Gone`，不得在创作流程中按提示词生成音效；
|
||||
6. `spacetime-client` 不得自行合成 `/generated-wooden-fish-assets/...` 音效占位路径；缺少真实 `hitSoundAsset` 时应使用默认木鱼音兜底展示与播放。
|
||||
|
||||
### 6.3 封面
|
||||
|
||||
首版封面使用 `hitObjectAsset.imageSrc` 作为 `coverImageSrc`。背景环境图不作为封面图，不单独新增第三次图片生成。
|
||||
首版封面使用 `hitObjectAsset.imageSrc` 作为 `coverImageSrc`。背景环境图与返回按钮图不作为封面图。
|
||||
|
||||
## 7. 契约草案
|
||||
|
||||
@@ -213,13 +228,14 @@ WF-*
|
||||
6. `themeTags[]`；
|
||||
7. `hitObjectPrompt`；
|
||||
8. `hitObjectReferenceImageSrc`；
|
||||
9. `hitSoundPrompt`；
|
||||
9. `hitSoundPrompt`，历史兼容字段，当前创作流程恒为 `null`；
|
||||
10. `floatingWords[]`；
|
||||
11. `hitObjectAsset`；
|
||||
12. `backgroundAsset`；
|
||||
13. `hitSoundAsset`；
|
||||
14. `coverImageSrc`；
|
||||
15. `generationStatus`。
|
||||
13. `backButtonAsset`；
|
||||
14. `hitSoundAsset`；
|
||||
15. `coverImageSrc`；
|
||||
16. `generationStatus`。
|
||||
|
||||
`WoodenFishImageAsset` 至少包含：
|
||||
|
||||
@@ -238,7 +254,7 @@ WF-*
|
||||
2. `audioSrc`；
|
||||
3. `audioObjectKey`；
|
||||
4. `assetObjectId`；
|
||||
5. `source = generated | uploaded | recorded | placeholder`；
|
||||
5. `source = uploaded | recorded | bundled-default`；
|
||||
6. `prompt`；
|
||||
7. `durationMs`。
|
||||
|
||||
@@ -277,7 +293,6 @@ GET /api/runtime/wooden-fish/gallery/{publicWorkCode}
|
||||
```text
|
||||
compile-draft
|
||||
regenerate-hit-object
|
||||
generate-hit-sound
|
||||
replace-hit-sound
|
||||
update-work-meta
|
||||
update-floating-words
|
||||
@@ -289,19 +304,21 @@ finish
|
||||
|
||||
`compile-draft` 是长耗时动作。前端进入生成页后应展示可恢复进度；如果请求失败，标记失败前必须复读 session，确认后端是否已经生成并写回草稿。
|
||||
|
||||
敲木鱼创作请求在前端必须使用长等待窗口，避免 `createSession` 或 `executeAction` 仍沿用共享创作工厂默认的 15 秒超时。因为 `compile-draft` 会串行等待敲击物、背景、返回按钮和 OSS 落库，木鱼 client 需要单独配置与整条 image2 链路匹配的超时。
|
||||
|
||||
## 9. SpacetimeDB 表和 view
|
||||
|
||||
新增表：
|
||||
|
||||
1. `wooden_fish_agent_session`；
|
||||
2. `wooden_fish_work_profile`，其中 `background_asset_json` 保存背景环境图资产快照；
|
||||
2. `wooden_fish_work_profile`，其中 `background_asset_json` 保存背景环境图资产快照，`back_button_asset_json` 保存主题返回按钮图资产快照；
|
||||
3. `wooden_fish_runtime_run`；
|
||||
4. `wooden_fish_event`。
|
||||
|
||||
新增 view：
|
||||
|
||||
1. `wooden_fish_gallery_card_view`：公开列表卡片投影，只暴露已发布作品；
|
||||
2. `wooden_fish_gallery_view`：公开详情兼容投影，包含图案、音效和祝福词配置。
|
||||
2. `wooden_fish_gallery_view`：公开详情兼容投影，包含图案、背景、返回按钮、音效和祝福词配置。
|
||||
|
||||
新增或调整表、procedure、view 后必须同步 `migration.rs`、后端表目录、生成 bindings，并执行 `npm run check:spacetime-schema`。
|
||||
|
||||
@@ -322,11 +339,11 @@ finish
|
||||
结果页必须支持：
|
||||
|
||||
1. 重生成敲击物图案；
|
||||
2. 生成、上传或替换敲击音效；
|
||||
2. 上传、录制或替换敲击音效；未提供时使用默认木鱼音；
|
||||
3. 修改标题、简介和标签；
|
||||
4. 修改祝福词，最多 8 条。
|
||||
|
||||
图案重生成和音效生成是独立局部生成态，不得把已有可查看结果重新变成不可打开的全局生成中。
|
||||
图案重生成是独立局部生成态，不得把已有可查看结果重新变成不可打开的全局生成中。音效替换只接受上传或录音资产，不触发提示词音效生成。
|
||||
|
||||
## 11. 运行态规则
|
||||
|
||||
@@ -334,7 +351,7 @@ finish
|
||||
|
||||
功能区：
|
||||
|
||||
1. 顶部计数器；
|
||||
1. 顶部总数记录卡和其下拉的子项计数器面板；
|
||||
2. 设置、暂停、返回、发布分享等按钮；
|
||||
3. 结果弹层和音频授权提示。
|
||||
|
||||
@@ -343,11 +360,13 @@ finish
|
||||
1. 点击非功能区才算一次敲击；
|
||||
2. 每次敲击立即本地累加 `totalTapCount`；
|
||||
3. 随机等概率从 `floatingWords[]` 中取一个词条；
|
||||
4. 若词条首次出现，顶部创建对应计数器；
|
||||
4. 子项计数面板中预置展示所有词条，未出现词条初始值为 0；
|
||||
5. 后续同词条出现时对应计数器 +1；
|
||||
6. 播放敲击音效；
|
||||
7. 敲击物图案执行压缩、回弹或轻微震动动画；
|
||||
8. 木鱼上方飘出“词条+1”并淡出。
|
||||
8. 木鱼上方飘出“词条+1”并淡出，飘字只显示文字本体，不加底板、胶囊背景或说明面板。
|
||||
|
||||
运行态左上角返回按钮必须优先使用 `backButtonAsset` 渲染主题化按钮图；缺失时才回退通用图标按钮。运行态不提供右上角重开按钮。
|
||||
|
||||
音频播放：
|
||||
|
||||
@@ -367,18 +386,20 @@ finish
|
||||
## 13. 验收
|
||||
|
||||
1. 创作入口能看到 `敲木鱼` 模板；
|
||||
2. 工作台可以填写敲击物描述、上传参考图、配置音效和祝福词；
|
||||
2. 工作台可以填写敲击物描述、上传参考图、上传或录制音效、配置祝福词；
|
||||
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` 通过。
|
||||
5. 提交后按去绿后的敲击物主体和背景环境图生成主题返回按钮图；
|
||||
6. 上传图不会直接进入运行态；
|
||||
7. 用户上传或录制音效时直接持久化该资产，未提供时使用默认木鱼音；
|
||||
8. 结果页能看到背景、图案、试听音效、编辑祝福词并试玩；
|
||||
9. 运行态功能区点击不触发敲击；
|
||||
10. 运行态左上角使用主题返回按钮图，右上角不出现重开按钮；
|
||||
11. 非功能区点击会计数、播放音效、播放敲击动画并飘出无底板大号文字；
|
||||
12. 顶部总数卡点击后展开子项计数器面板，面板内预置全部词条且未出现词条初始值为 0，面板外点击可收起；
|
||||
13. 连点不丢计数；
|
||||
14. `checkpoint` 和 `finish` 只保存单次 run 摘要；
|
||||
15. 作品可以发布、进入公开列表和公开详情；
|
||||
16. `WF-*` 公开作品号能进入分享和运行态；
|
||||
17. `npm run check:encoding` 通过；
|
||||
18. schema 变更后 `npm run check:spacetime-schema` 通过。
|
||||
|
||||
@@ -160,9 +160,9 @@ npm run check:server-rs-ddd
|
||||
- Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端固定从该 sheet 解析并持久化 20 个物品、每个 5 个形态；通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。
|
||||
- Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。
|
||||
- Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。
|
||||
- 敲木鱼敲击物和背景环境图：VectorEngine `/v1/images/edits`，模型固定 `gpt-image-2`。敲击物支持 multipart 多参考图，第一张固定为后端内嵌默认木鱼图，用户上传图只作为新主题参考；背景环境图只使用新敲击物图作为参考。
|
||||
- 敲木鱼敲击物和背景环境图：VectorEngine `/v1/images/edits`，模型固定 `gpt-image-2`。敲击物支持 multipart 多参考图，第一张固定为后端内嵌默认木鱼图，用户上传图只作为新主题参考；prompt 必须要求 `1:1` 真实透明 alpha PNG 并禁止黑底、白底、棋盘格和任何实底背景。当前敲击物上传 OSS 前不做服务端抠图后处理，避免误伤玉米等主体像素。背景环境图只使用第一步抠图完成后的透明敲击物图作为参考，prompt 必须要求中央主体预留区保持干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围，且必须显式声明不继承任何绿色底色、绿幕底色或纯绿色画布。
|
||||
- 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'`。
|
||||
- 音频：视觉小说专用音频路由保留；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。
|
||||
- OSS：私有 generated legacy path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。
|
||||
- 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。当前通用 VectorEngine `gpt-image-2-all` 图片生成 / 编辑适配器在 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段失败时记录 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`；metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount 和 imageModel。入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。
|
||||
|
||||
@@ -423,7 +423,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` 兼容。
|
||||
- 说明：敲木鱼作品 profile 真相，包含敲击物图案、背景环境图、主题返回按钮图、敲击音效、飘字配置、发布状态和公开计数；`background_asset_json` 保存 image2 生成的 9:16 背景环境图资产快照，`back_button_asset_json` 保存 image2 生成并去绿后的 1:1 返回按钮图资产快照，旧迁移数据按 `None` 兼容。
|
||||
|
||||
### SpacetimeDB view：`wooden_fish_gallery_card_view`
|
||||
|
||||
@@ -437,7 +437,7 @@ npm run check:server-rs-ddd
|
||||
- Rust view：`wooden_fish_gallery_view`
|
||||
- 返回类型：`Vec<WoodenFishGalleryViewRow>`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/wooden_fish.rs`
|
||||
- 说明：敲木鱼公开详情兼容投影，包含敲击物图案、敲击音效和飘字配置；公开列表主路径优先使用 `wooden_fish_gallery_card_view`。
|
||||
- 说明：敲木鱼公开详情兼容投影，包含敲击物图案、背景环境图、主题返回按钮图、敲击音效和飘字配置；公开列表主路径优先使用 `wooden_fish_gallery_card_view`。
|
||||
|
||||
### `match3d_agent_message`
|
||||
|
||||
|
||||
@@ -45,10 +45,20 @@ npm run dev:api-server
|
||||
|
||||
后端日志默认写入 `logs/api-server/`。后端 API smoke 使用 `npm run dev:api-server` 并检查 `/healthz`；不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
|
||||
|
||||
如果本地 `GET /api/creation-entry/config` 返回 `No such procedure`，通常是 `.env.local` 指向的 SpacetimeDB 库还没有发布当前 `spacetime-module`，或当前 CLI 身份无权发布该库。debug 构建的 `api-server` 会临时使用后端默认入口配置兜底，避免创作作品架整块消失；正式修复仍应切换到拥有目标库权限的 SpacetimeDB 身份后重新运行 `npm run dev` 完成发布，或用 gitignored 的 `spacetime.local.json` 指向可发布的本地库。
|
||||
如果本地 `GET /api/creation-entry/config` 返回 `No such procedure`，或 `api-server` 日志出现 `no such table: puzzle_gallery_card_view` / `no such table: wooden_fish_gallery_card_view` 这类公开 view 缺失，通常是 `.env.local` 指向的 SpacetimeDB 库还没有发布当前 `spacetime-module`，或当前 CLI 身份无权发布该库。debug 构建的 `api-server` 会临时使用后端默认入口配置兜底，避免创作作品架整块消失；正式修复仍应切换到拥有目标库权限的 SpacetimeDB 身份后重新运行 `npm run dev` 完成发布，或用 gitignored 的 `spacetime.local.json` 指向可发布的本地库。
|
||||
|
||||
本地排查 schema 漂移时，先用当前 dev server 显式查询目标库，例如：
|
||||
|
||||
```bash
|
||||
spacetime sql <database> "SELECT * FROM puzzle_gallery_card_view LIMIT 1" --server http://127.0.0.1:3101
|
||||
```
|
||||
|
||||
如果旧 `.env.local` 仍指向缺少当前 view 的库，例如 `xushi-p4wfr`，而当前可发布库已经包含这些 view，可在 gitignored 的 `spacetime.local.json` 写入 `{"database":"genarrative-dev-codex"}` 作为本机覆盖；写入时不要带 UTF-8 BOM，否则 `scripts/dev.mjs` 会忽略该文件。修改后重启 `api-server`，再检查 `/healthz` 和 `/api/runtime/puzzle/gallery`。
|
||||
|
||||
本地 `npm run dev:spacetime` 发布模块时必须显式忽略仓库根目录的 `spacetime.json`，由脚本固定追加 `--no-config` 并使用命令参数里传入的数据库名和 `--server http://127.0.0.1:3101`。否则 CLI 可能把发布目标改写到配置文件里的其他数据库，导致 `dev:spacetime` 启动后又因发布失败自动退出，浏览器随后会在 `ws://127.0.0.1:3101/v1/database/.../subscribe` 看到连接拒绝。
|
||||
|
||||
本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致。若版本错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value`，api-server 最终表现为敲木鱼等创作动作的 `SpacetimeDB procedure 调用超时`。排障时先运行 `spacetime --version`，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."`；需要切版本时执行 `spacetime version install <version> && spacetime version use <version>`，然后重新启动 `npm run dev:spacetime`。当前 `scripts/dev.mjs` 会在启动和复用本地 SpacetimeDB 前写入并校验 `dev-spacetime-tool-version`，避免把旧 standalone 继续带进新一轮创作。
|
||||
|
||||
本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查 RPG / 拼图 / 抓大鹅等 VectorEngine 生图链路时，确认 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。开局 CG 故事板、首图、背景和图集都属于长耗时图片请求；后端默认会把 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 下限收口到 `1000000`，旧进程仍可能沿用重启前的短超时。若开局 CG 故事板在 `send()` 阶段失败且日志显示 `SendRequest`，先看同一 request_id 的 `request_body_bytes`、`reference_data_url_bytes`、`sourceChain` 和 `rootSource`；当前开局 CG 会把角色图与首幕背景图压到单边 768 的 JPEG 后再作为 generations `image` 数组发送，`/v1/images/generations` 使用默认 HTTP 协商，只有 multipart `/v1/images/edits` 单独强制 HTTP/1.1。
|
||||
|
||||
查看本地 Rust / SpacetimeDB 日志：
|
||||
|
||||
@@ -133,12 +133,12 @@ RPG / 拼图等运行态存档选择入口统一在个人中心 `常用功能 >
|
||||
创作输入固定为：
|
||||
|
||||
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`。
|
||||
2. `敲击音效`：音频资产槽位，当前创作阶段只支持用户上传或麦克风录制；未提供音频时统一写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。提示词生成音效入口临时关闭，通用 `/api/creation/audio/sound-effect` 对木鱼 `hit_sound` 目标也返回 `410 Gone`；`hitSoundPrompt` 只作为历史兼容字段保留，不参与当前创作流程，也不得由 `spacetime-client` 合成假音频路径。
|
||||
3. `功德有什么`：最多 8 条飘字，默认 `幸运、健康、财富、姻缘、幸福、事业、成功、功德`；创作态只保存词条名，运行态飘字展示时再追加 `+1`。运行态顶部总数卡采用品牌化徽标样式，子项计数器预置展示在可展开面板中，未出现词条初始值为 0。
|
||||
|
||||
图片生成链路固定为双图 image2 流程：第一步用默认木鱼图作为结构和画风参考，按用户题材关键词或参考图主题生成 `1:1` 透明底新敲击物；第二步用新敲击物作为主题和画风参考生成 `9:16` 背景环境图，背景图只适配主题和画风，不能包含新敲击物本体，也不能增加木槌互动物品。两个资产分别写回 `hitObjectAsset` 与 `backgroundAsset`，并绑定到 `wooden_fish_work` 的 `hit_object` / `background` 槽位。运行态和结果页消费 `backgroundAsset` 做竖屏背景，中央再叠加 `hitObjectAsset`。
|
||||
图片生成链路固定为三图 image2 流程：第一步用默认木鱼图作为结构和画风参考，按用户题材关键词或参考图主题生成 `1:1` 绿色背景主体图（纯绿色绿幕），prompt 必须显式要求背景为单一纯绿色 `#00FF00` 且平整无纹理、无渐变、无阴影、无道具，主体完整居中，且禁止黑底、白底、棋盘格和任何实底背景；后端在落库前只对这张绿幕主体图执行去绿背景处理，不做泛抠图，避免误伤玉米等主体像素。第二步必须使用第一步抠图完成后的透明图作为参考图，再用新敲击物作为主题和画风参考生成 `9:16` 背景环境图，背景图只适配主题和画风，不能包含新敲击物本体，也不能增加木槌互动物品；画面中央主体预留区必须干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围。第三步必须使用去绿后的敲击物主体图和背景环境图作为参考图生成 `1:1` 返回按钮图，返回按钮必须始终是标准圆形，中央只保留单个左箭头，参考图只约束圆形底色和箭头配色，不得延伸到复杂造型和花纹；按钮不得出现文字、数字、水印、额外 UI 面板或木槌物品。三个资产分别写回 `hitObjectAsset`、`backgroundAsset` 与 `backButtonAsset`，并绑定到 `wooden_fish_work` 的 `hit_object` / `background` / `back_button` 槽位。运行态和结果页消费 `backgroundAsset` 做竖屏背景，中央再叠加 `hitObjectAsset`，左上角返回按钮消费 `backButtonAsset`。
|
||||
|
||||
运行态规则真相以后端 run 摘要为准，前端只做点击低延迟表现、敲击动画、音频播放和飘字渲染。每次非功能区点击在当前 run 内累计 `totalTapCount` 和 `wordCounters`；计数不进入账号长期账本，不做排行榜。顶部计数器仅在词条首次出现时创建，后续同词条继续累加。
|
||||
运行态规则真相以后端 run 摘要为准，前端只做点击低延迟表现、敲击动画、音频播放和飘字渲染。每次非功能区点击在当前 run 内累计 `totalTapCount` 和 `wordCounters`；计数不进入账号长期账本，不做排行榜。顶部总数卡点击后展开子项计数器面板，子项计数在面板中按词条纵列预置展示，未出现词条初始值为 0，后续同词条继续累加；运行态左上角使用主题化返回按钮图，不提供右上角重开按钮。
|
||||
|
||||
平台首页推荐、精选、最新、公开详情、搜索、已玩作品和公开试玩统一按 `sourceType='wooden-fish'` 与 `WF-*` 公开作品号识别敲木鱼作品；公开列表应走 `wooden_fish_gallery_card_view` 订阅缓存，公开详情或运行态启动时卡片摘要不足则补读完整 work profile。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user