Files

T

kdletters 7ea463ed08 退役旧创作模板业务并保留数据壳

保留 SpacetimeDB 历史表、迁移白名单与最小兼容读取定义
移除旧创作前后端、worker、业务过程及纯业务 crate 的编译依赖
恢复现役创作、项目、我的入口及桌面移动导航
收紧 Vite、TypeScript、ESLint、Vitest 与静态资源退役边界
补齐开发栈、网关、原生壳和文档退役约束

2026-07-18 22:02:22 +08:00

107 KiB

Raw Permalink Blame History

平台入口与玩法链路

2026-07-17 退役覆盖：全部旧创作模板的前端、API、worker、reducer/procedure、纯业务 crate、生成发布链路、公开业务详情和专属运行态已下线，仅保留相关历史表的数据壳与必要兼容读取。本文后续玩法章节只作为历史设计记录，不再描述当前可用能力；当前实现与验收以 docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md 为准。

更新时间：2026-07-18

现役平台壳

旧创作模板退役后，桌面端继续保留统一平台壳，一级导航固定为 创作 / 项目 / 我的：

/creation 展示基于图片编辑器的创作工具主页，只读取编辑器项目与公开编辑器素材。
/project 展示当前账号的图片编辑器项目，项目卡继续进入 /editor/canvas。
/profile 是“我的”稳定路由，保留头像与昵称编辑、陶泥号复制、泥点余额与账单、累计统计、泥点充值、兑换码、玩家社区、反馈与建议、通用设置、开发者 API Key 和法律信息等平台公共能力。
桌面顶栏保留现役项目 / 素材搜索、泥点入口和账号胶囊。搜索只筛选当前编辑器项目与已读取的公开编辑器素材，不恢复旧公开作品号搜索、旧广场、旧作品详情或旧运行态。
桌面端使用公共侧边栏，移动端使用同样包含“创作 / 项目 / 我的”的三项底部 dock；点击、刷新及浏览器前进 / 后退都必须保持 URL、标题和选中态一致。

现役入口和公共资料能力只能依赖 creation-home、project、image-editor、公共组件及 services/platform-entry 等现役模块。Vite 模块门禁会拒绝 components/rpg-entry、services/rpg-entry、旧玩法目录和旧平台业务模块进入依赖图；Tailwind @source、TypeScript include、ESLint ignore 或 Vite watch ignore 都不能替代这条运行时依赖门禁。

历史平台创作入口

本节及后续玩法章节保留退役前的设计记录，其中出现的 /api/creation-entry/config、/creation/<play>、模板工作台、公开作品和专属运行态均不是现役契约，不得用于当前实现或运维验收。

创作入口配置事实源在 SpacetimeDB，通过 GET /api/creation-entry/config 下发；后台通过 /admin/api/creation-entry/config 管理入口开关，通过 /admin/api/creation-entry/config/interactions 管理公开作品点赞 / 改造能力矩阵。前端只在展示层派生可见卡片、入口状态和作品详情互动状态，api-server 路由熔断也使用同一份配置。不要恢复前端硬编码入口配置文件。

当前点击底部加号进入的创作入口页承载后台公告位、创作入口页签和两列模板卡；页签中只有真实后端作品架摘要存在时才展示“最近创作”，其余为玩法模板分类。点击模板卡后直接进入对应玩法已有的入口创作表单 stage，不再经过空白占位页，也不把旧表单嵌进创作入口页；模板点击的占位 no-op、隐藏模板拦截、未知入口 no-op 和工作台启动目标统一由 platformCreationLaunchModel.ts 判定，壳层只执行启动前准备、错误提示和受保护动作。移动端创作入口页顶栏在 陶泥儿 品牌同一行显示真实账户泥点数，数据来自 profileDashboard.walletBalance，不得再把公告内容或活动奖池当作账号余额展示。创作入口页公告位数据优先读取 GET /api/creation-entry/config 的 eventBanners 数组，多条配置时前端自动轮播；旧 eventBanner 只保留字段回显与旧客户端兼容，不再作为前端公告数组的兜底来源。后台公告配置面向表单：每条公告包含标题和 HTML 内容，后台保存时序列化为后端 eventBannersJson 传输字段，由前端空权限沙箱 iframe 展示；旧结构化 banner 字段仅保留回显兼容，不再作为后台公告配置主格式；不得执行 JSX 或把后台代码直接注入 DOM。玩法列表不再套外部边框卡片，移动端需要压缩横向边距和两列间距；玩法卡统一按“上图、左上状态标签（仅非开放态显示）、封面右下显示 creationTypes[].unifiedCreationSpec.mudPointCost 经前端格式化后的泥点消耗、下方白底标题/描述”结构展示，旧契约缺少该字段时兜底 10 并由前端显示为 10泥点数，卡片高度保持紧凑但标题、描述和预估消耗点数都必须可见。创作入口页根容器不再使用 platform-page-stage 这类全局内容卡片壳，但继续保留 platform-remap-surface 作为主题和输入框样式命中钩子。创作入口页字号需要对齐平台普通 UI 档位：顶栏泥点组件、公告正文、分类 Tab 和玩法卡标题 / 副标题 / 消耗说明优先使用 11px 到 14px，不使用 text-lg、text-xl 或更大的展示级字号。草稿 Tab 继续承接作品架；底部加号入口页的“最近创作”只用 7 天内的真实后端作品架摘要判断是否展示，并从摘要里推导最近使用过的模板 ID，页面必须展示“仅显示最近7天内使用过的模板”提示，列表内容必须复用其它页签里的模板卡样式、文案和点击行为，不展示具体作品名称、摘要或生成状态，也不新增独立最近创作卡组件。RPG、RPG 之外的各玩法入口分别落到既有的 agent-workspace、big-fish-agent-workspace、match3d-agent-workspace、square-hole-agent-workspace、jump-hop-workspace、wooden-fish-workspace、puzzle-agent-workspace、bark-battle-workspace、visual-novel-agent-workspace、baby-object-match-workspace，这些入口继续承接各玩法自己的表单、草稿恢复和后续编排，不作为创作入口页内容。

/creation 是桌面端创作工具主页；移动端直达 /creation 时只显示桌面端打开引导，不加载桌面创作主页和项目 / 素材数据。/creation/<play> 仍按各玩法路由直达对应工作台、生成页或结果页，不受该引导影响。

旧库或旧迁移包没有 event_banners_json 时，后端读取层必须把 eventBanners 归一到 module-runtime 默认公告数组，不能把旧结构化 eventBanner 当成前端优先数组下发。默认公告引用的背景图必须指向 public/ 下真实存在的站内静态资源，当前默认使用 /creation-type-references/puzzle.webp，避免创作入口顶部 banner 出现失效图片。

创作页和草稿页顶栏右上角统一复用公共泥点资产入口，不再把余额区本身作为直接充值按钮。顶部总余额优先展示会随扣费、退回和到账刷新的 profileDashboard.walletBalance，充值中心的 mudPointBalance 只承接展开面板中的不限时 / 每日免费泥点明细，不得用已缓存的明细总数覆盖已刷新的顶部余额。余额区展开后只展示不限时泥点、每日免费泥点及重置口径；会员周期限时泥点仅由后端保留用于存量兼容和结算，当前版本不在前台展示。独立“充值”按钮进入“购买更多泥点”弹窗，“使用详情”进入泥点账单。主站各位置必须保持同一组件、数据口径和交互语义，头像 / 设置等账号入口继续保留各自语义。

创作恢复参数只保留 sessionId、profileId、draftId、workId 这四个私有 query。它们只允许在同一条创作链路的结果页、生成页、工作台之间保留；切到首页、公开作品详情、runtime 或另一条玩法链路时必须清掉。平台入口刷新直达时，路径到玩法恢复目标、四个 query 归一化、生成页标记、大鱼吃小鱼 workId 兜底、作品 / 草稿身份匹配和跳一跳 / 敲木鱼恢复阶段落点统一由 platformCreationUrlStateModel.ts 解析，壳层只执行读取作品、恢复草稿和切换阶段等副作用。生成页等待时间统一以生成状态里的 startedAtMs 为准；创建该状态时优先使用后端 session 下发的时间戳，作品摘要里的 updatedAt 仍只用于排序与摘要展示，不作为前端自行推导业务状态的真相。

生成页进度 tick 是否启动统一由 platformGenerationProgressTickModel.ts 判定：各小游戏生成页只在当前 stage 与对应生成状态匹配、状态存在且 phase 非 ready / failed 时 tick；视觉小说继续使用 startedAtMs 与轻量 phase 判定，不强行转成小游戏生成状态。平台壳只保留 Date.now()、setInterval 和 cleanup 副作用，不在壳层重复维护 stage 到 state 的三元链。

拼图 runtime 刷新恢复、跳一跳生成中草稿打开和敲木鱼生成中 / detail 草稿恢复所需的 session / work DTO 映射统一由 platformMiniGameSessionMappingModel.ts 构造。平台壳只负责读取后端、写入本地 state、写 URL 和切换 stage；不得在壳层重新手写 sessionId 优先级、pending draft 空素材默认值或拼图稳定 ID 映射。

平台小游戏生成状态的恢复、失败 / 完成收尾、展示 rebase、拼图后端进度合并和 ready / generating 判定统一由 platformMiniGameDraftGenerationStateModel.ts 处理。平台壳只决定何时调用并写入对应 React state，不得在壳层重新维护 MiniGameDraftGenerationState 的 phase 阈值、finishedAtMs 清理或拼图进度 metadata 合并规则。

拼图 / 抓大鹅草稿恢复和提交所需的表单 payload、拼图编译 action、pending metadata 与拼图 form-only 草稿判定统一由 platformMiniGameDraftPayloadModel.ts 构造。平台壳不得重新手写拼图描述字段优先级、formDraft 回退、form-only 空草稿判定、Match3D config / draft / anchorPack 优先级、数字解析或 pending 标题摘要派生规则。

拼图生成完成后刷新恢复的草稿归一化与可恢复完成态判定统一由 platformPuzzleDraftRecoveryModel.ts 处理。恢复链路只有在首图、关卡画面、UI spritesheet 与关卡背景资产包完整时才可把 draft 和首关状态抬为 ready；只有 cover 或候选图的半成品不得直接进入结果页完成态。

后端拼图发布 / 待发布门槛同样必须要求首图、关卡画面、UI spritesheet 与关卡背景资产包完整：module-puzzle preview blockers 与 api-server session stage 判定不得只凭 cover、标题、描述和标签把半成品标为 publishReady 或 ready_to_publish。

平台入口个人钱包本地 delta 由 platformProfileWalletDeltaModel.ts 判定：余额归一、本地扣点 / 返还后的 dashboard 乐观更新，以及服务端 dashboard 刷新后的 delta 对账不得散落在平台壳层；壳层只负责 API、React ref 和 state 写入。

RPG Agent 结果页发布门禁展示由 platformRpgAgentResultPreviewModel.ts 判定：平台壳不得重新手写 CustomWorldProfile 顶层、creatorIntent、anchorContent、章节蓝图与首幕 acts 的结构探测，也不得在壳层内联 result preview source label 映射；壳层只负责 session/profile 编排和结果页 props 传递。

统一创作入口覆盖当前可进入创作链路的已有模板：rpg、big-fish、puzzle、match3d、jump-hop、wooden-fish、square-hole、bark-battle、visual-novel、baby-object-match 和 creative-agent；airp 仍是未开放占位，不作为当前统一创作链路目标。拼图、抓大鹅、跳一跳和敲木鱼在前端继续经过 UnifiedCreationWorkspace 和 UnifiedGenerationPage：UnifiedCreationWorkspace 作为平台壳依赖的统一创作编排层，再内部调用 src/components/unified-creation/workspaces/ 下的 PuzzleCreationWorkspace、Match3DCreationWorkspace、JumpHopCreationWorkspace 和 WoodenFishCreationWorkspace。其它已有模板由平台壳用 UnifiedCreationPage 包住既有工作台，复用统一标题栏、返回入口、页面级纵向滚动和隐藏字段契约，同时保留各玩法自己的表单、草稿恢复和后续编排。创作页字段清单、表头和入口卡泥点消耗数量由后端在 GET /api/creation-entry/config 的 creationTypes[].unifiedCreationSpec 下发，前端仅在该扩展位缺失时回退到本地默认 spec；字段类型只保留 text、select、image、audio。统一创作页表头按 unifiedCreationSpec.title 契约内容原样显示，入口卡泥点消耗按 unifiedCreationSpec.mudPointCost 由前端格式化为 X泥点数，读取和保存时不再用入口名称或前端固定文案自动覆盖；需要改表头或入口卡消耗数量时应在后台契约结构卡片点击修改，并通过弹窗表单编辑 title 或 mudPointCost 字段，不再要求直接编辑 JSON。workspaceStage、generationStage 和 resultStage 属于内部阶段标识，后台弹窗不展示也不允许编辑；保存时沿用已有契约值，新增契约时按 playId 的前端固定阶段映射自动带出。UnifiedCreationPage 不在 UI 中额外展示字段说明 chip，也不在右上角显示内部 playId、模板 ID 或工作台阶段名；竖屏移动端必须能从标题、表单一路滑到提交按钮。统一创作页根容器必须保留平台浅色背景并让内容区占满剩余高度，移动端软键盘打开或视口被小程序宿主压缩时，短表单也不得露出浏览器 / 宿主黑底；H5 根节点在 data-mobile-keyboard-open=true 时必须把 html / body / #root 背景切到当前平台浅色底，但不得再用 .platform-viewport-shell 全局 transform 二次上推页面；小程序 web-view 页面原生宿主也必须使用浅色背景，不能沿用全局黑色 page 背景。各玩法工作台负责渲染真实输入控件、上传、历史素材、校验和提交，但返回按钮只保留在统一页头，工作台内部不再重复渲染。暗色创作进度卡片位于 platform-remap-surface 内时，必须用组件专属 class 覆盖浅色主题 remap，确保白字、浅色边框和进度条底色不会被全局规则改成深色；不要只依赖通用 text-white* 类。敲木鱼的音效和功德词条面板不得放进独立内部滚动容器，移动端应跟随页面自然滚动展开。生成页统一展示阶段、当前步骤、总进度、错误和重试动作。

