1

2026-04-22 20:14:15 +08:00
parent 0773a0d0ca
commit 0e9c286a57
205 changed files with 25790 additions and 1623 deletions
--- a/docs/prd/AI_NATIVE_AGENT_FIRST_BIG_FISH_GAME_CREATION_AND_GAMEPLAY_PRD_2026-04-22.md
+++ b/docs/prd/AI_NATIVE_AGENT_FIRST_BIG_FISH_GAME_CREATION_AND_GAMEPLAY_PRD_2026-04-22.md
--- a/docs/prd/AI_NATIVE_PUZZLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-22.md
+++ b/docs/prd/AI_NATIVE_PUZZLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-22.md
--- a/docs/technical/BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md
+++ b/docs/technical/BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md
@@ -0,0 +1,273 @@
+# 大鱼吃小鱼玩法创作与运行态最小落地技术方案
+
+日期：`2026-04-22`
+
+## 1. 文档目的
+
+本文件承接 PRD《AI 原生 Agent-First 大鱼吃小鱼玩法创作工具与玩法系统》，冻结本轮工程落地的最小完整闭环。
+
+本轮目标不是抽象一个通用街机玩法引擎，而是在现有平台内新增一个独立 `big_fish` 玩法域，跑通：
+
+1. 平台创作入口选择大鱼吃小鱼玩法
+2. Agent 会话创建、消息提交和 SSE 兼容返回
+3. 基于 4 个高杠杆锚点编译玩法草稿
+4. 结果页生成等级主图、等级动作、场地背景的正式资产槽位
+5. 发布校验
+6. 启动测试运行态
+7. 后端推进摇杆输入、刷怪、吞噬收编、三合一、屏外清理和胜负裁决
+
+## 2. 本轮明确不做
+
+1. 不接入真实图片 / 动作模型调用，只生成可预览的占位资产引用与冻结提示词快照。
+2. 不新增 WebSocket 依赖；首版运行态使用 `POST input + GET snapshot` 的有限 HTTP 辅助接口，后续再升级长连接。
+3. 不把 Big Fish 写回 `custom_world`、`rpgCreation` 或 RPG runtime 旧语义。
+4. 不新增作品市场、排行榜、复盘、局外成长、PvP。
+5. 不要求前端本地模拟真相；前端只渲染后端 snapshot。
+
+## 3. Rust crate 边界
+
+新增：
+
+1. `server-rs/crates/module-big-fish`
+   - 纯领域模型、输入校验、草稿编译、资产覆盖率、运行态规则推进。
+   - 可开启 `spacetime-types` feature，为 `spacetime-module` 派生 SpacetimeDB 类型。
+
+接入：
+
+1. `server-rs/crates/spacetime-module`
+   - 新增 Big Fish 表与 procedure。
+   - 只存状态与结构化引用，不做 OSS / LLM 外部 IO。
+2. `server-rs/crates/spacetime-client`
+   - 新增 Big Fish facade，隐藏 generated bindings。
+3. `server-rs/crates/shared-contracts`
+   - 新增 HTTP DTO。
+4. `server-rs/crates/api-server`
+   - 新增 `big_fish_creation.rs`、`big_fish_assets.rs`、`big_fish_runtime.rs` 或最小合并的 `big_fish.rs`。
+
+## 4. SpacetimeDB 表
+
+本轮只新增必要表，所有表主键使用 Axum 生成的显式业务 ID。
+
+### 4.1 `big_fish_creation_session`
+
+字段：
+
+1. `session_id: String`
+2. `owner_user_id: String`
+3. `seed_text: String`
+4. `current_turn: u32`
+5. `progress_percent: u32`
+6. `stage: BigFishCreationStage`
+7. `anchor_pack_json: String`
+8. `draft_json: Option<String>`
+9. `asset_coverage_json: String`
+10. `last_assistant_reply: Option<String>`
+11. `publish_ready: bool`
+12. `created_at: Timestamp`
+13. `updated_at: Timestamp`
+
+索引：
+
+1. `by_big_fish_session_owner_user_id(owner_user_id)`
+
+### 4.2 `big_fish_agent_message`
+
+字段：
+
+1. `message_id: String`
+2. `session_id: String`
+3. `role: BigFishAgentMessageRole`
+4. `kind: BigFishAgentMessageKind`
+5. `text: String`
+6. `created_at: Timestamp`
+
+索引：
+
+1. `by_big_fish_message_session_id(session_id)`
+
+### 4.3 `big_fish_asset_slot`
+
+字段：
+
+1. `slot_id: String`
+2. `session_id: String`
+3. `asset_kind: BigFishAssetKind`
+4. `level: Option<u32>`
+5. `motion_key: Option<String>`
+6. `status: BigFishAssetStatus`
+7. `asset_url: Option<String>`
+8. `prompt_snapshot: String`
+9. `updated_at: Timestamp`
+
+索引：
+
+1. `by_big_fish_asset_session_id(session_id)`
+2. `by_big_fish_asset_slot(session_id, asset_kind, level, motion_key)`
+
+### 4.4 `big_fish_runtime_run`
+
+字段：
+
+1. `run_id: String`
+2. `session_id: String`
+3. `owner_user_id: String`
+4. `status: BigFishRunStatus`
+5. `snapshot_json: String`
+6. `last_input_x: f32`
+7. `last_input_y: f32`
+8. `tick: u64`
+9. `created_at: Timestamp`
+10. `updated_at: Timestamp`
+
+索引：
+
+1. `by_big_fish_run_owner_user_id(owner_user_id)`
+2. `by_big_fish_run_session_id(session_id)`
+
+## 5. SpacetimeDB procedure
+
+本轮全部使用 procedure 同步返回快照，避免 Axum 额外拼读模型。
+
+1. `create_big_fish_session(input) -> BigFishSessionProcedureResult`
+2. `get_big_fish_session(input) -> BigFishSessionProcedureResult`
+3. `submit_big_fish_message(input) -> BigFishSessionProcedureResult`
+4. `compile_big_fish_draft(input) -> BigFishSessionProcedureResult`
+5. `generate_big_fish_asset(input) -> BigFishSessionProcedureResult`
+6. `publish_big_fish_game(input) -> BigFishSessionProcedureResult`
+7. `start_big_fish_run(input) -> BigFishRunProcedureResult`
+8. `submit_big_fish_input(input) -> BigFishRunProcedureResult`
+9. `get_big_fish_run(input) -> BigFishRunProcedureResult`
+
+说明：
+
+1. `submit_big_fish_message` 只做 deterministic 锚点补全，不调用 LLM。
+2. `generate_big_fish_asset` 只写正式资产槽位和提示词快照，真实模型生成后续由 AI/OSS worker 替换。
+3. `submit_big_fish_input` 每次至少推进 1 个后端 tick，前端不能本地裁决。
+4. 运行态所有“持续时间”语义按真实秒数累计，前端即使摇杆静止也要持续以当前输入心跳驱动后端推进，避免刷怪与屏外 `3` 秒清理依赖手速或提交频率。
+
+## 6. HTTP contract
+
+所有接口挂在 `/api/runtime/big-fish/*`，全部需要 Bearer 鉴权。
+
+开发态本地链路补充约定：
+
+1. 浏览器仍只请求同源 `/api/runtime/big-fish/*`。
+2. `vite -> server-node:8081` 保持不变，由 `server-node` 先复用现有登录态完成 Bearer 校验。
+3. `server-node` 仅作为 Big Fish 兼容网关，把“已校验用户身份 + 原始请求体”转发到 Rust `api-server`。
+4. Rust `api-server` 继续作为 Big Fish 真相后端，正式处理会话、草稿、资产动作和运行态规则。
+5. 本地默认端口：
+   - `vite`: `3000`
+   - `server-node`: `8081`
+   - Rust `api-server`: `3100`
+   - `SpacetimeDB standalone`: `3001`
+6. `GENARRATIVE_SPACETIME_DATABASE` 本地开发优先跟随仓库根目录 `spacetime.local.json` 的 `database` 字段，避免 `api-server` 默认连到错误数据库名。
+   - `.env.local` 或进程环境显式配置 `GENARRATIVE_SPACETIME_DATABASE` 时可覆盖本地配置。
+   - `.env.example` 只提供示例默认值，不得压过 `spacetime.local.json`。
+
+### 6.1 创作会话
+
+1. `POST /api/runtime/big-fish/agent/sessions`
+2. `GET /api/runtime/big-fish/agent/sessions/{sessionId}`
+3. `POST /api/runtime/big-fish/agent/sessions/{sessionId}/messages/stream`
+4. `POST /api/runtime/big-fish/agent/sessions/{sessionId}/actions`
+
+`messages/stream` 首版兼容当前前端 SSE 解析方式，只输出：
+
+1. `reply_delta`
+2. `session`
+3. `done`
+4. `error`
+
+`actions` 首版支持：
+
+1. `big_fish_compile_draft`
+2. `big_fish_generate_level_main_image`
+3. `big_fish_generate_level_motion`
+4. `big_fish_generate_stage_background`
+5. `big_fish_publish_game`
+
+### 6.2 运行态
+
+1. `POST /api/runtime/big-fish/sessions/{sessionId}/runs`
+2. `GET /api/runtime/big-fish/runs/{runId}`
+3. `POST /api/runtime/big-fish/runs/{runId}/input`
+
+`input` 请求体：
+
+```json
+{
+  "x": 0.4,
+  "y": -0.2
+}
+```
+
+## 7. 运行态最小规则
+
+后端推进规则固定：
+
+1. 开局拥有 1 个 `level = 1` 己方实体。
+2. 开局视野内生成至少 2 个同级野生实体。
+3. 己方实体碰撞低于或等于自己等级的野生实体时收编。
+4. 高于己方等级的野生实体碰撞己方实体时吃掉该己方实体。
+5. 每次结算后从低等级开始做三合一连锁合成。
+6. 野生实体池围绕玩家最高己方等级维持低 1~2 级与高 1~2 级。
+7. 同等级、高 3 级及以上、低 3 级及以下的野生实体，屏外连续 3 秒后删除。
+8. 玩家首次拥有最高等级实体时立即胜利。
+9. 己方实体归零时失败。
+
+## 8. 前端接入边界
+
+新增目录：
+
+1. `src/services/big-fish-creation/`
+2. `src/components/big-fish-creation/`
+3. `src/components/big-fish-result/`
+4. `src/components/big-fish-runtime/`
+
+复用现有平台入口壳层，但入口脚本必须使用通用平台命名，禁止把 Big Fish 业务状态写进 `rpg-entry` 命名脚本：
+
+1. 在 `src/components/platform-entry/PlatformEntryCreationTypeModal.tsx` 新增“大鱼吃小鱼”选项。
+2. 在 `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx` 中新增 Big Fish 专属 stage。
+3. Big Fish 不使用 `RpgCreationResultView`，使用 `BigFishResultView`。
+4. `src/components/rpg-entry/*` 只能保留兼容导出或 RPG 专属组件，不允许承载 Big Fish 业务分支。
+
+前端只允许：
+
+1. 展示会话、草稿、资产槽位、运行快照。
+2. 发送聊天、action 和摇杆输入。
+3. 根据后端 snapshot 渲染实体。
+
+前端禁止：
+
+1. 自行决定刷怪。
+2. 自行决定吞噬 / 合成 / 清理 / 胜负。
+
+## 9. 本轮验收
+
+完成后至少执行：
+
+1. `cargo fmt -p module-big-fish -p shared-contracts -p spacetime-module -p spacetime-client -p api-server`
+2. `cargo check -p module-big-fish`
+3. `cargo check -p shared-contracts`
+4. `cargo check -p spacetime-module`
+5. `spacetime generate` 刷新 Rust bindings
+6. `cargo check -p spacetime-client`
+7. `cargo check -p api-server`
+8. 前端类型 / 构建检查
+9. `npm run check:encoding`
+
+## 10. 本地开发补充
+
+为避免再次出现 `POST /api/runtime/big-fish/agent/sessions` 命中旧 Node 后端 `404`，本轮额外冻结以下联调口径：
+
+1. `npm run dev` 需要同时拉起：
+   - `server-node`
+   - Rust `api-server`
+   - `vite`
+2. `server-node` 新增 Big Fish 专用兼容网关路由，不在 Node 内复制 Big Fish 玩法逻辑。
+3. Node -> Rust 转发使用内部桥接头：
+   - `x-genarrative-authenticated-user-id`
+   - `x-genarrative-internal-api-secret`
+4. Rust 侧只对带正确内部密钥的本地桥接请求接受该用户头，不对普通外部请求放开匿名身份伪造。
+
+如检查发现本轮主链缺口，继续补齐；如已经满足上述验收，不继续扩展额外玩法能力。
--- a/docs/technical/PUZZLE_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md
+++ b/docs/technical/PUZZLE_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md
@@ -0,0 +1,384 @@
+# 拼图玩法创作与运行态最小落地技术方案
+
+日期：`2026-04-22`
+
+## 1. 文档目的
+
+本文件承接 PRD《AI 原生拼图玩法创作工具与玩法系统》，冻结本轮拼图玩法在当前平台内的最小完整闭环。
+
+本轮目标不是抽象一个通用拼图编辑器，也不是额外搭建一个脱离平台的新小游戏站点，而是在现有平台壳层内新增独立 `puzzle` 玩法域，跑通下面这条主链：
+
+1. 平台创作入口选择拼图玩法
+2. Agent-first 对话收束 5 个高杠杆视觉锚点
+3. 编译结果页草稿
+4. 在结果页编辑关卡名、标签并生成候选拼图图片
+5. 发布作品进入拼图广场
+6. 玩家从广场进入第 1 关
+7. 后端初始化 `3x3 / 4x4` 棋盘
+8. 后端裁决交换、合并、拖动、拆分与通关
+9. 通关后根据“标签相似度 `70%` + 同作者 `30%`”推荐下一关
+
+## 2. 本轮明确不做
+
+1. 不做异形拼块、旋转拼块、道具、体力、倒计时。
+2. 不做新的平台站点或新的全局导航系统。
+3. 不做前端本地推荐、前端本地裁决、前端本地持久化真相。
+4. 不做复杂图片模型编排；首版图片生成沿用 `api-server` 的占位资产生成方式，保证完整链路可跑通。
+5. 不把拼图玩法继续挂在 `customWorld`、`rpgWorld` 或 RPG runtime 旧语义下。
+6. 不扩到拼图排行榜、社交评论、收藏、复盘系统。
+
+## 3. 分层边界
+
+### 3.1 前端
+
+前端继续使用当前 `React + TypeScript + Vite` 平台壳层，只负责：
+
+1. 展示拼图创作中心、Agent 工作区、结果页、广场、运行时画布。
+2. 发起聊天、结果页编辑、发布、开始游戏、交换与拖动请求。
+3. 基于后端快照渲染棋盘、HUD、选中态与合并反馈。
+
+前端禁止：
+
+1. 自行判断下一关推荐。
+2. 自行判断拼块是否应当合并。
+3. 自行判断合并块是否应当拆分。
+4. 自行判断通关。
+
+### 3.2 Axum
+
+`server-rs/crates/api-server` 负责：
+
+1. 对外暴露 `/api/runtime/puzzle-*` HTTP 接口。
+2. 鉴权、请求上下文、错误 envelope。
+3. 结果页占位图片生成与静态资产落盘。
+4. 调用 `spacetime-client` 读写拼图玩法真相态。
+
+### 3.3 SpacetimeDB
+
+`server-rs/crates/spacetime-module` 负责：
+
+1. 存储拼图 Agent session / message。
+2. 存储已发布拼图作品 profile。
+3. 存储拼图运行态 run snapshot。
+4. 通过 procedure 同步返回 session / works / gallery / runtime 快照。
+
+### 3.4 纯领域 crate
+
+新增 `server-rs/crates/module-puzzle`，承载：
+
+1. 5 个锚点与会话阶段的纯领域模型。
+2. 草稿编译、标签规范化、发布校验。
+3. `3x3 / 4x4` 棋盘初始化。
+4. 交换、合并、拖动、拆分、通关与下一关推荐算法。
+
+## 4. 共享契约
+
+### 4.1 TypeScript shared contracts
+
+在 `packages/shared/src/contracts/` 新增：
+
+1. `puzzleAgentSession.ts`
+2. `puzzleAgentDraft.ts`
+3. `puzzleAgentActions.ts`
+4. `puzzleResultPreview.ts`
+5. `puzzleWorkSummary.ts`
+6. `puzzleRuntimeSession.ts`
+
+这些文件分别承载：
+
+1. Agent session / message / anchor pack
+2. 结果页草稿与候选图片
+3. Agent actions 与 works/gallery mutation request
+4. 结果页 publish gate / preview
+5. owner-only works 与 gallery card
+6. runtime run / board / swap / drag / next-level contract
+
+### 4.2 Rust shared contracts
+
+在 `server-rs/crates/shared-contracts/src/` 新增：
+
+1. `puzzle_agent.rs`
+2. `puzzle_works.rs`
+3. `puzzle_gallery.rs`
+4. `puzzle_runtime.rs`
+
+Rust DTO 只承载对前端公开的 HTTP contract，不直接泄露 `module-puzzle` 内部实现细节。
+
+## 5. Spacetime 表与 procedure
+
+本轮保持“最小闭环优先”，作品与运行时仍以结构化字段 + `snapshot_json` 组合持久化，不额外拆出更多高耦合表。
+
+### 5.1 `puzzle_agent_session`
+
+字段：
+
+1. `session_id`
+2. `owner_user_id`
+3. `seed_text`
+4. `current_turn`
+5. `progress_percent`
+6. `stage`
+7. `anchor_pack_json`
+8. `draft_json`
+9. `last_assistant_reply`
+10. `published_profile_id`
+11. `created_at`
+12. `updated_at`
+
+### 5.2 `puzzle_agent_message`
+
+字段：
+
+1. `message_id`
+2. `session_id`
+3. `role`
+4. `kind`
+5. `text`
+6. `created_at`
+
+### 5.3 `puzzle_work_profile`
+
+字段：
+
+1. `profile_id`
+2. `owner_user_id`
+3. `source_session_id`
+4. `author_display_name`
+5. `level_name`
+6. `summary_text`
+7. `theme_tags_json`
+8. `cover_image_src`
+9. `cover_asset_id`
+10. `anchor_pack_json`
+11. `publication_status`
+12. `play_count`
+13. `updated_at`
+14. `published_at`
+
+### 5.4 `puzzle_runtime_run`
+
+字段：
+
+1. `run_id`
+2. `owner_user_id`
+3. `entry_profile_id`
+4. `current_profile_id`
+5. `cleared_level_count`
+6. `current_level_index`
+7. `current_grid_size`
+8. `played_profile_ids_json`
+9. `previous_level_tags_json`
+10. `snapshot_json`
+11. `updated_at`
+12. `created_at`
+
+### 5.5 Procedure
+
+本轮全部使用 procedure 同步返回快照，避免 Axum 再次读 private table：
+
+1. `create_puzzle_agent_session`
+2. `get_puzzle_agent_session`
+3. `submit_puzzle_agent_message`
+4. `compile_puzzle_agent_draft`
+5. `save_puzzle_generated_images`
+6. `select_puzzle_cover_image`
+7. `publish_puzzle_work`
+8. `list_puzzle_works`
+9. `get_puzzle_work_detail`
+10. `update_puzzle_work`
+11. `list_puzzle_gallery`
+12. `get_puzzle_gallery_detail`
+13. `start_puzzle_run`
+14. `get_puzzle_run`
+15. `swap_puzzle_pieces`
+16. `drag_puzzle_piece_or_group`
+17. `advance_puzzle_next_level`
+
+## 6. 结果页图片生成策略
+
+本轮不引入新的真实图像模型编排，而是复用 `api-server` 里已有的占位资产写盘模式：
+
+1. 每次生成 2 张候选图。
+2. 候选图通过 `api-server` 写入 `public/generated-puzzle-covers/...`。
+3. Axum 把候选图 URL、assetId、prompt snapshot 回写到 Spacetime session draft。
+4. 创作者在结果页选择其中 1 张作为正式图。
+
+这样可以保证：
+
+1. 结果页图片生成、重生、应用正式图完整可用。
+2. 发布链有正式图片可校验。
+3. 不额外扩到模型供应商集成。
+
+### 6.1 发布前编辑真相补充
+
+结果页允许创作者在发布前直接编辑：
+
+1. `关卡名`
+2. `摘要`
+3. `题材标签`
+
+这 3 个字段不能只停留在前端临时态。
+
+本轮冻结为：
+
+1. `publish_puzzle_work` 允许直接携带 `levelName / summary / themeTags`
+2. `spacetime-module` 在发布事务内先把这些字段覆盖回 session draft 真相
+3. 覆盖后的 draft 再参与发布校验与 profile 持久化
+
+这样可以避免额外新增一条“草稿轻量编辑 procedure”，同时确保结果页编辑内容会真实进入广场作品与后续运行时 HUD。
+
+## 7. 运行态规则冻结
+
+### 7.1 难度推进
+
+```ts
+function resolvePuzzleGridSize(clearedLevelCount: number): 3 | 4 {
+  return clearedLevelCount >= 3 ? 4 : 3;
+}
+```
+
+### 7.2 棋盘初始化
+
+1. 根据正式图片与网格规格生成 `pieceId -> correctRow/correctCol`。
+2. 随机打乱到非完成态。
+3. 生成初始 `mergedGroups = []`，再执行一次正确连接检查。
+
+### 7.3 正确连接
+
+若两个拼块在当前棋盘中四向相邻，且它们在原图上的正确位置也以同方向相邻，则视为正确连接。
+
+所有正确连接链通过并查集合并为 `mergedGroup`。
+
+### 7.4 拖动与拆分
+
+1. 单块拖到单块位置：执行交换。
+2. 合并块拖到任意目标锚点：保持内部相对布局整体重排。
+3. 单块拖到合并块占据位置：先拆分目标合并块，再执行交换，最后重算合并。
+
+### 7.5 通关
+
+当所有拼块回到正确位置，或全盘只剩一个覆盖全部拼块的合并组时，标记当前关卡 `cleared`。
+
+### 7.6 下一关推荐
+
+固定公式：
+
+```ts
+finalScore = tagSimilarityScore * 0.7 + sameAuthorScore * 0.3;
+```
+
+标签相似度首版使用规范化标签集合的 Jaccard。
+
+同分裁决顺序：
+
+1. `tagSimilarityScore` 更高
+2. 当前 run 未出现过
+3. `play_count` 更低
+4. `updated_at` 更近
+
+## 8. 前端接入
+
+### 8.1 平台入口
+
+只改现有平台壳层：
+
+1. 在创作类型弹层新增“拼图玩法”。
+2. 新增拼图专属 stage，不改 RPG runtime 主链。
+
+### 8.2 组件目录
+
+新增：
+
+1. `src/components/puzzle-agent/`
+2. `src/components/puzzle-result/`
+3. `src/components/puzzle-gallery/`
+4. `src/components/puzzle-runtime/`
+
+### 8.3 服务目录
+
+新增：
+
+1. `src/services/puzzle-agent/`
+2. `src/services/puzzle-works/`
+3. `src/services/puzzle-gallery/`
+4. `src/services/puzzle-runtime/`
+
+本轮全部走 HTTP facade，不引入新的前端 Spacetime 直连。
+
+### 8.4 当前前端最小落地补充
+
+当前实现固定走下面这条最小链路：
+
+1. `PlatformEntryCreationTypeModal` 选择 `puzzle`
+2. `PuzzleAgentWorkspace` 收束锚点并触发 `compile_puzzle_draft`
+3. `PuzzleResultView` 编辑 `levelName / summary / themeTags`
+4. 图片生成通过独立 `PuzzleImageStudioModal` 触发，不在结果页内联堆叠
+5. 发布后跳转 `PuzzleGalleryDetailView`
+6. 从详情进入 `PuzzleRuntimeShell`
+
+创作中心作品展示冻结为：
+
+1. 拼图作品也是平台作品，和其他创作作品共用同一套列表项样式。
+2. 创作中心不再保留独立“拼图玩法作品模块”。
+3. 拼图作品仅通过 `拼图` 标签与题材标签区分，不额外拆出第二块作品区。
+4. 创作中心仍保留统一“新建作品”入口，由创建类型弹层继续分流到 RPG / 拼图玩法。
+
+运行时前端表现冻结为：
+
+1. 使用正式封面图按 `correctRow / correctCol` 做真实网格切片渲染
+2. 点击两块时仅前端维护轻量选中态，真正交换以后端返回快照为准
+3. 拖动统一采用 pointer 事件，兼顾网页端与移动端
+4. 不在前端计算合并、拆分、通关与下一关推荐
+
+## 9. 验收与检查
+
+完成后至少执行：
+
+1. `npm run check:encoding`
+2. `npm run typecheck`
+3. `npm run test`
+4. `cargo check -p module-puzzle`
+5. `cargo check -p shared-contracts`
+6. `cargo check -p spacetime-module`
+7. `spacetime generate --no-config --lang rust --out-dir server-rs/crates/spacetime-client/src/module_bindings --module-path server-rs/crates/spacetime-module --include-private --yes`
+8. `cargo check -p spacetime-client`
+9. `cargo check -p api-server`
+
+如果检查中发现拼图主链缺口，继续补齐；如果已经满足 PRD 主链和上述检查，不再追加额外玩法能力。
+
+## 10. 2026-04-22 最终验收记录
+
+本轮已按“最小完整闭环、禁止超出需求过度实现”完成拼图玩法主链落地，并补齐收尾检查。
+
+### 10.1 已落地主链
+
+1. 平台创作中心可选择 `puzzle` 玩法入口。
+2. `PuzzleAgentWorkspace` 已接入 Agent-first 锚点收束与草稿编译。
+3. `PuzzleResultView` 已支持最小结果页编辑与独立图片生成弹层。
+4. 发布后作品可进入拼图广场与详情页。
+5. `PuzzleRuntimeShell` 已按正式封面图真实切片渲染 `3x3 / 4x4` 关卡。
+6. 交换、拖动、拆分、合并、通关、下一关推荐真相全部以后端快照为准。
+
+### 10.2 本轮额外修复的验收阻塞
+
+在最终验收阶段，补齐了与拼图主链无直接业务耦合、但会阻塞仓库整体检查的基线问题：
+
+1. `typecheck` 基线类型不兼容。
+2. `AccountModal` 测试 mock 字段落后于最新鉴权契约。
+3. `customWorld` 存档归一化中场景连接方向未收敛到强类型。
+4. 结果页生成资源在签名 URL 尚未返回时会短暂空白，已调整为先展示原路径占位，再异步替换签名读地址。
+
+### 10.3 实际通过的检查
+
+1. `npm run check:encoding`
+2. `npm run typecheck`
+3. `npm run test`
+4. `cargo check -p module-puzzle`
+5. `cargo check -p shared-contracts`
+6. `cargo check -p spacetime-module`
+7. `cargo check -p spacetime-client`
+8. `cargo check -p api-server`
+
+### 10.4 冻结说明
+
+截至本次验收，拼图玩法已满足 PRD 要求的最小产品闭环；未继续扩展排行榜、提示、体力、异形拼块、倒计时、前端本地裁决等超出本轮需求的能力。
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -42,6 +42,9 @@
 - [SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md)：冻结 `M5` Agent session create / snapshot 的最小 SpacetimeDB 与 Axum facade 闭环，明确本轮不迁移 LLM、SSE、卡片更新和完整 action registry。
 - [SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md)：冻结 `M5` Agent `message submit / operation query` 的 deterministic 最小闭环，明确同步写入 user/assistant 消息、`process_message` operation 与 session 进度推进规则。
 - [SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md)：冻结 `M5` Agent `/messages/stream` 的最小兼容 SSE facade，明确复用 Stage 7 的同步写表逻辑，只输出当前前端真实消费的 `reply_delta / session / done / error` 事件。
