GenarrativeAI/Genarrative
11
0
Fork 0
Code Issues 14 Pull Requests 3 Actions Packages Projects 3 Releases Wiki Activity
Files
b43c3cd823a4b1ba0de89b44a2106895e67a344f
Genarrative/docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md
T

21 KiB
Raw Blame History

敲木鱼玩法模板 PRD 2026-05-20

1. 目标

新增一个可创作、可试玩、可发布的轻量休闲玩法模板：

敲木鱼

模板按平台新增玩法 SOP 接入完整闭环：

创作入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态 -> 公开详情/分享

首版默认屏幕中央展示内置卡通透明敲击物图案 /wooden-fish/default-hit-object.png。玩家点击运行态非功能区时触发一次敲击：播放敲击音效、敲击物图案执行被敲击动画，并在敲击物上方随机飘出一条祝福词。顶部只展示总数记录；子项计数收纳到总数卡片下方的折叠面板中，总数卡片点击后展开各子项计数，词条在面板中预置显示，未出现时初始值为 0，点击面板外收起。计数仅属于当前单次 run，不进入账号长期账本。

2. 模板定位

模板 ID：

wooden-fish

用户展示名：

敲木鱼

公开作品号前缀：

WF-*

体验关键词：

  1. 单屏点击；
  2. 轻量解压；
  3. 飘字反馈；
  4. 单局累计；
  5. 可自定义敲击物、敲击音效和祝福词。

3. 与拼图创作流程的复用边界

可以复用：

  1. 创作入口配置、入口开关和作品架；
  2. 表单/图片输入工作台；
  3. 生成过程页和生成中恢复；
  4. 结果页的返回编辑、局部重生成、试玩、发布；
  5. 公开列表、公开详情、分享码和推荐流分发；
  6. 平台资产对象、OSS 私有读取换签和音频资产持久化能力。

不复用：

  1. 拼图关卡、棋盘、拼块、排行榜和关卡推进语义；
  2. 跳一跳地块图集和蓄力判定语义；
  3. 抓大鹅物品消除、五视角图集和容器语义；
  4. 任何长期功德账本、账号维度排行榜或全局累计。

4. 创作工具平台接入声明

  • 工作台模式：表单/图片输入创作工作台
  • 创作链路：入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态
  • 单图资产槽位：
    • slotId=hit-object
    • slotType=hit-object-image
    • slotName=敲击物图案
    • 提示词来源：hitObjectPrompt 与可选 hitObjectReferenceImageSrc
    • 写回字段：hitObjectAsset
    • 是否允许历史图：允许
    • 是否允许 AI 重绘：允许；上传图只作为 image2 参考，最终运行态只消费 image2 生成图
    • slotId=background
    • slotType=background-image
    • slotName=背景环境图
    • 提示词来源：第一步生成的敲击物图案与用户原始题材关键词 / 参考图主题
    • 写回字段：backgroundAsset
    • 是否允许历史图：不单独选择；由敲击物图案生成链路派生
    • 是否允许 AI 重绘：允许；随敲击物图案一起重生成
  • 系列素材槽位：无；首版只有敲击物图案与背景环境图两个单图资产，不生成图集
  • 音频资产槽位：
    • slotId=hit-sound
    • slotType=hit-sound-audio
    • slotName=敲击音效
    • 来源：用户上传/麦克风录制音频，或使用默认木鱼音
    • 写回字段：hitSoundAsset
    • 默认兜底：/wooden-fish/default-hit-sound.mp3
  • API 命名空间：
    • /api/creation/wooden-fish/...
    • /api/runtime/wooden-fish/...
  • 业务真相：
    • 后端裁决并持久化 session、work profile、发布状态、run 摘要和公开投影；
    • 前端只负责点击低延迟表现、音频播放、动画、飘字渲染和定期 checkpoint。
  • 创作工具模式例外：无
  • 验证命令：
    • npm run check:encoding
    • npm run typecheck
    • cargo test -p shared-contracts wooden_fish --manifest-path server-rs/Cargo.toml
    • cargo test -p module-wooden-fish --manifest-path server-rs/Cargo.toml
    • cargo check -p api-server --manifest-path server-rs/Cargo.toml
    • npm run spacetime:generate
    • npm run check:spacetime-schema
    • npm run dev:api-server 后检查 /healthz

5. 创作输入

工作台提交结构化 payload，不提交聊天消息。