创作表单提交前的泥点余额前置校验只允许用独立弹窗提示失败原因，不得把用户退回创作入口或玩法模板列表，也不得清空当前表单状态。当前适用拼图、抓大鹅和汪汪声浪等会在前端提交前校验泥点的生成入口；校验成本必须读取同一份 creationTypes[].unifiedCreationSpec.mudPointCost，不能回到前端常量。余额不足、余额读取失败都应停留在当前工作台，由用户关闭提示后继续编辑或自行补足泥点。

平台入口、生成页、结果页、作品详情、作品架和运行态的跨流程错误统一收口到 PlatformErrorDialog。弹窗必须带明确错误来源，例如某个草稿、某次生成、作品详情或某个游玩实例，并提供复制按钮复制“错误来源 + 错误内容”。页面内不再重复渲染裸错误 banner；表单校验、发布确认弹窗里的局部业务错误可以保留在原弹窗内。生成任务在用户离开生成页后异步失败时，也必须通过同一弹窗通知用户，并把失败消息写入该 session 的草稿 notice，供草稿页和失败重试页恢复使用。

生成任务在用户离开生成页后异步完成时，平台壳层必须弹出 PlatformTaskCompletionDialog。完成弹窗同样要带来源，例如某个草稿或生成会话，并提供复制按钮复制“来源 + 状态”；如果用户仍停留在生成页并被自动带入结果页或试玩页，生成页 / 结果页本身即为完成反馈，不再额外叠加完成弹窗。外部生成队列的用户可见概览统一放在移动端一级 我的 页签，生成页 / 进度页只展示当前玩法的阶段、步骤、总进度、错误和重试动作；用户离开生成页后仍可在 我的 页查看当前账号可见的排队与生成数量。队列概览只作为等待状态补充，草稿 ready / failed 与作品结果仍以后端玩法 session/detail 回读为准。

入口配置中的 open=false 表示关闭新建创作入口，不表示下架已有草稿、私有作品或公开作品。api-server 的入口熔断只允许拦截新建创作、新建草稿、首次生成入口和 Remix 成草稿等会产生新创作的请求；公开广场列表、公开详情、点赞、已发布作品启动、运行态过程请求、存档 / 浏览记录和已有作品回读不能因为创作入口关闭而返回 creation_entry_disabled。平台首页如果遇到旧服务端返回的 creation_entry_disabled，只能降级为空列表或隐藏入口，不弹平台级错误弹窗。

公开作品点赞 / 改造是否开放不跟随入口 open 字段，而是读取 GET /api/creation-entry/config 的 publicWorkInteractions。后台可以按 sourceType 分别关闭点赞或改造并维护关闭提示；前端只据此关闭已接入的作品详情动作，尚未接入后端动作的玩法仍按实际能力矩阵返回不可用提示。api-server 对已接入的 RPG、自定义世界兼容路径、大鱼吃小鱼和拼图点赞 / 改造接口做同源熔断，关闭时返回 public_work_interaction_disabled，但公开列表、公开详情、已发布作品启动和运行态过程请求不受影响。

创作入口页的关闭态卡片必须有明显差异：卡片禁用点击，展示后台配置的关闭态 badge 或 暂未开放，不再显示泥点消耗这类可创建成本提示；开放态卡片仍不显示普通 可创建 / 可创作 badge。

PlatformEntryFlowShellImpl.tsx 仍是平台入口编排壳，后续维护时应优先把独立 UI 片段、公开作品映射、草稿生成 notice 和运行态状态 helper 拆到 src/components/platform-entry/PlatformEntryFlowShellImpl/ 或同目录紧邻 helper 文件。拆分只允许改变文件组织，不改变入口配置事实源、默认导出、props、页面阶段、UI 文案或现有交互；其中拼图首访 onboarding 已拆为 PlatformEntryFlowShellImpl/PuzzleOnboardingView.tsx。

platformEntryCreationTypes.ts 只做前端展示派生，分组时必须把后端 creationTypes 里的 categoryId / categoryLabel 当作可缺失字段处理，空值统一回退到 recommended / 热门推荐，并把历史 recent / 最近创作 归一到推荐分类。最近创作 不属于模板分类页签，只能由 7 天内的真实草稿 / 作品架后端数据决定是否展示；展示内容仍然从后端入口配置的模板卡中筛选，不读取或渲染作品标题、作品摘要、草稿阶段文案。

移动端底部一级导航是全局平台样式，不按单一玩法分叉。当前视觉统一为米白浮动胶囊底座、浅棕分隔线、棕色线性图标、橘色选中态和底部短下划线；中间 创作 入口保持凸起圆形主按钮，但凸起位移只能作用在按钮内容层，不能移动承载分隔线的 Tab 按钮容器，确保创作左右分隔线与其他分隔线垂直位置一致。Tab 名称和可见性仍由现有 PlatformHomeTab / 登录态规则决定，样式调整不得改写 Tab 文案或导航状态。

新增玩法创作工具平台 SOP

新增玩法默认采用表单/图片输入创作工作台，链路为：

创作入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态

后端链路也按同一条平台主干组织：所有创作、生成、作品回读、发布、试玩、正式 runtime、公开详情、作品架、运行态设置 / 存档、游玩历史、存档归档、游玩统计、历史素材、AI task、runtime chat、文档解析、角色资产工坊和玩法生成支撑资产相关 HTTP 路由，先注册到 server-rs/crates/api-server/src/modules/play_flow.rs，由主干在进入领域 handler 前统一解析 PlayFlowRequestContext，再在最后一步分发给对应领域模块或支撑能力 handler 处理。app.rs 不再逐玩法挂载创作 / 运行态路由，modules/platform.rs 只保留通用 LLM / 语音代理；新增玩法、补齐旧玩法或迁移旧路径时，必须先补 play_flow 的 playId、领域模块 key、创作路由前缀、运行态路由前缀和入口开关匹配规则，再补具体 handler。领域规则、胜负裁决、计分、发布状态、资产完整性和排行榜仍留在各自 module-* 与 SpacetimeDB procedure 中，不把平台主干写成某个玩法的新业务真相。

默认工作台只提交结构化表单、图片槽位和配置 payload，不默认增加聊天输入区、流式消息区或轻输入 Agent。确需偏离该模式时，必须先在 PRD 和本文档写明例外原因、影响范围和回退方式，再进入编码。

单图资产编辑统一通过 CreativeImageInputPanel 承载上传、AI 重绘、参考图、历史图、主图预览和删除确认；新玩法页面不得重复手写这些交互。主图已有图片时，默认点击图片打开全屏预览，上传 / 更换收口到右下角 ImagePlus 图标按钮；无图时仍允许点击空图卡上传。调用方只能通过 canUploadMainImage、canUseImageHistory 等受控参数开关上传和历史入口，不得用复制组件或样式遮挡改行为。系列素材图集生成统一走“批量规划 -> sheet 生图 -> 后端切图 -> 透明化 -> OSS 持久化 -> 状态回写 -> 局部重生成”流程，玩法只提供 sheetSpec、slotSpecs、提示词和字段映射，不把任一玩法专属素材 DTO 当作平台通用模型。

通用系列素材图集能力的实现真相源在 platform-image::generated_asset_sheets：n 是必选参数，模块负责组装 n*n sheet prompt、按 n*n 切片、默认绿幕 / 近白底透明化、导出 PNG 和 OSS 持久化请求；高风险撞色玩法可显式使用专用 key 色、关闭近白扣除并限制为边缘连通背景扣除。api-server::generated_asset_sheets 只保留 AppError / AppState 适配，不再承载图像处理和 OSS 请求构造细节。物品名称 prompt 和特殊设定 prompt 是可选输入；调用方可传入类似“每个物品生成五个不同视图”的视角约束，通用模块会把 sheet prompt、物品行 prompt、特殊设定 prompt 编码写入 OSS 元数据。玩法仍负责计费、物品规划、slot 映射、失败回写和把通用切片结果映射回自己的草稿 / profile / runtime 字段。

当前所有玩法生成页 UI 统一收敛为圆环主视觉：media/create_bg_video.mp4 作为生成页固定全屏背景层循环静音播放，主进度圆环居中覆盖在背景之上，围绕陶泥儿视觉展示；页面只保留当前步骤名称和当前步骤进度，不再渲染步骤列表块，也不再展示“当前拼图信息”“当前敲木鱼信息”“当前世界信息”等玩法设定信息模块。视频层需要显式触发播放，不能只依赖 autoPlay/loop/muted 属性。圆环内部保持 400x400 SVG 坐标系，外层显示宽度以 400px 为上限，窄屏按视口宽度收缩，预计等待 / 已耗时信息卡在窄屏下落到圆环下方，和当前步骤卡保持更大的垂直间距；预计等待左边缘、已耗时右边缘必须分别与当前步骤卡左右边缘对齐，避免右侧裁切或横向漂移。生成页顶部返回栏和状态标识不参与内容滚动，滚动只发生在进度内容区。共用生成页 CustomWorldGenerationView 和汪汪声浪生成页都必须遵循这一口径。

草稿与作品架

草稿页作品卡对齐发现页列表卡风格：左侧信息，右侧封面图，移动端单列，桌面两到三列。
草稿页顶部 全部 / 草稿 / 已发布 筛选与发现页 推荐 / 今日 / 分类 / 排行 频道标签复用同一选中 / 未选中视觉，即 platform-mobile-home-channel 与 platform-mobile-home-channel--active，不再使用旧 platform-tab 胶囊样式。
草稿页与底部导航的未读提示点统一使用平台暖棕色点和暖棕光晕，不再使用红点或红色 glow；草稿 Tab 作品架卡片无论草稿 / 已发布都不外露作者信息；已发布作品卡右上角直接显示带底色的分享 icon，并统一唤起发布分享弹窗 PublishShareModal，不在卡片内部单独复制分享文案。删除等破坏性动作在作品卡上也要直接开放统一 actions.delete 入口，左滑、长按和键盘左箭头仅作为打开同一操作层的辅助交互；所有玩法草稿和已发布列表项都必须通过该统一接口接入删除确认、删除中状态和列表刷新，不允许只给拼图保留专属滑动删除分支。
生成中作品在整卡上加等待遮罩，但不移除作品基础信息。
生成中状态不能只存在前端内存 notice。后端作品摘要必须下发可恢复的 generationStatus；前端刷新或退出产品后，作品架优先用摘要状态恢复等待遮罩，本轮内存 notice 只作为即时反馈。
点击 generationStatus=generating 的草稿卡必须恢复对应玩法的生成进度页，不能进入空白结果页或普通工作区；恢复生成页的 startedAtMs 优先使用后端 session 的 updatedAt，没有 session 时再使用作品摘要 updatedAt，不得因重新进入页面从 0 秒重新计时。
生成失败必须按 session 独立记录，不能用一个失败打断或覆盖同玩法的其它生成任务。失败 notice 需要保存错误消息并覆盖作品架本地状态：即使后端摘要暂时仍是 generationStatus=generating 或只写出半成品投影，草稿卡也不得继续显示“生成中”，点击后必须进入失败 / 重试生成页，不能重新创建一轮生成。失败页点击重新生成时必须优先复用当前可恢复 sessionId 执行编译 action；只有没有可恢复 session 时才允许回退到新建草稿。拼图这类失败半成品若没有有效 workTitle，作品架标题回退为“拼图草稿”，不暴露“第1关”空壳。
从草稿 Tab 作品架打开草稿工作区、生成页或结果页时，返回按钮必须回到草稿 Tab 的同一作品架语境；从创作 Tab 新建或直接进入创作链路时才回到创作 Tab。平台壳层需要显式记录本次创作流的返回来源，不能让结果页返回动作固定跳到创作入口。
私有 generated 图片必须通过 ResolvedAssetImage / /api/assets/read-url 换签读取。
敲木鱼作品架读取当前用户作品列表时走 GET /api/creation/wooden-fish/works；发布成功后平台壳必须同时刷新作品架与公开广场，避免作品刚发布时仍停留在旧列表。
移动端草稿页整体禁止长按选择文字，避免误触系统选区；输入框、文本域和可编辑区域仍必须保留文本选择能力。
作品架删除确认的纯规则统一由 platformCreationWorkDeleteFlow.ts 解析，输出确认框 id/title/detail 与删除成功后清理的草稿 notice keys；平台壳只接回该模型执行删除 API、刷新列表、清错误和跳转。Jump Hop、Wooden Fish、Bark Battle 虽在作品架 action 层有预留删除入口，但未补齐删除 API 前不得传入删除 handler 或开放按钮。

