diff --git a/.gitignore b/.gitignore
index 66ab730b..7b5bde66 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,7 @@ coverage/
/.codex-cargo-home-*/
/.codex-cache*/
/.tmp*/
+/.idea/
.preview.*
tmp_*
tmp/
@@ -27,3 +28,4 @@ temp*build*/
/public/generated-character-drafts
/public/generated-characters
/.codex-temp
+/target/
diff --git a/.idea/Genarrative.iml b/.idea/Genarrative.iml
deleted file mode 100644
index 20f0a74d..00000000
--- a/.idea/Genarrative.iml
+++ /dev/null
@@ -1,34 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
index 3d74691c..a77790fa 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -10,7 +10,7 @@
- [技术方案](./technical/README.md)：动画、服务端、外部产品形态拆解。
- [规划与优先级](./planning/README.md)：当前阶段的迭代排序与落地优先级。
- [参考目录](./reference/README.md)：脚本/Function 速查入口。
-- [PRD](./prd)：产品需求与阶段计划。
+- [PRD](./prd)：产品需求与阶段计划；新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)。
## 推荐阅读顺序
diff --git 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
index d262256c..54c436a8 100644
--- 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
@@ -313,6 +313,8 @@ interface PuzzleAnchorPack {
1. `api-server` 写入 SpacetimeDB 的候选图 JSON 必须使用 `module-puzzle::PuzzleGeneratedImageCandidate` 持久化结构。
2. 持久化字段名保持 Rust 侧 `snake_case`，例如 `candidate_id`、`image_src`、`asset_id`、`actual_prompt`、`source_type`。
3. 面向前端的 HTTP 响应仍由 `shared-contracts` 单独映射为 `camelCase`，不能把响应层字段名直接写入 SpacetimeDB JSON。
+4. 多次生成候选图时必须追加到当前候选池，不能清空已有候选图；已有正式选择保持不变，新追加候选图默认不抢占 `selected` 状态。
+5. 追加生成时 `candidate_id` 必须按当前候选数量续号，避免前端列表 key 与后端选择动作命中旧候选图。
## 7.6 拼图图片资产要求
diff --git a/docs/prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md b/docs/prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md
new file mode 100644
index 00000000..55e13adc
--- /dev/null
+++ b/docs/prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md
@@ -0,0 +1,637 @@
+# AI 原生 RPG 模板开场动画 PRD
+
+更新时间：`2026-04-25`
+
+## 0. 文档目的
+
+这份 PRD 用于把 RPG 模板中的“开场动画”从一张静态封面或一段普通介绍，升级成可由 AI 资产链稳定生成、可保存、可预览、可发布、可在开局自动播放的 `15` 秒视频。
+
+本次开场动画采用当前 AI 视频生成更稳定的工程化工作流：
+
+```text
+RPG 世界草稿 / 模板锚点
+-> 生成 4 张首尾关键帧图
+-> 用关键帧 1-2 生成第 1 段 5 秒视频
+-> 用关键帧 2-3 生成第 2 段 5 秒视频
+-> 用关键帧 3-4 生成第 3 段 5 秒视频
+-> 统一规格转码并拼接为 15 秒开场动画
+-> 挂回 RPG 模板与作品资产
+-> 玩家首次进入 RPG 运行态时播放，结束后进入开局场景
+```
+
+这份文档只做产品、数据、生成链路和落地边界设计，不直接改工程代码。
+
+---
+
+## 1. 在线工作流调研结论
+
+### 1.1 为什么不用一次性生成 15 秒长视频
+
+当前主流 AI 视频模型已经能直接生成较长视频，但对游戏开场来说，一次性生成 `15` 秒仍有 4 个风险：
+
+1. 角色、服装、标志物和世界风格容易在中段漂移。
+2. 镜头容易自发切换，导致关键叙事信息没有按顺序出现。
+3. 第 15 秒无法稳定落到玩家即将进入的开局场景。
+4. 失败后重跑成本高，不能只修某一幕。
+
+因此本项目第一版采用“关键帧定锚 + 分段生成 + 后期拼接”的方式。每段只表达一个镜头目标，失败时只重跑对应片段。
+
+### 1.2 可参考的行业能力
+
+调研到的主流能力如下：
+
+| 来源 | 对本项目有用的结论 |
+| --- | --- |
+| Google Vertex AI Veo | 官方支持上传起始帧与结束帧生成视频，控制视频首尾画面。文档更新时间为 `2026-04-24`。参考：https://docs.cloud.google.com/vertex-ai/generative-ai/docs/video/generate-videos-from-first-and-last-frames |
+| Runway Gen-4 | 官方建议 `5` 或 `10` 秒片段，把每次生成视作单一场景，并强调输入图决定起始视觉、提示词重点写运动。参考：https://help.runwayml.com/hc/en-us/articles/39789879462419-Gen-4-Video-Prompting-Guide |
+| Kling AI | 首尾帧功能用于上传两张图生成过渡视频，并提示两张图主题和构图越接近，`5` 秒内过渡越稳定；差异太大会触发镜头切换。参考：https://kling.ai/quickstart/ai-video-start-end-frames |
+| Luma Ray | 强调关键帧、角色参考和跨镜头连续性，可用于理解“长镜头拆段 + 关键帧控制”的制作方向。参考：https://lumalabs.ai/ray |
+
+### 1.3 对本项目的工作流选择
+
+本项目优先采用如下策略：
+
+1. 用文本模型先从 RPG 模板锚点生成 `openingAnimationBlueprint`。
+2. 用图片模型一次性生成 `4` 张统一风格关键帧。
+3. 用首尾帧视频模型生成 `3` 个 `5` 秒片段。
+4. 用后端 `ffmpeg` 做统一转码、无缝拼接和封面帧提取。
+5. 用 OSS + `asset_object` + `asset_entity_binding` 保存最终资产。
+6. 前端只展示生成状态、预览视频和开局播放，不承担生成逻辑和视频拼接。
+
+第一版模型供应商不写死在产品逻辑中。国内可用主链优先复用当前 Rust 资产生成链中已有的 Ark / DashScope 配置；如后续接入 Veo、Runway、Kling、Luma，只作为 `provider` 扩展，不改变 RPG 模板数据结构。
+
+---
+
+## 2. 一句话定义
+
+RPG 模板开场动画是一段由 `4` 张叙事关键帧和 `3` 个 `5` 秒 AI 视频片段组成的 `15` 秒多场景冒险开场演出，用于在玩家首次进入作品时快速建立世界观、核心冲突、目标牵引，并自然衔接到开局场景。
+
+---
+
+## 3. 本次目标
+
+1. RPG 模板必须新增开场动画蓝图，作为世界草稿和发布作品的一部分。
+2. 开场动画必须固定为 `4` 张关键帧、`3` 个视频片段、总时长 `15` 秒。
+3. 四张关键帧必须分别表达：
+ - 第一幕：世界观
+ - 第二幕：核心冲突与核心角色出场
+ - 第三幕：核心目标
+ - 第四幕：衔接开局场景
+4. 三段视频必须分别由相邻关键帧作为首尾帧生成：
+ - 视频 1：关键帧 1 -> 关键帧 2
+ - 视频 2：关键帧 2 -> 关键帧 3
+ - 视频 3：关键帧 3 -> 关键帧 4
+5. 最终成片必须能在 RPG 作品详情、创作结果页和运行时开局链路中复用。
+6. 播放结束后必须进入 RPG 开局场景；如果玩家跳过，也进入同一个开局场景。
+7. 开场动画生成失败不能阻断 RPG 发布和进入游戏，必须允许重新生成和无动画降级。
+8. 所有生成、拼接、资产落库和状态流转都必须在 Rust 后端完成，禁止回到 `server-node`。
+
+---
+
+## 4. 明确不做
+
+1. 不做一次性长视频生成主链。
+2. 不在前端浏览器里拼接视频。
+3. 不把功能说明、规则解释默认写进游戏 UI。
+4. 不新增独立的“开场动画系统页面”；入口嵌入现有 RPG 创作结果页和模板配置区。
+5. 不要求第一版生成配音、字幕、音乐和音效。
+6. 不要求运行时根据玩家选择动态改写开场动画。
+7. 不在 SpacetimeDB reducer 内调用外部视频模型、OSS 或文件系统。
+8. 不兼容 `server-node` 旧生成链；旧实现只允许参考和迁移。
+
+---
+
+## 5. 叙事设计
+
+## 5.1 四幕语义
+
+| 幕 | 关键表达 | 画面职责 | 与 RPG 模板字段关系 |
+| --- | --- | --- | --- |
+| 第一幕：世界观 | 这个世界是什么样，正在承受什么长期压力 | 展示地貌、文明、时代气质、异常现象或历史伤痕 | 读取 `worldTheme`、`worldHook`、世界线程、主题母题、核心地标 |
+| 第二幕：核心冲突与核心角色 | 谁被卷入冲突，冲突以什么形式爆发 | 让可扮演角色或核心 NPC 出场，并露出敌对力量、灾变、追捕、仪式或阵营压迫 | 读取主角、核心 NPC、阵营线、明线冲突 |
+| 第三幕：核心目标 | 玩家为什么要开始冒险 | 展示目标物、禁地、远方地标、失落遗物、必须抵达的地点或必须拯救的人 | 读取主线目标、初始任务、关键物件、章节目标 |
+| 第四幕：开局衔接 | 玩家即将在哪里醒来、抵达或被迫行动 | 画面落到第一个可操作场景，构图必须可作为游戏开局背景的前导镜头 | 读取开局场景、多幕第一幕背景、初始 NPC |
+
+### 5.2 镜头节奏
+
+| 视频片段 | 时长 | 首尾帧 | 镜头目标 |
+| --- | --- | --- | --- |
+| `opening_clip_01` | `5s` | 世界观帧 -> 冲突帧 | 从宏观世界推进到冲突爆发，镜头可采用推进、俯冲、穿越云层、掠过地标 |
+| `opening_clip_02` | `5s` | 冲突帧 -> 目标帧 | 让核心角色带着冲突压力朝目标靠近，镜头可采用跟随、转身、拔剑、奔跑、法阵亮起 |
+| `opening_clip_03` | `5s` | 目标帧 -> 开局场景帧 | 从目标牵引落回玩家即将进入的地点，镜头可采用推门、坠落、醒来、抵达、火光转场 |
+
+### 5.3 提示词原则
+
+生成视频片段时，提示词只描述本段运动，不重复大段设定说明。
+
+每段提示词必须包含：
+
+1. 镜头运动：例如缓慢推进、低空掠过、跟随角色、从远景落到近景。
+2. 主体运动：例如角色转身、队伍穿过遗迹、光芒汇聚、风暴逼近。
+3. 场景运动：例如云层翻涌、旗帜震动、烛火摇曳、尘土散开。
+4. 连续性约束：首帧和尾帧中的角色、服装、标志物、色彩基调保持一致。
+5. 游戏开场质感：多场景冒险 RPG、电影感、清晰主体、可读构图。
+
+每段提示词禁止：
+
+1. 同时要求多个互相冲突的镜头切换。
+2. 用抽象词替代具体运动。
+3. 使用“不出现 / 不要 / 禁止”作为主要约束；应改写成正向描述。
+4. 要求模型在 `5` 秒内完成跨时代、跨空间、跨角色的大跳变。
+
+---
+
+## 6. 数据结构设计
+
+## 6.1 RPG 模板新增字段
+
+在 RPG 模板 / 世界 profile 中新增：
+
+```ts
+type RpgOpeningAnimationBlueprint = {
+ id: string;
+ enabled: boolean;
+ status: 'not_started' | 'planning' | 'keyframes_generating' | 'clips_generating' | 'stitching' | 'ready' | 'failed';
+ version: number;
+ provider: string;
+ aspectRatio: '16:9';
+ totalDurationSec: 15;
+ clipDurationSec: 5;
+ keyframes: RpgOpeningAnimationKeyframe[];
+ clips: RpgOpeningAnimationClip[];
+ finalAsset?: RpgOpeningAnimationFinalAsset;
+ fallbackPosterAssetId?: string;
+ error?: RpgOpeningAnimationError;
+ createdAt: string;
+ updatedAt: string;
+};
+```
+
+说明：
+
+1. `enabled` 控制运行时是否播放。
+2. `status` 由后端写入，前端只订阅和展示。
+3. `provider` 表示真实使用的生成供应商，例如 `ark`、`dashscope`、`veo`、`runway`、`kling`、`luma`。
+4. 第一版只支持 `16:9`，移动端播放时做安全裁切，不生成竖版副本。
+
+## 6.2 关键帧对象
+
+```ts
+type RpgOpeningAnimationKeyframe = {
+ id: string;
+ order: 1 | 2 | 3 | 4;
+ actRole: 'worldview' | 'conflict_and_role' | 'core_goal' | 'opening_scene_bridge';
+ title: string;
+ narrativeIntent: string;
+ prompt: string;
+ negativePrompt?: string;
+ sourceAnchorIds: string[];
+ assetObjectId?: string;
+ previewUrl?: string;
+ generationStatus: 'pending' | 'generating' | 'ready' | 'failed';
+};
+```
+
+字段口径：
+
+1. `title` 只用于后台调试和创作结果页内部管理，不直接作为游戏 UI 文案。
+2. `narrativeIntent` 必须写清该帧承担的剧情功能。
+3. `sourceAnchorIds` 记录本帧来自哪些模板锚点，便于后续重新生成时保持语义。
+
+## 6.3 视频片段对象
+
+```ts
+type RpgOpeningAnimationClip = {
+ id: string;
+ order: 1 | 2 | 3;
+ fromKeyframeId: string;
+ toKeyframeId: string;
+ durationSec: 5;
+ prompt: string;
+ providerTaskId?: string;
+ assetObjectId?: string;
+ previewUrl?: string;
+ generationStatus: 'pending' | 'generating' | 'ready' | 'failed';
+ technicalProfile: {
+ width: number;
+ height: number;
+ fps: 24 | 25 | 30;
+ codec: 'h264';
+ container: 'mp4';
+ };
+};
+```
+
+## 6.4 最终资产对象
+
+```ts
+type RpgOpeningAnimationFinalAsset = {
+ assetObjectId: string;
+ playbackUrl: string;
+ posterAssetObjectId: string;
+ posterUrl: string;
+ durationSec: 15;
+ width: number;
+ height: number;
+ fps: 24 | 25 | 30;
+ codec: 'h264';
+ container: 'mp4';
+ clips: string[];
+ generatedAt: string;
+};
+```
+
+---
+
+## 7. 后端生成流程
+
+## 7.1 总流程
+
+```text
+POST /api/custom-world/:profileId/opening-animation/generate
+-> 校验作品归属与 RPG 类型
+-> 读取世界 profile / 模板锚点 / 开局场景 / 角色视觉描述
+-> 生成 openingAnimationBlueprint 文本计划
+-> 生成 4 张关键帧图
+-> 生成 3 个首尾帧视频片段
+-> 下载远端视频
+-> 统一转码为同规格 mp4
+-> 拼接为 final opening mp4
+-> 提取 poster
+-> 上传 OSS
+-> 确认 asset_object
+-> 绑定到 RPG profile 的 opening-animation 槽位
+-> 写回状态 ready
+```
+
+## 7.2 生成计划阶段
+
+生成计划由 `api-server` 调用 `platform-llm` 完成，不进入 SpacetimeDB reducer。
+
+输入上下文最少包含：
+
+1. 世界一句话钩子。
+2. 主题母题。
+3. 明线冲突。
+4. 暗线冲突的非剧透摘要。
+5. 主角 / 核心 NPC 的视觉描述。
+6. 第一个场景章节和开局场景。
+7. 初始任务目标。
+8. 已有场景图 / 角色图资产 URL。
+
+输出必须是结构化 JSON，至少包含：
+
+1. 四幕 `narrativeIntent`。
+2. 四张关键帧图片 prompt。
+3. 三段视频 motion prompt。
+4. 风格统一约束。
+5. 关键角色和标志物连续性约束。
+
+## 7.3 关键帧生成阶段
+
+关键帧生成必须优先复用已有图片生成链：
+
+1. 统一走 Rust `api-server`。
+2. 真实请求外部图片服务。
+3. 结果落 OSS。
+4. 确认 `asset_object`。
+5. 绑定槽位：
+ - `rpg-opening-keyframe-1`
+ - `rpg-opening-keyframe-2`
+ - `rpg-opening-keyframe-3`
+ - `rpg-opening-keyframe-4`
+
+关键帧生成要求：
+
+1. 分辨率首版固定 `1280x720` 或供应商最接近的 `16:9` 输出。
+2. 四张图必须共享同一 `styleSeed / visualBible`。
+3. 核心角色在第二幕和第三幕必须保持同一服装、轮廓、武器或标志物。
+4. 第四幕必须与开局场景背景语义一致，必要时使用开局场景图作为参考图。
+
+## 7.4 视频片段生成阶段
+
+每段视频生成请求必须显式传入：
+
+1. 首帧图片。
+2. 尾帧图片。
+3. `5` 秒时长。
+4. `16:9` 比例。
+5. 本段 motion prompt。
+6. 连续性约束。
+
+视频片段槽位：
+
+1. `rpg-opening-clip-1`
+2. `rpg-opening-clip-2`
+3. `rpg-opening-clip-3`
+
+如果供应商不支持首尾帧：
+
+1. 该供应商不能作为首选主链。
+2. 只允许作为内部实验 provider。
+3. 不允许把只支持单首帧的结果标记为正式通过。
+
+## 7.5 拼接与转码
+
+后端必须在拼接前统一三段视频规格：
+
+1. 容器：`mp4`
+2. 编码：`h264`
+3. 像素格式：`yuv420p`
+4. 分辨率：`1280x720`
+5. 帧率：优先 `24fps`，若供应商固定 `25fps` 或 `30fps`，三段必须统一。
+6. 音频：第一版默认无音轨；如供应商返回音频，拼接前静音或统一移除。
+
+拼接后必须提取：
+
+1. `poster`：第 `0.5` 秒或第一张关键帧。
+2. `endPoster`：第 `14.5` 秒，用于确认衔接开局场景。
+3. `duration`：必须在 `14.5s ~ 15.5s`。
+
+---
+
+## 8. SpacetimeDB 与 Rust 边界
+
+### 8.1 SpacetimeDB 负责
+
+1. 保存 RPG profile 中的开场动画蓝图状态。
+2. 保存资产对象与业务槽位绑定关系。
+3. 通过 reducer / procedure 更新可订阅状态。
+4. 让前端通过订阅或查询拿到当前 `openingAnimationBlueprint`。
+
+### 8.2 SpacetimeDB 不负责
+
+1. 不调用外部模型。
+2. 不下载视频。
+3. 不执行 `ffmpeg`。
+4. 不访问 OSS。
+5. 不在 reducer 里生成随机非确定性内容。
+
+### 8.3 Rust api-server 负责
+
+1. 编排 LLM 计划、图片生成、视频生成、转码拼接。
+2. 管理异步任务轮询。
+3. 处理 OSS 上传与下载。
+4. 调用 SpacetimeDB procedure 写入最终状态和资产绑定。
+5. 对前端提供 HTTP / SSE 生成进度。
+
+这条边界必须遵守 SpacetimeDB 规则：reducer 是确定性事务，不能把外部 I/O 放进去。
+
+---
+
+## 9. 前端嵌入设计
+
+## 9.1 创作结果页
+
+入口位置：
+
+1. 复用 RPG 创作结果页现有资产区。
+2. 增加一个“开场动画”资产槽。
+3. 点击槽位打开独立面板，不在当前卡片下方展开。
+
+面板能力：
+
+1. 预览最终 `15` 秒视频。
+2. 展示四张关键帧缩略图。
+3. 展示三段视频状态。
+4. 支持重新生成全部。
+5. 支持只重生某张关键帧，并自动标记相关视频片段需要重生。
+6. 支持只重生某段视频。
+7. 支持禁用开场动画。
+
+UI 约束：
+
+1. 不展示大段功能说明。
+2. 状态用短标签和进度表达。
+3. 移动端优先：关键帧横向滑动，视频预览保持 `16:9`。
+4. 按钮使用图标 + 短文本，避免规则说明型文案。
+
+## 9.2 RPG 模板发布
+
+发布时校验：
+
+1. 如果 `enabled = true`，则 `finalAsset` 必须存在且可读取。
+2. 如果生成失败，发布不阻断，但自动写入 `enabled = false` 并保留错误状态。
+3. 发布后的作品详情页可展示开场动画 poster，但不强制自动播放。
+
+## 9.3 运行时开局播放
+
+播放时机：
+
+```text
+玩家点击开始游戏 / 继续进入新开局
+-> 完成角色选择
+-> 初始化 RPG session
+-> 若 openingAnimation.enabled 且 finalAsset 可用
+-> 播放开场动画
+-> 播放结束或跳过
+-> 进入开局场景
+```
+
+规则：
+
+1. 同一个存档只自动播放一次。
+2. 玩家跳过后必须记录 `openingAnimationPlayed = true`。
+3. 继续游戏不自动播放，除非玩家从作品详情页手动预览。
+4. 视频加载失败时直接进入开局场景。
+5. 移动端播放必须提供明显的跳过按钮，但不写说明段落。
+
+---
+
+## 10. 状态机
+
+```text
+not_started
+-> planning
+-> keyframes_generating
+-> clips_generating
+-> stitching
+-> ready
+
+任意生成阶段
+-> failed
+-> planning / keyframes_generating / clips_generating
+```
+
+关键规则：
+
+1. 重生关键帧 1，会使视频 1 失效。
+2. 重生关键帧 2，会使视频 1 和视频 2 失效。
+3. 重生关键帧 3，会使视频 2 和视频 3 失效。
+4. 重生关键帧 4，会使视频 3 失效。
+5. 重生某段视频后必须重新拼接最终成片。
+6. 最终成片 ready 后，旧版本资产不能立即删除，至少保留最近 `2` 个版本用于回滚。
+
+---
+
+## 11. API 设计
+
+### 11.1 生成开场动画
+
+```http
+POST /api/custom-world/:profileId/opening-animation/generate
+```
+
+请求：
+
+```json
+{
+ "mode": "full",
+ "provider": "auto",
+ "forceRegenerate": false
+}
+```
+
+返回：
+
+```json
+{
+ "jobId": "opening_anim_job_xxx",
+ "status": "planning"
+}
+```
+
+### 11.2 重生关键帧
+
+```http
+POST /api/custom-world/:profileId/opening-animation/keyframes/:keyframeId/regenerate
+```
+
+### 11.3 重生视频片段
+
+```http
+POST /api/custom-world/:profileId/opening-animation/clips/:clipId/regenerate
+```
+
+### 11.4 查询状态
+
+```http
+GET /api/custom-world/:profileId/opening-animation
+```
+
+返回当前 `RpgOpeningAnimationBlueprint`。
+
+### 11.5 订阅进度
+
+```http
+GET /api/custom-world/:profileId/opening-animation/jobs/:jobId/stream
+```
+
+SSE 事件：
+
+1. `planning`
+2. `keyframe_ready`
+3. `clip_ready`
+4. `stitching`
+5. `ready`
+6. `error`
+
+---
+
+## 12. 工程落地阶段
+
+### 阶段 1：文档与契约冻结
+
+1. 确认 `RpgOpeningAnimationBlueprint` 字段。
+2. 确认资产槽位命名。
+3. 确认 provider 抽象。
+4. 确认运行时只播放一次的状态字段。
+
+验收：
+
+1. 文档字段可直接编码。
+2. 前后端对同一 JSON contract 无歧义。
+
+### 阶段 2：后端计划与关键帧生成
+
+1. `api-server` 生成四幕计划。
+2. 接入图片生成。
+3. 关键帧落 OSS 和 `asset_object`。
+4. profile 写回关键帧状态。
+
+验收：
+
+1. 能在结果页看到四张真实生成图。
+2. 第四张图语义上能衔接开局场景。
+
+### 阶段 3：首尾帧视频生成
+
+1. 三段视频真实请求外部模型。
+2. 每段固定 `5` 秒。
+3. 每段落 OSS。
+4. 支持失败重试与单段重生。
+
+验收：
+
+1. 三段视频都不是占位视频。
+2. 每段首尾画面与对应关键帧一致。
+
+### 阶段 4：拼接发布与运行时播放
+
+1. 后端统一转码。
+2. 拼接成 `15` 秒成片。
+3. 提取 poster。
+4. RPG 运行态首次开局播放。
+5. 播放结束或跳过进入开局场景。
+
+验收：
+
+1. 最终视频时长在 `14.5s ~ 15.5s`。
+2. 播放后进入的场景与第四幕一致。
+3. 同一存档不会重复自动播放。
+
+---
+
+## 13. 质量验收标准
+
+### 13.1 叙事验收
+
+1. 第一幕不用字幕也能看出世界类型和主要气质。
+2. 第二幕能看出冲突正在发生，并且核心角色可被识别。
+3. 第三幕能看出玩家即将追求的目标。
+4. 第四幕能自然落到开局场景，不像另一个无关地点。
+5. 四幕之间存在视觉连续性，不是四张无关插图。
+
+### 13.2 视频验收
+
+1. 三段均为真实外部生成结果。
+2. 每段约 `5` 秒。
+3. 拼接后无明显黑帧、重复帧、尺寸跳变。
+4. 主体没有严重形变、闪烁、消失。
+5. 核心角色在第二、第三幕保持可识别一致。
+6. 移动端播放不裁掉核心主体。
+
+### 13.3 工程验收
+
+1. 所有生成任务由 Rust `api-server` 编排。
+2. 资产落 OSS，并有 `asset_object` 记录。
+3. 业务实体通过槽位绑定读取资产。
+4. SpacetimeDB reducer 不包含外部 I/O。
+5. 前端刷新后仍能恢复生成状态。
+6. 生成失败有可重试状态，不写入假成功。
+
+---
+
+## 14. 风险与降级
+
+| 风险 | 降级策略 |
+| --- | --- |
+| 关键帧风格不一致 | 用同一 visual bible、参考图和角色视觉描述重生四张图 |
+| 首尾帧差异过大导致视频硬切 | 调整相邻关键帧构图，使主体、视角、色彩更接近 |
+| 第二幕角色漂移 | 使用角色主形象作为参考图，并在第二、第三幕共享角色约束 |
+| 视频生成超时 | 单段失败只重试该段，不重跑全流程 |
+| 拼接后有黑帧 | 后端转码时强制统一 fps、分辨率、像素格式 |
+| 移动端加载慢 | poster 先显示，视频懒加载；失败直接进开局场景 |
+| 供应商审核失败 | 后端生成更保守的原创 prompt 重试一次，仍失败则标记 failed |
+
+---
+
+## 15. 后续扩展
+
+1. 增加背景音乐和环境音，但不改变四帧三段主链。
+2. 为移动端生成 `9:16` 竖版裁切版本。
+3. 支持创作者手动上传某张关键帧，再生成相邻视频。
+4. 支持发布后版本化替换开场动画。
+5. 支持用第四幕直接生成开局场景动态背景。
+6. 支持把开场动画拆出的关键帧回流为作品详情页轮播素材。
+
diff --git a/docs/technical/PUZZLE_AGENT_ACTION_RESPONSE_SESSION_2026-04-25.md b/docs/technical/PUZZLE_AGENT_ACTION_RESPONSE_SESSION_2026-04-25.md
new file mode 100644
index 00000000..2b3c7a8d
--- /dev/null
+++ b/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. 发布后仍能跳转到已发布拼图详情。
diff --git a/docs/technical/PUZZLE_BIG_FISH_DRAFT_PROGRESS_AND_ASSET_CHAIN_2026-04-25.md b/docs/technical/PUZZLE_BIG_FISH_DRAFT_PROGRESS_AND_ASSET_CHAIN_2026-04-25.md
new file mode 100644
index 00000000..2edcc6ec
--- /dev/null
+++ b/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 静态资产路径。
diff --git a/docs/technical/PUZZLE_SINGLE_PLAYER_AND_REAL_IMAGE_PLAN_2026-04-24.md b/docs/technical/PUZZLE_SINGLE_PLAYER_AND_REAL_IMAGE_PLAN_2026-04-24.md
index 9fb0373d..f945798c 100644
--- a/docs/technical/PUZZLE_SINGLE_PLAYER_AND_REAL_IMAGE_PLAN_2026-04-24.md
+++ b/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 进度。
diff --git a/docs/technical/README.md b/docs/technical/README.md
index 0cb211ad..1a89ccef 100644
--- a/docs/technical/README.md
+++ b/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 字段的修复口径。
diff --git a/packages/shared/src/contracts/puzzleAgentActions.ts b/packages/shared/src/contracts/puzzleAgentActions.ts
index 183ec46a..2cc6c2c4 100644
--- a/packages/shared/src/contracts/puzzleAgentActions.ts
+++ b/packages/shared/src/contracts/puzzleAgentActions.ts
@@ -1,3 +1,5 @@
+import type { PuzzleAgentSessionSnapshot } from './puzzleAgentSession';
+
export type PuzzleAgentSuggestedActionType =
| 'request_summary'
| 'compile_puzzle_draft'
@@ -54,6 +56,10 @@ export type PuzzleAgentActionRequest =
themeTags?: string[];
};
+/**
+ * 拼图操作接口直接返回最新会话，避免前端在选图等轻操作后再额外 GET 大体积快照。
+ */
export interface PuzzleAgentActionResponse {
operation: PuzzleAgentOperationRecord;
+ session: PuzzleAgentSessionSnapshot;
}
diff --git a/packages/shared/src/contracts/puzzleRuntimeSession.ts b/packages/shared/src/contracts/puzzleRuntimeSession.ts
index de8cf815..22ebcf83 100644
--- a/packages/shared/src/contracts/puzzleRuntimeSession.ts
+++ b/packages/shared/src/contracts/puzzleRuntimeSession.ts
@@ -58,6 +58,11 @@ export interface StartPuzzleRunRequest {
profileId: string;
}
+export interface AdvanceLocalPuzzleNextLevelRequest {
+ run: PuzzleRunSnapshot;
+ sourceSessionId?: string | null;
+}
+
export interface PuzzleRunResponse {
run: PuzzleRunSnapshot;
}
diff --git a/scripts/dev-rust-stack.sh b/scripts/dev-rust-stack.sh
index 320e5ec6..08e16179 100644
--- a/scripts/dev-rust-stack.sh
+++ b/scripts/dev-rust-stack.sh
@@ -89,6 +89,39 @@ wait_for_spacetime() {
exit 1
}
+is_spacetime_ready() {
+ local server="$1"
+ local root_dir="$2"
+
+ spacetime --root-dir="${root_dir}" server ping "${server}" >/dev/null 2>&1
+}
+
+describe_spacetime_root_owner() {
+ local root_dir="$1"
+ local windows_root_dir="${root_dir}"
+
+ if [[ "${windows_root_dir}" =~ ^/([a-zA-Z])/(.*)$ ]]; then
+ windows_root_dir="${BASH_REMATCH[1]}:/${BASH_REMATCH[2]}"
+ fi
+
+ # Windows 本地开发最常见的失败是同一个 root-dir 下已有 standalone 持有 spacetime.pid；
+ # 启动前先打印占用进程，避免用户只看到底层 os error 33 而不知道该停哪个实例。
+ if command -v powershell.exe >/dev/null 2>&1; then
+ ROOT_DIR_FOR_POWERSHELL="${windows_root_dir}" powershell.exe -NoProfile -Command '
+$rootDir = $env:ROOT_DIR_FOR_POWERSHELL
+$normalized = $rootDir.Replace("/", "\")
+Get-CimInstance Win32_Process |
+ Where-Object { $_.Name -match "spacetime" -and $_.CommandLine -and $_.CommandLine.Replace("/", "\") -like "*$normalized*" } |
+ ForEach-Object { "pid=$($_.ProcessId) name=$($_.Name) command=$($_.CommandLine)" }
+' 2>/dev/null || true
+ return
+ fi
+
+ if command -v ps >/dev/null 2>&1; then
+ ps -ef 2>/dev/null | grep '[s]pacetime' | grep -F "${root_dir}" || true
+ fi
+}
+
wait_for_api_server() {
local health_url="$1"
local timeout_seconds="$2"
@@ -333,17 +366,29 @@ echo "[dev:rust] api timeout: ${API_SERVER_TIMEOUT_SECONDS}s"
if [[ "${SKIP_SPACETIME}" -ne 1 ]]; then
mkdir -p "${SPACETIME_ROOT_DIR}"
sync_local_spacetime_install "${SPACETIME_ROOT_DIR}"
- echo "[dev:rust] 启动 spacetimedb"
- (
- cd "${SERVER_RS_DIR}"
- exec spacetime \
- --root-dir="${SPACETIME_ROOT_DIR}" \
- start \
- --edition standalone \
- --listen-addr "${SPACETIME_HOST}:${SPACETIME_PORT}"
- ) &
- PIDS+=("$!")
- NAMES+=("spacetimedb")
+ if is_spacetime_ready "${SPACETIME_SERVER}" "${SPACETIME_ROOT_DIR}"; then
+ echo "[dev:rust] 复用已运行的 SpacetimeDB: ${SPACETIME_SERVER}"
+ else
+ SPACETIME_ROOT_OWNER="$(describe_spacetime_root_owner "${SPACETIME_ROOT_DIR}")"
+ if [[ -n "${SPACETIME_ROOT_OWNER}" ]]; then
+ echo "[dev:rust] 当前 root-dir 已被其他 SpacetimeDB 实例占用，无法再次启动。" >&2
+ echo "[dev:rust] 目标地址未就绪: ${SPACETIME_SERVER}" >&2
+ echo "[dev:rust] 如需复用，请传入占用实例实际端口，例如 --spacetime-port 3199；如需重启，请先停止下列进程。" >&2
+ echo "${SPACETIME_ROOT_OWNER}" >&2
+ exit 1
+ fi
+ echo "[dev:rust] 启动 spacetimedb"
+ (
+ cd "${SERVER_RS_DIR}"
+ exec spacetime \
+ --root-dir="${SPACETIME_ROOT_DIR}" \
+ start \
+ --edition standalone \
+ --listen-addr "${SPACETIME_HOST}:${SPACETIME_PORT}"
+ ) &
+ PIDS+=("$!")
+ NAMES+=("spacetimedb")
+ fi
fi
if [[ "${SKIP_PUBLISH}" -ne 1 ]]; then
diff --git a/server-rs/crates/api-server/src/app.rs b/server-rs/crates/api-server/src/app.rs
index 79954cfd..c3ca91df 100644
--- a/server-rs/crates/api-server/src/app.rs
+++ b/server-rs/crates/api-server/src/app.rs
@@ -78,11 +78,12 @@ use crate::{
password_management::{change_password, reset_password},
phone_auth::{phone_login, send_phone_code},
puzzle::{
- advance_puzzle_next_level, create_puzzle_agent_session, delete_puzzle_work,
- drag_puzzle_piece_or_group, execute_puzzle_agent_action, get_puzzle_agent_session,
- get_puzzle_gallery_detail, get_puzzle_run, get_puzzle_work_detail, get_puzzle_works,
- list_puzzle_gallery, put_puzzle_work, start_puzzle_run, stream_puzzle_agent_message,
- submit_puzzle_agent_message, swap_puzzle_pieces,
+ advance_local_puzzle_next_level, advance_puzzle_next_level, create_puzzle_agent_session,
+ delete_puzzle_work, drag_puzzle_piece_or_group, execute_puzzle_agent_action,
+ get_puzzle_agent_session, get_puzzle_gallery_detail, get_puzzle_run,
+ get_puzzle_work_detail, get_puzzle_works, list_puzzle_gallery, put_puzzle_work,
+ start_puzzle_run, stream_puzzle_agent_message, submit_puzzle_agent_message,
+ swap_puzzle_pieces,
},
refresh_session::refresh_session,
request_context::{attach_request_context, resolve_request_id},
@@ -645,6 +646,13 @@ pub fn build_router(state: AppState) -> Router {
require_bearer_auth,
)),
)
+ .route(
+ "/api/runtime/puzzle/runs/local-next-level",
+ post(advance_local_puzzle_next_level).route_layer(middleware::from_fn_with_state(
+ state.clone(),
+ require_bearer_auth,
+ )),
+ )
.route(
"/api/runtime/puzzle/runs/{run_id}",
get(get_puzzle_run).route_layer(middleware::from_fn_with_state(
diff --git a/server-rs/crates/api-server/src/big_fish.rs b/server-rs/crates/api-server/src/big_fish.rs
index 3079bcec..dbc9acee 100644
--- a/server-rs/crates/api-server/src/big_fish.rs
+++ b/server-rs/crates/api-server/src/big_fish.rs
@@ -434,10 +434,13 @@ pub async fn execute_big_fish_action(
let now = current_utc_micros();
let session = match payload.action.trim() {
"big_fish_compile_draft" => {
- state
- .spacetime_client()
- .compile_big_fish_draft(session_id, owner_user_id, now)
- .await
+ compile_big_fish_draft_with_all_assets(
+ &state,
+ session_id,
+ owner_user_id,
+ now,
+ )
+ .await
}
"big_fish_generate_level_main_image" => {
let asset_url = generate_big_fish_formal_asset(
@@ -766,6 +769,98 @@ fn map_big_fish_asset_coverage_response(
}
}
+async fn compile_big_fish_draft_with_all_assets(
+ state: &AppState,
+ session_id: String,
+ owner_user_id: String,
+ now: i64,
+) -> Result {
+ let session = state
+ .spacetime_client()
+ .compile_big_fish_draft(session_id.clone(), owner_user_id.clone(), now)
+ .await?;
+ let draft = session
+ .draft
+ .clone()
+ .ok_or_else(|| SpacetimeClientError::Runtime("大鱼吃小鱼玩法草稿尚未生成".to_string()))?;
+ // 点击生成草稿时一次性生成所有首版玩法资产，前端只负责展示进度和最终 session。
+ for level in &draft.levels {
+ let asset_url = generate_big_fish_formal_asset(
+ state,
+ &owner_user_id,
+ &session_id,
+ "level_main_image",
+ Some(level.level),
+ None,
+ current_utc_micros(),
+ )
+ .await
+ .map_err(|error| SpacetimeClientError::Runtime(error.message().to_string()))?;
+ state
+ .spacetime_client()
+ .generate_big_fish_asset(BigFishAssetGenerateRecordInput {
+ session_id: session_id.clone(),
+ owner_user_id: owner_user_id.clone(),
+ asset_kind: "level_main_image".to_string(),
+ level: Some(level.level),
+ motion_key: None,
+ asset_url: Some(asset_url),
+ generated_at_micros: current_utc_micros(),
+ })
+ .await?;
+ }
+ for level in &draft.levels {
+ for motion_key in ["idle_float", "move_swim"] {
+ let asset_url = generate_big_fish_formal_asset(
+ state,
+ &owner_user_id,
+ &session_id,
+ "level_motion",
+ Some(level.level),
+ Some(motion_key),
+ current_utc_micros(),
+ )
+ .await
+ .map_err(|error| SpacetimeClientError::Runtime(error.message().to_string()))?;
+ state
+ .spacetime_client()
+ .generate_big_fish_asset(BigFishAssetGenerateRecordInput {
+ session_id: session_id.clone(),
+ owner_user_id: owner_user_id.clone(),
+ asset_kind: "level_motion".to_string(),
+ level: Some(level.level),
+ motion_key: Some(motion_key.to_string()),
+ asset_url: Some(asset_url),
+ generated_at_micros: current_utc_micros(),
+ })
+ .await?;
+ }
+ }
+ let asset_url = generate_big_fish_formal_asset(
+ state,
+ &owner_user_id,
+ &session_id,
+ "stage_background",
+ None,
+ None,
+ current_utc_micros(),
+ )
+ .await
+ .map_err(|error| SpacetimeClientError::Runtime(error.message().to_string()))?;
+ state
+ .spacetime_client()
+ .generate_big_fish_asset(BigFishAssetGenerateRecordInput {
+ session_id,
+ owner_user_id,
+ asset_kind: "stage_background".to_string(),
+ level: None,
+ motion_key: None,
+ asset_url: Some(asset_url),
+ generated_at_micros: current_utc_micros(),
+ })
+ .await
+}
+
fn map_big_fish_agent_message_response(
message: BigFishAgentMessageRecord,
) -> BigFishAgentMessageResponse {
diff --git a/server-rs/crates/api-server/src/custom_world_ai.rs b/server-rs/crates/api-server/src/custom_world_ai.rs
index 5dda2b94..4f3c47c8 100644
--- a/server-rs/crates/api-server/src/custom_world_ai.rs
+++ b/server-rs/crates/api-server/src/custom_world_ai.rs
@@ -2548,24 +2548,26 @@ mod tests {
name: Some("礁石神殿".to_string()),
description: Some("古老礁石上的半沉神殿。".to_string()),
};
- let manual_prompt = build_custom_world_scene_image_prompt(SceneImagePromptParams {
- profile: SceneImagePromptProfile {
- name: profile_input.name.as_deref().unwrap_or_default(),
- subtitle: profile_input.subtitle.as_deref().unwrap_or_default(),
- tone: profile_input.tone.as_deref().unwrap_or_default(),
- player_goal: profile_input.player_goal.as_deref().unwrap_or_default(),
- summary: profile_input.summary.as_deref().unwrap_or_default(),
- setting_text: profile_input.setting_text.as_deref().unwrap_or_default(),
+ let manual_prompt = build_custom_world_scene_image_prompt(
+ SceneImagePromptParams {
+ profile: SceneImagePromptProfile {
+ name: profile_input.name.as_deref().unwrap_or_default(),
+ subtitle: profile_input.subtitle.as_deref().unwrap_or_default(),
+ tone: profile_input.tone.as_deref().unwrap_or_default(),
+ player_goal: profile_input.player_goal.as_deref().unwrap_or_default(),
+ summary: profile_input.summary.as_deref().unwrap_or_default(),
+ setting_text: profile_input.setting_text.as_deref().unwrap_or_default(),
+ },
+ landmark: SceneImagePromptLandmark {
+ name: landmark.name.as_deref().unwrap_or_default(),
+ description: landmark.description.as_deref().unwrap_or_default(),
+ },
+ user_prompt,
+ has_reference_image: false,
+ fallback_landmark_name: Some("礁石神殿"),
+ fallback_world_name: "雾海群岛",
},
- landmark: SceneImagePromptLandmark {
- name: landmark.name.as_deref().unwrap_or_default(),
- description: landmark.description.as_deref().unwrap_or_default(),
- },
- user_prompt,
- has_reference_image: false,
- fallback_landmark_name: Some("礁石神殿"),
- fallback_world_name: "雾海群岛",
- });
+ );
let normalized = normalize_scene_image_request(CustomWorldSceneImageRequest {
profile_id: Some("profile_001".to_string()),
diff --git a/server-rs/crates/api-server/src/puzzle.rs b/server-rs/crates/api-server/src/puzzle.rs
index 5f665ed3..c1ba06b7 100644
--- a/server-rs/crates/api-server/src/puzzle.rs
+++ b/server-rs/crates/api-server/src/puzzle.rs
@@ -32,10 +32,10 @@ use shared_contracts::{
},
puzzle_gallery::{PuzzleGalleryDetailResponse, PuzzleGalleryResponse},
puzzle_runtime::{
- DragPuzzlePieceRequest, PuzzleBoardSnapshotResponse, PuzzleCellPositionResponse,
- PuzzleMergedGroupStateResponse, PuzzlePieceStateResponse, PuzzleRunResponse,
- PuzzleRunSnapshotResponse, PuzzleRuntimeLevelSnapshotResponse, StartPuzzleRunRequest,
- SwapPuzzlePiecesRequest,
+ AdvanceLocalPuzzleNextLevelRequest, DragPuzzlePieceRequest, PuzzleBoardSnapshotResponse,
+ PuzzleCellPositionResponse, PuzzleMergedGroupStateResponse, PuzzlePieceStateResponse,
+ PuzzleRunResponse, PuzzleRunSnapshotResponse, PuzzleRuntimeLevelSnapshotResponse,
+ StartPuzzleRunRequest, SwapPuzzlePiecesRequest,
},
puzzle_works::{
PutPuzzleWorkRequest, PuzzleWorkDetailResponse, PuzzleWorkMutationResponse,
@@ -50,9 +50,10 @@ use spacetime_client::{
PuzzleCreatorIntentRecord, PuzzleGeneratedImageCandidateRecord,
PuzzleGeneratedImagesSaveRecordInput, PuzzlePublishRecordInput, PuzzleResultDraftRecord,
PuzzleResultPreviewBlockerRecord, PuzzleResultPreviewFindingRecord, PuzzleResultPreviewRecord,
+ PuzzleBoardRecord, PuzzleCellPositionRecord, PuzzleMergedGroupRecord, PuzzlePieceStateRecord,
PuzzleRunDragRecordInput, PuzzleRunRecord, PuzzleRunStartRecordInput, PuzzleRunSwapRecordInput,
- PuzzleSelectCoverImageRecordInput, PuzzleWorkProfileRecord, PuzzleWorkUpsertRecordInput,
- SpacetimeClientError,
+ PuzzleRuntimeLevelRecord, PuzzleSelectCoverImageRecordInput, PuzzleWorkProfileRecord,
+ PuzzleWorkUpsertRecordInput, SpacetimeClientError,
};
use std::convert::Infallible;
use tokio::time::sleep;
@@ -435,14 +436,17 @@ pub async fn execute_puzzle_agent_action(
let (operation_type, phase_label, phase_detail, session) = match payload.action.trim() {
"compile_puzzle_draft" => {
- let session = state
- .spacetime_client()
- .compile_puzzle_agent_draft(session_id, owner_user_id, now)
- .await;
+ let session = compile_puzzle_draft_with_initial_cover(
+ &state,
+ session_id.clone(),
+ owner_user_id.clone(),
+ now,
+ )
+ .await;
(
"compile_puzzle_draft",
- "结果页草稿",
- "已根据当前锚点编译结果页草稿。",
+ "完整拼图草稿",
+ "已编译草稿、生成候选图并应用正式图片。",
session,
)
}
@@ -464,6 +468,7 @@ pub async fn execute_puzzle_agent_action(
.filter(|value| !value.trim().is_empty())
.unwrap_or_else(|| draft.summary.clone());
let candidate_count = payload.candidate_count.unwrap_or(2).clamp(1, 2);
+ let candidate_start_index = draft.candidates.len();
let candidates = generate_puzzle_image_candidates(
&state,
owner_user_id.as_str(),
@@ -471,6 +476,7 @@ pub async fn execute_puzzle_agent_action(
&draft.level_name,
&prompt,
candidate_count,
+ candidate_start_index,
)
.await
.map_err(SpacetimeClientError::Runtime);
@@ -572,6 +578,18 @@ pub async fn execute_puzzle_agent_action(
)
})?;
+ let session = state
+ .spacetime_client()
+ .get_puzzle_agent_session(session_id.clone(), owner_user_id.clone())
+ .await
+ .map_err(|error| {
+ puzzle_error_response(
+ &request_context,
+ PUZZLE_AGENT_API_BASE_PROVIDER,
+ map_puzzle_client_error(error),
+ )
+ })?;
+
return Ok(json_success_body(
Some(&request_context),
PuzzleAgentActionResponse {
@@ -584,6 +602,7 @@ pub async fn execute_puzzle_agent_action(
progress: 100,
error: None,
},
+ session: map_puzzle_agent_session_response(session),
},
));
}
@@ -616,6 +635,7 @@ pub async fn execute_puzzle_agent_action(
progress: 100,
error: None,
},
+ session: map_puzzle_agent_session_response(session),
},
))
}
@@ -1046,6 +1066,36 @@ pub async fn advance_puzzle_next_level(
))
}
+pub async fn advance_local_puzzle_next_level(
+ State(state): State,
+ Extension(request_context): Extension,
+ Extension(authenticated): Extension,
+ payload: Result, JsonRejection>,
+) -> Result, Response> {
+ let Json(payload) = payload.map_err(|error| {
+ puzzle_error_response(
+ &request_context,
+ PUZZLE_RUNTIME_PROVIDER,
+ AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+ "provider": PUZZLE_RUNTIME_PROVIDER,
+ "message": error.body_text(),
+ })),
+ )
+ })?;
+
+ let owner_user_id = authenticated.claims().user_id().to_string();
+ let run = build_local_next_puzzle_run(&state, payload, owner_user_id.as_str())
+ .await
+ .map_err(|error| puzzle_error_response(&request_context, PUZZLE_RUNTIME_PROVIDER, error))?;
+
+ Ok(json_success_body(
+ Some(&request_context),
+ PuzzleRunResponse {
+ run: map_puzzle_run_response(run),
+ },
+ ))
+}
+
fn map_puzzle_agent_session_response(
session: PuzzleAgentSessionRecord,
) -> PuzzleAgentSessionSnapshotResponse {
@@ -1248,6 +1298,74 @@ fn map_puzzle_run_response(run: PuzzleRunRecord) -> PuzzleRunSnapshotResponse {
}
}
+fn map_puzzle_run_request_record(run: PuzzleRunSnapshotResponse) -> PuzzleRunRecord {
+ PuzzleRunRecord {
+ run_id: run.run_id,
+ entry_profile_id: run.entry_profile_id,
+ cleared_level_count: run.cleared_level_count,
+ current_level_index: run.current_level_index,
+ current_grid_size: run.current_grid_size,
+ played_profile_ids: run.played_profile_ids,
+ previous_level_tags: run.previous_level_tags,
+ current_level: run.current_level.map(map_puzzle_level_request_record),
+ recommended_next_profile_id: run.recommended_next_profile_id,
+ }
+}
+
+fn map_puzzle_level_request_record(
+ level: PuzzleRuntimeLevelSnapshotResponse,
+) -> PuzzleRuntimeLevelRecord {
+ PuzzleRuntimeLevelRecord {
+ run_id: level.run_id,
+ level_index: level.level_index,
+ grid_size: level.grid_size,
+ profile_id: level.profile_id,
+ level_name: level.level_name,
+ author_display_name: level.author_display_name,
+ theme_tags: level.theme_tags,
+ cover_image_src: level.cover_image_src,
+ board: map_puzzle_board_request_record(level.board),
+ status: level.status,
+ }
+}
+
+fn map_puzzle_board_request_record(board: PuzzleBoardSnapshotResponse) -> PuzzleBoardRecord {
+ PuzzleBoardRecord {
+ rows: board.rows,
+ cols: board.cols,
+ pieces: board
+ .pieces
+ .into_iter()
+ .map(|piece| PuzzlePieceStateRecord {
+ piece_id: piece.piece_id,
+ correct_row: piece.correct_row,
+ correct_col: piece.correct_col,
+ current_row: piece.current_row,
+ current_col: piece.current_col,
+ merged_group_id: piece.merged_group_id,
+ })
+ .collect(),
+ merged_groups: board
+ .merged_groups
+ .into_iter()
+ .map(|group| PuzzleMergedGroupRecord {
+ group_id: group.group_id,
+ piece_ids: group.piece_ids,
+ occupied_cells: group
+ .occupied_cells
+ .into_iter()
+ .map(|cell| PuzzleCellPositionRecord {
+ row: cell.row,
+ col: cell.col,
+ })
+ .collect(),
+ })
+ .collect(),
+ selected_piece_id: board.selected_piece_id,
+ all_tiles_resolved: board.all_tiles_resolved,
+ }
+}
+
fn map_puzzle_runtime_level_response(
level: spacetime_client::PuzzleRuntimeLevelRecord,
) -> PuzzleRuntimeLevelSnapshotResponse {
@@ -1336,6 +1454,65 @@ fn build_stable_puzzle_work_ids(session_id: &str) -> (String, String) {
)
}
+async fn compile_puzzle_draft_with_initial_cover(
+ state: &AppState,
+ session_id: String,
+ owner_user_id: String,
+ now: i64,
+) -> Result {
+ let compiled_session = state
+ .spacetime_client()
+ .compile_puzzle_agent_draft(session_id.clone(), owner_user_id.clone(), now)
+ .await?;
+ let draft = compiled_session
+ .draft
+ .clone()
+ .ok_or_else(|| SpacetimeClientError::Runtime("拼图结果页草稿尚未生成".to_string()))?;
+ // 点击生成草稿时一次性完成首图生成与正式图选定，前端只展示进度，不再承担业务编排。
+ let candidates = generate_puzzle_image_candidates(
+ state,
+ owner_user_id.as_str(),
+ &compiled_session.session_id,
+ &draft.level_name,
+ &draft.summary,
+ 2,
+ draft.candidates.len(),
+ )
+ .await
+ .map_err(SpacetimeClientError::Runtime)?;
+ let selected_candidate_id = candidates
+ .iter()
+ .find(|candidate| candidate.selected)
+ .or_else(|| candidates.first())
+ .map(|candidate| candidate.candidate_id.clone())
+ .ok_or_else(|| SpacetimeClientError::Runtime("拼图候选图生成结果为空".to_string()))?;
+ let candidates_json = serde_json::to_string(
+ &candidates
+ .iter()
+ .map(to_puzzle_generated_image_candidate)
+ .collect::>(),
+ )
+ .map_err(|error| SpacetimeClientError::Runtime(format!("拼图候选图序列化失败：{error}")))?;
+ state
+ .spacetime_client()
+ .save_puzzle_generated_images(PuzzleGeneratedImagesSaveRecordInput {
+ session_id: compiled_session.session_id.clone(),
+ owner_user_id: owner_user_id.clone(),
+ candidates_json,
+ saved_at_micros: current_utc_micros(),
+ })
+ .await?;
+ state
+ .spacetime_client()
+ .select_puzzle_cover_image(PuzzleSelectCoverImageRecordInput {
+ session_id,
+ owner_user_id,
+ candidate_id: selected_candidate_id,
+ selected_at_micros: current_utc_micros(),
+ })
+ .await
+}
+
fn ensure_non_empty(
request_context: &RequestContext,
provider: &str,
@@ -1442,6 +1619,7 @@ async fn generate_puzzle_image_candidates(
level_name: &str,
prompt: &str,
candidate_count: u32,
+ candidate_start_index: usize,
) -> Result, String> {
let count = candidate_count.clamp(1, 2);
let settings =
@@ -1461,7 +1639,7 @@ async fn generate_puzzle_image_candidates(
let mut items = Vec::with_capacity(generated.images.len());
for (index, image) in generated.images.into_iter().enumerate() {
- let candidate_id = format!("{session_id}-candidate-{}", index + 1);
+ let candidate_id = format!("{session_id}-candidate-{}", candidate_start_index + index + 1);
let asset = persist_puzzle_generated_asset(
state,
owner_user_id,
@@ -1481,7 +1659,7 @@ async fn generate_puzzle_image_candidates(
prompt: prompt.to_string(),
actual_prompt: Some(prompt.to_string()),
source_type: "generated".to_string(),
- selected: index == 0,
+ selected: candidate_start_index == 0 && index == 0,
});
}
@@ -1499,6 +1677,249 @@ async fn generate_puzzle_image_candidates(
.collect())
}
+async fn build_local_next_puzzle_run(
+ state: &AppState,
+ payload: AdvanceLocalPuzzleNextLevelRequest,
+ owner_user_id: &str,
+) -> Result {
+ let run = map_puzzle_run_request_record(payload.run);
+ let current_level = run.current_level.clone().ok_or_else(|| {
+ AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+ "provider": PUZZLE_RUNTIME_PROVIDER,
+ "message": "currentLevel is required",
+ }))
+ })?;
+ if current_level.status != "cleared" {
+ return Err(AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+ "provider": PUZZLE_RUNTIME_PROVIDER,
+ "message": "current level is not cleared",
+ })));
+ }
+
+ if let Some(gallery_item) = resolve_gallery_next_puzzle_work(state, &run).await? {
+ return Ok(build_next_run_from_puzzle_work(run, gallery_item));
+ }
+
+ let source_session_id = payload.source_session_id.unwrap_or_default();
+ if source_session_id.trim().is_empty() {
+ return Err(AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+ "provider": PUZZLE_RUNTIME_PROVIDER,
+ "message": "sourceSessionId is required when gallery has no next puzzle work",
+ })));
+ }
+ let session = state
+ .spacetime_client()
+ .get_puzzle_agent_session(source_session_id, owner_user_id.to_string())
+ .await
+ .map_err(map_puzzle_client_error)?;
+ if let Some(candidate) = session
+ .draft
+ .as_ref()
+ .and_then(|draft| pick_unused_puzzle_candidate(&draft.candidates, &run.played_profile_ids))
+ {
+ return Ok(build_next_run_from_candidate(run, &session, candidate));
+ }
+
+ let draft = session.draft.clone().ok_or_else(|| {
+ AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+ "provider": PUZZLE_RUNTIME_PROVIDER,
+ "message": "puzzle draft is required when gallery has no next puzzle work",
+ }))
+ })?;
+ let candidates = generate_puzzle_image_candidates(
+ state,
+ owner_user_id,
+ &session.session_id,
+ &draft.level_name,
+ &draft.summary,
+ 2,
+ draft.candidates.len(),
+ )
+ .await
+ .map_err(|message| {
+ AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+ "provider": PUZZLE_RUNTIME_PROVIDER,
+ "message": message,
+ }))
+ })?;
+ let candidates_json = serde_json::to_string(
+ &candidates
+ .iter()
+ .map(to_puzzle_generated_image_candidate)
+ .collect::>(),
+ )
+ .map_err(|error| {
+ AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
+ "provider": PUZZLE_RUNTIME_PROVIDER,
+ "message": format!("拼图候选图序列化失败：{error}"),
+ }))
+ })?;
+ let updated_session = state
+ .spacetime_client()
+ .save_puzzle_generated_images(PuzzleGeneratedImagesSaveRecordInput {
+ session_id: session.session_id,
+ owner_user_id: owner_user_id.to_string(),
+ candidates_json,
+ saved_at_micros: current_utc_micros(),
+ })
+ .await
+ .map_err(map_puzzle_client_error)?;
+ let candidate = updated_session
+ .draft
+ .as_ref()
+ .and_then(|draft| draft.candidates.iter().find(|candidate| !candidate.image_src.is_empty()))
+ .ok_or_else(|| {
+ AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+ "provider": PUZZLE_RUNTIME_PROVIDER,
+ "message": "现场生成后没有可用候选图",
+ }))
+ })?;
+ Ok(build_next_run_from_candidate(run, &updated_session, candidate))
+}
+
+async fn resolve_gallery_next_puzzle_work(
+ state: &AppState,
+ run: &PuzzleRunRecord,
+) -> Result, AppError> {
+ let items = state
+ .spacetime_client()
+ .list_puzzle_gallery()
+ .await
+ .map_err(map_puzzle_client_error)?;
+ Ok(items.into_iter().find(|item| {
+ item.publication_status == "published"
+ && item.cover_image_src.as_ref().is_some_and(|value| !value.is_empty())
+ && !run.played_profile_ids.contains(&item.profile_id)
+ }))
+}
+
+fn pick_unused_puzzle_candidate<'a>(
+ candidates: &'a [PuzzleGeneratedImageCandidateRecord],
+ played_profile_ids: &[String],
+) -> Option<&'a PuzzleGeneratedImageCandidateRecord> {
+ candidates.iter().find(|candidate| {
+ !candidate.image_src.is_empty()
+ && !played_profile_ids
+ .iter()
+ .any(|profile_id| profile_id.contains(&candidate.candidate_id))
+ })
+}
+
+fn build_next_run_from_puzzle_work(
+ run: PuzzleRunRecord,
+ item: PuzzleWorkProfileRecord,
+) -> PuzzleRunRecord {
+ build_next_run_from_parts(
+ run,
+ item.profile_id,
+ item.level_name,
+ item.author_display_name,
+ item.theme_tags,
+ item.cover_image_src,
+ )
+}
+
+fn build_next_run_from_candidate(
+ run: PuzzleRunRecord,
+ session: &PuzzleAgentSessionRecord,
+ candidate: &PuzzleGeneratedImageCandidateRecord,
+) -> PuzzleRunRecord {
+ let draft = session.draft.as_ref();
+ let level_index = run.current_level_index + 1;
+ build_next_run_from_parts(
+ run,
+ format!(
+ "{}-{}-level-{}",
+ session.session_id, candidate.candidate_id, level_index
+ ),
+ draft
+ .map(|draft| format!("{} · 候选 {}", draft.level_name, level_index))
+ .unwrap_or_else(|| format!("候选拼图 {level_index}")),
+ "当前草稿".to_string(),
+ draft.map(|draft| draft.theme_tags.clone()).unwrap_or_default(),
+ Some(candidate.image_src.clone()),
+ )
+}
+
+fn build_next_run_from_parts(
+ run: PuzzleRunRecord,
+ profile_id: String,
+ level_name: String,
+ author_display_name: String,
+ theme_tags: Vec,
+ cover_image_src: Option,
+) -> PuzzleRunRecord {
+ let next_level_index = run.current_level_index + 1;
+ let grid_size = if run.cleared_level_count >= 3 { 4 } else { 3 };
+ let mut played_profile_ids = run.played_profile_ids.clone();
+ if !played_profile_ids.contains(&profile_id) {
+ played_profile_ids.push(profile_id.clone());
+ }
+ PuzzleRunRecord {
+ run_id: run.run_id.clone(),
+ entry_profile_id: run.entry_profile_id,
+ cleared_level_count: run.cleared_level_count,
+ current_level_index: next_level_index,
+ current_grid_size: grid_size,
+ played_profile_ids,
+ previous_level_tags: theme_tags.clone(),
+ current_level: Some(PuzzleRuntimeLevelRecord {
+ run_id: run.run_id,
+ level_index: next_level_index,
+ grid_size,
+ profile_id,
+ level_name,
+ author_display_name,
+ theme_tags,
+ cover_image_src,
+ board: build_local_puzzle_board(grid_size),
+ status: "playing".to_string(),
+ }),
+ recommended_next_profile_id: None,
+ }
+}
+
+fn build_local_puzzle_board(grid_size: u32) -> PuzzleBoardRecord {
+ let total = grid_size * grid_size;
+ let mut positions = (0..total)
+ .map(|index| PuzzleCellPositionRecord {
+ row: index / grid_size,
+ col: index % grid_size,
+ })
+ .collect::>();
+ if !positions.is_empty() {
+ let first = positions.remove(0);
+ positions.push(first);
+ }
+ let pieces = (0..total)
+ .map(|index| {
+ let current = positions
+ .get(index as usize)
+ .cloned()
+ .unwrap_or(PuzzleCellPositionRecord {
+ row: index / grid_size,
+ col: index % grid_size,
+ });
+ PuzzlePieceStateRecord {
+ piece_id: format!("piece-{index}"),
+ correct_row: index / grid_size,
+ correct_col: index % grid_size,
+ current_row: current.row,
+ current_col: current.col,
+ merged_group_id: None,
+ }
+ })
+ .collect();
+ PuzzleBoardRecord {
+ rows: grid_size,
+ cols: grid_size,
+ pieces,
+ merged_groups: Vec::new(),
+ selected_piece_id: None,
+ all_tiles_resolved: false,
+ }
+}
+
struct PuzzleDashScopeSettings {
base_url: String,
api_key: String,
diff --git a/server-rs/crates/shared-contracts/src/puzzle_agent.rs b/server-rs/crates/shared-contracts/src/puzzle_agent.rs
index 8275c885..42a6c279 100644
--- a/server-rs/crates/shared-contracts/src/puzzle_agent.rs
+++ b/server-rs/crates/shared-contracts/src/puzzle_agent.rs
@@ -187,4 +187,6 @@ pub struct PuzzleAgentOperationResponse {
#[serde(rename_all = "camelCase")]
pub struct PuzzleAgentActionResponse {
pub operation: PuzzleAgentOperationResponse,
+ /// 操作完成后的最新会话快照，供前端直接更新界面，避免重复拉取完整 session。
+ pub session: PuzzleAgentSessionSnapshotResponse,
}
diff --git a/server-rs/crates/shared-contracts/src/puzzle_runtime.rs b/server-rs/crates/shared-contracts/src/puzzle_runtime.rs
index 62caa0b1..1c3d6452 100644
--- a/server-rs/crates/shared-contracts/src/puzzle_runtime.rs
+++ b/server-rs/crates/shared-contracts/src/puzzle_runtime.rs
@@ -6,6 +6,14 @@ pub struct StartPuzzleRunRequest {
pub profile_id: String,
}
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct AdvanceLocalPuzzleNextLevelRequest {
+ pub run: PuzzleRunSnapshotResponse,
+ #[serde(default)]
+ pub source_session_id: Option,
+}
+
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct SwapPuzzlePiecesRequest {
diff --git a/server-rs/crates/spacetime-module/src/puzzle.rs b/server-rs/crates/spacetime-module/src/puzzle.rs
index f6a0fa14..944d8a0a 100644
--- a/server-rs/crates/spacetime-module/src/puzzle.rs
+++ b/server-rs/crates/spacetime-module/src/puzzle.rs
@@ -684,7 +684,7 @@ fn save_puzzle_generated_images_tx(
if candidates.is_empty() {
return Err("拼图候选图不能为空".to_string());
}
- draft.candidates = candidates;
+ append_generated_candidates(&mut draft, candidates);
draft.generation_status = "ready".to_string();
if let Some(selected) = draft
.candidates
@@ -1507,6 +1507,23 @@ fn increment_puzzle_profile_play_count(
);
}
+fn append_generated_candidates(
+ draft: &mut PuzzleResultDraft,
+ candidates: Vec,
+) {
+ let has_selected_candidate = draft.candidates.iter().any(|entry| entry.selected);
+ // 再次生成图片是扩充候选池，不覆盖创作者已经看到或已经选择的候选图。
+ // 若已有正式选择，新追加候选图保持未选中，避免同一草稿出现多个 selected。
+ draft
+ .candidates
+ .extend(candidates.into_iter().map(|mut candidate| {
+ if has_selected_candidate {
+ candidate.selected = false;
+ }
+ candidate
+ }));
+}
+
fn list_published_puzzle_profiles(ctx: &TxContext) -> Result, String> {
ctx.db
.puzzle_work_profile()
@@ -1613,6 +1630,40 @@ mod tests {
assert!(preview.publish_ready);
}
+ #[test]
+ fn puzzle_generated_images_are_appended_without_clearing_existing_candidates() {
+ let anchor_pack = infer_anchor_pack("蒸汽城市雨夜猫咪", Some("蒸汽城市雨夜猫咪"));
+ let mut draft = compile_result_draft(&anchor_pack, &[]);
+ draft.candidates = vec![PuzzleGeneratedImageCandidate {
+ candidate_id: "session-1-candidate-1".to_string(),
+ image_src: "/generated-puzzle-assets/session-1/old/cover.png".to_string(),
+ asset_id: "asset-old".to_string(),
+ prompt: "旧提示词".to_string(),
+ actual_prompt: Some("旧提示词".to_string()),
+ source_type: "generated".to_string(),
+ selected: true,
+ }];
+
+ append_generated_candidates(
+ &mut draft,
+ vec![PuzzleGeneratedImageCandidate {
+ candidate_id: "session-1-candidate-2".to_string(),
+ image_src: "/generated-puzzle-assets/session-1/new/cover.png".to_string(),
+ asset_id: "asset-new".to_string(),
+ prompt: "新提示词".to_string(),
+ actual_prompt: Some("新提示词".to_string()),
+ source_type: "generated".to_string(),
+ selected: true,
+ }],
+ );
+
+ assert_eq!(draft.candidates.len(), 2);
+ assert_eq!(draft.candidates[0].candidate_id, "session-1-candidate-1");
+ assert!(draft.candidates[0].selected);
+ assert_eq!(draft.candidates[1].candidate_id, "session-1-candidate-2");
+ assert!(!draft.candidates[1].selected);
+ }
+
#[test]
fn puzzle_recommendation_score_prefers_same_author_weight() {
let left = PuzzleWorkProfile {
diff --git a/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx b/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
index c6833b9f..bd41e520 100644
--- a/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
+++ b/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
@@ -1,4 +1,5 @@
-import { AnimatePresence, motion } from 'motion/react';
+import { Loader2 } from 'lucide-react';
+import { AnimatePresence, motion } from 'motion/react';
import {
lazy,
Suspense,
@@ -9,6 +10,7 @@ import {
useState,
} from 'react';
+import type { PublicUserSummary } from '../../../packages/shared/src/contracts/auth';
import type {
BigFishRuntimeSnapshotResponse,
BigFishSessionSnapshotResponse,
@@ -31,7 +33,6 @@ import type {
CustomWorldGalleryCard,
CustomWorldLibraryEntry,
} from '../../../packages/shared/src/contracts/runtime';
-import type { PublicUserSummary } from '../../../packages/shared/src/contracts/auth';
import { buildCustomWorldPlayableCharacters } from '../../data/characterPresets';
import {
getPublicAuthUserByCode,
@@ -43,15 +44,22 @@ import {
getBigFishCreationSession,
streamBigFishCreationMessage,
} from '../../services/big-fish-creation';
-import {
- deleteBigFishWork,
- listBigFishWorks,
-} from '../../services/big-fish-works';
import {
startBigFishRuntimeRun,
submitBigFishRuntimeInput,
} from '../../services/big-fish-runtime';
+import {
+ deleteBigFishWork,
+ listBigFishWorks,
+} from '../../services/big-fish-works';
import { readCustomWorldAgentUiState } from '../../services/customWorldAgentUiState';
+import {
+ buildBigFishGenerationAnchorEntries,
+ buildMiniGameDraftGenerationProgress,
+ buildPuzzleGenerationAnchorEntries,
+ createMiniGameDraftGenerationState,
+ type MiniGameDraftGenerationState,
+} from '../../services/miniGameDraftGenerationProgress';
import { getPlatformProfileDashboard } from '../../services/platform-entry';
import {
createPuzzleAgentSession,
@@ -60,17 +68,17 @@ import {
streamPuzzleAgentMessage,
} from '../../services/puzzle-agent';
import { getPuzzleGalleryDetail, listPuzzleGallery } from '../../services/puzzle-gallery';
+import { advanceLocalPuzzleNextLevel } from '../../services/puzzle-runtime';
import {
- advanceLocalPuzzleLevel,
dragLocalPuzzlePiece,
startLocalPuzzleRun,
swapLocalPuzzlePieces,
} from '../../services/puzzle-runtime/puzzleLocalRuntime';
import { deletePuzzleWork, listPuzzleWorks } from '../../services/puzzle-works';
-import { deleteRpgEntryWorldProfile } from '../../services/rpg-entry';
-import { getRpgEntryWorldGalleryDetailByCode } from '../../services/rpg-entry/rpgEntryLibraryClient';
import { deleteRpgCreationAgentSession } from '../../services/rpg-creation';
import { rpgCreationPreviewAdapter } from '../../services/rpg-creation/rpgCreationPreviewAdapter';
+import { deleteRpgEntryWorldProfile } from '../../services/rpg-entry';
+import { getRpgEntryWorldGalleryDetailByCode } from '../../services/rpg-entry/rpgEntryLibraryClient';
import type { CustomWorldProfile } from '../../types';
import { useAuthUi } from '../auth/AuthUiContext';
import { CustomWorldCreationHub } from '../custom-world-home/CustomWorldCreationHub';
@@ -88,13 +96,13 @@ import {
type PlatformPublicGalleryCard,
} from '../rpg-entry/rpgEntryWorldPresentation';
import { PlatformEntryCreationTypeModal } from './PlatformEntryCreationTypeModal';
+import type { PlatformCreationTypeId } from './platformEntryCreationTypes';
import { PlatformEntryHomeView } from './PlatformEntryHomeView';
import {
buildCreationHubFallbackItems,
normalizeAgentBackedProfile,
resolveRpgCreationErrorMessage,
} from './platformEntryShared';
-import type { PlatformCreationTypeId } from './platformEntryCreationTypes';
import type { PlatformEntryFlowShellProps } from './platformEntryTypes';
import { PlatformEntryWorldDetailView } from './PlatformEntryWorldDetailView';
import { usePlatformEntryBootstrap } from './usePlatformEntryBootstrap';
@@ -341,6 +349,8 @@ export function PlatformEntryFlowShellImpl({
const [bigFishRun, setBigFishRun] =
useState(null);
const [isBigFishLoadingLibrary, setIsBigFishLoadingLibrary] = useState(false);
+ const [bigFishGenerationState, setBigFishGenerationState] =
+ useState(null);
const bigFishInputInFlightRef = useRef(false);
const [puzzleOperation, setPuzzleOperation] =
useState(null);
@@ -352,6 +362,10 @@ export function PlatformEntryFlowShellImpl({
useState(null);
const [puzzleRun, setPuzzleRun] = useState(null);
const [isPuzzleLoadingLibrary, setIsPuzzleLoadingLibrary] = useState(false);
+ const [puzzleGenerationState, setPuzzleGenerationState] =
+ useState(null);
+ const [isPuzzleNextLevelGenerating, setIsPuzzleNextLevelGenerating] =
+ useState(false);
const [isSearchingPublicCode, setIsSearchingPublicCode] = useState(false);
const [publicSearchError, setPublicSearchError] = useState(null);
const [searchedPublicUser, setSearchedPublicUser] =
@@ -773,8 +787,44 @@ export function PlatformEntryFlowShellImpl({
onSessionOpened: () => {
setShowCreationTypeModal(false);
},
- onActionComplete: ({ response, setSession }) => {
+ onActionComplete: ({ payload, response, setSession }) => {
setSession(response.session);
+ if (payload.action !== 'big_fish_compile_draft') {
+ return;
+ }
+ setBigFishGenerationState((current) =>
+ current
+ ? {
+ ...current,
+ phase: 'ready',
+ completedAssetCount: response.session.assetSlots.filter(
+ (slot) => slot.status === 'ready',
+ ).length,
+ totalAssetCount: response.session.assetSlots.length,
+ }
+ : current,
+ );
+ },
+ beforeExecuteAction: ({ payload }) => {
+ if (payload.action !== 'big_fish_compile_draft') {
+ return;
+ }
+ setSelectionStage('big-fish-generating');
+ setBigFishGenerationState(createMiniGameDraftGenerationState('big-fish'));
+ },
+ onActionError: ({ payload, errorMessage }) => {
+ if (payload.action !== 'big_fish_compile_draft') {
+ return;
+ }
+ setBigFishGenerationState((current) =>
+ current
+ ? {
+ ...current,
+ phase: 'failed',
+ error: errorMessage,
+ }
+ : current,
+ );
},
});
@@ -784,7 +834,7 @@ export function PlatformEntryFlowShellImpl({
{ session: PuzzleAgentSessionSnapshot },
SendPuzzleAgentMessageRequest,
PuzzleAgentActionRequest,
- { operation: PuzzleAgentOperationRecord }
+ { operation: PuzzleAgentOperationRecord; session: PuzzleAgentSessionSnapshot }
>({
client: {
createSession: createPuzzleAgentSession,
@@ -811,8 +861,9 @@ export function PlatformEntryFlowShellImpl({
onSessionOpened: () => {
setShowCreationTypeModal(false);
},
- onActionComplete: async ({ payload, response, session, setSession }) => {
+ onActionComplete: async ({ payload, response, setSession }) => {
setPuzzleOperation(response.operation);
+ setSession(response.session);
if (payload.action === 'publish_puzzle_work') {
await Promise.allSettled([
@@ -821,21 +872,51 @@ export function PlatformEntryFlowShellImpl({
]);
}
- const latestResponse = await getPuzzleAgentSession(session.sessionId);
- const latestSession = latestResponse.session;
- setSession(latestSession);
+ if (payload.action === 'compile_puzzle_draft') {
+ setPuzzleGenerationState((current) =>
+ current
+ ? {
+ ...current,
+ phase: 'ready',
+ completedAssetCount: 1,
+ totalAssetCount: 1,
+ }
+ : current,
+ );
+ }
if (
payload.action === 'publish_puzzle_work' &&
- latestSession.publishedProfileId
+ response.session.publishedProfileId
) {
const galleryDetail = await getPuzzleGalleryDetail(
- latestSession.publishedProfileId,
+ response.session.publishedProfileId,
);
setSelectedPuzzleDetail(galleryDetail.item);
setSelectionStage('puzzle-gallery-detail');
}
},
+ beforeExecuteAction: ({ payload }) => {
+ if (payload.action !== 'compile_puzzle_draft') {
+ return;
+ }
+ setSelectionStage('puzzle-generating');
+ setPuzzleGenerationState(createMiniGameDraftGenerationState('puzzle'));
+ },
+ onActionError: ({ payload, errorMessage }) => {
+ if (payload.action !== 'compile_puzzle_draft') {
+ return;
+ }
+ setPuzzleGenerationState((current) =>
+ current
+ ? {
+ ...current,
+ phase: 'failed',
+ error: errorMessage,
+ }
+ : current,
+ );
+ },
});
const bigFishSession = bigFishFlow.session;
@@ -906,12 +987,15 @@ export function PlatformEntryFlowShellImpl({
const leaveBigFishFlow = useCallback(() => {
setBigFishRun(null);
+ setBigFishGenerationState(null);
bigFishFlow.leaveFlow();
}, [bigFishFlow]);
const leavePuzzleFlow = useCallback(() => {
setPuzzleOperation(null);
setPuzzleRun(null);
+ setPuzzleGenerationState(null);
+ setIsPuzzleNextLevelGenerating(false);
puzzleFlow.leaveFlow();
}, [puzzleFlow]);
@@ -1039,9 +1123,35 @@ export function PlatformEntryFlowShellImpl({
return;
}
+ const currentLevel = puzzleRun.currentLevel;
+ if (!currentLevel || currentLevel.status !== 'cleared') {
+ return;
+ }
+
+ setIsPuzzleBusy(true);
+ setIsPuzzleNextLevelGenerating(true);
setPuzzleError(null);
- setPuzzleRun(advanceLocalPuzzleLevel(puzzleRun));
- }, [isPuzzleBusy, puzzleRun]);
+
+ try {
+ const { run } = await advanceLocalPuzzleNextLevel({
+ run: puzzleRun,
+ sourceSessionId:
+ selectedPuzzleDetail?.sourceSessionId ?? puzzleSession?.sessionId ?? null,
+ });
+ setPuzzleRun(run);
+ } catch (error) {
+ setPuzzleError(resolvePuzzleErrorMessage(error, '准备下一关失败。'));
+ } finally {
+ setIsPuzzleNextLevelGenerating(false);
+ setIsPuzzleBusy(false);
+ }
+ }, [
+ isPuzzleBusy,
+ puzzleRun,
+ puzzleSession,
+ resolvePuzzleErrorMessage,
+ selectedPuzzleDetail,
+ ]);
const leaveAgentWorkspace = useCallback(() => {
enterCreateTab();
@@ -1713,6 +1823,49 @@ export function PlatformEntryFlowShellImpl({
)}
+ {selectionStage === 'big-fish-generating' && (
+
+ }
+ >
+ {
+ setSelectionStage('big-fish-agent-workspace');
+ }}
+ onRetry={() => {
+ void executeBigFishAction({ action: 'big_fish_compile_draft' });
+ }}
+ onInterrupt={undefined}
+ backLabel="返回创作中心"
+ settingActionLabel={null}
+ retryLabel="重新生成草稿"
+ settingTitle="当前玩法信息"
+ settingDescription={null}
+ progressTitle="大鱼吃小鱼草稿生成进度"
+ activeBadgeLabel="草稿生成中"
+ pausedBadgeLabel="草稿生成已暂停"
+ idleBadgeLabel="等待返回工作区"
+ />
+
+
+ )}
+
{selectionStage === 'big-fish-result' && bigFishSession?.draft && (
)}
+ {selectionStage === 'puzzle-generating' && (
+
+ }
+ >
+ {
+ setSelectionStage('puzzle-agent-workspace');
+ }}
+ onRetry={() => {
+ void executePuzzleAction({ action: 'compile_puzzle_draft' });
+ }}
+ onInterrupt={undefined}
+ backLabel="返回创作中心"
+ settingActionLabel={null}
+ retryLabel="重新生成草稿"
+ settingTitle="当前拼图信息"
+ settingDescription={null}
+ progressTitle="拼图草稿生成进度"
+ activeBadgeLabel="草稿生成中"
+ pausedBadgeLabel="草稿生成已暂停"
+ idleBadgeLabel="等待返回工作区"
+ />
+
+
+ )}
+
{selectionStage === 'puzzle-result' && puzzleSession?.draft && (
{
setSelectionStage('puzzle-gallery-detail');
@@ -1867,6 +2063,17 @@ export function PlatformEntryFlowShellImpl({
void advancePuzzleLevel();
}}
/>
+ {isPuzzleNextLevelGenerating ? (
+
+
+
+
正在准备下一关
+
+ 广场暂无可接续作品，正在生成新的候选图。
+
+
+