必填字段：

  1. templateId = "wooden-fish"；
  2. hitObjectPrompt：用户想敲的对象关键词或描述，默认“默认敲击物图案，圆润木质质感，透明背景”；
  3. floatingWords[]：祝福词，最多 8 条，不填或清空时使用默认祝福词。

可选字段：

  1. hitObjectReferenceImageSrc：上传或历史图引用，只能作为 image2 参考，不可直接进入运行态；
  2. hitSoundPrompt：历史兼容字段，当前创作流程不再使用；
  3. hitSoundAsset：用户上传、录音或默认音频资产。

结果页补录字段：

  1. workTitle：作品标题，默认值在结果页可编辑；
  2. workDescription：作品简介；
  3. themeTags[]：最多 6 个标签，样式对齐拼图结果页标签编辑器。

创作界面默认祝福词：

幸运

用户可通过加号继续新增 7 个词条，总数最多 8 条。新增词条右侧提供减号 / 删除小按钮；默认的第一个词条保留为普通输入格。

floatingWords[] 保存词条名本身，不保存 +1 后缀；运行态每次敲击时再把飘字展示为“词条+1”。

6. 生成规则

6.1 敲击物图案、背景环境图与返回按钮图

默认模板在用户未自定义关键词且未上传参考图时，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 与 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，必须输出绿色背景主体图（纯绿色绿幕），背景为单一纯绿色 #00FF00，并显式禁止黑底、白底、棋盘格、纸板底或任何其它实底背景；
  5. 提示词严格使用：
生成敲木鱼新样式，要求结构，画风与参考图保持高度一致，新样式颜色搭配使用新主题对应的颜色。尺寸1:1，先输出绿色背景主体图（纯绿色绿幕），背景必须是单一纯绿色 #00FF00 且平整无纹理、无渐变、无阴影、无道具，主体完整居中，主体边缘必须干净，不要直接输出透明底。随后由服务端对绿色背景主体图做抠图去除绿色背景。最终结果只保留单个敲击物图案，禁止黑底、白底、棋盘格、纸板底或任何实底背景；主体本身不要使用与绿幕接近的纯绿色，若新主题天然包含绿色，请改用偏深、偏黄或偏蓝的绿色并与绿幕清晰区分。
新主题为：（用户提供参考图或用户输入关键词）

敲击物图案落盘前，api-server 必须只对第一步生成的纯绿色绿幕背景执行去绿处理，把绿色背景转成真实透明 alpha PNG；不得对黑底、白底或其它未知实底执行泛抠图，避免误伤玉米等主体像素。去绿处理必须保留主体内部深色结构和主题细节。

背景环境图生成流程固定为：

  1. 调用 VectorEngine /v1/images/edits，模型固定为 gpt-image-2；
  2. multipart 参考图固定为第一步敲击物图案抠图完成后的透明图；默认未生成新敲击物时使用内置默认敲击物图案的透明兜底图；
  3. 尺寸固定竖屏 9:16；
  4. 背景环境图只适配新敲击物主题和画风，背景中不得包含新敲击物本体，也不得增加木槌互动物品；中央主体预留区必须保持干净，画面中央 40% 区域禁止出现主题主体、主体局部特写、主体轮廓影子、重复元素或主题主体的局部碎片；
  5. 提示词严格使用：
生成敲木鱼背景，要求主题，画风与参考图保持高度一致，背景元素和颜色搭配与主题对应，木鱼预设在屏幕中央位置，木鱼主体周围元素保持干净，背景氛围围绕外围设计，背景环境图中不包含新木鱼物品，背景氛围中不增加木槌互动物品。尺寸竖屏9:16。参考图必须是第一步敲击物抠图完成后的透明图，不继承任何绿色底色、绿幕底色或纯绿色画布，并要求最终输出完整不透明的背景环境图。中央主体预留区必须保持干净，画面中央 40% 区域禁止出现主题主体、主体局部特写、主体轮廓影子、重复元素或主题主体的局部碎片；主题元素只允许出现在外围氛围，不得把主题物品画在画面中央，也不要把主题物品作为背景中心装饰。
主题为：（用户提供参考图或用户输入关键词）

