1

docs/technical/PUZZLE_AGENT_ACTION_RESPONSE_SESSION_2026-04-25.md

@@ -0,0 +1,18 @@
+# 拼图 Agent 操作回包收口说明
+
+## 背景
+
+拼图结果页在执行 `select_puzzle_image` 时，前端先调用 `POST /api/runtime/puzzle/agent/sessions/:sessionId/actions`，随后又调用 `GET /api/runtime/puzzle/agent/sessions/:sessionId` 拉取完整会话。完整会话包含消息、草稿与结果预览，体积明显大于一次选图操作本身，导致选择候选图时出现无意义流量与体感延迟。
+
+## 落地规则
+
+- `actions` 接口在服务端本来已经拿到变更后的 session，因此回包必须直接包含 `operation + session`。
+- 前端收到 `actions` 回包后直接用 `session` 更新本地状态，不再为了同步选图、生成图片或编译草稿而补发完整会话 `GET`。
+- `publish_puzzle_work` 发布后仍由服务端重新读取一次最新 session 并放入同一个 action response，前端只保留作品架与广场详情的必要刷新。
+- 该改动只收敛 Rust api-server 与前端 contract，不引入 server-node 兼容逻辑。
+
+## 验收口径
+
+1. 选择拼图候选图只产生一次 `POST /actions`，不再紧跟完整 session `GET`。
+2. 选图后结果页仍立即反映选中的正式图。
+3. 发布后仍能跳转到已发布拼图详情。

docs/technical/PUZZLE_BIG_FISH_DRAFT_PROGRESS_AND_ASSET_CHAIN_2026-04-25.md

@@ -0,0 +1,53 @@
+# 拼图与大鱼吃小鱼草稿生成进度页落地方案（2026-04-25）
+
+## 背景
+
+RPG 在点击生成草稿后会离开聊天工作区，进入独立的生成进度页，并在该页展示生成链路的阶段、锚点与最终草稿内容。拼图与大鱼吃小鱼此前点击“生成结果页”后直接跳到结果页，正式图片、动作与背景仍分散在结果页工坊里逐个生成，导致用户无法看到“正在一次性准备完整草稿”的过程。
+
+## 落地边界
+
+- 前端只负责展示生成进度与触发已有后端动作，不新增 server-node 或 PostgreSQL 链路。
+- 后端继续沿用 `server-rs` + SpacetimeDB 的会话、草稿与资产写入能力；“一次性生成所有需要的东西”必须由 `server-rs` 的 compile action 承担，前端只发起一次 action 并展示进度页。
+- 拼图生成草稿链路必须包含：结果页草稿、候选图生成、正式图确认。
+- 大鱼吃小鱼生成草稿链路必须包含：玩法草稿、关卡主图、动作素材、场地背景。
+- 生成过程中展示的“角色描述、角色图片、动作”等，统一映射为锚点、草稿蓝图与资产步骤，不把规则说明类文本写成默认 UI 文案。
+
+## 交互设计
+
+1. 用户在拼图或大鱼吃小鱼 Agent 工作区点击生成按钮。
+2. 页面立即切换到独立生成进度页，同时只向 `server-rs` 发起一次 compile action，返回按钮在生成中禁用，避免中途回退造成状态漂移。
+3. 进度页左侧展示阶段进度、步骤卡片与错误信息；右侧展示当前锚点与已成形的草稿结构。
+4. 全量生成成功后自动进入对应结果页，结果页直接展示已生成的资产。
+5. 生成失败时停留在进度页，用户可返回工作区补充设定，或点击重试重新执行完整草稿链路。
+
+## 阶段映射
+
+### 拼图
+
+- `compile_puzzle_draft`：在 `server-rs` 内整理主题、主体、构图与标签，写入结果页草稿。
+- `compile_puzzle_draft`：同一次后端 action 内根据草稿摘要生成候选图。
+- `compile_puzzle_draft`：同一次后端 action 内自动选择第一张候选图作为正式图。
+- `ready`：进入拼图结果页。
+
+### 大鱼吃小鱼
+
+- `big_fish_compile_draft`：在 `server-rs` 内生成玩法草稿、关卡角色描述、背景蓝图与运行参数。
+- `big_fish_compile_draft`：同一次后端 action 内按每个关卡生成主角色/鱼群图片。
+- `big_fish_compile_draft`：同一次后端 action 内按每个关卡生成 `idle_float` 与 `move_swim` 动作素材。
+- `big_fish_compile_draft`：同一次后端 action 内生成玩法场地背景。
+- `ready`：进入大鱼吃小鱼结果页。
+
+## 前端流程收口
+
+- 拼图与大鱼吃小鱼共用 `usePlatformCreationAgentFlowController` 管理会话、流式回复、忙碌态、错误态和草稿恢复，页面层不再重复手写两套 submit/action 流程。
+- 玩法特有的生成进度只通过 `beforeExecuteAction` 与 `onActionError` 这类回调接入：compile action 发起前切到独立生成页并初始化进度，失败时把进度置为 failed。
+- compile action 成功后继续由通用控制器切到结果页，页面层只补齐生成资产数量、拼图操作记录、作品架与广场刷新等玩法差异。
+- 离开玩法流程时，先清理运行态与生成进度态，再交给通用控制器恢复创作中心，避免流式回复和进度状态在下一次创作中残留。
+
+## 验收点
+
+- 拼图和大鱼吃小鱼点击生成草稿后不再直接停留在聊天工作区等待。
+- 生成中可看到独立进度页，且进度步骤随 action 完成逐步推进。
+- 拼图结果页打开时已有正式图；大鱼结果页打开时主图、动作和背景资产均已写入 `assetSlots`。
+- 前端点击生成草稿时不串行调用多个资产 action；多阶段业务编排收敛在 `server-rs`。
+- 不新增 server-node 依赖，不复活 legacy public 静态资产路径。