+- [BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md](./BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md)：冻结大鱼吃小鱼玩法本轮最小完整落地方案，明确 `module-big-fish`、SpacetimeDB 表 / procedure、Axum facade、前端接入和运行态规则边界。
+- [PUZZLE_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md](./PUZZLE_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md)：冻结拼图玩法本轮最小完整落地方案，明确 `module-puzzle`、SpacetimeDB 表 / procedure、Axum facade、前端接入，以及交换 / 合并 / 拖动 / 拆分 / 下一关推荐边界。
+- [UNIFIED_CREATION_AGENT_CHAT_FRAMEWORK_2026-04-22.md](./UNIFIED_CREATION_AGENT_CHAT_FRAMEWORK_2026-04-22.md)：冻结所有创作品类 Agent 聊天 UI 与对话进度管理统一框架，明确品类差异只保留锚点映射、提示词/话术和 action。
 - [SPACETIMEDB_CUSTOM_WORLD_LIBRARY_DETAIL_STAGE5_EXTENSION_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_DETAIL_STAGE5_EXTENSION_DESIGN_2026-04-22.md)：补齐 `M5` Stage 5 遗漏的 owner-only `GET /api/runtime/custom-world-library/:profileId` 设计，冻结单条 profile detail 的 SpacetimeDB procedure、client facade、404 语义与 Axum 路由扩展方式。
 - [SPACETIMEDB_CUSTOM_WORLD_WORKS_AND_AGENT_EXTENSION_STAGE9_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_WORKS_AND_AGENT_EXTENSION_STAGE9_DESIGN_2026-04-22.md)：冻结 `M5` 剩余主链的 works、card detail、publish gate、supportedActions、action registry 与 AI/OSS 兼容路由边界，作为 Stage 9 到收口阶段的统一落地依据。
 - [M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](./M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)：冻结 `M3` 第二批 `browse history` 纵向切片的 `user_browse_history` 表、双路径 facade、宽松归一化、去重排序规则与测试策略。
