Merge remote-tracking branch 'origin/master' into codex/bark-battle

docs/README.md

@@ -13,7 +13,7 @@
   重点补充：RPG 创作与运行时脚本职责地图见 [RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md](./reference/RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md)。
 - [埋点查询](./tracking/README.md)：埋点原始事件与聚合投影的本地 SQL 查询。
 - [运营查询](./operations/README.md)：任务、领奖、钱包对账等后台核查查询。
-- [PRD](./prd/README.md)：产品需求与阶段计划；参考 MOKU / 幕间类 AI 文游的陶泥儿 `text-game` 模板口径见 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md)，视觉小说模板 TXT 玩法平台化接入口径见 [AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md](./prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)，创意互动内容 Agent Phase 1 的 LangChain-Rust PoC、拼图闭环和并行任务拆分见 [CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md](./prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)，幸存者类模板闭环见 [AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md](./prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md)，后台管理独立前端工程见 [ADMIN_WEB_CONSOLE_PRD_2026-04-30.md](./prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md)，方洞挑战创作、发布与试玩闭环见 [AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md](./prd/AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)。
+- [PRD](./prd/README.md)：产品需求与阶段计划；参考 MOKU / 幕间类 AI 文游的陶泥儿 `text-game` 模板口径见 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md)，视觉小说模板 TXT 玩法平台化接入口径见 [AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md](./prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)，创意互动内容 Agent Phase 1 的 LangChain-Rust PoC、拼图闭环和并行任务拆分见 [CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md](./prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)，幸存者类模板闭环见 [AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md](./prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md)，后台管理独立前端工程见 [ADMIN_WEB_CONSOLE_PRD_2026-04-30.md](./prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md)，方洞挑战创作、发布与试玩闭环见 [AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md](./prd/AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)，跳一跳俯视角玩法模板 PRD 见 [【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md](./prd/%E3%80%90%E7%8E%A9%E6%B3%95%E5%88%9B%E4%BD%9C%E3%80%91%E8%B7%B3%E4%B8%80%E8%B7%B3%E4%BF%AF%E8%A7%86%E8%A7%92%E7%8E%A9%E6%B3%95%E6%A8%A1%E6%9D%BFPRD-2026-05-19.md)。
 
 生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。
 

docs/prd/BABY_OBJECT_MATCH_EDUTAINMENT_TEMPLATE_PRD_2026-05-11.md

@@ -1,4 +1,4 @@
-# 宝贝识物寓教于乐模板 PRD 2026-05-11
+# 宝贝识物寓教于乐模板 PRD 2026-05-11
 
 ## 1. 目标
 
@@ -32,7 +32,7 @@
 5. 游戏视觉主题包；
 6. 作品标签。
 
-素材使用 VectorEngine `gpt-image-2-all` / image-2 生成。图片生成只能走后端接口，前端不得读取、拼接或暴露 `VECTOR_ENGINE_API_KEY`。
+素材使用 VectorEngine `gpt-image-2` / image-2 生成。图片生成只能走后端接口，前端不得读取、拼接或暴露 `VECTOR_ENGINE_API_KEY`。
 
 为降低生成成本，创作提交后只生成两张原始图片：一张 `2x2` 素材 sheet 和一张单独场景背景图。`2x2` 素材 sheet 固定包含左上物品 A、右上物品 B、左下篮子、右下礼物盒。服务端必须按固定格切图，并把物品、篮子和礼物盒转成透明 PNG。只有透明抠图后的两个物品素材才允许写入草稿 `itemAssets` 并进入游戏运行态。左右手位置指示器属于运行态默认规则，使用项目内置静态素材，不在每次创作时生成。
 

docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md