docs/technical/PUZZLE_SINGLE_PLAYER_AND_REAL_IMAGE_PLAN_2026-04-24.md

@@ -15,7 +15,7 @@
 2. 交换拼图块、拖动拼图块、关卡是否拼完，全部由前端本地计算。
 3. 本地运行态不调用 `/api/runtime/puzzle/runs/*` 写回当前过程状态。
 4. 关闭玩法后，这次运行态直接失效，不做断点续玩，不做跨端同步。
-5. 通关后的第一版接续只保证单次游玩闭环：本地生成一个临时 `recommendedNextProfileId`，点击“下一关”后沿用当前作品图片、作者和标签，重建下一关棋盘；正式的广场推荐池仍留给后端运行态版本恢复。
+5. 通关后的第一版接续按“广场作品优先”执行：先从拼图广场读取未玩过且有正式图的作品；广场没有可用作品时，再使用当前草稿期间已生成但未消费的候选图；候选图仍不足时，现场调用 `generate_puzzle_images` 生成候选图，并在运行页弹出等待面板。
 6. 后端仍然负责：
    - Agent 会话
    - 结果页草稿编译
@@ -59,8 +59,11 @@
 1. 进入玩法时从作品详情构造本地 `run`
 2. 交换 / 拖动 / 通关时由前端工具函数返回新的 `run`
 3. 通关时本地写入临时下一关 id，用于显示“下一关”按钮
-4. 点击下一关时重置棋盘、推进关卡序号，并按已通关数量切换 `3x3 / 4x4`
-5. 当前不依赖后端 `start/swap/drag/next-level` 接口完成主链
+4. 点击下一关时前端只提交当前 `run` 与可选 `sourceSessionId` 到 Rust `api-server`，不在前端判断图片来源
+5. `api-server` 优先用广场作品详情构造下一关；如果广场没有可用作品，则把草稿候选图包装成一次本地关卡来源
+6. 草稿候选图仍不足时，`api-server` 现场调用真实生图链生成候选图；前端只展示等待弹窗并接收最终 `run`
+7. 每次进入下一关都会重置棋盘、推进关卡序号，并按已通关数量切换 `3x3 / 4x4`
+8. 当前不依赖后端 `start/swap/drag/next-level` 接口保存过程状态
 
 ## 5. 当前实现判断标准
 
@@ -70,5 +73,7 @@
 2. 返回路径切到 `/generated-puzzle-assets/*`。
 3. 未配置 DashScope 或 OSS 时，接口明确返回 provider 级错误，而不是静默回退占位图。
 4. 玩家进入拼图玩法后，即使后端运行态接口不可用，也能在本地完成交换与拖动。
-5. 玩家完成整张图后能看到通关态与“下一关”入口，点击后进入新棋盘。
-6. 关闭玩法后不保留当前 run 进度。
+5. 玩家完成整张图后能看到通关态与“下一关”入口。
+6. 广场有可用作品时，下一关内容来自广场作品。
+7. 广场没有可用作品时，下一关内容来自草稿候选图；候选图不足时现场生成并显示等待面板。
+8. 关闭玩法后不保留当前 run 进度。

docs/technical/README.md