发现页 / 推荐页公开作品卡的作者行只显示可读公开昵称；不得把手机号掩码、账号生成的脱敏手机号、SY-* 陶泥号或作品号拼接进卡片作者名。陶泥号搜索、作品号复制和完整作品身份只在搜索、详情页或明确的复制入口展示，避免卡片列表暴露账号标识。推荐页运行态、标题和作者信息必须使用同一套公开作品 key 选中当前条目；新增或补齐公开玩法类型时复用 buildPlatformPublicGalleryCardKey(...)，避免运行内容已切换但标题 / 作者仍退回第一条作品。

平台公开搜索的分流顺序、per-play 公开码匹配、公开可见性过滤和详情卡 DTO 映射统一由 platformPublicCodeSearchModel.ts 判定：user_ / user- 内部用户 ID 只查用户 ID；PZ、BF、JH、WF、BO、M3、SH、VN、BB 前缀分别直达对应玩法公开作品；M3D-* 作为抓大鹅旧前缀继续匹配；CW 与 1-8 位纯数字先查 RPG 公开作品再回退陶泥号；普通关键词和 SY 陶泥号保持先查陶泥号、再查 RPG 作品、再查汪汪声浪作品、最后陶泥号兜底的既有顺序。平台壳只按计划执行网络读取、详情打开、Bark Battle runtime 特例和缺失作品归航，不在壳层重复维护前缀布尔链、isSame*PublicWorkCode 或 DTO 映射。

个人“玩过作品”面板点击作品时，玩法别名、worldKey 前缀兜底、RPG 公开详情 payload 和大鱼吃小鱼缺 gallery 命中时的 fallback work 统一由 platformPlayedWorkOpenModel.ts 判定。平台壳只负责关闭面板、调用对应公开详情打开函数、刷新大鱼 gallery、优先使用真实 gallery 命中项和写入错误提示；不要在壳层重新维护 worldType / worldKey 分支链。

发现 Tab、创作 Tab 与草稿 Tab 的页面根内容区不再套 platform-page-stage 外层全局卡片壳，让列表、筛选和玩法卡获得更宽的横向空间；推荐页和我的页仍按各自页面设计保留原有全局卡片口径。移动端“我的”页仍按顶部头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、设置入口和法律信息组织，不保留旧的底部“填邀请码”次级入口；常用功能当前只展示四项常驻入口时必须按四列铺满整行，不保留五列网格导致左对齐空位；每日任务卡必须读取 /api/profile/tasks 的当前任务摘要并在领取后同步刷新卡片进度。字号必须维持平台普通 UI 档位，不能因为窄屏把卡片标题、功能 label 或法律信息撑成展示级字号；最后一屏内容必须能在底部 dock 上方完整滚动露出，不得被固定底部导航遮挡。

RPG / 自定义世界

当前 RPG 创作入口使用 playId = rpg，工程域和运行态源类型沿用历史 custom-world。默认入口状态为 visible=true、open=true，对外展示为“文字冒险”；airp 仍是独立的“AI RPG”占位入口，保持 open=false，不要把它当作当前 RPG 创作链路开放。

当前链路为：

创作入口 -> RPG Agent 共创工作台 -> 生成过程页 -> 结果页 -> 进入世界/试玩 -> 发布 -> RPG 运行态

RPG 是历史既有链路例外：当前仍使用对话式 Agent 共创工作台和 RPG 资产编辑器体系，不作为新增玩法默认模板复制。新增玩法继续遵循本文默认的表单/图片输入工作台、CreativeImageInputPanel 单图槽位和通用系列素材图集生成流程；如果要把 RPG 逐步迁回默认模式，应先补 PRD 和迁移方案，再改代码。