--- a/docs/technical/UNIFIED_CREATION_AGENT_CHAT_FRAMEWORK_2026-04-22.md
+++ b/docs/technical/UNIFIED_CREATION_AGENT_CHAT_FRAMEWORK_2026-04-22.md
@@ -0,0 +1,126 @@
+# 统一创作品类 Agent 对话框架技术方案
+
+日期：`2026-04-22`
+
+## 1. 目标
+
+把平台内所有“先 Agent 聊天收束锚点，再生成结果页”的创作流程统一到一套前端框架：
+
+1. UI 交互共用一套：标题区、返回、生成结果页按钮、锚点卡片、进度条、操作横幅、聊天气泡、推荐回复、输入框。
+2. 对话进度管理共用一套：进度归一化、忙碌态判断、SSE `reply_delta / session / error` 解析、操作状态展示。
+3. 品类差异只允许落在配置和后端领域逻辑：锚点列表、提示词/占位文案、生成结果页 action、快捷补全/总结话术、结果页与运行态。
+
+## 2. 本轮范围
+
+覆盖当前已接入平台入口的三条创作链：
+
+1. RPG / Custom World Agent 创作。
+2. 大鱼吃小鱼 Agent 创作。
+3. 拼图 Agent 创作。
+
+本轮不迁移结果页、运行态、发布、资产生成 UI；这些仍按各品类自己的页面承载。
+
+## 3. 前端结构
+
+新增目录：
+
+```text
+src/components/creation-agent/
+├─ CreationAgentWorkspace.tsx
+└─ index.ts
+
+src/services/creation-agent/
+├─ creationAgentProgress.ts
+├─ creationAgentSse.ts
+└─ index.ts
+```
+
+### 3.1 `CreationAgentWorkspace`
+
+统一组件只接收通用 view model：
+
+1. `session`: `CreationAgentSessionView | null`
+2. `theme`: 品类主题色与背景 class
+3. `primaryAction`: 生成结果页按钮配置
+4. `progressActions`: 总结、补全等可选快捷动作
+5. `activeOperation`: 可选操作状态
+6. `streamingReplyText / isStreamingReply / isBusy / error`
+7. `onBack / onSubmitText / onPrimaryAction / onQuickAction`
+
+组件内部只做表现，不读取任何 RPG、Big Fish、Puzzle 专属字段。
+
+### 3.2 会话 view model
+
+各品类工作区负责把自己的 session 映射成：
+
+1. `title`
+2. `assistantSummary`
+3. `progressPercent`
+4. `currentTurn`
+5. `anchors: { key, label, value, status }[]`
+6. `messages: { id, role, kind, text, createdAt }[]`
+7. `recommendedReplies`
+
+因此新增品类时只需要新增 mapper，不再复制聊天工作区。
+
+### 3.3 进度管理
+
+`creationAgentProgress.ts` 统一提供：
+
+1. `normalizeCreationAgentProgress(progressPercent)`
+2. `isCreationAgentOperationBusy(operation)`
+3. `resolveCreationAgentProgressHint(progressPercent, copy?)`
+4. `resolveCreationAnchorStatusLabel(status)`
+5. `createCreationAgentClientMessageId(prefix)`
+
+### 3.4 SSE 解析
+
+`creationAgentSse.ts` 统一解析现有 SSE 事件：
+
+1. `reply_delta`: 调用 `onUpdate(text)`
+2. `session`: 缓存最终 session
+3. `error`: 抛出后端错误
+4. 流结束后若没有 session，抛出品类传入的 incomplete message
+
+各品类 client 只负责打开自己的 URL 和提供类型参数。
+
+## 4. 品类差异边界
+
+### 4.1 RPG / Custom World
+
+保留差异：
+
+1. 8 个 RPG 高杠杆锚点映射。
+2. 总结当前设定话术。
+3. 补全剩余设定话术。
+4. 生成结果页 action：`draft_foundation`。
+
+### 4.2 大鱼吃小鱼
+
+保留差异：
+
+1. 4 个玩法锚点映射。
+2. 输入框占位提示。
+3. 生成结果页 action：`big_fish_compile_draft`。
+
+### 4.3 拼图
+
+保留差异：
+
+1. 拼图视觉/题材锚点映射。
+2. 输入框占位提示。
+3. 生成结果页 action：`compile_puzzle_draft`。
+
+## 5. 禁止事项
+
+1. 禁止在统一组件中判断具体品类名称后写分支业务。
+2. 禁止把 Big Fish / Puzzle 的状态写入 RPG 命名脚本。
+3. 禁止把后端锚点收束、提示词生成或进度裁决搬到前端。
+4. 禁止为了统一 UI 改写结果页、运行态或发布流程。
+
+## 6. 验收
+
+1. 三个创作流程的 Agent 聊天区都通过 `CreationAgentWorkspace` 渲染。
+2. Big Fish 与 Puzzle 不再各自复制聊天 UI、锚点卡片、输入框和进度条。
+3. RPG / Custom World 保留原有“总结当前设定 / 补全剩余设定 / 生成游戏设定草稿”交互。
+4. 定向 TypeScript / ESLint / 编码检查通过。