@@ -17,11 +17,13 @@
 - [CREATION_AGENT_CLIENT_AND_FLOW_CONTROLLER_REUSE_2026-04-25.md](./CREATION_AGENT_CLIENT_AND_FLOW_CONTROLLER_REUSE_2026-04-25.md)：冻结三类作品创作 Agent client 通用工厂与平台轻量流程 controller 的复用边界，明确本轮只收口 HTTP/SSE 骨架和大鱼/拼图会话流程，不合并 RPG 自动保存主链。
 - [BACKEND_CREATION_AGENT_LLM_TURN_COMMONIZATION_2026-04-25.md](./BACKEND_CREATION_AGENT_LLM_TURN_COMMONIZATION_2026-04-25.md)：冻结后端创作 Agent LLM turn 公共化边界，收口模型可用性检查、流式 JSON 回复抽取、最终 JSON 解析与中文错误映射，玩法 schema 和写回逻辑继续留在各自模块。
 - [CREATION_WORK_SHELF_UNIFICATION_2026-04-25.md](./CREATION_WORK_SHELF_UNIFICATION_2026-04-25.md)：冻结创作中心作品货架统一视图模型，先在前端归一 RPG、大鱼、拼图 works 的展示字段、筛选状态和卡片动作语义，不新增后端聚合接口。
+- [PUZZLE_BIG_FISH_DRAFT_PROGRESS_AND_ASSET_CHAIN_2026-04-25.md](./PUZZLE_BIG_FISH_DRAFT_PROGRESS_AND_ASSET_CHAIN_2026-04-25.md)：冻结拼图与大鱼吃小鱼点击生成草稿后进入独立进度页，并一次性生成草稿、图片与动作资产的前端编排边界。
 - [BIG_FISH_DIRECTION_TOUCH_CONTROL_2026-04-24.md](./BIG_FISH_DIRECTION_TOUCH_CONTROL_2026-04-24.md)：记录大鱼吃小鱼从固定摇杆改为屏幕首触点方向控制，并要求本地直达局在未操作时保持对象运动。
 - [RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md](./RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md)：记录 `server-rs` 无参数 `cargo build` 链接 `spacetime-module` 失败的根因，并冻结默认只构建原生 `api-server`、模块产物继续走 `spacetime build` 的命令边界。
 - [BIG_FISH_DIRECT_ROUTE_PLAYGROUND_2026-04-24.md](./BIG_FISH_DIRECT_ROUTE_PLAYGROUND_2026-04-24.md)：记录 `/big-fish` 大鱼吃小鱼玩法直达入口，明确复用现有 `BigFishRuntimeShell` 和本地占位运行态的调试边界。
 - [PUZZLE_DIRECT_ROUTE_PLAYGROUND_2026-04-24.md](./PUZZLE_DIRECT_ROUTE_PLAYGROUND_2026-04-24.md)：记录 `/puzzle` 拼图玩法直达入口，明确复用现有 `PuzzleRuntimeShell` 和本地占位图运行态的调试边界。
 - [FRONTEND_INDEPENDENT_PAGE_ROUTES_2026-04-25.md](./FRONTEND_INDEPENDENT_PAGE_ROUTES_2026-04-25.md)：记录平台入口、RPG 创作、拼图创作和大鱼吃小鱼创作各页面的独立前端路径，以及与 `/puzzle`、`/big-fish` 调试直达入口的边界。
+- [PUZZLE_AGENT_ACTION_RESPONSE_SESSION_2026-04-25.md](./PUZZLE_AGENT_ACTION_RESPONSE_SESSION_2026-04-25.md)：记录拼图 Agent `actions` 回包直接携带最新 session，避免选图后额外拉取完整会话大包的接口收口规则。
 - [CREATION_AGENT_PUBLISH_GATE_NORMALIZE_WRITEBACK_FIX_2026-04-24.md](./CREATION_AGENT_PUBLISH_GATE_NORMALIZE_WRITEBACK_FIX_2026-04-24.md)：记录结果页 profile 归一化回写丢失顶层 `worldHook / playerPremise` 导致 publish gate 继续误报结构 blocker 的根因，并冻结前端归一化保留发布字段的修复口径。
 
 - [CUSTOM_WORLD_RESULT_ENTITY_GENERATION_FIX_2026-04-24.md](./CUSTOM_WORLD_RESULT_ENTITY_GENERATION_FIX_2026-04-24.md)：记录世界结果页在 Agent 草稿模式下新增场景、新增 NPC 生成成功但结果页字段不可用的根因，并冻结 `api-server` 生成归一化层补齐 profile 字段的修复口径。