返回按钮图生成流程固定为：

  1. 调用 VectorEngine /v1/images/edits，模型固定为 gpt-image-2；
  2. multipart 参考图固定包含第一步去除绿色背景后的敲击物主体图，以及第二步生成的背景环境图；
  3. 尺寸固定 1:1，必须输出绿色背景主体图（纯绿色绿幕），后端落库前执行同一套去绿背景处理；
  4. 按主题、画风、材质和配色生成左上角返回按钮图，但参考图只用于约束圆形底色和中央左箭头的颜色搭配，不得借鉴复杂造型、花纹、浮雕边、异形外框或装饰图案；按钮必须始终是标准圆形，主体视觉尺寸比当前模板再放大约 50%，圆形外沿必须有与主题色搭配的干净外描边，中央只保留单个清晰左箭头或返回箭头，不得包含文字、数字、水印、额外 UI 面板、木槌或敲击道具；
  5. 提示词严格使用：
生成敲木鱼左上角返回按钮图。要求以参考图-去除绿色背景后的敲击物主体和背景环境图为主题、画风、材质和配色参考，但参考图只用来约束圆形底色和中央左箭头的颜色搭配，不要继承复杂造型、花纹、浮雕边、异形外框或装饰图案。按钮必须始终是标准圆形，整体像单个圆形图标，按钮主体在画布中的视觉尺寸比当前模板再放大约 50%，圆心居中，圆形外沿加一圈和主题色搭配的干净外描边，让它更像一个按钮，但仍然只保留一个清晰、简洁、居中的向左返回箭头，不要出现文字、数字、水印、按钮外标签、额外 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 中没有真实对象时图片无法显示。

默认图案要求：

  1. 中央主体使用 /wooden-fish/default-hit-object.png；
  2. 透明背景；
  3. 适合移动端居中展示；
  4. 不包含 UI、按钮、说明文字、水印或品牌标识；
  5. 图片主体需留出敲击动画缩放空间。

6.2 敲击音效

音效统一写回 hitSoundAsset。

写回规则：

  1. 若 payload 已包含上传/录音音频资产，compile-draft 跳过音效生成，直接持久化该资产；
  2. 若 payload 已上传或录制音频，则直接写回 hitSoundAsset；
  3. 若两者都没有，后端写回默认木鱼音 /wooden-fish/default-hit-sound.mp3；
  4. 音效资产必须包含可播放地址、对象键、asset object id、来源和可选时长；
  5. 通用创作音频接口当前对 wooden_fish 的 hit_sound 目标返回 410 Gone，不得在创作流程中按提示词生成音效；
  6. spacetime-client 不得自行合成 /generated-wooden-fish-assets/... 音效占位路径；缺少真实 hitSoundAsset 时应使用默认木鱼音兜底展示与播放。

6.3 封面

首版封面使用 hitObjectAsset.imageSrc 作为 coverImageSrc。背景环境图与返回按钮图不作为封面图。

7. 契约草案

WoodenFishDraft 至少包含：

  1. templateId = "wooden-fish"；
  2. templateName = "敲木鱼"；
  3. profileId；
  4. workTitle；
  5. workDescription；
  6. themeTags[]；
  7. hitObjectPrompt；
  8. hitObjectReferenceImageSrc；
  9. hitSoundPrompt，历史兼容字段，当前创作流程恒为 null；
  10. floatingWords[]；
  11. hitObjectAsset；
  12. backgroundAsset；
  13. backButtonAsset；
  14. hitSoundAsset；
  15. coverImageSrc；
  16. generationStatus。

WoodenFishImageAsset 至少包含：

  1. assetId；
  2. imageSrc；
  3. imageObjectKey；
  4. assetObjectId；
  5. generationProvider；
  6. prompt；
  7. width；
  8. height。

WoodenFishAudioAsset 至少包含：

  1. assetId；
  2. audioSrc；
  3. audioObjectKey；
  4. assetObjectId；
  5. source = uploaded | recorded | bundled-default；
  6. prompt；
  7. durationMs。

WoodenFishRunSnapshot 至少包含：

  1. runId；
  2. profileId；
  3. ownerUserId；
  4. status = playing | finished；
  5. totalTapCount；
  6. wordCounters[]；
  7. startedAtMs；
  8. updatedAtMs；
  9. finishedAtMs。

8. API 草案

HTTP 路由：

POST /api/creation/wooden-fish/sessions
GET  /api/creation/wooden-fish/sessions/{sessionId}
POST /api/creation/wooden-fish/sessions/{sessionId}/actions
GET  /api/creation/wooden-fish/works
GET  /api/creation/wooden-fish/works/{profileId}
POST /api/creation/wooden-fish/works/{profileId}/publish
GET  /api/runtime/wooden-fish/works/{profileId}
POST /api/runtime/wooden-fish/runs
POST /api/runtime/wooden-fish/runs/{runId}/checkpoint
POST /api/runtime/wooden-fish/runs/{runId}/finish
GET  /api/runtime/wooden-fish/gallery
GET  /api/runtime/wooden-fish/gallery/{publicWorkCode}