@@ -0,0 +1,485 @@
+# 跳一跳俯视角玩法模板 PRD 2026-05-19
+
+## 1. 目标
+
+新增一个可创作、可试玩、可发布的玩法模板：
+
+```text
+跳一跳
+```
+
+本模板参考拼图模板的创作闭环，沿用“创作入口 -> 生成过程页 -> 结果页 -> 试玩 -> 发布”的平台链路，但玩法本体改为俯视角 / 等距视角的跳跃闯关。
+
+首版要求：
+
+1. 初始草稿生成时，角色形象单独调用一次生图；
+2. 初始草稿生成时，地块只调用一次生图，输出 3D 视图的 2D 图片图集；
+3. 运行态不接真实 3D 网格，不生成 GLB / glTF；
+4. 作品可以直接进入试玩和发布。
+
+## 2. 模板定位
+
+模板 ID：
+
+```text
+jump-hop
+```
+
+用户展示名：
+
+```text
+跳一跳
+```
+
+体验关键词：
+
+1. 俯视角；
+2. 等距感地块；
+3. 单局闯关；
+4. 长按蓄力，松手起跳；
+5. 轻量休闲。
+
+首版采用竖屏优先的移动端体验，桌面端保持居中展示，画面比例以 `9:16` 为主。参考图的核心视觉要点是：
+
+1. 大面积留白或浅色渐变背景；
+2. 角色站在单个地块上；
+3. 地块有明显顶面、侧面和投影；
+4. 整体是俯视角 / 等距视角，而不是横版平台跳跃；
+5. UI 克制，只保留必要控制，不堆说明文案。
+
+## 3. 与拼图模板的复用边界
+
+可以复用：
+
+1. 创作入口和模板分流；
+2. 生成过程页；
+3. 结果页的草稿保存、返回编辑、试玩、发布、分享链路；
+4. 作品架展示和草稿恢复口径；
+5. 平台统一的发布与公开展示流程。
+
+不复用：
+
+1. 拼图关卡切片逻辑；
+2. 拼图拖拽拼块逻辑；
+3. 拼图 UI 背景和多关卡编辑结构；
+4. 任何方格拼合语义。
+
+## 4. 工程接入范围
+
+首版需要做到完整玩法闭环，不只做入口占位。
+
+新增前端阶段：
+
+```text
+jump-hop-workspace
+jump-hop-generating
+jump-hop-result
+jump-hop-runtime
+jump-hop-gallery-detail
+```
+
+新增前端组件建议：
+
+1. `src/components/jump-hop-creation/JumpHopWorkspace.tsx`；
+2. `src/components/jump-hop-result/JumpHopResultView.tsx`；
+3. `src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`；
+4. `src/services/jump-hop/jumpHopClient.ts`。
+
+新增共享契约建议：
+
+1. `packages/shared/src/contracts/jumpHop.ts`；
+2. `server-rs/crates/shared-contracts/src/jump_hop.rs`。
+
+新增后端模块建议：
+
+1. `server-rs/crates/module-jump-hop`：纯领域规则，包含路径生成、蓄力换算、落点判定、通关 / 失败状态机；
+2. `server-rs/crates/api-server/src/jump_hop.rs` 和 `src/jump_hop/` 子模块：HTTP handler、生成编排、资产保存和 DTO 映射；
+3. `server-rs/crates/spacetime-module/src/jump_hop.rs`：session、work profile、runtime run、公开 view 和 reducer / procedure；
+4. `server-rs/crates/spacetime-client/src/jump_hop.rs`：api-server 访问 SpacetimeDB 的 facade；
+5. `server-rs/crates/api-server/src/modules/jump_hop.rs`：路由挂载。
+
+入口配置事实源必须走 SpacetimeDB `creation_entry_type_config` 默认种子和后台配置接口，不新增前端硬编码入口配置。
+
+## 5. 创作输入
+
+创作者需要填写以下内容：
+
+1. 作品主题描述，必填；
+2. 角色形象描述，必填；
+3. 地块风格卡，必选；
+4. 难度，必选；
+5. 可选的终点氛围或节奏偏好。
+
+推荐的最小输入形态是：
+
+1. 一句话主题；
+2. 角色一句话描述；
+3. 风格卡；
+4. 难度卡。
+
+不在首版开放手工拖拽平台编辑器。平台路径、地块间距和终点位置由系统自动生成，创作者只负责风格与难度选择。
+
+### 5.1 地块风格卡
+
+建议提供以下风格：
+
+1. 极简积木；
+2. 纸模玩具；
+3. 霓虹玻璃；
+4. 森林石块；
+5. 未来金属；
+6. 自定义。
+
+### 5.2 难度
+
+建议提供以下离散档位：
+
+1. 轻松；
+2. 标准；
+3. 进阶；
+4. 挑战。
+
+难度主要影响：
+
+1. 平台路径长度；
+2. 平台间距；
+3. 可落点容差；
+4. 完美落点窗口；
+5. 终点前的节奏变化。
+
+## 6. 生成规则
+
+本模板必须把生图责任拆成两条独立链路：
+
+### 6.1 角色形象只生一次
+
+角色形象必须只调用一次生图，输出一张可直接进入运行态的主角色图。
+
+角色图要求：
+
+1. 单人主角；
+2. 全身可见；
+3. 透明背景；
+4. 角色站姿或轻微前倾姿态；
+5. 镜头和透视必须匹配俯视角场景；
+6. 不要求多视角，不要求多帧动画图集。
+
+角色图生成后作为作品级锚点资产使用，结果页、封面合成、试玩和发布都复用同一张图。后续如果只修改标题、标签、难度或路径，不应默认重新生角色。只有用户在结果页明确点击“重生成角色”时，才允许再调用一次角色生图。
+
+### 6.2 地块只生一次图集
+
+地块必须只调用一次生图，输出一张 3D 视图的 2D 图片图集，再由后端切成运行态可用的地块资产。
+
+地块图集要求：
+
+1. 统一使用等距 / 俯视角；
+2. 必须表现出顶面、侧面和投影；
+3. 必须与角色图保持同一光向；
+4. 必须有清晰的立体层次，但仍然是 2D 图片；
+5. 必须包含至少以下地块类型：
+   - 起点地块；
+   - 普通地块；
+   - 目标地块；
+   - 终点地块。
+
+建议额外包含：
+
+1. 奖励地块；
+2. 视觉强调地块；
+3. 风格化变体地块。
+
+图集生成后按地块类型切分并去掉背景，运行态直接消费切好的 PNG，不在前端做复杂拼接。只有用户在结果页明确点击“重生成地块”时，才允许再调用一次地块图集生图。
+
+### 6.3 不新增第三次生成
+
+首版不把封面、分享海报、路径预览再拆成第三次图像生成。封面和分享图必须由角色图 + 地块图集在本地或后端轻量合成，不额外增加新的角色生图次数。
+
+### 6.4 路径元数据
+
+除图片资产外，系统还必须生成跳跃路径元数据：
+
+1. 平台序列；
+2. 平台中心点；
+3. 平台宽度；
+4. 平台间距；
+5. 终点索引；
+6. 评分和容差参数。
+
+路径由领域规则自动生成，创作者不直接编辑坐标。路径元数据不依赖 LLM 或图片生成。
+
+### 6.5 推荐的难度区间
+
+| 难度 | 平台数量 | 平台间距 | 节奏 |
+| --- | ---: | --- | --- |
+| 轻松 | 12 - 14 | 短 | 宽容 |
+| 标准 | 16 - 18 | 中 | 稳定 |
+| 进阶 | 20 - 24 | 中长 | 紧凑 |
+| 挑战 | 26 - 32 | 长 | 高压 |
+
+平台宽度和容差由系统按难度自动缩放，不要求创作者手工填写。
+
+## 7. 契约草案
+
+### 7.1 草稿结构
+
+`JumpHopDraft` 至少包含：
+
+1. `templateId = "jump-hop"`；
+2. `templateName = "跳一跳"`；
+3. `profileId`；
+4. `workTitle`；
+5. `workDescription`；
+6. `themeTags`；
+7. `difficulty`；
+8. `stylePreset`；
+9. `characterPrompt`；
+10. `tilePrompt`；
+11. `characterAsset`；
+12. `tileAtlasAsset`；
+13. `tileAssets[]`；
+14. `path`；
+15. `coverComposite`；
+16. `generationStatus`。
+
+### 7.2 资产结构
+
+`JumpHopCharacterAsset` 至少包含：
+
+1. `assetId`；
+2. `imageSrc`；
+3. `imageObjectKey`；
+4. `assetObjectId`；
+5. `generationProvider`；
+6. `prompt`；
+7. `width`；
+8. `height`。
+
+`JumpHopTileAsset` 至少包含：
+
+1. `tileType`；
+2. `imageSrc`；
+3. `imageObjectKey`；
+4. `assetObjectId`；
+5. `sourceAtlasCell`；
+6. `visualWidth`；
+7. `visualHeight`；
+8. `topSurfaceRadius`；
+9. `landingRadius`。
+
+`tileType` 首版限定：
+
+```text
+start | normal | target | finish | bonus | accent
+```
+
+### 7.3 路径结构
+
+`JumpHopPath` 至少包含：
+
+1. `seed`；
+2. `difficulty`；
+3. `platforms[]`；
+4. `finishIndex`；
+5. `cameraPreset`；
+6. `scoring`。
+
+`JumpHopPlatform` 至少包含：
+
+1. `platformId`；
+2. `tileType`；
+3. `x`；
+4. `y`；
+5. `width`；
+6. `height`；
+7. `landingRadius`；
+8. `perfectRadius`；
+9. `scoreValue`。
+
+### 7.4 运行态快照
+
+`JumpHopRunSnapshot` 至少包含：
+
+1. `runId`；
+2. `profileId`；
+3. `status = playing | failed | cleared`；
+4. `currentPlatformIndex`；
+5. `score`；
+6. `combo`；
+7. `lastJump`；
+8. `startedAtMs`；
+9. `finishedAtMs`。
+
+`lastJump` 至少包含：
+
+1. `chargeMs`；
+2. `jumpDistance`；
+3. `targetPlatformIndex`；
+4. `landedX`；
+5. `landedY`；
+6. `result = miss | hit | perfect | finish`。
+
+## 8. API 草案
+
+HTTP 路由建议：
+
+```text
+POST /api/creation/jump-hop/sessions
+GET  /api/creation/jump-hop/sessions/{sessionId}
+POST /api/creation/jump-hop/sessions/{sessionId}/actions
+POST /api/creation/jump-hop/works/{profileId}/publish
+GET  /api/runtime/jump-hop/works/{profileId}
+POST /api/runtime/jump-hop/runs
+POST /api/runtime/jump-hop/runs/{runId}/jump
+POST /api/runtime/jump-hop/runs/{runId}/restart
+GET  /api/runtime/jump-hop/gallery
+GET  /api/runtime/jump-hop/gallery/{publicWorkCode}
+```
+
+动作类型建议：
+
+```text
+compile-draft
+regenerate-character
+regenerate-tiles
+update-work-meta
+update-difficulty
+```
+
+`compile-draft` 是长耗时动作。前端进入生成页后必须持久化 `generationStatus=generating`，刷新后能从作品架恢复生成页。失败前需要复读 session；如果后端已经完成草稿并写回资产，前端按成功收尾。
+
+## 9. SpacetimeDB 表和 view
+
+建议新增表：
+
+1. `jump_hop_agent_session`；
+2. `jump_hop_work_profile`；
+3. `jump_hop_runtime_run`；
+4. `jump_hop_event`；
+5. `jump_hop_leaderboard_entry`，首版可暂不对外展示；
+6. `jump_hop_gallery_view`；
+7. `jump_hop_gallery_card_view`。
+
+表结构新增字段必须按 SpacetimeDB 迁移规则放在结构体末尾并设置明确默认值。新增或调整表、reducer、procedure、view 后必须同步 `migration.rs`、表目录、生成 bindings，并执行 `npm run check:spacetime-schema`。
+
+公开列表主路径应优先订阅 `jump_hop_gallery_card_view` 后在 `api-server` 本地 cache 构造列表响应，不要让每个 HTTP 请求都调用 SpacetimeDB procedure 组装全量列表。
+
+## 10. 结果页能力
+
+结果页必须展示：
+
+1. 作品标题；
+2. 作品简介；
+3. 角色形象；
+4. 地块图集；
+5. 路径预览；
+6. 标签；
+7. 试玩；
+8. 发布；
+9. 返回编辑。
+
+结果页还必须支持：
+
+1. 单独重生成角色；
+2. 单独重生成地块图集；
+3. 单独修改标题和简介；
+4. 单独调整标签和难度。
+
+结果页不应强制再走一次封面生图。封面只做合成，不新增图像生成调用。
+
+## 11. 运行态规则
+
+运行态采用 2D 表现，但画面视觉上必须保留参考图那种俯视角 / 等距感。
+
+### 11.1 核心玩法
+
+1. 玩家长按蓄力；
+2. 松手后角色按蓄力长度起跳；
+3. 跳跃距离决定是否落到下一个地块；
+4. 落在目标区域内判定成功；
+5. 落在地块外或越界判定失败；
+6. 到达终点地块判定通关。
+
+### 11.2 判定规则
+
+1. 只做一个当前局面的起跳判定；
+2. 不做复杂连招动作树；
+3. 不新增生命数、体力、回合数；
+4. 不新增计时赛作为首版核心规则；
+5. 不把前端动画结果当成最终真相，通关与失败必须能回写运行态状态。
+
+### 11.3 角色动画
+
+角色不需要多帧生图，运行态只通过位移、缩放、轻微旋转和投影变化表达：
+
+1. 蓄力时轻微压缩；
+2. 起跳时向上抬升；
+3. 空中保持可读轮廓；
+4. 落地时轻微弹性回弹；
+5. 失败时从地块边缘跌落。
+
+### 11.4 摄像机与构图
+
+1. 相机以当前角色和下一地块为中心；
+2. 至少保证下一个落点一直可见；
+3. 画面要留出顶部和底部的 UI 安全区；
+4. 不要把地块做得太满，保留参考图那种疏朗感。
+
+### 11.5 UI
+
+运行态 UI 只保留必要元素：
+
+1. 分数；
+2. 暂停；
+3. 重新开始；
+4. 分享；
+5. 结算按钮。
+
+不默认展示大段规则说明。首进如果需要引导，只能用一次轻量提示，不允许常驻一屏的说明文案。
+
+## 12. 视觉规范
+
+本模板的视觉目标是“像 3D，但仍是 2D 图片”。
+
+必须遵守：
+
+1. 平台有明确厚度；
+2. 侧面可见分层或材质变化；
+3. 投影统一且方向一致；
+4. 背景干净，颜色克制；
+5. 角色尺寸在小屏上依然可读；
+6. 地块不能出现过多文字、按钮或装饰信息；
+7. 不能把运行态做成重 UI 面板。
+
+建议的背景策略：
+
+1. 以静态浅色渐变或纯色背景为主；
+2. 不把背景也做成每次都生成的重资产；
+3. 让地块和角色成为画面的第一视觉焦点。
+
+## 13. 发布后体验
+
+发布后的作品必须支持：
+
+1. 进入作品架和公开展示；
+2. 分享；
+3. 试玩；
+4. 重新进入结果页编辑。
+
+发布后的卡片封面应优先由角色图和地块图合成，不要求单独再生成封面图。
+
+首版不新增排行榜、回放和对局对抗。后续如要扩展排行，可另起版本，不要塞进首版模板范围。
+
+## 14. 验收
+
+1. 创作入口能看到 `跳一跳` 模板；
+2. 创作者可以填写主题、角色描述、风格和难度；
+3. 提交后只生成一次角色图和一次地块图集；
+4. 结果页能看到角色图、地块图集和路径预览；
+5. 结果页可单独重生成角色或地块；
+6. 试玩进入跳一跳运行态；
+7. 长按蓄力、松手起跳、落点判定、失败和通关都可用；
+8. 作品可以保存、发布和分享；
+9. 前端不直接读取或暴露生图密钥；
+10. 发布后的封面不依赖第三次额外生图。
+11. `npm run check:spacetime-schema` 在 schema 变更后通过；
+12. `npm run check:encoding` 通过。

docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md

@@ -1,4 +1,4 @@
-# 宝贝识物创作发布实现方案 2026-05-11
+# 宝贝识物创作发布实现方案 2026-05-11
 
 ## 1. 范围
 