RPG API 仍沿用历史命名空间：/api/runtime/custom-world*、/api/story/*、/api/runtime/chat/*。这些路由在 api-server 入口熔断中统一映射到 rpg，只按 open 判断是否允许调用；visible 只控制创作页入口展示和作品架可见性。

RPG Agent 结果页点击发布或发布并进入世界时，必须先把结果页当前 profile 通过 sync_result_profile 保存回 custom_world_agent_session.draft_profile_json，再发送发布动作；发布动作前端契约只允许提交 { action: 'publish_world' }，api-server 只补作者公开信息，不转发 profile、draftProfile、legacyResultProfile 或 settingText。spacetime-module 发布时只读取当前 session 的 draft_profile_json 作为草稿真相，从 settingText、creatorIntent.rawSettingText、creatorIntent.worldHook、worldHook、anchorContent.worldPromise(.hook)、summary、name/title 依次派生正式 setting_text，最后才回退 seed_text。不要把 seed_text 当作唯一设定来源，旧会话可能为空。

Agent session 已进入 published 后，结果页按钮只能执行“进入世界”：前端需先通过 result-view 回读已发布 profile 并启动运行态，不得再次调用 sync_result_profile 或发送 { action: 'publish_world' }。publish_world 只允许在 object_refining、visual_refining、long_tail_review、ready_to_publish 等发布前阶段触发；否则会被后端阶段门槛拒绝。

legacyResultProfile 只作为历史结果页 profile 兼容兜底；编译正式 profile 时，session 草稿内已保存字段优先于 legacy 字段，legacy 只能补缺失字段。publish_world 不再接受前端临时传入的 legacy 载荷；历史兼容路径中 legacy 缺省或显式为 null 时等价于未提供，不得因此报 custom_world.compile.legacy_result_profile_json 不是合法 JSON object。真正的数组、字符串、数字等非 object legacy 载荷仍应拒绝。

RPG 结果页开局 CG 是 profile.openingCg 资产槽位：api-server 负责 VectorEngine / OSS 副作用并返回故事板和视频引用，前端只把结果写回当前 profile；sync_result_profile、作品库保存和 normalizeCustomWorldProfileRecord 都必须保留该槽位。封面是 profile.cover 资产槽位，默认封面也要保留 sourceType='default' 和 characterRoleIds，不能因为没有 imageSrc 就当作空封面。若生成成功后画面短暂显示又变回空白，优先检查父层重新同步或 profile 归一化是否把 openingCg / cover 丢掉，而不是先怀疑已生成资源本身失效。

RPG 从作品架、广场详情或作品号搜索点击“启动”前，入口 client 必须把后端返回的完整 profile 先经过 normalizeCustomWorldProfileRecord，并用作品条目的 profileId/worldName/subtitle/summaryText 补齐旧数据缺失字段；运行态和详情页不得直接消费未归一化的旧 profile。作品架列表或 savedCustomWorldEntries 中的摘要 profile 只可用于卡片展示，不可在详情接口已回读完整 profile 后覆盖 selectedDetailEntry；若摘要缺少 playableNpcs、storyNpcs、landmarks、items、sceneChapterBlueprints、cover、openingCg、skills[].actionPreviewConfig、initialItems[].iconSrc、attributeSchema、角色 attributeProfile、场景残留或场景幕背景资产，启动和编辑必须继续使用详情 profile，否则会进入默认角色 / 默认 profile，或在编辑页丢 CG、封面、技能预览和初始物品图标。正式“进入世界”发布 / 回读结果页时，同一 profile.id 下也不得用字段更少的后端旧视图降级当前结果页完整 profile。角色选择页还需要在角色数组异常或为空时回退默认角色，并显示可返回的轻量空态，不能 return null 造成黑屏。运行态懒加载 fallback 必须可见，不能用纯 null 让用户误判为黑屏。

RPG 运行态的战斗终局、继续冒险、继续探索和切场景都属于服务端 runtime 快照真相：module-runtime-story 必须在终局战斗 action 后调用 post-battle finalization，持久写入 story_continue_adventure、deferredOptions、deferredRuntimeState.storyEngineMemory.currentSceneActState 和清理后的战斗状态；idle_travel_next_scene / camp_travel_home_scene 必须由后端写入新的 currentScenePreset、currentSceneActState、currentEncounter 和 runtimeStats.scenesTraveled。前端只播放退场、进场和继续按钮表现，不能用默认 观察/试探/调息 fallback 或本地动画假装推进剧情。旧 bootstrap 快照可能只有 connectedSceneIds / forwardSceneId 而没有 connections，后端生成战后旅行选项时必须兼容这些字段。

RPG / 拼图等运行态存档仍以 /api/profile/save-archives 的后端列表为真相，恢复动作继续走对应恢复接口，但移动端“我的”页已经不再提供独立的 次级入口 > 存档 和设置入口存档按钮；“玩过”弹窗可以继续合并展示可继续存档，个人中心只保留设置、扫码和五项常用功能。移动端“我的”页的五项常用功能宫格只放泥点充值、邀请好友、兑换码、玩家社区、反馈与建议，避免把存档或填邀请码挤入主宫格破坏参考图布局。前端只展示 /api/profile/save-archives 返回的列表并在用户选择后调用对应恢复接口，不能本地拼装或筛选正式存档真相。

拼图

当前拼图链路：

创作入口 -> 图像/描述输入 -> 生成过程页 -> 结果页 -> 试玩 -> 发布 -> 运行态

当前口径：

图像输入复用 CreativeImageInputPanel。
结果页每关画面编辑复用 CreativeImageInputPanel；入口页和关卡画面只共享受控 UI 模块，不共享数据源、状态、action 或存储位置：入口页继续写 formDraft 与草稿编译 payload，关卡画面写 levels[].pictureReference/pictureDescription 并触发 generate_puzzle_images。结果页删除独立“素材配置”Tab，不再提供单独 UI 背景生成入口。通用图片面板的展示图和 AI 重绘参考图能力必须分开控制：结果页正式关卡图只作为预览图，不因存在正式图自动暴露 AI 重绘开关；只有本地上传、历史选择或已保存 pictureReference 可作为重绘参考图时，才显示 AI 重绘开关并把状态带入 generate_puzzle_images。用户在本次编辑中上传或选择历史图后，该图优先占据主图卡片，可删除、切换 AI 重绘，也可关闭 AI 重绘直用；仅有正式图预览时，画面描述框仍可上传多张参考图。关卡详情弹窗应使用加宽面板，关卡名称、画面图和画面描述合并在同一个纵向列表中，名称输入和画面编辑模块外层不再包独立 platform-subpanel；画面图卡仍必须保留稳定最小高度，避免弹窗内 flex-1 布局坍缩后只剩标题、描述输入和操作按钮。
历史图片选择弹窗只展示缩略图与生成时间，不展示从对象路径或文件名解析出的图片名称；选中历史图后内部兜底文案统一使用“历史素材”。
支持画面描述生图、多参考图生图、上传或历史生成主图后 AI 重绘、上传或历史生成主图后不重绘；主链要求浏览器先经 /api/assets/direct-upload-tickets 直传 OSS 并确认 asset_object，创作 action 只提交 referenceImageAssetObjectId(s)，由后端校验 owner / bucket / kind / MIME / size 后签发 OSS 只读 URL 并下载为 VectorEngine /v1/images/edits 的 multipart image part。本地上传 Data URL 与历史 /generated-* 图片路径仅保留为旧草稿、旧入口或未迁移客户端的兼容输入；关闭 AI 重绘时，后端统一解析为首关或当前关卡正式图后再持久化，不调用第一段拼图首图生成。
草稿生成会先持久化 generationStatus=generating 的作品摘要，生成完成并回写关卡拼图画面、关卡画面参考图、UI spritesheet 和关卡背景图后再变为 ready；当前不自动生成背景音乐。生成页步骤推进必须跟随后端 session progressPercent 的真实里程碑：88 表示草稿编译完成并进入出图步骤，94 表示生成图已保存并进入 UI / 背景步骤，96 表示正式图与 UI 背景已确认并进入写入步骤，最终 action 成功或发布才进入完成态；每个步骤内部可以按实际等待时间使用假进度平滑推进。88/94/96 只负责切换当前步骤，不作为总进度地板；总进度按已完成步骤权重加当前步骤内假进度推导，非完成态最多停在 98%。任一同步 action 回包到达时立即以真实完成/失败结果冻结进度。
作品架拼图草稿的“生成中”遮罩只表示初始草稿还没有可查看结果；只要作品摘要、首关封面或任一关卡候选图已经可用，后续 UI 背景重生成和追加关卡生图都必须作为结果页局部生成态处理，不能阻止打开草稿结果页。生成失败后，同一浏览器会话内的失败 notice 必须覆盖后端可能仍短暂返回的 generationStatus=generating 摘要，作品架保留对应草稿卡但不再显示“生成中”，点击后回到失败 / 重试状态。
拼图草稿编译是长耗时 action，前端 action 请求默认等待 1_800_000ms（30 分钟）且不自动重试。每次图片生成调用的预期用时按 90 秒计算，但 生成拼图首图 单独按 4 分钟展示；完整 AI 重绘路径为 编译首关草稿 8 秒、生成关卡名称 10 秒、生成拼图首图 4 分钟、生成关卡画面 90 秒、生成UI与背景 90 秒、写入正式草稿 10 秒，合计约 448 秒。上传图且关闭 AI 重绘时必须跳过 生成拼图首图，直接进入 生成关卡画面 和 生成UI与背景，合计约 208 秒。生成页恢复时必须使用后端 session updatedAt 或作品摘要 updatedAt 作为原始 startedAtMs；失败/完成态用 finishedAtMs 冻结耗时。生成完成后若自动进入草稿试玩，进入 /runtime/puzzle 前必须先把 /creation/puzzle/result 和当前 sessionId/profileId/workId 写成浏览器历史前一站；运行态返回按钮和系统返回都应回到结果页，不得退回生成进度页或暴露重新生成入口。未收到对应后端里程碑前，后续步骤保持待处理；即使当前步骤预计时长耗尽，也只能让当前步骤内部进度停在 98% 内，不能自动完成当前步骤或跳到后续步骤。生成页每个步骤只展示标题和进度，不展示步骤详细描述。
前端创作、结果页、生成页和错误提示不展示 GPT / Gemini 等具体模型名称；如需在内部保留模型路由，UI 只使用“标准模式”“创意模式”等产品化名称。
若浏览器锁屏、息屏或网络切换导致 compile 请求失败，前端在标记失败前必须先复读 getPuzzleAgentSession(sessionId)；只有最新 session 仍缺 draft.coverImageSrc、首关 coverImageSrc 或候选图时才展示失败，复读到已生成草稿时按成功收尾、刷新作品架并继续自动试玩/结果页链路。
拼图参考图 AI 重绘走 VectorEngine /v1/images/edits；无参考图时走 /v1/images/generations。两者模型都使用 gpt-image-2，参考图由后端作为 multipart image part 传入编辑接口。
每次新建关卡生成或重新生成关卡图都必须由 api-server 串起当前关卡资产包：AI 重绘开启时第一段沿用草稿生成第一关的拼图主图提示词配置和模型 / 尺寸 / 参考图规则生成 coverImageSrc/coverAssetId 作为关卡拼图画面和结果页预览图，提示词来源同样按显式画面描述、关卡画面描述、草稿摘要顺序回退，且固定要求输出画面比例为 1:1；上传图且关闭 AI 重绘时跳过这一段，把上传图或历史图持久化为 sourceType=uploaded 的正式候选。随后用正式候选图作为参考，9:16 生成完整拼图游戏关卡画面并写入 levelSceneImageSrc/levelSceneImageObjectKey，提示词必须要求道具按钮上不要显示次数标注，且返回按钮和设置按钮旁禁止标注文字；UI spritesheet 与关卡纯背景在关卡画面完成后并发生成，spritesheet 用 1:1、1k 先生成单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景图，后端上传 OSS 前必须把绿幕扣成透明 PNG，再写入 uiSpritesheetImageSrc/uiSpritesheetImageObjectKey，按钮顺序固定为返回、设置、下一关、提示、原图、冻结，按钮素材自身保留对应中文文字，返回和设置按钮不得额外生成白色外圈、白底圆环或浮雕外框；纯背景用 9:16、1k 写入 levelBackgroundImageSrc/levelBackgroundImageObjectKey，提示词必须包含“禁止在背景中出现人像或和拼图画面中主体一致的内容”。运行态不直接使用第二段完整关卡画面，但必须持久化它用于追踪和后续再生成。结果页局部关卡生成进度按 AI 重绘开启约 270 秒、关闭 AI 重绘约 180 秒展示。
结果页允许多关卡并行编辑和生成；某一关卡图片生成完成回包只静默更新该关卡素材与生成态，不得自动打开或切换关卡详情面板，避免打断用户正在编辑的其它关卡。
结果页关卡图片生成只标记对应关卡的局部生成进度，不禁用“新增关卡”、其它关卡详情编辑和结果页导航。
结果页单关测试只能把完整草稿持久化，并通过 levelId 指定运行态起始关卡；不得把单关快照作为整份草稿调用 updatePuzzleWork，否则 source session 和作品 profile 的 levels 会被覆盖成单关，退出重进后其它关卡会丢失。
拼图试玩和正式运行态刷新恢复不复用创作私有 query。进入 /runtime/puzzle 时必须写入 runtimeProfileId、草稿 runtimeSessionId、可选 runtimeLevelId、公开作品 work 和 mode=draft|published；进入运行态的导航顺序必须先切到 /runtime/puzzle，再写这些 runtime query，避免被阶段导航清掉后刷新停在“正在进入拼图关卡”。
结果页生成关卡图时若关卡名为空，前端必须传 shouldAutoNameLevel=true，后端复用首关命名契约先按画面描述生成关卡名，再在图片生成后用视觉命名结果精修，并把生成名和 UI 背景提示词随本次关卡快照写回。
拼图运行态背景优先读取当前关卡 levelBackgroundImageSrc/levelBackgroundImageObjectKey，旧数据才兼容 uiBackgroundImageSrc/uiBackgroundImageObjectKey；本地试玩、直达指定关卡和正式 next-level 推进时，目标关卡缺关卡背景时必须继承同作品首个可用关卡背景，仍缺失时才沿用当前运行态快照背景或默认 UI。运行态按钮视觉优先读取当前关卡 uiSpritesheetImageSrc/uiSpritesheetImageObjectKey，先按透明 alpha 自动边界检测识别 spritesheet 中的独立按钮展示矩形，再按原图位置从左到右、从上到下映射到返回、设置、下一关、提示、原图、冻结；同一组件还要按较高 alpha 阈值派生紧致点击热区，透明留白和柔边低 alpha 区域尽量不响应点击。检测失败时回退旧固定六格裁切，缺失时才用现有图标按钮兜底。有 spritesheet 时，返回、设置和下一关的点击容器只提供透明点击区，不再叠加默认白色圆形底、胶囊主按钮底或额外文字；下一关按钮在通关弹窗和底部入口中都直接使用 spritesheet 裁切出的 next 素材作为按钮本体。底部提示、原图、冻结三枚素材按检测矩形的原始宽高比显示，不能强行拉伸成正圆或铺满整列。底部道具区不再使用连片胶囊背景，提示、原图、冻结三个按钮均匀分布；运行态只展示按钮素材本身，不额外叠加“提示 / 原图 / 冻结”文字。
推荐页本身不是登录门禁入口，未登录用户点击底部或侧边栏的推荐 Tab 应直接进入嵌入运行态，不主动打开登录弹窗。推荐页嵌入运行态必须按真实身份分流：已登录用户或本地已有 access token 时，正式 runtime 启动与后续局内动作继续走账号 Bearer；只有确认为匿名访客时才申请并透传 runtime guest token。平台壳统一通过 buildRecommendRuntimeRequestOptions(...) 为各玩法的 start / checkpoint / finish / input / drop / click / restart / time-up / leaderboard / next-level 等动作生成局部 request options，不允许每个玩法各写一套匿名分支。后端 /api/runtime/* 正式运行态写请求统一接受 RuntimePrincipal，可识别账号用户和匿名 runtime guest；推荐卡片的后台读写请求仍使用 local auth impact，避免单卡 401 清空整站登录态。创作、个人作品、删除、发布、Remix 等账号或所有权动作仍保持普通用户鉴权。
推荐页作品队列只能通过 buildPlatformRecommendFeedEntries(...) 生成，首页卡片窗口、桌面推荐格、嵌入 runtime 自动启动和上一条 / 下一条切换都必须消费同一队列。不得在首页和 PlatformEntryFlowShellImpl 内分别按“最新列表顺序”和“评分推荐顺序”各算一套相邻作品，否则连续切换会出现视觉上跳过作品或回跳。
推荐页作品信息区的分享按钮统一唤起发布分享弹窗 PublishShareModal，不在推荐卡内部单独拼接分享文案或只做剪贴板复制反馈；拼图推荐作品的 H5 分享链接继续沿用 /gallery/puzzle/detail?work=...，其它统一公开作品默认走 /works/detail?work=...。微信小程序 WebView 内复制动作必须改为小程序 pages/web-view/index 路径并补齐 targetPath=/works/detail 与 work 参数。推荐页当前 active 作品必须通过 wx.miniProgram.postMessage 同步给原生 web-view 页，让右上角系统“转发给朋友”和“分享到朋友圈”也使用当前作品参数生成小程序短链背后的 path。微信小程序 WebView 内的推荐页运行态需要启用分享快照安全区，把游戏画面等比缩放并保持在页面中部，避免用户直接点击小程序自带“分享到聊天”时只截到游戏画面局部。
拼图运行态棋盘不叠加分块蒙版、描边、阴影、选中底色或合并块 SVG 轮廓；拼图片本体需要裁切为圆角形状，单块使用独立圆角裁切，合并块使用 SVG 原生 clipPath 裁切整体外轮廓，外凸角和内凹角分别计算半径，内凹角半径要比外凸角更明显以避免手机 WebView 中看起来仍是直角。原图道具只在用户主动确认后打开独立原图查看层，不在当前拼图棋盘上叠加原图。
拼图运行态拖拽必须完全跟随手指或鼠标位置，pointermove 期间即时写入可见拼块的 transform，不依赖等待后端回包、React 重渲染或下一帧动画队列；进入拖动后不展示拼块选中态或“已选择”提示，松手后再提交目标格同步规则真相。
拼图运行态的提示、设置等点击弹层跟随当前运行态主色主题，使用普通圆角主题面板，不复用像素九宫格素材框。
拼图运行态壳层自身要补齐 platform-ui-shell / platform-theme / platform-theme--light|dark，不能依赖外层平台壳来提供主题变量；/puzzle 直达页和平台内嵌页都必须渲染同一套主题语义类。
拼图运行态顶部关卡信息采用游戏化铭牌样式：橘棕横向关卡名牌承载 第 N 关 和关卡名，左侧固定使用 media/logo-runtime-hud.webp 卡通形象小图；倒计时作为下挂米白小牌独立显示，紧贴铭牌但不遮挡棋盘。该样式只改变运行态 HUD 视觉，不改变计时、暂停、失败同步或关卡推进规则。
拼图运行态进行中关卡的 elapsedMs 仍是结算字段，设置面板的“当前用时”必须按 startedAtMs、暂停累计和冻结累计实时派生；不要直接把进行中的 currentLevel.elapsedMs 当作展示值。
推荐页嵌入拼图运行态时，通关结算弹层必须挂到页面级 fixed 浮层，不能留在推荐卡片视觉区内的 absolute 覆盖层；推荐页滑动卡片和运行态视口都使用 overflow: hidden，半屏内容区会裁剪排行榜、下一关按钮和相似作品卡。
推荐页嵌入拼图运行态时，“下一关”应优先切到相似作品；如果当前推荐候选为空，才回退到同作品下一关，避免匿名推荐流在多关卡作品上持续停留在同一作品内。下一关请求 pending 期间必须保留当前 PuzzleRuntimeShell 和棋盘，不得把推荐卡整体切回 加载中... 占位态；局部同步状态由拼图运行态自己的 busy 表现承接。后端返回的新关卡属于其它作品时，前端必须同步 selectedPuzzleDetail、推荐页 puzzleGalleryEntries 缓存和 activeRecommendEntryKey，让底部作品信息、分享 / 点赞 / 改造和下一次“下一个”基准都指向新作品。
推荐页里的拼图作品如果从运行态进入“改造”结果页，返回平台后要清掉推荐嵌入态的 activeRecommendEntryKey / activeRecommendRuntimeKind / isStartingRecommendEntry，再重新按推荐页自动启动逻辑进入作品，不能复用已经被清空的旧 puzzleRun。
拼图运行态允许前端低延迟交互表现，但通关、排行榜、奖励和作品状态仍以后端确认为准。

跳一跳

对外名称：跳一跳。工程域：jump-hop。PRD 见 docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md。

当前定位为竖屏俯视角 2D 平台跳跃模板，链路对齐平台创作闭环：

创作入口 -> 主题输入 -> 生成过程页 -> 结果页 -> 试玩 -> 发布 -> 运行态

创作入口配置事实源仍是 SpacetimeDB creation_entry_type_config：默认 visible=true、open=true、badge=可创建、subtitle=主题驱动平台跳跃、image_src=/creation-type-references/jump-hop.webp。旧库中仍停留在 subtitle=俯视角跳跃闯关 且 image_src=/creation-type-references/puzzle.webp 的系统默认行会在入口配置播种流程中自动迁移；同时 spacetime-client 的入口配置读模型也会对同一条旧系统默认行做纠偏，避免订阅缓存长期回放老口径。后台手动改过的跳一跳入口配置不被覆盖。

素材生成规则固定为：

创作端只保留主题输入，作品标题、简介、标签和地块提示词由系统派生；
v1 不再单独生成角色图片，运行态固定使用抠除白底后的陶泥儿 logo 透明 PNG 作为玩家角色；
地板贴图只调用一次 image2，输出一张 1024x1536 竖版、3列*6行、单一纯洋红 #FF00FF key 安全缝 / 外圈背景的立方体主题物体 UV 展开图集；image2 要生成 18 个完整 1x1x1 立方体主题物体包装，每个大单元格内部固定为 4列*3行 UV 网：第 1 行第 2 列为 top，第 2 行依次为 left / front / right / back，第 3 行第 2 列为 bottom，其它 UV 空位保持纯洋红。每个大单元格的六个面必须属于同一个方块化主题物体，top/front/right/back/left/bottom 之间的果皮、切面、籽点、条纹、果柄、叶片等身份特征要连续一致，不能把同一张纹理重复六次，也不能六面各画互不相关的小图标。水果主题应生成 18 种可一眼辨认的方块水果 UV，例如方块苹果、方块香蕉、方块橙子、方块西瓜、方块草莓、方块葡萄、方块奇异果、方块菠萝、方块柠檬、方块桃子、方块梨、方块蓝莓、方块芒果、方块椰子、方块火龙果、方块樱桃、方块哈密瓜、方块石榴；苹果需要果柄叶片跨 top/front，香蕉需要剥皮条带跨 front/right，橙子需要放射切面跨 top/front，西瓜需要红瓤黑籽和绿皮条纹在各面连续。禁止文字、UI、底座、托盘、圆台、地板垫层、落地投影、接触阴影、方形阴影、洋红描边、紫色底边、粉色脏边、彩色光晕、发光边、透明背景、留白、自然圆形水果、自然长条香蕉、孤立水果照片、小型贴纸、纯果皮材质、纯果肉纹理、纯叶脉纹理和无法分辨具体物体的抽象纹理；真实透视、极小倒角、侧壁厚度和阴影统一由运行态 Three.js 标准 1x1x1 等比立方体生成。后端只把洋红 key 作为图集安全边界处理，先按 3x6 大单元格切出 18 个方块，再按每格 4x3 UV 网切出 108 张 256x256 不透明面贴图，不再运行透明化抠图、最大 alpha 连通主体保留或透明安全边补白；若裁切后仍残留极少洋红 key 色，会转成不透明材质底色。前端和后端默认 tilePrompt 都必须使用“立方体主题物体 UV 展开包装图集 / cube object UV unwrap atlas”的口径，不再提交“正面30度主题物体 / 平台素材 / 跳台 / 地块成品 / 地砖 / 材质贴片 / 平铺纹理”等会把模型拉回 2D 地块、平台或单纯材质的词，后端生成前也会清洗旧草稿遗留的这些词；当主题或地块提示词命中宝可梦 / 神奇宝贝 / 口袋妖怪 / Pokemon / Pikachu / 精灵球等宝可梦相关词时，仅生图请求侧改写为“原创幻想萌宠冒险道具 / 彩色冒险能量球 / 黄色闪电萌宠符号”，用户草稿标题和主题展示不改；
背景底图同样由 image2 生成，复用现有 coverComposite / coverImageSrc 作为运行态背景读写字段，OSS 槽位固定为 background/image.png；提示词必须严格以用户主题关键词为背景主题，结构以左右两侧氛围为主，中央纵轴 1/2 区域保持少元素、简洁、可读且有纵深感，两侧允许更强立体层次和行进感；背景只作为底图，禁止生成跳板、地块、落脚物、角色、UI、返回按钮、文字、路径箭头或海报排版；左上角返回按钮不允许画进背景，而是单独生成 backButtonAsset 透明 PNG，OSS 槽位固定为 back-button/image.png，提示词要求标准圆形、主题色材质包装、居中左箭头、纯绿色 key 背景，后端去绿后写入作品 profile；
后端按从上到下、从左到右均匀切分为 tile-01 到 tile-18，每个方块再持久化 tile-XX-top/front/right/back/left/bottom 六个独立 slot/path，不能按重复的 tileType 复用槽位；tileAssets[].faceAssets 保存六面贴图，历史兼容字段 imageSrc/imageObjectKey/assetObjectId 写 top 面作为旧单贴图 fallback；运行态只有在六面 faceAssets 完整时才启用 Three.js 立方体贴面，旧作品没有完整 faceAssets 时只走 DOM 图片 / 原型兜底层，不再把单张旧贴图强行贴到立方体所有面；
结果页只展示陶泥儿 logo 透明角色预览、地块池预览和首屏 2 地块预览；不再提供旧角色图生成槽；移动端结果页必须由结果页根容器承接纵向滚动并保留底部安全区，确保素材预览较长时仍能下滑到返回编辑、试玩和发布按钮；
前端跳一跳创作 client 的创建会话与执行生成动作请求都必须使用 20 分钟等待窗口，避免背景底图、返回按钮去绿、地板贴图图集切片和 OSS 写入仍在后端执行时被共创会话默认 15 秒超时中断。

待解决问题（风险程度：高）：跳一跳创作链路目前仍是一次 HTTP 请求内串行生成背景底图、返回按钮、地板贴图图集、切片和 OSS 写入；VectorEngine image2 单步 timeout/connect 失败会在后端最多重试 5 次，而前端只有 20 分钟总等待窗口。若某次背景底图生成接近或超过 18 分钟，前端会先报“请求超时，请稍后重试”，但后端可能继续跑完并在数分钟后写入草稿；同时因为背景、返回按钮和图集等中间资产未按阶段落库，同一 session 超时后重试会重新从背景图开始生成，存在重复生图、重复计费、用户误以为失败、作品架状态短时间不一致的风险。后续应将跳一跳生成改为后端任务化 / 可轮询真实阶段进度，并在每个素材阶段成功后写入可恢复状态；同时收口后端全局生成 deadline、前端等待策略和失败态回写，确保超时、重试和最终成功不会互相打架。

生成页“当前跳一跳信息”只展示实际参与创作提示词的主题、地块提示词等用户可理解信息；stylePreset 等未参与当前 image2 提示词组装的内部风格枚举不得作为兜底内容展示，避免把 minimal-blocks、paper-toy 等工程值暴露给创作者。

运行态地块刷新规则固定由后端路径快照决定：后续地块只会出现在当前地块正负 45 度方向，当前版本已有的最远相邻地块间距作为各难度 max_gap，每次新地块距离按 seed 在 max_gap * 55% 到 max_gap 之间随机，距离不允许为 0。前端可见窗口不得再把目标块强制放到固定屏幕坐标，而必须按服务端真实相邻距离缩放投影；最大距离沿用当前固定视觉间距，较近距离沿同一 45 度方向靠近当前块。

运行态规则真相必须沉到 module-jump-hop，前端只做长按蓄力、角色位移、投影和落地反馈。失败、成功跳跃次数、游戏时长冻结、运行态快照和发布作品状态以后端为准。v1 不保留公开 combo / perfect / 通关语义，旧 score 兼容映射为成功跳跃次数。公开列表应走 jump_hop_gallery_card_view 订阅缓存，不要每次 HTTP 请求调用 procedure 组装全量列表。

每屏只展示 2 个地块：当前地块和目标地块，不再展示下一预览地块。平台流按同一 seed 无限生成，服务端每次补齐路径时只能把下一块生成在当前脚下块的正 45 度或负 45 度方向上，世界坐标满足 abs(next.x - current.x) == next.y - current.y；前端不得自行生成正式路径，只能按服务端路径方向把当前两块可见窗口投影成左上 / 右上 45 度布局，并把当前脚下地块偏向目标反侧，给目标地块留出更大视野空间。运行态 HUD 顶部只保留返回按钮和成功跳跃次数，不展示计时器或右上角重开按钮；生成背景和游戏舞台必须覆盖整个运行态视口，HUD 直接绝对定位压在背景上，不再用外层白底、居中窄栏、卡片边框或游戏区域圆角裁切背景。返回按钮固定在左上角安全区，交互热区固定为移动端 56px、桌面约 62px，不显示“返回”文字，并通过顶部锚点微调与得分标题牌保持协调；运行态优先使用独立 backButtonAsset 透明 PNG 作为真实可点击按钮图，旧作品缺失该字段时才使用同尺寸 CSS 主题色圆形按钮兜底。上方成功跳跃次数 UI 复用拼图模板顶部 HUD 结构：puzzle-runtime-header-card 内包含陶泥儿 IP logo、居中的“得分”标题牌，以及下挂 puzzle-runtime-timer-card / puzzle-runtime-timer 居中数字卡；数字卡展示成功跳跃次数而不是倒计时。游玩中不显示左下角“进行中”状态，也不在屏幕底部常驻排行榜。排行榜按作品维度展示玩家 ID、成功跳跃次数和游戏时长；每位玩家只保留 1 条最佳记录，排序固定为 成功跳跃次数 desc -> 游戏时长 asc -> 更新时间 asc，并只在失败结算弹窗内展示，弹窗保留重开和返回动作。

运行态渲染分层固定为：舞台底层 .jump-hop-runtime__scene-backdrop 优先使用 coverComposite / coverImageSrc 中的 image2 背景底图，图片读取继续走平台资产换签，没有背景时才回退到内置渐变；Three.js 场景层复用同一份标准 1x1x1 等比极小倒角立方体几何体，按地块自身真实规格计算当前 / 目标地块尺寸，并且只有在 tileAssets[].faceAssets 六面贴图完整时才把生成切片作为主题身份方块包装贴图加载到立方体表面；六面贴图通过换签或 blob 异步解析时，Three.js 平台 mesh 的刷新签名必须纳入 top/front/right/back/left/bottom 六面 texture URL，任一面 URL 变化都要重建平台材质，不能只监听旧单图 imageSrc 或基础 render key；玩法坐标把 Z 轴作为立方体竖直高度，运行态必须把逻辑 top 映射到 Three.js +Z 顶面，材质数组按 Three group 顺序写入 right / left / back / front / top / bottom 并按每面 UV 朝向做翻转校正；单块地板统一绕玩法竖直 Z 轴自转 45°，让玩家稳定看到顶面和两个侧面，不做 Y 轴偏航，也不得把 x/y/z 缩放成扁盒子；Three.js 方块模型边长在当前基础上视觉放大 1 倍，但只改变模型显示尺寸，不改变平台中心点、上一轮 max_gap * 55% 到 max_gap 的随机相对间距和蓄力换算；后端命中 footprint 必须严格等于当前视觉完整顶面，不论何时都不得额外收缩或放宽；地块材质使用 alphaTest 裁边但不得放进透明材质队列，避免透明排序把地块画到角色之上；运行态采用约 1.69x 近距相机、45° 下压视角和更紧凑的可见地板间距，当前脚下地块根据目标方向偏向场地反侧，目标地块向上展开，侧壁、倒角、透视和软椭圆阴影均由 Three.js 统一表现；地块从出现开始保持真实规格，不再按当前 / 目标 / 远近或预览状态叠加倍率缩放，视觉远近只由相机和 Three.js 投影决定；Three.js 平台、Three.js Sprite 角色和 DOM fallback 层必须保持屏幕 X 轴同向，不得通过反向 camera.up 或镜像 wrapper 把平台层左右翻转，否则会出现地块显示在右侧但蓄力与飞行动画朝左侧的反向错觉；DOM 地块图片层只作为资产换签、预加载、WebGL 不可用和测试环境 fallback，Three.js 平台层 ready 后必须隐藏 DOM 地块图片和 DOM 阴影，避免露出旧原型方块或双层闪现；旧作品没有完整 faceAssets 时不启用 Three 平台层，继续显示 DOM 图片 / 原型兜底层；推进期存在旧地块退出保留时，Three 平台层必须继续承接 3D 地块渲染，旧地块只跟随后续相机推进逐步离屏，不播放独立飞走动画，超过屏幕后自然销毁；图片读取继续走平台资产换签，并以 assetObjectId 作为刷新键避免重生成后沿用旧签名或旧图片缓存。角色主路径使用 Three.js Sprite 承载 public/branding/jump-hop-taonier-character.png 陶泥儿 logo 透明 PNG，开局脚点必须位于初始地块顶面中心，Sprite 脚点必须按当前方块半高抬到顶面中心高度且绘制顺序高于地块；DOM 角色层仅在 WebGL 或角色贴图加载失败时兜底，并使用同一个顶面中心屏幕锚点，不得额外锚到地块侧面或阴影中心。长按蓄力、计时刷新和角色位置变化只能更新 refs 或 DOM 状态，不得销毁重建透明画布、背景、平台贴图预加载层或角色层，否则会造成背景、地块和角色层频闪。

跳一跳当前长按蓄力手感统一采用 chargeToDistanceRatio=0.004，用于把长按时长换算成世界跳跃距离；如果历史路径仍保存其它系数，start_run 会在开局归一化到新系数。用户按住画面开始蓄力，松手立即起跳；跳跃朝向永远由角色当前脚点指向下一块地块顶面中心，前端不再提交拖拽方向，后端即使收到旧客户端的 dragVectorX/dragVectorY 也必须忽略。实际落点只由蓄力时长换算出的跳跃距离决定，成功判定只使用下一块地块完整可见顶面 footprint：后端以该地块 width/height 按 45° 顶面投影得到的完整菱形区域作为命中区，必须严格和视觉方块顶面效果对齐，禁止隐藏收缩命中区。落点进入该视觉顶面则成功，未进入则失败；地块侧面、底面、投影阴影和旧 landingRadius/perfectRadius 半径范围都不算正确落点，旧半径字段只保留兼容读写，不再作为当前命中真相。蓄力中角色只做垂直压缩，不沿目标方向拉伸；蓄力反馈可显示朝向下一块顶面中心的轻量引导。当前调参验证阶段，按住蓄力时允许显示一枚实时预测落点指示器，位置必须复用同一套前端预测结果：先按真实脚点到下一块顶面中心计算 landedX/landedY，再把该世界坐标投影到当前窗口和 Three.js 顶面脚点屏幕位置，不得用当前地块中心或屏幕线性插值替代；松手或取消时隐藏，不参与后端裁决、不写入作品配置。松手后运行态必须立即生成 visualJump，用当前角色真实脚点作为起点、前端预测真实落点作为终点，播放约 560ms 的角色飞行动画：视觉预测必须使用当前显示窗口的 current/next 地块作为方向来源，即使后端最新 run 已提前返回，也不能拿新 run 目标配旧窗口角色导致下一跳反向；角色沿当前脚点到下一块顶面中心方向弹向预测真实落点，成功也不得强制吸附回目标地块中心。若后端新 run 晚于飞行动画返回，角色必须停在预测真实落点等待；新 run 到达后应优先用 lastJump.landedX/landedY 映射出的真实落点显示角色，成功跳跃在飞行动画结束后保留约 300ms 落地停顿，再把显示态切到后端最新 run，并用约 1440ms 的相机层推进过渡承接新窗口，避免先飞过很远再瞬间拉回地块或刚落地就立刻拉镜头。推进时地块层和角色层统一包在同一个 camera layer 下移动，旧当前地块只随相机推进保留在屏幕后方，不单独执行向上 / 向下飞走动画；玩家继续向前跳时，旧地块继续被新的相机推进带离视口，超过离屏阈值后自然销毁，新目标地块从上方露出，禁止用 p1/p2 各自 top/left 过渡造成角色和地块不同步。相机层推进必须同时使用 X/Y 偏移，从旧真实落点位置斜向滑到新当前地块聚焦位置，不得先横向瞬切到居中再纵向滑动。地块从出现开始保持自身真实尺寸，不得通过当前 / 目标 / 远近 / 预览状态附加 CSS scale(...) 或深度倍率；推进期只做统一相机层位移，远近变化交给相机和 Three.js 真实投影。相机推进期间 DOM 兜底角色自身必须禁用 left/top transition，只允许父级 camera layer 负责位移，否则角色局部坐标切换和相机推进会叠加，表现为落地后又从屏幕外闪回。

平台首页推荐、精选、最新、公开详情、搜索、已玩作品和公开试玩统一按 sourceType='jump-hop' 与 JH-* 公开作品号识别跳一跳作品；从公开详情或推荐流启动运行态时，若卡片摘要不足以携带地板贴图图集和路径配置，必须先补读完整 work profile 再传入运行态。结果页草稿试玩调用启动 run 时必须把 runtimeMode=draft 写进请求 body，不能只放在请求选项里；正式作品深链和推荐流使用 published 默认模式。/runtime/jump-hop?work=JH-* 这类正式深链必须先通过公开作品号回读 gallery detail，再以 profileId 启动 published run；直接打开没有 work 参数的 /runtime/jump-hop 时不能停留在空运行态或“正在加载内容”，应回到平台首页。平台壳层必须同步注册 jump-hop-workspace、jump-hop-generating、jump-hop-result、jump-hop-runtime、jump-hop-gallery-detail 阶段，并在 appPageRoutes.ts 映射 /creation/jump-hop、/creation/jump-hop/generating、/creation/jump-hop/result、/gallery/jump-hop/detail、/runtime/jump-hop，同时持有 session、work、run、gallery、busy/error 与生成进度状态，避免只合入渲染分支但遗漏状态源或分享路径导致 typecheck 失败、刷新回首页。

跳一跳作品架走创作中心的统一作品列表：前端通过 /api/creation/jump-hop/works 拉取作品摘要，草稿态会与 pending notice 合并后显示在作品架里，已发布作品点击后会先按 profileId 读取完整详情再进入详情或运行态。生成中作品仍以后端摘要里的 generationStatus 为准，刷新后应能恢复等待遮罩，不能只依赖内存 notice。

跳一跳作品架删除入口必须走 /api/creation/jump-hop/works/{profile_id}，并通过 SpacetimeDB 同步删除 work profile、源 session、运行态 run 与事件，再刷新作品架和公开广场；不得只做前端本地隐藏。

推荐页匿名游玩不再限定为跳一跳。移动端一级 推荐 Tab 是内嵌运行态刷卡流，会自动选择推荐作品并启动对应玩法；移动端首次进入或刷新站点时弹出一次欢迎提示，说明移动端仅支持作品展示、体验创作工具需使用电脑端访问，用户点击 好 后关闭；本次页面生命周期内站内导航或切换下方页签不再弹出。桌面端首页不启动这套移动推荐运行态，而是渲染桌面发现壳，展示 今日游戏、推荐、作品分类 等桌面内容。推荐页候选顺序由前端轻量推荐算法 platformRecommendation.ts 统一生成：先按公开作品 key 去重，再使用公开读模型已有的精选来源、近 7 日游玩、点赞、改造、总游玩、发布时间新鲜度、封面和标签完整度做确定性评分，最后优先交错不同玩法类型；只要还有其它玩法候选，就不要连续推荐同一玩法，只有候选池已没有其它玩法时才允许同玩法相邻。该算法不得新增前端业务真相或绕过公开作品 read model。断点事实统一走 platformEntryResponsive.ts 的 usePlatformDesktopLayout()，平台壳和首页视图必须共用同一个判断，避免桌面发现页与移动推荐页同时挂载、重复触发请求或启动运行态。移动端推荐页拿到推荐作品列表后必须预加载每个作品的卡片封面、主封面和玩法兜底封面；启动或切换作品时先展示当前带玩法标签和标题的作品卡面遮罩，嵌入 runtime 在卡面下层加载，不得再从卡面闪切到另一层单独纯封面图。作品切换提交后，当前 runtime 遮罩接手已在屏幕上的卡面时必须瞬时贴合，不允许再执行“卡面到同一卡面”的淡入或重绘过渡；推荐页 runtime 必须通过统一 ready 门控等待对应运行态 run / profile、lazy runtime 组件和 runtime DOM 内图片资源都准备好，且必须持续观察后续新增图片、内联 background-image 和换签中的资源标记，不能只在首次挂载时扫描主图或封面；ready 返回 true 后才由外层放开游戏画面并只让卡面遮罩渐隐。遮罩层级必须高于并隔离下层 runtime，防止运行态 HUD、canvas 或高 z-index 子层穿透到封面上；ready 前不展示“加载中”文案，但封面内必须保留无文案加载动效或进度条，避免用户误以为卡片损坏，也不得把未准备好的运行态直接暴露给用户。切换推荐作品时，如果上一条作品的启动请求、退出收口或目标玩法 busy 状态尚未结束，应继续显示当前作品卡面遮罩并等待下一轮自动启动；只有目标作品启动明确失败时，才显示“作品暂时无法进入，请稍后再试。”这类失败态。推荐页内拼图通关后的同 run 相似作品推进不视为推荐作品切换，不能重新显示启动封面；如果需要跨公开作品进入下一关，则必须走推荐页统一切卡入口，不能复用拼图 runtime 的跨作品 handoff，也不能直接把当前 run 改写到另一个作品，activeRecommendEntryKey 只能由推荐页统一选择下一作品后更新。推荐页嵌入运行态启动时按真实身份分流：已登录用户或本地已有 access token 时继续使用账号 Bearer，但请求选项必须是 local auth impact，避免单卡 401 清空整站登录态；只有确认为匿名访客时才申请短期 Runtime Guest Token，并只把它作为局部请求头传给运行态客户端，不写入全局登录态、不触发 refresh，也不把匿名流量伪装成普通用户。当前覆盖矩阵为：跳一跳、视觉小说、抓大鹅 Match3D、方洞挑战、拼图、敲木鱼、大鱼吃小鱼、汪汪声浪。每个模板的启动请求、推荐页内后续运行态动作以及需要上报的 play/finish/leaderboard/next-level 类请求，都必须继续按该身份分流；公开读取入口仍可匿名读取，创作、个人作品、删除、发布、Remix 等账号/所有权动作仍保持普通用户鉴权。推荐 runtime 的 none / background / runtime-guest 请求计划和拼图 default / isolated runtime auth mode 由 platformRecommendRuntimeAuthModel.ts 统一判定，平台壳只负责读取 token、申请 Runtime Guest Token 和传递 request options。推荐 runtime 自动启动只由 platformPublicGalleryFlow.ts 输出 noop / clear / start(entry) 决策，平台壳只执行清空 state 或启动指定作品。

敲木鱼

对外名称：敲木鱼。工程域：wooden-fish。PRD 见 docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md。

首版定位为单屏点击解压模板，链路对齐拼图的创作闭环：

创作入口 -> 工作台 -> 生成过程页 -> 结果页 -> 试玩 -> 发布 -> 运行态

创作输入固定为：

敲什么：敲击物单图资产槽位。默认模板使用内置透明 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 秒。选择文件或录音结束后，前端只在浏览器本地解码并生成待提交音频对象，不在选择阶段请求 /api/assets/direct-upload-tickets。上传和录音统一裁掉前后声音过小片段，裁切后仍超过 1 秒时提示错误且不写入表单状态；有效音频按浏览器端近似算法做响度平衡，目标为 GY/T 377-2023 口径下的 -15 LKFS，并做峰值保护后重新编码为可上传 Blob。用户点击 生成 时才把处理后的音频直传 OSS、确认 asset_object，创作 session/action 只提交 hitSoundAsset.assetObjectId、audioSrc 和对象 key 等轻量字段；未提供音频时统一写回内置默认木鱼音 /wooden-fish/default-hit-sound.mp3。提示词生成音效入口临时关闭，通用 /api/creation/audio/sound-effect 对木鱼 hit_sound 目标也返回 410 Gone；hitSoundPrompt 只作为历史兼容字段保留，不参与当前创作流程，也不得由 spacetime-client 合成假音频路径。后端对敲木鱼创作 JSON 的放宽 body limit 仅用于兼容旧小程序 Data URL 请求，不作为新链路输入方式。
功德有什么：最多 8 条飘字，创作态首屏只保留一个默认词条 幸运，其下提供加号格继续追加词条；创作态只保存词条名，运行态飘字展示时再追加 +1。运行态顶部总数卡采用品牌化徽标样式，子项计数器预置展示在可展开面板中，未出现词条初始值为 0。
作品标题 / 作品简介 / 主题标签：不再放在创作工作台首屏，改为生成草稿后的结果页补录区，提交试玩或发布前必须先写回当前作品信息。主题标签编辑样式对齐拼图结果页的胶囊标签编辑器。

图片生成链路固定为三图 image2 流程：第一步用默认木鱼图作为结构和画风参考，按用户题材关键词或参考图主题生成 1:1 单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景主体图，prompt 必须显式要求背景严格使用该固定色且平整无纹理、无渐变、无阴影、无道具，主体完整居中，且禁止黑底、白底、棋盘格和任何实底背景；后端在落库前只对这张绿幕主体图执行去绿背景处理，不做泛抠图，避免误伤玉米等主体像素。第二步必须使用第一步抠图完成后的透明图作为参考图，再用新敲击物作为主题和画风参考生成 9:16 背景环境图，背景图只适配主题和画风，不能包含新敲击物本体，也不能增加木槌互动物品；画面中央主体预留区必须干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围。第三步必须使用去绿后的敲击物主体图和背景环境图作为参考图生成 1:1 返回按钮图，返回按钮必须始终是标准圆形，主体视觉尺寸比当前模板再放大约 50%，圆形外沿必须有与主题色搭配的干净外描边，中央只保留单个左箭头，参考图只约束圆形底色和箭头配色，不得延伸到复杂造型和花纹；按钮不得出现文字、数字、水印、额外 UI 面板或木槌物品。三个资产分别写回 hitObjectAsset、backgroundAsset 与 backButtonAsset，并绑定到 wooden_fish_work 的 hit_object / background / back_button 槽位。运行态和结果页消费 backgroundAsset 做竖屏背景，中央再叠加 hitObjectAsset，左上角返回按钮消费 backButtonAsset。

木鱼初始 compile-draft 是长耗时同步 action，生成页必须按上述三图 image2 链路展示进度：整理草稿、生成敲击物、生成背景环境图、生成返回按钮图、写入正式草稿。本地或供应商慢时一次 action 可能持续数分钟；前端不得把已关闭的提示词生成音效当成进度阶段，也不得在未收到 action 回包前宣称生成完成。

运行态规则真相以后端 run 摘要为准，前端只做点击低延迟表现、敲击动画、音频播放和飘字渲染。每次非功能区点击在当前 run 内累计 totalTapCount 和 wordCounters；计数不进入账号长期账本，不做排行榜。顶部总数卡点击后展开子项计数器面板，子项计数在面板中按词条纵列预置展示，未出现词条初始值为 0，后续同词条继续累加；运行态左上角使用主题化返回按钮图，不提供右上角重开按钮。

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

拼消消

对外名称：拼消消。工程域与 playId：puzzle-clear。公开作品码前缀：PC-。当前按新增玩法 SOP 接入完整公开闭环，不复用拼图运行态规则本体。

链路为：

创作入口 -> 轻表单工作台 -> 生成过程页 -> 结果页 -> 试玩 -> 发布 -> 统一作品详情 -> 正式运行态

工作台字段固定为作品标题、简介、主题词、场地底图主题词 boardBackgroundPrompt、中央场地底图槽位、是否 AI 生成底图。中央场地底图必须复用 CreativeImageInputPanel，支持上传、历史图和 AI 重绘；若用户填写 boardBackgroundPrompt，AI 生成底图只读取该字段，字段为空时才回退读取 themePrompt；用户上传底图时不再用主题词重写该资产。中央场地底图的字段名保留平台口径，但实际语义是玩家逐步消除清空棋盘后露出的主题目标图，生成尺寸必须与中央棋盘一致，按 1:1 正方形出图；prompt 必须强绑定主题、画面精致、强表现力并一眼体现主题，不再要求“画面干净”或“适合作为卡牌棋盘底图”。运行态必须把中央场地底图作为棋盘内部静态底图使用，不能降级成整页氛围背景；卡牌消除后产生的空位和拖拽源位应露出该棋盘底图。卡面背面背景 v1 使用默认占位图，不作为创作者配置项。规则参数不开放编辑：单关 6x6、每局 10 分钟、35 次目标消除、形状解锁、防死局发牌和半锁定规则均由后端规则集固定。

素材生成使用拼消消专用编排，但必须复用 platform-image、VectorEngine gpt-image-2、OSS、asset_object、换签和失败审计。素材目标是 4 张 1024x1536 竖版工作表，每张后台按 4 列 x 6 行 裁切，每格 256x256；服务端从工作表切出总计 95 个 1x1 卡牌碎片，再合成一张 10x10 / 2560x2560 最终 atlas。复合图案组总数固定为 35，形状配比固定为 1x2=23、1x3=5、2x2=4、2x3=3。服务端先预排每个复合图案组的 sheet 布局、最终 atlas 坐标和形状，再按坐标切成 1x1 卡牌碎片作为运行态素材；sheet 生图 prompt 只能要求复合图案组可按后台 4x6 均等切成 1x1 方形小份，不能让模型在小图案上绘制切分线、边框、网格线、编号或裁切参考线。当前只有单关，同关内复合图案不重复。草稿编译和发布都必须使用 api-server 已持久化的真实 atlas / card assets，拒绝缺失、空对象键或 placeholder 占位素材，不允许 spacetime-client 或 SpacetimeDB 侧合成临时素材绕过平台图片底座。

运行态规则：

单关固定为 6x6 / 35次消除。
每局固定 10 分钟；超时只判当前关失败，可重试当前关。
当前关直接出现 1x2、1x3、2x2 和 2x3。
开局棋盘随机铺满并保证至少一步可解；补牌后也必须由后端保证至少一步可解。
顶部卡牌准备区按纵列补位，某列有空格时该列卡牌从顶部下落。
非 2 格消除时，补牌不得破坏已完成局部；只有玩家主动交换或撞入才允许打散半锁定拼接组。
正式 runtime 只消费后端 snapshot 与 action 结果；前端负责开局翻转、拖拽、掉落、消除和弹层动画。拖拽手感必须对齐拼图模板：开局小卡片只翻转一次，交换落位不得重新翻牌；按住后可见卡片立即跟随鼠标或手指，源位置即时留出空槽；放下时被替换卡片要快速飞向对应空位；已完成局部拼接组要以连续整体呈现并可作为整组拖起。拖拽浮层必须挂到页面级 document.body portal，避免平台壳层 transform 让 position: fixed 和 clientX/clientY 坐标系错位。
正式 published run 的终态事件使用 run-finished 和 level-failed，事件结果 JSON 至少包含 status、level、clears、clearDelta 和 elapsedMs，供基础统计与排障回读。

新增阶段为 puzzle-clear-workspace、puzzle-clear-generating、puzzle-clear-result 和 puzzle-clear-runtime；路由为 /creation/puzzle-clear、/creation/puzzle-clear/generating、/creation/puzzle-clear/result 与 /runtime/puzzle-clear。API 命名空间为 /api/creation/puzzle-clear/* 与 /api/runtime/puzzle-clear/*。验证命令见 docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md 与 docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md。

抓大鹅 Match3D

对外名称：抓大鹅。工程域：match3d。

入口表单只展示：

题材主题。
难度：轻松、标准、进阶、硬核。

入口不再要求用户选择素材风格；历史草稿和旧接口中的 assetStyleId / assetStyleLabel / assetStylePrompt 仅作为兼容字段保留，新入口提交不再写入这些字段。

难度映射：

难度	clearCount	difficulty	总物品数	物品种类
轻松	8	2	24	3
标准	12	4	36	9
进阶	16	6	48	15
硬核	21	8	63	20

当前素材生成流水线：

点击生成前弹出泥点确认，草稿初始生成成本来自后台入口契约 creationTypes[].unifiedCreationSpec.mudPointCost；抓大鹅完整草稿生成按该值一次性预扣，汪汪声浪初始三张图按该值分摊到三次素材请求，结果页单图重新生成仍按单图资产操作计费。
先写入可恢复草稿 profile，再执行文本计划、关卡整图生成、三张派生图生成、OSS 上传和素材解析；作品摘要在背景、UI spritesheet 或物品 spritesheet 未完整时下发 generationStatus=generating，完整后下发 ready，草稿完成条件不包含 backgroundMusic。
首次调用 VectorEngine gpt-image-2，无参考图，竖屏 9:16，生成完整抓大鹅关卡画面并持久化到 generatedBackgroundAsset.levelSceneImageSrc/levelSceneImageObjectKey。提示词必须包含用户主题描述、顶部返回 / 标题倒计时 / 设置按钮、中间与主题匹配且贴横向边缘的容器，以及底部“移出 / 凑齐 / 打乱”三个道具按钮。
关卡整图完成后并发发起三次 gpt-image-2 编辑请求，三者都以关卡整图作为参考图：1K、1:1 的 UI spritesheet 写入 uiSpritesheetImageSrc/uiSpritesheetImageObjectKey；1K、9:16 的背景图写入 imageSrc/imageObjectKey；2K、1:1 的物品 spritesheet 写入 itemSpritesheetImageSrc/itemSpritesheetImageObjectKey。
UI spritesheet 提示词固定要求按从上到下、从左到右整理单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景素材：返回按钮、设置按钮、方格素材（不含边框，仅保留一个）、移出按钮、凑齐按钮、打乱按钮；后端上传 OSS 前必须把绿幕扣成透明 PNG。背景图提示词固定要求移除全部 UI 组件和容器内含物，完整保留容器和背景，并补全被 UI 覆盖的背景内容。
物品 spritesheet 固定 10行*10列、统一单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；素材间距严格均匀分布，每一行包含两种物品，每种物品五个不同形态，物品来自参考图中心容器中的 2D 素材，严禁高相似度物品。新流程每次解析并持久化 20 种物品，物品信息列表全部展示这 20 种；后端切 generatedItemAssets[].imageViews[] 时优先按透明 alpha 连通域识别真实素材矩形，再按原图从上到下、从左到右排序，每 5 个区域组成一个物品的五个形态；只有识别出的区域数量不足时才回退 10*10 固定网格。持久化单格映射元数据仍按 row = itemIndex / 2 + 1、col = itemIndex % 2 * 5 + viewIndex + 1 写入通用系列素材图集，不能再用 row = itemIndex + 1。generatedItemAssets[].imageViews[] 仍兼容已切好的五视角图，缺失时运行态和编辑器按 spritesheet 自动解析结果回退。
前端和运行态统一使用 alpha 连通域矩形检测解析 spritesheet：UI 图先把识别出的透明素材矩形按行聚类，再在每一行内按横向 x 坐标排序，最后按返回、设置、方格、移出、凑齐、打乱顺序映射回原 UI 位置；不能只按全局 y 坐标排序，否则同一行素材上下略有错位时会把方格和底部道具按钮顺序打乱。物品图按检测顺序每 5 个区域组成一个物品的五个形态，最多 20 个物品。透明背景是解析前提，不能在前端按固定像素坐标写死切片。
文本生成物品名称时必须同时生成 itemSize，只允许 大、中、小。该字段随 generatedItemAssets[].itemSize 持久化并下发；历史缺失字段的素材按 大 兼容，模型缺失或非法值按物品名本地推断。
当前抓大鹅音频生成关闭：入口无 生成音效，草稿不生成背景音乐或点击音效，结果页不展示背景音乐 Tab 或点击音效生成入口。历史 backgroundMusic / clickSound 字段继续兼容传递。
背景、UI spritesheet、物品 spritesheet 和历史容器兼容字段的持久化真相仍在 generatedItemAssets[].backgroundAsset 与提升后的 generatedBackgroundAsset；Agent session、work summary/detail、结果页和运行态入口都必须把该字段提升为 backgroundImageSrc/backgroundImageObjectKey/generatedBackgroundAsset 读取。草稿编译后的 draftJson 自身也必须携带 generatedItemAssets 快照；HTTP facade 不能只依赖 work detail 回读补齐 UI 资产，外部回读为空时也不得清空草稿内已有的背景 / 图集。平台壳层从作品架、广场、生成完成回调、结果页保存 / 发布 / 试玩回调进入 Match3D profile 时也要先归一化并提升，避免首次试玩、手动试玩、推荐流或公开详情运行态退回默认背景。

结果页当前结构：

作品信息：名称、描述、标签；封面编辑收口到发布面板。
难度配置：四档离散拖动条，显示需要消除、总物品数、物品种类、已生成物品种类。
素材配置 > 物品：两列素材卡固定展示 20 个物品，点击打开独立五视角预览面板；支持删除、批量新增和批量重新生成。替换模式必须保留原 itemId 和列表顺序。
素材配置 > UI素材：预览背景图、UI spritesheet 原图、物品 spritesheet 原图和物品 spritesheet 自动解析缩略图；背景图只支持预览，不提供重新生成入口。UI 预览必须复用运行态顶部 HUD、中央容器棋盘和底部槽位样式，不单独维护一套简化预览 UI。

运行态当前口径：

规则真相在后端；前端只做即时表现、点击候选、飞入、入槽、三消和胜负过渡。
物品选择只在 pointerup 时提交；pointerdown / pointermove 只更新候选样式。松手时按当前位置和最新快照命中一个最上层可点击物品；生成 2D PNG 物品必须按当前展示图的 alpha 像素做热区精筛，透明像素、object-contain 留白和 itemSize 缩小后的空白区不能响应点击。
物品 DOM 只负责展示，不通过自身 click 事件直接提交，避免浏览器后续 click 绕过松手判定造成重复提交。
初始物品坐标围绕容器口中心生成，并保留内缩安全距离，避免贴边和局部角落聚集。
本地试玩与 Rust module-match3d 后端领域生成使用同一套中心铺开口径；生成点覆盖四象限且均值接近中心。
运行态优先消费 2D 生成图；默认积木 / 程序化 3D 表现只作为视觉分支和兜底，不改变规则真相。
难度只决定本局加载的物品种类数量：轻松 3、标准 9、进阶 15、硬核 20。硬核仍保留 21 次消除和 63 件总物品，运行态按 20 种素材循环复用，不要求生成第 21 种素材。
运行态启动前要预加载 generatedItemAssets[].imageViews[]、顶层 generatedBackgroundAsset、物品挂载 backgroundAsset 中的背景、UI spritesheet 和物品 spritesheet；首次生成自动试玩、结果页手动试玩、推荐流和公开详情启动都必须传入提升后的 profile。卡片摘要缺图集字段时，进入运行态前必须补读 work detail。补读后的 profile 也要再次提升 generatedItemAssets[].backgroundAsset，确保背景和图集字段传给 Match3DRuntimeShell。
背景图作为运行态全屏背景，图内已经保留容器；旧 containerImage* 只作为历史透明容器兼容字段。若 containerImage* 与 uiSpritesheetImage* 同源，运行态不得把 UI spritesheet 当中心容器图叠到棋盘上。
抓大鹅运行态 HUD 需贴近拼图顶部信息条的视觉口径：左上只保留透明返回按钮；右上不再暴露设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板和同造型，并在牌面左侧挂上 media/logo-runtime-hud.webp 产品 logo 小图；下方备选栏和道具图标只保留内容与交互边界，不再显示灰白半透底板；中央容器图层视觉可隐藏，但棋盘命中边界仍保留。
generated 私有图换签未完成时，局内物品先隐藏等待，不得短暂显示默认积木；同一批资源在重启 run 时保留已解析签名 URL，只有资源源列表变化或换签失败后才允许进入兜底视觉。
itemSize 只缩放生成 2D 图片本体：大、中、小 均按相对尺寸缩放，其中 大 也比原始图片略小，中 和 小 进一步缩小；不改变后端下发的布局半径、点击半径或三消规则。
物品进入底部物品栏时按同类型插入：如果物品栏已有同类物品，新物品插到该类型最后一个物品后面，后续物品整体后移；没有同类时追加到当前末尾。达到三件同类时，在飞入物品栏动画结束后，左侧和右侧同类物品向中间合成，三件一起消失，播放合成音效，不展示星星图标，后面的物品再向前补位。该动效只是前端表现层，后端和本地试玩仍负责权威插入、指定点击类型清除与补位后的槽位快照。
抓大鹅运行态不渲染右上角设置入口，也不在局内直接暴露重新开始按钮；结算弹层仍保留结果态的再来一局动作。
高 DPR 移动端 WebGL canvas 必须锁定 CSS 尺寸，避免右下溢出。

发现页不再挂载前端固定官方抓大鹅静态 demo；公开卡片、作品号搜索、详情页和运行态启动只能来自后端真实 profile / gallery 投影。正式公开作品统一走 server runtime adapter，前端不得再用本地 demo profile 绕过后端统计和运行态链路。

视觉小说

当前视觉小说只吸收外部 TXT 玩法的创作与运行经验，不迁入外部平台社区、支付、榜单、私有存档或回放。

入口收敛为：

一句话创作输入。
横向视觉画风选择。
生成过程页。
结果页。

资产引用统一走平台资产对象：

文档上传走 /api/assets/direct-upload-tickets、OSS 直传、/api/assets/objects/confirm 和 /api/assets/read-url。
文档只把 assetObjectId 放入 sourceAssetIds，不要在前端状态或 SpacetimeDB 保存大 Data URL。
封面、场景、角色立绘和音乐写平台 asset id 或 generated 引用。
运行时图片渲染使用 ResolvedAssetImage 换签。

视觉小说禁止新增回放 / 录制 / 复盘类功能。npm run check:visual-novel-vn11 继续作为负向扫描门禁。

汪汪声浪 Bark Battle

对外名称：汪汪声浪大作战。工程域：bark-battle。

当前领域语言：

有效声浪触发：麦克风归一化响度在冷却结束后达到阈值的一次计分输入。
能量条：玩家与对手当前声浪优势的连续对抗刻度，推到玩家或对手一侧边界时本局立即结算。
主题 / 竞技背景描述：配置字段为 themeDescription，用于生成竞技背景并表达整体场景，不再使用 themePreset 或狗狗皮肤预设。
玩家 / 对手形象描述：配置字段为 playerImageDescription / opponentImageDescription，对外统一称“形象描述”，不再称“角色设定”。
后端裁决结果：后端根据 start run 与 finish 派生指标校验后的正式单局结果。
基础统计：只记录正式 published run 的开始、结算和派生指标，草稿试玩不写正式统计。
公开广场：统一读取 bark_battle_gallery_view 这类 read model，不再由前端自己拼公开列表。
创作者信息：统一作品详情和公开广场都必须展示后端返回的 authorDisplayName，不得只在详情页内层可见；草稿 Tab 作品架遵循平台作品架统一口径，无论草稿 / 已发布都不外露作者信息。
拟声词：配置字段为 onomatopoeia。创作者未手动编辑时，前端根据主题 / 竞技背景描述、玩家形象描述和对手形象描述生成高能词池；创作者手动编辑后按自定义词池发布。默认词池只在命中狗相关主题时加入狗叫词，不能把非狗主题强行带回狗语义。

当前入口默认开放：visible=true、open=true、badge=可创建，入口参考图使用 /creation-type-references/bark-battle.webp。创作入口使用 7 字段表单（作品标题、简介、主题 / 竞技背景描述 themeDescription、玩家形象描述、对手形象描述、拟声词、难度）；提交后先进入 bark-battle-generating 独立生成页，自动生成玩家形象、对手形象和竞技背景三图。生成页即使部分槽位失败也要继续落到结果页，失败槽位保留错误态和单槽重试入口，不在生成页停留。结果页只保留单槽重试、重新生成和上传，不再展示一次生成按钮、音频配置入口、皮肤预设入口或排名配置。发布成功后先跳统一作品详情页 /works/detail?work=BB-xxxxxxxx，正式 published runtime 从作品详情页进入并必须使用真实麦克风；draft 可试玩，可使用 mock 输入，且不写正式统计。统一作品详情和广场列表展示创作者名称；草稿 Tab 作品架不外露创作者名称，已发布作品只在右上角常驻分享入口。

移动端创作 Tab 内嵌 Bark Battle 表单时，只保留外层 Tab 面板承担纵向滚动；表单自身移动端不再创建独立纵向滚动容器，底部“生成草稿”按钮作为普通表单尾部并保留 safe-area 底部间距，避免与最后一组输入框、移动端键盘或底部 TabBar 形成套滚动 / 遮挡。

创作流程为：

创作 Tab 表单：填写作品标题、简介、主题 / 竞技背景描述、玩家形象描述、对手形象描述、拟声词和难度。拟声词支持换行、逗号、顿号、斜杠或竖线分隔；未手动编辑时随主题 / 形象描述自动重算，手动编辑后保持创作者自定义。
草稿编译：POST /api/creation/bark-battle/drafts 写入配置 JSON，返回包含 draftId、稳定 workId、configVersion 和 rulesetVersion 的草稿结果。
生成页：bark-battle-generating 自动并行产出玩家形象、对手形象和竞技背景三图；前端生成页 UI 和其它玩法保持同一圆环主视觉，media/create_bg_video.mp4 作为固定全屏页面背景层循环静音播放，主进度圆环居中展示总进度，只保留当前步骤名称和当前步骤进度，不再渲染三行槽位列表。视频层需要显式触发播放。三图都走 Bark Battle 专用后端生图接口 POST /api/creation/bark-battle/images/generate，由后端按 player-character、opponent-character、ui-background 分别拼装正式提示词、写入 generated-bark-battle-assets 私有资产前缀并返回实际 prompt。玩家 / 对手形象提示词必须保持用户形象描述，不强行注入狗相关主体，并要求正面、单个完整形象和透明背景。部分失败也继续进入结果页。
结果页：围绕三图槽位展示错误态与已生成结果，只保留单槽重试、重新生成和上传，不再提供一次生成按钮、音频配置入口或排名配置；生成回写 partial_failed 时作品架不再显示整卡“生成中”遮罩，由结果页槽位错误承接失败。
手动上传：结果页通过平台资产直传 /api/assets/direct-upload-tickets 与 /api/assets/objects/confirm 写入私有资产，再把返回的历史 generated 路径写回草稿配置。
发布：结果页确认后必须携带草稿返回的同一个 workId 和结果页最终 publishedSnapshot 调用 POST /api/creation/bark-battle/works/publish；SpacetimeDB 发布态的 config_json 必须使用该最终快照，works summary 若拿到 publishedSnapshotJson 也优先使用最终快照映射封面三图。发布成功后先进入统一作品详情页，再由详情页进入正式 runtime；缺少 workId 的旧草稿状态需要重新生成草稿。
作品架：Bark Battle 草稿 / 已发布列表优先读取后端 /works，但创建、生成完成、保存或发布后的本地摘要必须在后端 read model 尚未回读到同 workId 前继续保留；创作中心作品架同时接入 pending shelf 兜底，避免 ready 且三图齐全的草稿在刷新窗口期从“我的草稿 / 已发布”中消失。草稿三图完整性、pending_assets / partial_failed / ready 生成状态归一和作品摘要合并规则统一由 barkBattleWorkCache.ts 承接，平台壳只执行读取、刷新与 React state 副作用。
试玩与正式 runtime：草稿试玩使用 runtimeMode=draft 和 mock 输入，不写正式 run；正式 runtime 使用 runtimeMode=published，进入运行态后直接申请真实麦克风权限，授权成功后立刻进入倒计时，启动对局时调用 POST /api/runtime/bark-battle/works/{workId}/runs 登记 start run，并以返回的 runtimeConfig 作为本局前端规则参数；结算时调用 POST /api/runtime/bark-battle/runs/{runId}/finish 写入基础统计派生指标；对局会在能量条推到任一侧边界时提前结算并弹出独立结算弹窗，运行态内固定提供返回按钮。发布快照拼装、发布回包缺图时沿用草稿图，以及草稿 / 已发布作品进入前端 runtime 前的 BarkBattlePublishedConfig 映射也统一由 barkBattleWorkCache.ts 提供，缺失 publishedAt 时仍按 updatedAt 兜底。

支持的创作者可替换内容：

基础信息：作品标题、简介、主题 / 竞技背景描述（themeDescription）、玩家形象描述、对手形象描述和难度。
生成素材：玩家形象、对手形象和竞技背景三个槽位可单槽重试、重新生成或上传；形象图保持正面和透明背景，不把非狗形象描述改写成狗。
拟声词：最多保留前 24 个有效词；默认池按狗、机甲 / 科技、幻想 / 骑士等主题补充高能短词，并叠加通用“炸场 / 破阵 / 声浪拉满”等基础词。局内只要有效声浪触发就随机快速展示，避免连续重复。
运行态输入：正式 runtime 必须真实麦克风；草稿试玩允许 mock，不写正式统计。

这些创作字段写入 Bark Battle 配置 JSON，发布后由 runtime 和基础统计链路读取；对局时长、反作弊校验和后端裁决仍由规则集与后端控制，不能通过前端替换项改变。当前声浪触发口径为前端默认阈值 0.35、有效触发冷却 150ms，后端 BarkBattleRuleset 的 min_bark_gap_ms 也保持 150ms，用于正式成绩校验的物理触发上限。历史排名相关后端字段暂保留兼容，但 v1 公开闭环不展示音频、皮肤预设或排名配置入口。

方洞挑战

工程域：square-hole。当前链路具备 agent session、work profile、runtime run、drop shape、restart、stop、time-up 等后端 procedure 与前端 service。新改动应沿用独立 module-square-hole、shared-contracts 和 spacetime-client，不要挂回 RPG 或拼图语义。

方洞结果页的封面、背景、形状和洞口图片槽位继续归属现有 result edit state 与 PUT square-hole work 保存链路；在 Expo / Tauri 原生壳声明 file.importImage 时，“上传图片”优先调用 HostBridge 系统图片选择器，并把返回的图片内容副本转换为当前槽位 imageSrc，普通浏览器、小程序和未声明能力的壳仍保留浏览器文件输入。

大鱼吃小鱼

工程域：big-fish。当前保留创作会话、素材槽、事件、运行态 run、gallery、like、remix 和 play 记录。新创作和运行态规则应继续通过后端 profile / run 投影，不把运行态结果写成纯前端事实。

儿童向玩法

当前包含：

baby-object-match：宝贝识物当前入口状态为 visible=true、open=true，创作 Tab 展示为“可创建”，进入宝贝识物创作、生成、结果页、试玩和发布链路；资产生成接口为 /api/creation/edutainment/baby-object-match/assets。入口关闭只允许通过 SpacetimeDB / 后台入口配置显式调整，默认种子和 debug 兜底都必须保持可创建。
baby-love-drawing：宝贝爱画本地 demo，魔法生成接口为 /api/creation/edutainment/baby-love-drawing/magic。
child-motion-demo：儿童动作识别热身关。真实动作数据来自 mocap WebSocket，不要把浏览器摄像头视频流当作主动作数据源；发现页的寓教于乐频道同时提供独立热身关入口，点击后进入 /child-motion-demo。

创意互动 Agent

创意互动内容生成 Agent 的长期方向是用感知、思考、记忆、行动、反思、协作闭环理解文字、图片或文档，并选择模板生成草稿。当前 Phase 1 以拼图模板闭环为主；Agent 填充和修订模板字段，最终仍落到具体玩法的草稿契约和后端编排。

通用资产规则

供应商密钥不得进入前端、文档示例或 Git。
生成资产写入 OSS 后，前端读取前必须通过 /api/assets/read-url 换签。
生成失败时，后端应返回可操作 details.reason / details.missingEnv，前端优先展示具体原因。
半配置 OSS 不应阻断 api-server 启动；具体生成或换签接口在需要时返回配置缺失。
历史 generated path 可以兼容读取，但新链路不要把裸 path 当公开静态资源。
发现页 / 推荐流公开作品卡封面必须兼容旧移动浏览器内核：封面容器不能只依赖 CSS aspect-ratio 撑高，必须保留 16:9 或对应沉浸卡比例的可见高度兜底；generated 私有封面换签失败时要回落到玩法类型参考图，避免卡片整体黑底。

107 KiB Raw Permalink Blame History Unescape Escape