动作类型：

compile-draft
regenerate-hit-object
replace-hit-sound
update-work-meta
update-floating-words
publish
start-run
checkpoint
finish

compile-draft 是长耗时动作。前端进入生成页后应展示可恢复进度；如果请求失败，标记失败前必须复读 session，确认后端是否已经生成并写回草稿。

敲木鱼创作请求在前端必须使用长等待窗口，避免 createSession 或 executeAction 仍沿用共享创作工厂默认的 15 秒超时。因为 compile-draft 会串行等待敲击物、背景、返回按钮三次 image2 和 OSS 落库，木鱼 client 需要单独配置与整条 image2 链路匹配的超时。本地测试中该 action 可能达到数分钟级；生成页进度必须按“整理草稿 -> 生成敲击物 -> 生成背景环境图 -> 生成返回按钮图 -> 写入正式草稿”展示，不展示“提示词生成音效”阶段，因为当前木鱼音效只支持上传、录音或默认音。

作品架使用 GET /api/creation/wooden-fish/works 读取当前用户草稿和已发布摘要，前端发布成功后必须刷新该列表和 GET /api/runtime/wooden-fish/gallery 公开列表，使刚发布作品立即出现在草稿 Tab 的已发布筛选和推荐 / 最新流中。

9. SpacetimeDB 表和 view

新增表：

  1. wooden_fish_agent_session；
  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：公开详情兼容投影，包含图案、背景、返回按钮、音效和祝福词配置。

新增或调整表、procedure、view 后必须同步 migration.rs、后端表目录、生成 bindings，并执行 npm run check:spacetime-schema。

10. 结果页能力

结果页必须展示：

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

结果页必须支持：

  1. 重生成敲击物图案；
  2. 上传、录制或替换敲击音效；未提供时使用默认木鱼音；
  3. 修改标题、简介和标签，并在试玩或发布前写回当前作品信息；
  4. 修改祝福词，最多 8 条。

图案重生成是独立局部生成态，不得把已有可查看结果重新变成不可打开的全局生成中。音效替换只接受上传或录音资产，不触发提示词音效生成。

11. 运行态规则

运行态采用全屏单击模型。

功能区：

  1. 顶部总数记录卡和其下拉的子项计数器面板；
  2. 设置、暂停、返回、发布分享等按钮；
  3. 结果弹层和音频授权提示。

点击规则：

  1. 点击非功能区才算一次敲击；
  2. 每次敲击立即本地累加 totalTapCount；
  3. 随机等概率从 floatingWords[] 中取一个词条；
  4. 子项计数面板中预置展示所有词条，未出现词条初始值为 0；
  5. 后续同词条出现时对应计数器 +1；
  6. 播放敲击音效；
  7. 敲击物图案执行压缩、回弹或轻微震动动画；
  8. 木鱼上方飘出“词条+1”并淡出，飘字只显示文字本体，不加底板、胶囊背景或说明面板。

运行态左上角返回按钮必须优先使用 backButtonAsset 渲染主题化按钮图；缺失时才回退通用图标按钮。运行态不提供右上角重开按钮。

音频播放：

  1. 前端使用小复音池；
  2. 设置最小播放间隔，避免极端连点导致浏览器抖动；
  3. 点击计数不能因为音频节流而丢失；
  4. 签名 URL 未就绪时先静音表现，不请求裸 generated 私有路径。

后端只保存 run 摘要，不保存每次点击的完整明细；checkpoint 和 finish 都写入总敲击次数与词条计数快照。

12. 公开链路

平台首页推荐、发现、公开详情、搜索、已玩作品和公开试玩统一按 sourceType='wooden-fish' 与 WF-* 公开作品号识别敲木鱼作品。

公开列表优先消费 wooden_fish_gallery_card_view 订阅缓存。公开详情如果卡片摘要不足以进入运行态，必须补读完整 work profile。

13. 验收

  1. 创作入口能看到 敲木鱼 模板；
  2. 工作台可以填写敲击物描述、上传参考图、上传或录制音效、配置祝福词；
  3. 提交后按默认木鱼参考图生成 image2 敲击物图案；
  4. 提交后按新敲击物图案参考图生成 9:16 背景环境图；
  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 通过。
Reference in New Issue View Git Blame Copy Permalink