@@ -144,7 +144,7 @@ PUT  /api/creation/edutainment/baby-object-match/drafts/{draftId}
 POST /api/creation/edutainment/baby-object-match/drafts/{draftId}/publish
 ```
 
-图片生成必须在后端调用 VectorEngine `gpt-image-2-all`，不得从前端直接调用外部图片接口。
+图片生成必须在后端调用 VectorEngine `gpt-image-2`，不得从前端直接调用外部图片接口。
 
 后端 `2x2` 素材 sheet prompt 约束：
 

docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md

@@ -1,4 +1,4 @@
-# 儿童动作识别互动玩法 Demo 热身关开发规格文档
+# 儿童动作识别互动玩法 Demo 热身关开发规格文档
 
 > 日期：2026-05-09
 > 关联设计文档：[CHILD_MOTION_DEMO_WARMUP_LEVEL_DESIGN_2026-05-09.md](../design/CHILD_MOTION_DEMO_WARMUP_LEVEL_DESIGN_2026-05-09.md)
@@ -684,7 +684,7 @@
 1. 舞台主环境采用卡通绘本风格、明亮草地、天空、小山坡和树木的组合，默认背景环境需要保证中心与下方前景留空，便于角色轮廓和地面指示环叠加。
 2. 该卡通绘本草地风格是儿童动作 Demo 后续场景、物品、UI 资源的全局风格要求；新增资源不得切回暗色科技风、真实照片风或后台面板风。
 3. `src/index.css` 中的热身舞台、摄像头背景层、地面、角色轮廓、地面圆环、开始按钮和横屏提示均按绘本草地风格接入真实资源；资源加载失败时保留 CSS 兜底。
-4. 生成脚本固定为 `scripts/generate-child-motion-demo-assets.mjs`，并通过 `npm run assets:child-motion-demo` 触发；脚本使用 `gpt-image-2-all` 调用 VectorEngine `POST /v1/images/generations`，透明资源先生成品红底源图，再在本地移除色键，源图写入 `tmp/child-motion-demo-assets/`。
+4. 生成脚本固定为 `scripts/generate-child-motion-demo-assets.mjs`，并通过 `npm run assets:child-motion-demo` 触发；脚本使用 `gpt-image-2` 调用 VectorEngine `POST /v1/images/generations`，透明资源先生成品红底源图，再在本地移除色键，源图写入 `tmp/child-motion-demo-assets/`。
 5. 当前已生成并接入以下正式 Demo 资源：
    - `public/child-motion-demo/picture-book-grass-stage.png`：默认草地舞台背景。
    - `public/child-motion-demo/picture-book-foreground-grass-v2.png`：底部前景草坪条，只覆盖舞台下沿，不作为整块地板拉伸。

docs/technical/【后端架构】api-server能力模块化与生成资产Adapter总纲-2026-05-14.md

@@ -214,7 +214,7 @@ Handler 主要在 `story.rs`、`combat.rs`、`runtime_inventory.rs`：
 | Big Fish 正式图 | DashScope `wan2.2-t2i-flash` | 轮询 task 后 HTTP GET 图片 URL | `LegacyAssetPrefix::BigFishAssets` | 由 assetKind 映射主图/动作图/舞台背景等 | `big_fish_session` + session/entity id + slot | `big_fish.rs` 调用方 `execute_billable_asset_operation` | 配置缺失/上游失败直接错误；gallery 对部分 Spacetime 运行错误软降级 |
 | Square Hole 图片重生成 | OpenAI/VectorEngine GPT image helper | URL 下载或 base64/data URL 解码 | `LegacyAssetPrefix::SquareHoleAssets` | 方洞作品图片槽位相关 kind | profile/work + image slot | 调用方包裹 | 生成成功但入库失败保留 Data URL 回包 |
 | Custom World 场景/封面 | VectorEngine GPT image 2 / OpenAI helper | URL 下载或 base64 解码 | `LegacyAssetPrefix::CustomWorldScenes` 等 | scene/cover/opening storyboard | `custom_world_profile` 或 profile/landmark/scene slot | `custom_world_ai.rs` 调用方包裹 | entity/scene 生成存在 LLM fallback；资产持久化失败按当前错误口径返回 |
-| Puzzle 图片 | GPT image 2 generations/edits | multipart/base64/URL 结果归一 | `LegacyAssetPrefix::PuzzleAssets` | puzzle level/background/generated image，另有 `puzzle_background_music` | puzzle profile/run/level slot | `puzzle.rs` 调用方包裹 | connectivity 可按既有规则跳过部分计费；运行态 fallback 保持原逻辑 |
+| Puzzle 图片 | GPT image 2 generations/edits | 无参考图 JSON 创建；有参考图 multipart 编辑；base64/URL 结果归一 | `LegacyAssetPrefix::PuzzleAssets` | puzzle level/background/generated image，另有 `puzzle_background_music` | puzzle profile/run/level slot | `puzzle.rs` 调用方包裹 | connectivity 可按既有规则跳过部分计费；运行态 fallback 保持原逻辑 |
 | Match3D 图片 | APIMart/VectorEngine/OpenAI image helper | 下载、切图、透明化、校准后入库 | `LegacyAssetPrefix::Match3DAssets` | cover/background/item material sheet，音频 kind 另列 | match3d profile/session slot | `match3d.rs` 调用方包裹 | 新草稿不回退 Rodin/GLB；部分连接错误按现有计费跳过规则处理 |
 | Visual Novel 音频 | VectorEngine Suno/Vidu | 任务提交后按 task publish 下载音频 | 视觉小说/creation audio scope | `visual_novel_music`、`visual_novel_ambient_sound` | `visual_novel_scene` + scene id + `music`/`ambient_sound` | `vector_engine_audio_generation.rs` 调用方包裹 | 上游/下载失败显式错误，不混入图片 Adapter |
 | 通用音频 | VectorEngine Suno/Vidu | 同上 | creation audio scope | background_music/sound_effect 由调用方目标指定 | creation target entity/slot | 调用方包裹 | 不与 VN 场景语义混用 |

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -77,13 +77,16 @@ npm run check:server-rs-ddd
 
 1. 每个能力 Module 只暴露 `router(state) -> Router<AppState>`，由 `app.rs` 统一 `.merge(...)`。
 2. `app.rs` 只保留全局 middleware、TraceLayer、request context、tracking middleware、入口开关和少量顶层 glue。
-3. 路由迁移和业务重构分阶段处理；先移动路由装配，再拆 handler 内部实现。
-4. 大 handler 拆分时优先按 `router.rs`、`handlers.rs`、`application.rs`、`assets.rs`、`mapper.rs`、`errors.rs` 分层。`handlers.rs` 只做 Axum extract、鉴权和 request/response，业务规则继续下沉到 `module-*`。
-5. 手写 Rust 模块入口统一使用同名 `.rs` 文件，例如 `puzzle.rs` + `puzzle/*.rs`、`match3d.rs` + `match3d/*.rs`；不要再新增 `mod.rs` 入口。生成的 SpacetimeDB Rust bindings 也由生成脚本同步为 `module_bindings.rs` + `module_bindings/*.rs` 布局。
+3. 能力 Module 可在路由内部用 `FromRef<AppState>` 派生自己的 Feature State，例如 `PuzzleApiState`。全局 `AppState` 仍作为进程组合根、鉴权层和全局中间件状态，但业务 handler 优先只提取对应 Feature State，不直接暴露完整 `AppState`。
+4. Feature State 只暴露该能力实际需要的 facade / adapter / 配置快照；若必须复用仍要求 `AppState` 的横切 helper（例如计费、外部失败审计或通用 tracking），应通过 Feature State 的窄方法或显式 `root_state()` 过渡，并在后续继续收窄。
+5. 路由迁移和业务重构分阶段处理；先移动路由装配，再拆 handler 内部实现，再收窄 handler 可见状态。
+6. 大 handler 拆分时优先按 `router.rs`、`handlers.rs`、`application.rs`、`assets.rs`、`mapper.rs`、`errors.rs` 分层。`handlers.rs` 只做 Axum extract、鉴权和 request/response，业务规则继续下沉到 `module-*`。
+7. 手写 Rust 模块入口统一使用同名 `.rs` 文件，例如 `puzzle.rs` + `puzzle/*.rs`、`match3d.rs` + `match3d/*.rs`；不要再新增 `mod.rs` 入口。生成的 SpacetimeDB Rust bindings 也由生成脚本同步为 `module_bindings.rs` + `module_bindings/*.rs` 布局。
 
 拼图 `api-server` 内部拆分：
 
 - `server-rs/crates/api-server/src/modules/puzzle.rs` 只负责路由装配、鉴权层和参考图 body limit；对外继续引用同一批 handler 名称。
+- `server-rs/crates/api-server/src/state.rs` 中的 `PuzzleApiState` 是拼图 HTTP/BFF 的 Feature State，集中暴露 `SpacetimeClient`、`PuzzleGalleryCache`、OSS client、作者查询所需认证服务、拼图 LLM client 和少量 VectorEngine / Agent 配置快照。拼图 handler 只提取 `State<PuzzleApiState>`，不得重新改回 `State<AppState>`。
 - `server-rs/crates/api-server/src/puzzle.rs` 只作为聚合入口，保留共享 import / 常量、内部模块声明和 handler re-export，不继续承载大段实现。
 - `server-rs/crates/api-server/src/puzzle/handlers.rs` 承接 Axum handler，负责 extract、鉴权上下文、调用 SpacetimeDB facade / 编排 helper，并返回 HTTP/SSE 响应。
 - `server-rs/crates/api-server/src/puzzle/draft.rs` 承接表单草稿保存、草稿编译、首关命名、UI 背景 prompt、降级 snapshot 和初始资产就绪校验。
@@ -101,8 +104,8 @@ npm run check:server-rs-ddd
 - `server-rs/crates/api-server/src/match3d/handlers.rs` 承接 Axum handler，负责 extract、鉴权上下文、调用 SpacetimeDB facade / 编排 helper，并返回 HTTP 响应。
 - `server-rs/crates/api-server/src/match3d/draft.rs` 承接 Agent session、草稿编译、题材 / 难度 / 物品计划和草稿持久化编排。
 - `server-rs/crates/api-server/src/match3d/works.rs` 承接作品 CRUD、封面 / 背景 / 容器资产生成入口、发布 / Remix / 点赞 / 游玩记录和作品级 helper。
-- `server-rs/crates/api-server/src/match3d/item_assets.rs` 承接物品 sheet 生成、绿幕 / 近白底透明化、切图、append / replace / delete / sort / merge 和素材持久化。
-- `server-rs/crates/api-server/src/match3d/vector_engine_gemini.rs` 承接 VectorEngine Gemini 请求体、响应解析、base64 图片下载和上游错误归一。
+- `server-rs/crates/api-server/src/match3d/item_assets.rs` 承接物品生成批次编排、append / replace / delete / sort / merge、计费外层和草稿素材映射；sheet prompt、绿幕 / 近白底透明化、切图和切片持久化复用 `generated_asset_sheets` 通用模块。
+- `server-rs/crates/api-server/src/match3d/vector_engine_gemini.rs` 仅保留历史 VectorEngine Gemini 物品 sheet helper；当前草稿物品 spritesheet 以关卡整图为参考走 `gpt-image-2` 编辑链路，提示词、绿幕透明化和 OSS 持久化由 `item_assets.rs` / `works.rs` 约束。
 - `server-rs/crates/api-server/src/match3d/runtime.rs` 保留运行态轻量归一 helper；`mappers.rs` / `tags.rs` / `tests.rs` 分别承接 DTO 映射、标签 / 通用错误 helper 和原有单测。
 
 该拆分只改变 `api-server` 文件组织，不改变 `/api/creation/match3d/*`、`/api/runtime/match3d/*` route、DTO、error envelope、SpacetimeDB schema、公开 gallery cache 语义、VectorEngine / OSS 副作用边界或计费语义；后续继续细分时也必须先保持行为不变，再单独讨论领域规则下沉到 `module-match3d`。
@@ -114,6 +117,8 @@ npm run check:server-rs-ddd
 3. Adapter 输出应保留 legacy public path、object key、asset object id、MIME、extension、task id 和实际 prompt。
 4. Adapter 不负责扣费、退款或钱包读取；计费仍由调用方显式包裹。
 5. Puzzle、Match3D、音频、GLB、视频等复杂媒体可以复用 OSS + asset object + binding 的底层持久化能力，但玩法专属处理规则留在各自编排层，不塞进公共接口。
+6. 拼图图生图参考图主链不得再把大图 Data URL 塞进创作 JSON body；前端先直传 OSS 并提交 `referenceImageAssetObjectId(s)`，`api-server` 校验 `asset_object` 的 bucket、kind、图片 MIME、大小和 owner 后签发只读 URL 给 VectorEngine 读取，Data URL / `/generated-*` 仅作为旧请求兼容。
+7. 系列素材图集使用 `server-rs/crates/api-server/src/generated_asset_sheets.rs`：调用方必须传入 `grid_size` 作为 `n*n` 的 `n`，可选传入物品名称 prompt 模板和特殊设定 prompt；模块负责 sheet prompt 组装、按 `n*n` 切片、透明化、PNG 输出、OSS private upload 请求构造和 sheet / item / special prompt 元数据持久化。玩法只负责规划 slot、调用具体生图 provider、计费、失败回写，以及把通用切片结果映射回自己的 DTO / 草稿 / runtime 字段。
 
 ## SpacetimeDB schema 变更规则
 
@@ -151,12 +156,12 @@ npm run check:server-rs-ddd
 
 - LLM：`GENARRATIVE_LLM_*`，创意 Agent 另用 `APIMART_BASE_URL` / `APIMART_API_KEY`。
 - 图片生成：VectorEngine / APIMart / DashScope，密钥只在后端环境变量中。
-- Match3D 物品 sheet：VectorEngine Gemini `gemini-3-pro-image-preview` 原生 `generateContent`。
-- Match3D 封面和 9:16 纯背景：VectorEngine `/v1/images/generations`。
-- Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。
+- 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。
 - Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；新 Match3D 草稿和批量新增不再生成 GLB。
 - 音频：视觉小说专用音频路由保留；拼图和抓大鹅生成入口暂时关闭，通用 `/api/creation/audio/*` 对相关目标返回 `410 Gone`。
 - 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。
 
 ## SpacetimeDB 表目录
 
@@ -324,6 +329,7 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`CustomWorldAgentSession`
 - 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
+- 发布约束：`publish_world` 的 action payload 不要求携带 `settingText`；`spacetime-module` 调用 `module-custom-world::resolve_custom_world_publish_setting_text(...)`，优先从当前 `draft_profile_json` 草稿真相派生正式 `setting_text`，避免旧会话 `seed_text` 为空时在最终 compile / publish 阶段触发 `custom_world.setting_text 不能为空`。
 
 ### `custom_world_draft_card`
 
@@ -361,6 +367,40 @@ npm run check:server-rs-ddd
 - Rust 结构体：`InventorySlot`
 - 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
+### `jump_hop_agent_session`
+
+- Rust 结构体：`JumpHopAgentSessionRow`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop/tables.rs`
+
+### `jump_hop_event`
+
+- Rust 结构体：`JumpHopEventRow`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop/tables.rs`
+
+### `jump_hop_runtime_run`
+
+- Rust 结构体：`JumpHopRuntimeRunRow`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop/tables.rs`
+
+### `jump_hop_work_profile`
+
+- Rust 结构体：`JumpHopWorkProfileRow`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop/tables.rs`
+
+### SpacetimeDB view：`jump_hop_gallery_card_view`
+
+- Rust view：`jump_hop_gallery_card_view`
+- 返回类型：`Vec<JumpHopGalleryCardViewRow>`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop.rs`
+- 说明：跳一跳公开广场列表卡片投影，只暴露 `publication_status = Published` 的作品卡片字段；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM jump_hop_gallery_card_view` 后，从本地 cache 构造跳一跳公开列表响应。个人作品列表、详情、发布和运行态仍按 procedure 路径处理。
+
+### SpacetimeDB view：`jump_hop_gallery_view`
+
+- Rust view：`jump_hop_gallery_view`
+- 返回类型：`Vec<JumpHopGalleryViewRow>`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop.rs`
+- 说明：跳一跳公开详情兼容投影，包含作品、路径和素材字段；公开列表主路径优先使用 `jump_hop_gallery_card_view`。
+
 ### `match3d_agent_message`
 
 - Rust 结构体：`Match3DAgentMessageRow`
@@ -545,6 +585,7 @@ npm run check:server-rs-ddd
 - `SELECT * FROM square_hole_gallery_view`
 - `SELECT * FROM visual_novel_gallery_view`
 - `SELECT * FROM big_fish_gallery_view`
+- `SELECT * FROM jump_hop_gallery_card_view`
 
 下列订阅用于统计或配置缓存，订阅失败不会让公开列表连接整体不可用，调用方保留兼容兜底：
 
@@ -561,6 +602,10 @@ npm run check:server-rs-ddd
 
 `GET /api/creation-entry/config` 和入口熔断优先从订阅 cache 读取创作入口配置；cache 缺失时使用最近一次成功读取的内存快照，再兜底调用 `get_creation_entry_config` procedure 完成空库种子或旧库兼容。
 
+RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；历史 `custom-world` 路由仍是 RPG 的工程域与运行态源类型。入口熔断把 `/api/runtime/custom-world*`、`/api/story/*` 和 `/api/runtime/chat/*` 统一映射到 `rpg`，不要新增平行 `airp` 路由或用 `airp` 接管当前文字冒险链路。
+
+结构化创作和 RPG 的 LLM JSON 链路默认不启用 Responses `web_search`；只有在明确需要联网增强时，才通过 `GENARRATIVE_RPG_LLM_WEB_SEARCH_ENABLED` 或 `GENARRATIVE_CREATION_AGENT_LLM_WEB_SEARCH_ENABLED` 显式打开。否则未开通工具的上游会先吐自然语言再返回 `ToolNotOpen`，这类失败要按上游工具不可用处理，不要误判成模型返回结果解析失败。
+
 未来可选：若发现页、推荐流和各玩法广场需要统一给浏览器前端直接订阅公开作品列表，只新增 / 统一专用 public read model，例如 `public_work_gallery_entry`。该 read model 必须是后端投影后的公开作品卡片契约，覆盖作品类型、公开作品号、标题、摘要、封面、作者展示名、排序键、公开统计和入口开关后的可见性，不暴露玩法领域源表 row shape。前端可选择订阅这个稳定投影来减少 HTTP 拉取，但不能订阅 `puzzle_work_profile`、`custom_world_profile` 等源表后自行拼装列表；BFF 仍保留首屏、SEO / 分享、旧客户端、订阅失败和灰度期间的 HTTP fallback。
 
 ### `quest_log`
@@ -636,6 +681,7 @@ npm run check:server-rs-ddd
 - Rust 结构体：`TrackingEvent`
 - 源码：`server-rs/crates/spacetime-module/src/runtime/profile.rs`
 - 写入：关键业务埋点同步调用单条 procedure；普通 HTTP route tracking 由 `api-server` 本机 outbox 批量调用 `record_tracking_events_and_return`。outbox 到达批量阈值时先封存 active 文件并切新 active，后台 worker 异步 flush sealed 文件，HTTP 请求线程不等待 SpacetimeDB。`FLUSH_INTERVAL_MS` 只负责兜底封存长时间未满批的 active 文件，`MAX_BYTES` 只做磁盘保护阈值。`event_id` 必须稳定且全局唯一，批量重试时用唯一索引做幂等跳过。
+- 外部 API 失败：`event_key = external_api_call_failure` 使用同一张表落库；它是供应商失败审计事实，不新增 SpacetimeDB 表，查询时按 `module_key = 'external-api'` 或 `scope_kind = module AND scope_id = '<provider>'` 过滤。
 
 ### `treasure_record`
 

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -40,10 +40,12 @@ npm run dev:web
 单独启动 Rust API server：
 
 ```bash
-npm run api-server
+npm run dev:api-server
 ```
 
-后端日志默认写入 `logs/api-server/`。后端 API smoke 使用 `npm run api-server` 并检查 `/healthz`；不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
+后端日志默认写入 `logs/api-server/`。后端 API smoke 使用 `npm run dev:api-server` 并检查 `/healthz`；不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
+
+本地 `.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 日志：
 
@@ -94,6 +96,33 @@ SpacetimeDB bindings：
 npm run spacetime:generate
 ```
 
+## CodeGraph 本地代码索引
+
+项目已安装 `@colbymchenry/codegraph` 作为开发期依赖，用于在本地生成语义代码索引，辅助 AI / IDE 做符号搜索、调用关系和影响范围分析。索引目录为 `.codegraph/`，其中 `config.json` 可提交，数据库、缓存和日志由 `.codegraph/.gitignore` 保持本机私有。
+
+首次拉取或需要重建索引时：
+
+```bash
+npm install
+npm run codegraph:init
+```
+
+日常使用：
+
+```bash
+npm run codegraph:status
+npm run codegraph:sync
+npm run codegraph:index
+```
+
+Codex 项目级 hook 已放在 `.codex/config.toml` 与 `.codex/hooks/`：
+
+- `PreToolUse` hook 会在 Codex 准备执行 `git commit` 前运行 `node .codex/hooks/pre-submit-compile-check.mjs`，依次执行 `npm run typecheck`、`npm run admin-web:typecheck`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`，发现编译错误会阻止本次提交。
+- `PostToolUse` hook 会在 Codex 工具修改文件后运行 `node .codex/hooks/post-edit-codegraph-sync.mjs`，执行 `npm run codegraph:sync` 刷新本地语义索引。
+- 如果某个 Codex 客户端版本尚未自动加载项目级 hook，可先手动运行 `node .codex/hooks/pre-submit-compile-check.mjs` 与 `node .codex/hooks/post-edit-codegraph-sync.mjs`；个人模型、token、MCP server 仍放在个人 `~/.codex/config.toml`，不要提交。
+
+若要把 CodeGraph 接到 Codex CLI / Cursor / Claude Code 等 MCP 客户端，按本机 agent 配置执行 `codegraph install` 或参考 `codegraph install --print-config codex` 输出；不要把个人全局 agent 配置、token 或本机绝对路径提交到仓库。
+
 ## 后端改动验收
 
 后端代码修改后，按变更范围选择：
@@ -103,7 +132,7 @@ npm run spacetime:generate
 - `cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`
 - `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`
 - `npm run check:server-rs-ddd`
-- `npm run api-server` 后请求 `/healthz`
+- `npm run dev:api-server` 后请求 `/healthz`
 
 涉及 SpacetimeDB schema 时必须补：
 
@@ -153,16 +182,18 @@ Windows Stdb module 构建流水线运行在 Jenkins `windows` 节点上。该
 
 生产环境变量模板：`deploy/env/api-server.env.example`。真实密钥只放服务器，不提交 Git，不写入文档示例。
 
-`Genarrative-Server-Provision` 会安装基础构建依赖、systemd 模板和 Nginx 站点模板。Ubuntu / apt 目标机会额外安装 `libnginx-mod-http-brotli-filter` 与 `libnginx-mod-http-brotli-static`，随后由 `scripts/jenkins-server-provision.sh` 通过临时 `nginx -t` 配置探测 Brotli 指令是否可用；该临时配置必须先 `include /etc/nginx/modules-enabled/*.conf`，因为 apt 安装的 Brotli 是动态模块，不会出现在普通 `nginx -V` 编译参数里。探测成功才在渲染后的 `deploy/nginx/genarrative.conf` / `genarrative-dev-http.conf` 中启用 Brotli，避免未安装模块的机器直接写入无效配置。
+`Genarrative-Server-Provision` 会安装基础构建依赖、systemd 模板和 Nginx 站点模板。Ubuntu / apt 目标机会额外安装 `libnginx-mod-http-brotli-filter` 与 `libnginx-mod-http-brotli-static`，随后由 `scripts/jenkins-server-provision.sh` 通过临时 `nginx -t` 配置探测 Brotli 指令是否可用；该临时配置必须先 `include /etc/nginx/modules-enabled/*.conf`，因为 apt 安装的 Brotli 是动态模块，不会出现在普通 `nginx -V` 编译参数里。探测成功才在渲染后的 `deploy/nginx/genarrative.conf` / `genarrative-dev-http.conf` 中启用 Brotli，避免未安装模块的机器直接写入无效配置。Provision 写入 Genarrative Nginx 站点时会把 `/etc/nginx/sites-enabled/default*` 移到 `/etc/nginx/sites-disabled/`，避免 Debian / Certbot 默认站点继续占用 `genarrative.world` / `www.genarrative.world` 并在 `nginx -T` 中出现 `conflicting server name ... ignored`。如果 `nginx -t` 失败，脚本会恢复写入前的 Genarrative 配置和被移动的默认站点。
 
 50 HTTP req/s 首版压测优化口径：
 
 - `api-server` 生产模板默认 `GENARRATIVE_API_LISTEN_BACKLOG=1024`、`GENARRATIVE_API_WORKER_THREADS=4`；本地未设置 worker threads 时继续使用 Tokio 默认值。
 - `GENARRATIVE_API_MAX_CONCURRENT_REQUESTS=512` 开启应用内 HTTP 并发背压；`GENARRATIVE_API_GALLERY_MAX_CONCURRENT_REQUESTS=320`、`GENARRATIVE_API_DETAIL_MAX_CONCURRENT_REQUESTS=64`、`GENARRATIVE_API_ADMIN_MAX_CONCURRENT_REQUESTS=16` 分别限制公开列表、公开详情和后台 API 热路径。超过许可时直接返回 `429 Too Many Requests` 和 `Retry-After: 1`，`/healthz` 不受该限制。这些值不是 RPS 限速；如果压测中 429 上升但内存和 p95 收敛，说明背压正在保护进程。直连 `api-server` 的极高 RPS 压测若出现 `connection refused`，通常已经打到 TCP 监听 / accept 层，应同时检查 backlog、Nginx upstream keepalive 和前置限流。
 - `genarrative-api.service` 设置 `LimitNOFILE=65535`、`TasksMax=2048`；上线后用 `systemctl show genarrative-api.service -p LimitNOFILE -p TasksMax` 和 `cat /proc/$(pidof api-server)/limits` 核对。
-- Server provision 不在目标机下载 SpacetimeDB 或 `otelcol-contrib`。Jenkins 的 `Prepare Provision Tools` 阶段在 `linux && genarrative-build` 构建机执行 `scripts/prepare-server-provision-tools.sh`：SpacetimeDB 仍通过官方安装入口 `https://install.spacetimedb.com` 准备；`otelcol-contrib` 默认要求在 Jenkins 参数 `OTELCOL_CONTRIB_ARCHIVE` 手动上传 `otelcol-contrib_0.151.0_linux_amd64.tar.gz`，再从上传包解出 `provision-tools/otelcol-contrib`。最终工具包通过 `stash/unstash` 上传到 release 部署 agent。目标机上的 `scripts/jenkins-server-provision.sh` 只从该工作区工具包安装 `/stdb/spacetime`、`/stdb/bin/current/*` 和 `/usr/local/bin/otelcol-contrib`。注意 `scripts/jenkins-checkout-source.sh` 会执行 `git reset --hard` / `git clean`，因此被直接执行的新增脚本必须以 Git `100755` 模式提交，或在二次 checkout 之后再补 `chmod +x`。
+- Server provision 不在目标机联网下载 SpacetimeDB 或 `otelcol-contrib`。`Genarrative-Server-Provision` 先在 Windows Jenkins 节点执行 `Download Provision Tool Archives`，把 `spacetime-x86_64-unknown-linux-gnu.tar.gz` 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz` 先下载到工作区，再通过 `stash/unstash` 带到 `genarrative-build-01`；Windows 下载前会先查 GitHub release asset 的 `digest` 字段做 SHA256 校验，已有本地文件且 digest 一致就直接复用，不再重复下载。目标 Linux 节点上的 `scripts/prepare-server-provision-tools.sh` 只消费这些本地下载件生成 `provision-tools/`，再交给 `scripts/jenkins-server-provision.sh` 安装 `/stdb/spacetime`、`/stdb/bin/current/*` 和 `/usr/local/bin/otelcol-contrib`。Windows 侧的 `runWindowsPowerShell(...)` 现在会先 `writeFile` 生成 UTF-8 `.ps1`，再直接把脚本文本读入内存并通过 `ScriptBlock::Create(...)` 执行，避免对同一个 workspace 脚本做原地 BOM 重写。排查时除了看下载日志，还要看 `[jenkins-powershell] workspace:`、`[jenkins-powershell] script:` 和 `[jenkins-powershell] loaded bytes:`。注意 `scripts/jenkins-checkout-source.sh` 会执行 `git reset --hard` / `git clean`，因此被直接执行的新增脚本必须以 Git `100755` 模式提交，或在二次 checkout 之后再补 `chmod +x`。
+- Windows 下载阶段如果出现 `curl: (18)` 或响应体截断，流水线会保留同名 `.download` 临时文件并用 `curl -C -` 断点续传；只有完整返回但 SHA256 digest 仍不匹配时才删除临时文件后重新下载。目标 Linux 节点仍只接收 `stash/unstash` 带过去的本地下载件，不回退外网下载。
+- Windows 下载阶段如果走代理，在 `Genarrative-Server-Provision` 参数 `PROVISION_DOWNLOAD_PROXY` 填写 Windows Jenkins 节点可访问的 HTTP 代理，例如 `http://127.0.0.1:7890`；不要填写目标 release 机器视角的 `127.0.0.1`，除非代理确实运行在该 Windows 节点本机。Linux 目标机阶段会强制要求使用本地下载件，缺少文件直接失败，不再回退到外网下载。
 - `otelcol-contrib.service` 作为可选系统服务加入 provision，默认监听 `127.0.0.1:4317/4318` 并使用 `deploy/otelcol/genarrative-debug.yaml`。api-server 是否发送 OTLP 仍由 `GENARRATIVE_OTEL_ENABLED` 控制，服务 unit 见 `deploy/systemd/otelcol-contrib.service`。
-- Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；`limit_conn` 负责连接 / 并发保护，`limit_req` 负责入口 RPS 快拒绝。当前模板把公开 gallery list 单独放到 `genarrative_gallery_rps`，默认 `rate=5000r/s`、`burst=4096`、`limit_conn=320`；公开详情和普通 API 放到 `genarrative_api_rps`，后台 API 放到 `genarrative_admin_rps`。压测时看 `/var/log/nginx/genarrative.access.log` 中的 `request_time`、`upstream_connect_time`、`upstream_header_time`、`upstream_response_time`、`upstream_status`、`request_id`。
+- Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；`limit_conn` 负责连接 / 并发保护，`limit_req` 负责入口 RPS 快拒绝。当前模板把公开 gallery list 单独放到 `genarrative_gallery_rps`，默认 `rate=5000r/s`、`burst=4096`、`limit_conn=320`；公开详情和普通 API 放到 `genarrative_api_rps`，后台 API 放到 `genarrative_admin_rps`。通用 `/api` location 设置 `client_max_body_size 64m` 只是反代兜底，防止旧客户端或兼容请求在到达 `api-server` 前被默认 1 MiB 上限拦截；长期主链不得依赖大 JSON body 承载图片，拼图参考图应先直传 OSS，只向创作接口提交 `referenceImageAssetObjectId(s)`，由后端签只读 URL 给外部模型读取。真实业务上限仍由 Rust 路由 `DefaultBodyLimit`、资产确认时 OSS HEAD 和解码后字节校验控制。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000`、`upstream_status=-`，说明请求在 Nginx 层被拦截，先用 `nginx -T | grep client_max_body_size` 检查 release 模板是否已渲染并 reload，同时检查前端是否仍在提交 Data URL 而不是 `assetObjectId`。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效；若线上压测看到 `limiting connections by zone "genarrative_api_conn"` 却返回 503，优先检查 `nginx -T` 里 HTTPS server 是否缺少这些状态码，以及 `/api/runtime/puzzle/gallery` 是否误落到通用 `location ~ ^/api` 的 `limit_conn=64`。压测时看 `/var/log/nginx/genarrative.access.log` 中的 `request_time`、`upstream_connect_time`、`upstream_header_time`、`upstream_response_time`、`upstream_status`、`request_id`。
 - 作品列表 K6 脚本一次 iteration 默认请求两个公开接口，因此约 50 HTTP req/s 的目标命令使用 `SCENARIO=spike START_RPS=5 PEAK_RPS=25 HOLD=60s END_RPS=5 DETAIL_RATIO=0 npm run loadtest:k6:works`。
 - 作品列表短期继续由 `api-server` / BFF 订阅 SpacetimeDB 公开 read model 后读本地 cache，不让浏览器前端直接订阅完整列表；未来如新增 `public_work_gallery_entry` 等专用公开作品列表 read model，前端只可订阅稳定、低基数、公开的专用投影，禁止订阅 `puzzle_work_profile`、`custom_world_profile` 等玩法源表后自行 join、聚合或判断权限。前端直订阅落地前必须先补齐权限、字段契约、排序 / 分页、埋点和 BFF 回退策略。
 - 50 HTTP req/s 验收目标为 `http_req_failed < 1%`、`p95 < 2s`、`dropped_iterations = 0`，同时压测窗口内 Nginx 无新增 502。2026-05-19 容器 2C / 2G 连续 10 轮不重启 SpacetimeDB 压测：`PEAK_RPS=2500` 等价约 5000 HTTP req/s，平均实际吞吐约 `4219 HTTP req/s`，10 轮总计 `1,897,357` 个 200、`212,542` 个 429、`0` 个 5xx，200 请求平均 `p95=123ms`、`p99=234ms`；该档会把 SpacetimeDB 容器内存从约 `366MiB` 推到约 `885MiB / 896MiB`，因此当前不要继续抬公开 gallery 入口并发，应优先处理 SpacetimeDB 侧连接 / 订阅 / tracking 写入后的内存高水位。
@@ -178,7 +209,7 @@ npm run container:k6
 npm run container:down
 ```
 
-容器方案默认暴露 `http://127.0.0.1:18080`，`api-server` 在容器内监听 `0.0.0.0:8082`，Nginx 通过 `api-server:8082` upstream 反代 `/api/` 和 `/admin/api/`。SpacetimeDB 也纳入 compose，容器内由 `spacetimedb:3101` 提供服务，宿主机通过 `http://127.0.0.1:13101` 进行模块发布；Collector 镜像使用 `otel/opentelemetry-collector-contrib:0.151.0`。生产 provision 侧则通过 Jenkins 构建机准备的 `provision-tools/otelcol-contrib` 安装本机 `otelcol-contrib.service`，真实库名、token 和外部服务密钥只写本地 `deploy/container/api-server.env`，不提交 Git。完整拓扑、端口、k6 参数和 OTLP debug exporter 使用方法见 `deploy/container/README.md`。
+容器方案默认暴露 `http://127.0.0.1:18080`，`api-server` 在容器内监听 `0.0.0.0:8082`，Nginx 通过 `api-server:8082` upstream 反代 `/api/` 和 `/admin/api/`。SpacetimeDB 也纳入 compose，容器内由 `spacetimedb:3101` 提供服务，宿主机通过 `http://127.0.0.1:13101` 进行模块发布；Collector 镜像使用 `otel/opentelemetry-collector-contrib:0.151.0`。生产 provision 侧则通过 Windows Jenkins 下载件在目标 Linux 节点生成 `provision-tools/otelcol-contrib`，再安装本机 `otelcol-contrib.service`，真实库名、token 和外部服务密钥只写本地 `deploy/container/api-server.env`，不提交 Git。完整拓扑、端口、k6 参数和 OTLP debug exporter 使用方法见 `deploy/container/README.md`。
 `npm run container:config` 默认只做 quiet 校验，避免把本地 env 中的 token 展开到终端；确需排查完整 compose 时再传 `-- --print`。
 
 OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日志与 Nginx 文件日志仍保留：
@@ -191,6 +222,7 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日
 - debug exporter / Rider 转发都会同时接收 traces、metrics 和 logs。
 - api-server 会随 metrics 发送进程级指标：`process.memory.usage`、`process.memory.virtual`、`process.cpu.time`、`genarrative.process.cpu.usage_percent`、`process.thread.count`、`genarrative.process.memory.private`；Windows 额外发送 `process.windows.handle.count`，Linux 额外发送 `process.unix.file_descriptor.count`。这些指标只描述当前进程，不携带请求、用户或作品 label。
 - HTTP 运行态补充发送 `genarrative.http.server.response_bodies.in_flight` 与 `genarrative.http.server.request_permits.available`，后者带低基数 `pool=default|gallery|detail|admin` label，用于区分业务 handler / 背压 permit 是否仍被占用；拼图广场热点缓存补充发送 `genarrative.puzzle_gallery.cache.*` 指标，记录 fresh hit、stale hit、未命中、后台刷新开始 / 失败、重建耗时和预序列化 data JSON 字节数。
+- 外部 API 失败统一发送 OTLP 并落库。当前 VectorEngine `gpt-image-2-all` 图片生成 / 编辑失败会输出 `外部 API 调用失败` trace/log，并记录指标 `genarrative.external_api.failures{provider,failure_stage,status_class,retryable}`；同时写入 `tracking_event`，`event_key = external_api_call_failure`、`module_key = external-api`、`scope_kind = module`、`scope_id = provider`。排障时先按 provider / failureStage 聚合，再结合 request 日志和上游响应 excerpt 判断是限流、超时、解析失败还是未返回图片。
 - SpacetimeDB 观测分为两类：procedure / reducer 调用继续用 `genarrative.spacetime.procedure.*`，订阅本地 cache 读使用 `genarrative.spacetime.read.*`。`read=list_puzzle_gallery` 表示拼图广场当前从 `puzzle_gallery_card_view` 本地 cache 读取，不再每个 HTTP 请求调用 `list_puzzle_gallery` procedure。
 - 本地 Windows 直连压测的内存高水位要结合 K6 VU / 连接数解释。250 RPS 下过高 `PREALLOCATED_VUS` 可能让 300 个本地 Established 连接把 `api-server` private memory 瞬时推到 GB 级，且 `/healthz` 小响应也能复现；若压测结束后回落、`response_bodies.in_flight` 和背压 permit 未显示业务积压，应优先按连接 / 发送链路高水位处理，而不是判断为 SpacetimeDB 或 JSON 缓存泄漏。
 - Rider 的 Logs 面板只展示 log event 自身字段，不会自动展开父 span 的全部 attributes；请求完成日志会直接带 `request_id`、`http.request.method`、`http.route`、`url.scheme`、`url.path`、`http.response.status_code`、`status_class`、`latency_ms` 和 `slow_request`，完整链路继续到 Traces 面板按 trace/span 查看。
@@ -211,6 +243,8 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日
 - `WECHAT_*`
 - `ALIYUN_OSS_*`
 
+结构化创作 / RPG 的 Responses JSON 链路默认不打开 `web_search`；本地和生产如需联网增强，必须显式配置 `GENARRATIVE_RPG_LLM_WEB_SEARCH_ENABLED=true` 或 `GENARRATIVE_CREATION_AGENT_LLM_WEB_SEARCH_ENABLED=true`。如果上游未开通工具，Responses 可能先吐自然语言再返回 `ToolNotOpen`，这类报错应按工具不可用排查，不要先当成 JSON 解析 bug。
+
 ### 手机验证码短信
 
 手机验证码发送走阿里云普通短信 `SendSms`，验证码由 `module-auth` 在当前 `api-server` 进程内生成、哈希存储和校验，不再调用阿里云托管验证码的 `SendSmsVerifyCode` / `CheckSmsVerifyCode`。因此 `api-server` 重启后，已发送但未校验的验证码会失效。
@@ -246,6 +280,16 @@ cargo test -p platform-auth --manifest-path server-rs/Cargo.toml aliyun_send_sms
 
 个人任务首版 scope 仅支持 `user`。后台、RPG、大鱼吃小鱼、Visual Novel、Story、Combat 等特定链路按 tracking 中间件排除规则处理；作品游玩统一使用 `work_play_start`。
 
+外部 API 失败审计复用 `tracking_event`，不新增表。失败事件优先写入本机 tracking outbox，再由后台 worker 批量落库；如果 outbox 因权限、磁盘或保护阈值不可写，会回退同步直写 SpacetimeDB。`metadata_json` 包含 endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel 和 rawExcerpt。常用查询：
+
+```sql
+SELECT event_id, scope_id AS provider, metadata_json, occurred_at
+FROM tracking_event
+WHERE event_key = 'external_api_call_failure'
+ORDER BY occurred_at DESC
+LIMIT 50;
+```
+
 tracking outbox 默认配置：
 
 ```env
@@ -258,6 +302,17 @@ GENARRATIVE_TRACKING_OUTBOX_MAX_BYTES=268435456
 
 outbox 采用 NDJSON 文件保存原始事件。达到 `BATCH_SIZE` 时会立刻把当前 active 文件原子封存为 sealed 文件，并马上切到新的 active 继续写入；后台 worker 异步 flush sealed 文件，HTTP 请求线程不等待 SpacetimeDB。`FLUSH_INTERVAL_MS` 只负责兜底封存长时间未满批的 active 文件。SpacetimeDB 批量 procedure 返回成功后删除 sealed 文件，失败则保留文件并重试。`MAX_BYTES` 是磁盘保护阈值，不是 flush 阈值；超过后低价值 route tracking 可以被丢弃并记录日志 / 指标，关键同步事件不进入该丢弃路径。sealed 文件若出现无法解析的坏行，会重命名为 `corrupt-*` 隔离并记录 `genarrative.tracking_outbox.files.corrupt` 指标，避免一个坏文件阻塞后续批量入库。该机制提供至少一次投递语义，依赖 `tracking_event.event_id` 幂等跳过重复事件。
 
+release 机器如果日志每秒刷 `tracking outbox ... Permission denied (os error 13)`，先检查 `/etc/genarrative/api-server.env` 是否缺少 `GENARRATIVE_TRACKING_OUTBOX_DIR`。缺少时 `api-server` 会回退到本地开发默认相对路径 `server-rs/.data/tracking-outbox`，而 systemd 的工作目录是只读发布目录 `/opt/genarrative/releases/<version>`，`genarrative` 用户无法在其中创建 `server-rs`。修复顺序：
+
+```bash
+install -d -o genarrative -g genarrative -m 0750 /var/lib/genarrative/tracking-outbox
+grep -n '^GENARRATIVE_TRACKING_OUTBOX' /etc/genarrative/api-server.env
+systemctl restart genarrative-api.service
+journalctl -u genarrative-api.service --since '30 seconds ago' --no-pager | grep -E 'tracking outbox|Permission denied|os error 13'
+```
+
+`Genarrative-Server-Provision` 和 `Genarrative-Api-Deploy` 会在保留旧 `/etc/genarrative/api-server.env` 的前提下补齐缺失的 tracking outbox 与 auth-store 运行态路径，并确保 `/var/lib/genarrative/tracking-outbox`、`/var/lib/genarrative/auth` 归属 `genarrative:genarrative`。
+
 常用检查思路：
 
 ```sql

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -10,6 +10,22 @@
 
 `PlatformEntryFlowShellImpl.tsx` 仍是平台入口编排壳，后续维护时应优先把独立 UI 片段、公开作品映射、草稿生成 notice 和运行态状态 helper 拆到 `src/components/platform-entry/PlatformEntryFlowShellImpl/` 或同目录紧邻 helper 文件。拆分只允许改变文件组织，不改变入口配置事实源、默认导出、props、页面阶段、UI 文案或现有交互；其中拼图首访 onboarding 已拆为 `PlatformEntryFlowShellImpl/PuzzleOnboardingView.tsx`。
 
+移动端底部一级导航是全局平台样式，不按单一玩法分叉。当前视觉统一为米白浮动胶囊底座、浅棕分隔线、棕色线性图标、橘色选中态和底部短下划线；中间 `创作` 入口保持凸起圆形主按钮，但凸起位移只能作用在按钮内容层，不能移动承载分隔线的 Tab 按钮容器，确保创作左右分隔线与其他分隔线垂直位置一致。Tab 名称和可见性仍由现有 `PlatformHomeTab` / 登录态规则决定，样式调整不得改写 Tab 文案或导航状态。
+
+## 新增玩法创作工具平台 SOP
+
+新增玩法默认采用表单/图片输入创作工作台，链路为：
+
+```text
+创作入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态
+```
+
+默认工作台只提交结构化表单、图片槽位和配置 payload，不默认增加聊天输入区、流式消息区或轻输入 Agent。确需偏离该模式时，必须先在 PRD 和本文档写明例外原因、影响范围和回退方式，再进入编码。
+
+单图资产编辑统一通过 `CreativeImageInputPanel` 承载上传、AI 重绘、参考图、历史图和删除确认；新玩法页面不得重复手写这些交互。系列素材图集生成统一走“批量规划 -> sheet 生图 -> 后端切图 -> 透明化 -> OSS 持久化 -> 状态回写 -> 局部重生成”流程，玩法只提供 `sheetSpec`、`slotSpecs`、提示词和字段映射，不把任一玩法专属素材 DTO 当作平台通用模型。
+
+`api-server` 的 `generated_asset_sheets` 是当前通用系列素材图集模块：`n` 是必选参数，模块负责组装 `n*n` sheet prompt、按 `n*n` 切片、绿幕 / 近白底透明化、导出 PNG 和 OSS 持久化请求。物品名称 prompt 和特殊设定 prompt 是可选输入；调用方可传入类似“每个物品生成五个不同视图”的视角约束，通用模块会把 sheet prompt、物品行 prompt、特殊设定 prompt 编码写入 OSS 元数据。玩法仍负责计费、物品规划、slot 映射、失败回写和把通用切片结果映射回自己的草稿 / profile / runtime 字段。
+
 ## 草稿与作品架
 
 1. 草稿页作品卡对齐发现页列表卡风格：左侧信息，右侧封面图，移动端单列，桌面两到三列。
@@ -20,6 +36,34 @@
 6. 点击 `generationStatus=generating` 的草稿卡必须恢复对应玩法的生成进度页，不能进入空白结果页或普通工作区；恢复生成页的 `startedAtMs` 使用作品摘要 `updatedAt` 推导。
 7. 私有 generated 图片必须通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签读取。
 
+## RPG / 自定义世界
+
+当前 RPG 创作入口使用 `playId = rpg`，工程域和运行态源类型沿用历史 `custom-world`。默认入口状态为 `visible=true`、`open=true`，对外展示为“文字冒险”；`airp` 仍是独立的“AI RPG”占位入口，保持 `open=false`，不要把它当作当前 RPG 创作链路开放。
+
+当前链路为：
+
+```text
+创作入口 -> 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` 返回的列表并在用户选择后调用对应恢复接口，不能本地拼装或筛选正式存档真相。
+
 ## 拼图
 
 当前拼图链路：
@@ -31,25 +75,51 @@
 当前口径：
 
 - 图像输入复用 `CreativeImageInputPanel`。
-- 支持画面描述生图、多参考图生图、上传或历史生成主图后 AI 重绘、上传或历史生成主图后不重绘；关闭 AI 重绘时，前端可提交本地上传 Data URL 或历史 `/generated-*` 图片路径，后端统一解析为首关正式图后再持久化。
-- 草稿生成会先持久化 `generationStatus=generating` 的作品摘要，生成完成并回写关卡图、UI 背景后再变为 `ready`；首关关卡图和 UI 背景在命名稳定后并行启动，当前不自动生成背景音乐。
+- 结果页每关画面编辑复用 `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`；当前不自动生成背景音乐。生成页进度不再按固定 5 分钟展示，而按实际开始时间和当前路径的分步骤预计时长推进；任一同步 action 回包到达时立即以真实完成/失败结果冻结进度。
 - 作品架拼图草稿的“生成中”遮罩只表示初始草稿还没有可查看结果；只要作品摘要、首关封面或任一关卡候选图已经可用，后续 UI 背景重生成和追加关卡生图都必须作为结果页局部生成态处理，不能阻止打开草稿结果页。
-- 拼图草稿编译是长耗时 action，前端 action 请求默认等待 `1_000_000ms` 且不自动重试，生成页预计完成时间按 `5` 分钟展示；生成页恢复时必须沿用作品摘要 `updatedAt` 作为原始 `startedAtMs`，失败/完成态用 `finishedAtMs` 冻结耗时，不能在锁屏或返回草稿页后重新从 0 计时。
+- 拼图草稿编译是长耗时 action，前端 action 请求默认等待 `1_800_000ms`（30 分钟）且不自动重试。每次 `gpt-image-2` 调用的预期用时按 90 秒计算；完整 AI 重绘路径为 `编译首关草稿` 8 秒、`生成关卡名称` 10 秒、`生成拼图首图` 90 秒、`生成关卡画面` 90 秒、`生成UI与背景` 90 秒、`写入正式草稿` 10 秒，合计约 298 秒。上传图且关闭 AI 重绘时必须跳过 `生成拼图首图`，直接进入 `生成关卡画面` 和 `生成UI与背景`，合计约 208 秒。生成页恢复时必须沿用作品摘要 `updatedAt` 作为原始 `startedAtMs`，失败/完成态用 `finishedAtMs` 冻结耗时，不能在锁屏或返回草稿页后重新从 0 计时。
 - 若浏览器锁屏、息屏或网络切换导致 compile 请求失败，前端在标记失败前必须先复读 `getPuzzleAgentSession(sessionId)`；只有最新 session 仍缺 `draft.coverImageSrc`、首关 `coverImageSrc` 或候选图时才展示失败，复读到已生成草稿时按成功收尾、刷新作品架并继续自动试玩/结果页链路。
-- 拼图参考图 AI 重绘优先走 VectorEngine `/v1/images/edits`；若编辑接口超时，`api-server` 会降级为 `/v1/images/generations`，并把同一参考图塞进 `image` 数组继续生成，避免参考图草稿整单失败。
-- 结果页素材配置当前只保留 UI 相关能力；旧背景音乐入口隐藏。
+- 拼图参考图 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` 先生成纯绿色绿幕背景图，后端上传 OSS 前必须把绿幕扣成透明 PNG，再写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`，按钮顺序固定为返回、设置、下一关、提示、原图、冻结，按钮素材自身保留对应中文文字，返回和设置按钮不得额外生成白色外圈、白底圆环或浮雕外框；纯背景用 `9:16`、`1k` 写入 `levelBackgroundImageSrc/levelBackgroundImageObjectKey`，提示词必须包含“禁止在背景中出现人像或和拼图画面中主体一致的内容”。运行态不直接使用第二段完整关卡画面，但必须持久化它用于追踪和后续再生成。结果页局部关卡生成进度按 AI 重绘开启约 270 秒、关闭 AI 重绘约 180 秒展示。
 - 结果页允许多关卡并行编辑和生成；某一关卡图片生成完成回包只静默更新该关卡素材与生成态，不得自动打开或切换关卡详情面板，避免打断用户正在编辑的其它关卡。
-- 结果页 UI 背景重生成只禁用 UI 背景自己的按钮和确认动作，不禁用“新增关卡”、关卡图片生成、关卡详情编辑和结果页导航；关卡图片生成也只标记对应关卡的局部生成进度。
+- 结果页关卡图片生成只标记对应关卡的局部生成进度，不禁用“新增关卡”、其它关卡详情编辑和结果页导航。
+- 结果页单关测试只能把完整草稿持久化，并通过 `levelId` 指定运行态起始关卡；不得把单关快照作为整份草稿调用 `updatePuzzleWork`，否则 source session 和作品 profile 的 `levels` 会被覆盖成单关，退出重进后其它关卡会丢失。
 - 结果页生成关卡图时若关卡名为空，前端必须传 `shouldAutoNameLevel=true`，后端复用首关命名契约先按画面描述生成关卡名，再在图片生成后用视觉命名结果精修，并把生成名和 UI 背景提示词随本次关卡快照写回。
-- 拼图 UI 背景是作品运行态背景，不只属于第一关；本地试玩、直达指定关卡和正式 `next-level` 推进时，目标关卡缺 `uiBackgroundImageSrc/uiBackgroundImageObjectKey` 必须继承同作品首个可用 UI 背景，仍缺失时才沿用当前运行态快照背景或默认 UI。
+- 拼图运行态背景优先读取当前关卡 `levelBackgroundImageSrc/levelBackgroundImageObjectKey`，旧数据才兼容 `uiBackgroundImageSrc/uiBackgroundImageObjectKey`；本地试玩、直达指定关卡和正式 `next-level` 推进时，目标关卡缺关卡背景时必须继承同作品首个可用关卡背景，仍缺失时才沿用当前运行态快照背景或默认 UI。运行态按钮视觉优先读取当前关卡 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`，先按透明 alpha 自动边界检测识别 spritesheet 中的独立按钮展示矩形，再按原图位置从左到右、从上到下映射到返回、设置、下一关、提示、原图、冻结；同一组件还要按较高 alpha 阈值派生紧致点击热区，透明留白和柔边低 alpha 区域尽量不响应点击。检测失败时回退旧固定六格裁切，缺失时才用现有图标按钮兜底。有 spritesheet 时，返回和设置按钮的点击容器只提供透明点击区，不再叠加默认白色圆形底；底部提示、原图、冻结三枚素材按检测矩形的原始宽高比显示，不能强行拉伸成正圆或铺满整列。底部道具区不再使用连片胶囊背景，提示、原图、冻结三个按钮均匀分布；运行态只展示按钮素材本身，不额外叠加“提示 / 原图 / 冻结”文字。
 - 拼图运行态棋盘不叠加分块蒙版、描边、阴影、选中底色或合并块 SVG 轮廓；拼图片本体需要裁切为圆角形状，单块使用独立圆角裁切，合并块使用 SVG 原生 `clipPath` 裁切整体外轮廓，外凸角和内凹角分别计算半径，内凹角半径要比外凸角更明显以避免手机 WebView 中看起来仍是直角。原图道具只在用户主动确认后打开独立原图查看层，不在当前拼图棋盘上叠加原图。
 - 拼图运行态拖拽必须完全跟随手指或鼠标位置，`pointermove` 期间即时写入可见拼块的 transform，不依赖等待后端回包、React 重渲染或下一帧动画队列；进入拖动后不展示拼块选中态或“已选择”提示，松手后再提交目标格同步规则真相。
 - 拼图运行态的提示、设置等点击弹层跟随当前运行态主色主题，使用普通圆角主题面板，不复用像素九宫格素材框。
 - 拼图运行态壳层自身要补齐 `platform-ui-shell` / `platform-theme` / `platform-theme--light|dark`，不能依赖外层平台壳来提供主题变量；`/puzzle` 直达页和平台内嵌页都必须渲染同一套主题语义类。
+- 拼图运行态顶部关卡信息采用游戏化铭牌样式：橘棕横向关卡名牌承载 `第 N 关` 和关卡名，左侧固定使用 `media/logo.png` 卡通形象；倒计时作为下挂米白小牌独立显示，紧贴铭牌但不遮挡棋盘。该样式只改变运行态 HUD 视觉，不改变计时、暂停、失败同步或关卡推进规则。
 - 拼图运行态进行中关卡的 `elapsedMs` 仍是结算字段，设置面板的“当前用时”必须按 `startedAtMs`、暂停累计和冻结累计实时派生；不要直接把进行中的 `currentLevel.elapsedMs` 当作展示值。
+- 推荐页嵌入拼图运行态时，通关结算弹层必须挂到页面级 fixed 浮层，不能留在推荐卡片视觉区内的 absolute 覆盖层；推荐页滑动卡片和运行态视口都使用 `overflow: hidden`，半屏内容区会裁剪排行榜、下一关按钮和相似作品卡。
 - 推荐页里的拼图作品如果从运行态进入“改造”结果页，返回平台后要清掉推荐嵌入态的 `activeRecommendEntryKey` / `activeRecommendRuntimeKind` / `isStartingRecommendEntry`，再重新按推荐页自动启动逻辑进入作品，不能复用已经被清空的旧 `puzzleRun`。
 - 拼图运行态允许前端低延迟交互表现，但通关、排行榜、奖励和作品状态仍以后端确认为准。
 
+## 跳一跳
+
+对外名称：`跳一跳`。工程域：`jump-hop`。PRD 见 `docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`。
+
+首版定位为俯视角 / 等距视角 2D 休闲跳跃模板，链路对齐拼图的创作闭环：
+
+```text
+创作入口 -> 模板输入 -> 生成过程页 -> 结果页 -> 试玩 -> 发布 -> 运行态
+```
+
+素材生成规则固定为：
+
+1. 初始草稿生成时，角色形象单独调用一次生图；
+2. 初始草稿生成时，地块单独调用一次生图，输出 3D 视图的 2D 图片图集；
+3. 地块图集由后端切分为起点、普通、目标、终点等透明 PNG；
+4. 封面和分享图由角色图与地块图轻量合成，不再额外调用第三次生图；
+5. 显式重生成角色或地块时，只重生成对应资产槽位。
+
+运行态规则真相必须沉到 `module-jump-hop`，前端只做蓄力表现、角色位移、投影和落地反馈。通关、失败、分数、combo、运行态快照和发布作品状态以后端为准。公开列表应走 `jump_hop_gallery_card_view` 订阅缓存，不要每次 HTTP 请求调用 procedure 组装全量列表。
+
+平台首页推荐、精选、最新、公开详情、搜索、已玩作品和公开试玩统一按 `sourceType='jump-hop'` 与 `JH-*` 公开作品号识别跳一跳作品；从公开详情或推荐流启动运行态时，若卡片摘要不足以携带角色图、地块图集和路径配置，必须先补读完整 work profile 再传入运行态。
+
 ## 抓大鹅 Match3D
 
 对外名称：`抓大鹅`。工程域：`match3d`。
@@ -57,9 +127,10 @@
 入口表单只展示：
 
 - 题材主题。
-- `2D素材风格` 横向风格卡：扁平图标、赛璐璐卡通、像素复古、手绘水彩、贴纸描边、厚涂图标、自定义。
 - 难度：轻松、标准、进阶、硬核。
 
+入口不再要求用户选择素材风格；历史草稿和旧接口中的 `assetStyleId` / `assetStyleLabel` / `assetStylePrompt` 仅作为兼容字段保留，新入口提交不再写入这些字段。
+
 难度映射：
 
 | 难度 | clearCount | difficulty | 总物品数 | 物品种类 |
@@ -67,28 +138,27 @@
 | 轻松 |          8 |          2 |       24 |        3 |
 | 标准 |         12 |          4 |       36 |        9 |
 | 进阶 |         16 |          6 |       48 |       15 |
-| 硬核 |         21 |          8 |       63 |       21 |
+| 硬核 |         21 |          8 |       63 |       20 |
 
 当前素材生成流水线：
 
 1. 点击生成前弹出泥点确认，草稿生成固定消耗 `10` 泥点。
-2. 先写入可恢复草稿 profile，再执行文本计划、图片生成、切图、OSS 上传、背景和容器生成；作品摘要在素材或背景未完整时下发 `generationStatus=generating`，素材和背景完整后下发 `ready`，草稿完成条件不包含 `backgroundMusic`。
-3. 物品素材不再调用 Hyper3D Rodin，不再生成 GLB。新草稿和批量新增固定生成 2D 五视角素材。
-4. 物品 sheet 走 VectorEngine Gemini `gemini-3-pro-image-preview` 原生 `generateContent`，单张 `1:1` 图固定 `5*5`，每张承载 `5` 个物品、每个物品 `5` 个视角。
-5. 切图前先在整张 sheet 上做绿幕 / 近白底透明化和边缘去污染，再按格子导出独立 PNG；每个视角图再以扩大的 PNG 边界带为种子，把连通的浅绿 / 近白抗锯齿边直接改为透明，并对贴透明背景的弱绿 / 暗绿轮廓像素做去绿污染处理，最后按剩余可见主体二次收紧；不要先裁剪单格再各自去绿。
-6. `generatedItemAssets[].imageViews[]` 是新素材主字段，`imageSrc/imageObjectKey` 只兼容首张视角。
-7. 文本生成物品名称时必须同时生成 `itemSize`，只允许 `大`、`中`、`小`。该字段随 `generatedItemAssets[].itemSize` 持久化并下发；历史缺失字段的素材按 `大` 兼容，模型缺失或非法值按物品名本地推断。
-8. 局内 `9:16` 纯背景图和 `1:1` 中心容器 UI 图分开生成。纯背景不得包含锅、盘、托盘、HUD、按钮、文字或物品，且入库前必须合成为全画幅不透明图片，不允许出现透明区域；容器图走 `/v1/images/edits` 参考透明容器图。
+2. 先写入可恢复草稿 profile，再执行文本计划、关卡整图生成、三张派生图生成、OSS 上传和素材解析；作品摘要在背景、UI spritesheet 或物品 spritesheet 未完整时下发 `generationStatus=generating`，完整后下发 `ready`，草稿完成条件不包含 `backgroundMusic`。
+3. 首次调用 VectorEngine `gpt-image-2`，无参考图，竖屏 `9:16`，生成完整抓大鹅关卡画面并持久化到 `generatedBackgroundAsset.levelSceneImageSrc/levelSceneImageObjectKey`。提示词必须包含用户主题描述、顶部返回 / 标题倒计时 / 设置按钮、中间与主题匹配且贴横向边缘的容器，以及底部“移出 / 凑齐 / 打乱”三个道具按钮。
+4. 关卡整图完成后并发发起三次 `gpt-image-2` 编辑请求，三者都以关卡整图作为参考图：`1K`、`1:1` 的 UI spritesheet 写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`；`1K`、`9:16` 的背景图写入 `imageSrc/imageObjectKey`；`2K`、`1:1` 的物品 spritesheet 写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。
+5. UI spritesheet 提示词固定要求按从上到下、从左到右整理纯绿色绿幕背景素材：返回按钮、设置按钮、方格素材（不含边框，仅保留一个）、移出按钮、凑齐按钮、打乱按钮；后端上传 OSS 前必须把绿幕扣成透明 PNG。背景图提示词固定要求移除全部 UI 组件和容器内含物，完整保留容器和背景，并补全被 UI 覆盖的背景内容。
+6. 物品 spritesheet 固定 `10行*10列`、统一纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；素材间距严格均匀分布，每一行包含两种物品，每种物品五个不同形态，物品来自参考图中心容器中的 2D 素材，严禁高相似度物品。新流程每次固定解析并持久化 `20` 种物品，物品信息列表全部展示这 `20` 种；持久化单格映射必须按 `row = itemIndex / 2 + 1`、`col = itemIndex % 2 * 5 + viewIndex + 1` 写入通用系列素材图集，不能再用 `row = itemIndex + 1`。`generatedItemAssets[].imageViews[]` 仍兼容已切好的五视角图，缺失时运行态和编辑器按 spritesheet 自动解析结果回退。
+7. 前端和运行态统一使用 alpha 连通域矩形检测解析 spritesheet：UI 图按返回、设置、方格、移出、凑齐、打乱顺序映射回原 UI 位置；物品图按检测顺序每 `5` 个区域组成一个物品的五个形态，最多 `20` 个物品。透明背景是解析前提，不能在前端按固定像素坐标写死切片。
+8. 文本生成物品名称时必须同时生成 `itemSize`，只允许 `大`、`中`、`小`。该字段随 `generatedItemAssets[].itemSize` 持久化并下发；历史缺失字段的素材按 `大` 兼容，模型缺失或非法值按物品名本地推断。
 9. 当前抓大鹅音频生成关闭：入口无 `生成音效`，草稿不生成背景音乐或点击音效，结果页不展示背景音乐 Tab 或点击音效生成入口。历史 `backgroundMusic` / `clickSound` 字段继续兼容传递。
-10. UI 背景和容器资产的持久化真相仍在 `generatedItemAssets[].backgroundAsset`；Agent session、work summary/detail、结果页和运行态入口都必须把该字段提升为 `backgroundImageSrc/backgroundImageObjectKey/generatedBackgroundAsset` 读取。草稿编译后的 `draftJson` 自身也必须携带 `generatedItemAssets` 快照；HTTP facade 不能只依赖 work detail 回读补齐 UI 资产，外部回读为空时也不得清空草稿内已有的背景 / 容器图。平台壳层从作品架、广场、生成完成回调、结果页保存 / 发布 / 试玩回调进入 Match3D profile 时也要先归一化并提升，避免首次试玩、手动试玩、推荐流或公开详情运行态退回默认背景 / 默认容器。
+10. 背景、UI spritesheet、物品 spritesheet 和历史容器兼容字段的持久化真相仍在 `generatedItemAssets[].backgroundAsset` 与提升后的 `generatedBackgroundAsset`；Agent session、work summary/detail、结果页和运行态入口都必须把该字段提升为 `backgroundImageSrc/backgroundImageObjectKey/generatedBackgroundAsset` 读取。草稿编译后的 `draftJson` 自身也必须携带 `generatedItemAssets` 快照；HTTP facade 不能只依赖 work detail 回读补齐 UI 资产，外部回读为空时也不得清空草稿内已有的背景 / 图集。平台壳层从作品架、广场、生成完成回调、结果页保存 / 发布 / 试玩回调进入 Match3D profile 时也要先归一化并提升，避免首次试玩、手动试玩、推荐流或公开详情运行态退回默认背景。
 
 结果页当前结构：
 
 - `作品信息`：名称、描述、标签；封面编辑收口到发布面板。
 - `难度配置`：四档离散拖动条，显示需要消除、总物品数、物品种类、已生成物品种类。
-- `素材配置 > 物品`：两列素材卡，点击打开独立五视角预览面板；支持删除、批量新增和批量重新生成。替换模式必须保留原 `itemId` 和列表顺序。
-- `素材配置 > UI`：纯背景图与运行态 UI 预览，重生成消耗 `2` 泥点；UI 预览必须复用运行态顶部 HUD、中央容器棋盘、容器图定位和底部槽位样式，不单独维护一套简化预览 UI。
-- `素材配置 > 容器形象`：单独预览和重生成中心容器，消耗 `2` 泥点。
+- `素材配置 > 物品`：两列素材卡固定展示 20 个物品，点击打开独立五视角预览面板；支持删除、批量新增和批量重新生成。替换模式必须保留原 `itemId` 和列表顺序。
+- `素材配置 > UI素材`：预览背景图、UI spritesheet 原图、物品 spritesheet 原图和物品 spritesheet 自动解析缩略图；背景图只支持预览，不提供重新生成入口。UI 预览必须复用运行态顶部 HUD、中央容器棋盘和底部槽位样式，不单独维护一套简化预览 UI。
 
 运行态当前口径：
 
@@ -98,8 +168,9 @@
 - 初始物品坐标围绕容器口中心生成，并保留内缩安全距离，避免贴边和局部角落聚集。
 - 本地试玩与 Rust `module-match3d` 后端领域生成使用同一套中心铺开口径；生成点覆盖四象限且均值接近中心。
 - 运行态优先消费 2D 生成图；默认积木 / 程序化 3D 表现只作为视觉分支和兜底，不改变规则真相。
-- 运行态启动前要预加载 `generatedItemAssets[].imageViews[]`、顶层 `generatedBackgroundAsset`、物品挂载 `backgroundAsset` 中的背景和容器图；首次生成自动试玩、结果页手动试玩、推荐流和公开详情启动都必须传入提升后的 profile。卡片摘要缺 UI 背景或容器字段时，进入运行态前必须补读 work detail。补读后的 profile 也要再次提升 `generatedItemAssets[].backgroundAsset`，确保背景和容器字段传给 `Match3DRuntimeShell`。
-- 局内容器图在移动端宽度大于屏幕宽度并略向下压，当前运行态使用 `w-[min(116vw,42rem)]` 与 `top-[54%]` 放大和下移容器图本体，保持原图比例不拉伸且不改变后端物品布局、点击半径或消除规则；生成容器图加载成功后棋盘外壳透明且 `overflow-visible`，只有生成图缺失或加载失败时才显示透明参考容器兜底。
+- 难度只决定本局加载的物品种类数量：轻松 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 当中心容器图叠到棋盘上。
 - generated 私有图换签未完成时，局内物品先隐藏等待，不得短暂显示默认积木；同一批资源在重启 run 时保留已解析签名 URL，只有资源源列表变化或换签失败后才允许进入兜底视觉。
 - `itemSize` 只缩放生成 2D 图片本体：`大`、`中`、`小` 均按相对尺寸缩放，其中 `大` 也比原始图片略小，`中` 和 `小` 进一步缩小；不改变后端下发的布局半径、点击半径或三消规则。
 - 物品进入底部物品栏时按同类型插入：如果物品栏已有同类物品，新物品插到该类型最后一个物品后面，后续物品整体后移；没有同类时追加到当前末尾。达到三件同类时，在飞入物品栏动画结束后，左侧和右侧同类物品向中间合成，三件一起消失，播放合成音效，不展示星星图标，后面的物品再向前补位。该动效只是前端表现层，后端和本地试玩仍负责权威插入、指定点击类型清除与补位后的槽位快照。

docs/【项目基线】当前产品与工程约束-2026-05-15.md

@@ -94,6 +94,8 @@ server-rs + Axum + SpacetimeDB
 8. 图像输入通用 UI 统一走 `src/components/common/CreativeImageInputPanel.tsx`。外层页面持有业务状态，组件只承担上传卡、预览、参考图缩略图、AI 重绘开关、错误展示和提交按钮。
 9. 发现页 `分类` 子频道的筛选必须打开独立 dialog / drawer / modal，至少支持玩法类型过滤与排序切换；筛选结果为空时显示空状态，不把筛选内容展开在当前列表下方。
 10. “我的”页泥点、游戏时长、玩过三张统计卡只展示各自标签和值，内容居中且不换行，不在统计区底部展示“更新于”时间。
+11. RPG 等运行态的战斗飘字、血量变化和即时反馈必须在暗色、噪声高的场景背景上保持可读：使用高亮文字、深色描边、强阴影或小面积半透明底，不只依赖红/绿文字本身表达伤害或治疗。
+11. 平台亮色 UI 配色以陶泥儿主视觉为准：暖白 / 米杏底、陶土橙主按钮、深棕正文与浅杏边框；新增界面优先复用 `src/index.css` 的 `--platform-*` 主题变量和 `apps/admin-web/src/styles/admin.css` 的同系色值，不再引入粉红、蓝绿等独立主色方案。
 
 ## 文案与编码