feat: restore agent sessions from creation drafts

docs/technical/CREATION_HUB_CARD_ACTIONS_2026-04-22.md

@@ -15,7 +15,9 @@
 | --- | --- | --- | --- | --- |
 | RPG Agent 草稿 | `draft` | `继续创作` / `继续完善` | 不展示，草稿需要先走发布链 | 不展示，本轮不新增 Agent session 物理删除 |
 | RPG 已发布作品 | `published` 且 `canEnterWorld=true` | `查看详情` | 展示 `体验`，直接调用现有进入世界链 | 展示 `删除`，走 owner-only 软删除 |
-| 拼图草稿 | `draft` | `查看详情` | 不展示 | 不展示，本轮不新增拼图删除契约 |
+| Big Fish 草稿 | `draft` | `继续创作` | 不展示，草稿需要先回到聊天或结果页继续完善 | 不展示，本轮不新增 Big Fish 草稿删除 |
+| Big Fish 已发布作品 | `published` | `查看详情` | 展示 `体验`，直接调用现有 Big Fish 运行态 | 不展示，本轮不新增 Big Fish 删除契约 |
+| 拼图草稿 | `draft` | `继续创作` | 不展示 | 不展示，本轮不新增拼图删除契约 |
 | 拼图已发布作品 | `published` | `查看详情` | 展示 `体验`，直接调用 `startPuzzleRun` | 不展示，本轮不新增拼图删除契约 |
 
 ## 3. 后端边界
@@ -40,6 +42,7 @@ RPG 删除必须继续遵守后端治理里的软删除规则：
 2. 不新增拼图作品删除。
 3. 不新增独立删除面板。
 4. 不新建创作页或运行时页面，只复用现有 `CustomWorldCreationHub`、RPG 进入世界链和拼图运行时链。
+5. Big Fish 草稿恢复链补齐时，只补创作中心 works 投影和恢复入口，不新建独立 Big Fish 作品系统。
 
 ## 6. 已落地结果
 
@@ -47,6 +50,8 @@ RPG 删除必须继续遵守后端治理里的软删除规则：
 2. RPG 与拼图已发布作品卡新增独立 `体验` 入口，直接复用各自现有运行时进入链路。
 3. RPG 已发布作品卡新增 `删除` 入口，调用 `/api/runtime/custom-world-library/{profile_id}` 的 `DELETE` 路由，按 owner-only 软删除规则刷新作品列表与公开广场。
 4. 创作中心详情页原有删除链路继续保留，和卡片删除共用同一后端删除契约。
+5. 后续拼图草稿恢复链补齐后，拼图 `draft` 卡主按钮语义收口为 `继续创作`，通过 `sourceSessionId` 恢复 Agent session，而不是进入详情页。
+6. 后续 Big Fish 草稿恢复链补齐后，Big Fish `draft` 卡主按钮同样收口为 `继续创作`，通过 `sourceSessionId` 恢复 Agent session，而不是重新创建会话。
 
 ## 7. 已验证
 

docs/technical/PUZZLE_DRAFT_SESSION_RESTORE_2026-04-23.md

@@ -0,0 +1,100 @@
+# 拼图草稿恢复 Agent 会话设计
+
+日期：`2026-04-23`
+
+## 1. 背景
+
+当前拼图链已经具备：
+
+1. `puzzle_agent_session / puzzle_agent_message` 作为聊天真相。
+2. `get_puzzle_agent_session(sessionId)` 可按会话恢复完整消息。
+3. `puzzle_work_profile` 作为创作中心与广场的作品列表投影。
+
+但现状仍有两个断点：
+
+1. `compile_puzzle_agent_draft` 只把结果页草稿写回 session，没有同步生成 `draft` 态 `puzzle_work_profile`。
+2. 创作中心点击拼图草稿卡时，只会走“查看详情”，没有利用 `sourceSessionId` 恢复聊天会话。
+
+这导致“进入创作草稿恢复聊天记录”在拼图链上并不完整。
+
+## 2. 目标
+
+本轮只实现以下闭环，不扩展到用户级历史列表：
+
+1. 拼图 Agent 编译出结果页草稿后，创作中心必须出现对应草稿卡。
+2. 草稿卡必须带 `sourceSessionId`，作为恢复聊天记录的唯一索引。
+3. 点击拼图草稿卡时：
+   - 若 session 仍存在且已带 `draft`，优先进入 `puzzle-result`。
+   - 若 session 存在但尚无 `draft`，进入 `puzzle-agent-workspace`。
+4. 恢复后继续复用同一个 `puzzleSession`，返回聊天工作区时能看到完整历史消息。
+
+## 3. 真相源与投影边界
+
+### 3.1 真相源
+
+拼图聊天历史、锚点、阶段、结果页草稿仍以 `puzzle_agent_session` 为准。
+
+### 3.2 投影
+
+`puzzle_work_profile` 只承担：
+
+1. 创作中心作品卡展示。
+2. 结果页 / 详情页入口锚点。
+3. 通过 `source_session_id` 反查 Agent session。
+
+它不是新的聊天真相，不承担额外会话列表职责。
+
+## 4. 后端落地
+
+### 4.1 编译草稿时同步 upsert draft 作品
+
+`compile_puzzle_agent_draft` 除了更新 session 外，还要：
+
+1. 依据当前 `draft` 创建或更新一条 `PuzzlePublicationStatus::Draft` 的 `puzzle_work_profile`。
+2. `source_session_id` 固定写当前 session id。
+3. `work_id / profile_id` 使用稳定的 session 派生规则，避免同一 session 每次编译都生成新卡。
+
+### 4.2 图片相关操作持续同步 draft 作品
+
+`save_puzzle_generated_images`、`select_puzzle_cover_image` 会改变结果页草稿真相，因此也要同步更新对应 draft 作品记录，保证创作中心卡片封面、摘要、标签与当前草稿一致。
+
+### 4.3 发布时升级同一条作品记录
+
+`publish_puzzle_work` 不再新生成随机 `work_id / profile_id`，而是复用 session 派生的稳定 ID，把同一条 draft 作品升级为 `published`：
+
+1. 避免创作中心出现“草稿卡 + 已发布卡”两条重复记录。
+2. 保持 `source_session_id` 连续可追溯。
+
+## 5. 前端落地
+
+### 5.1 创作中心卡片语义
+
+拼图草稿卡主按钮从 `查看详情` 改为 `继续创作`。
+
+### 5.2 打开拼图草稿
+
+平台壳层新增拼图草稿恢复入口：
+
+1. 读 `PuzzleWorkSummary.sourceSessionId`。
+2. 用现有 `getPuzzleAgentSession(sourceSessionId)` 拉回 session。
+3. 若 `session.draft` 存在：
+   - 写入 `puzzleSession`
+   - 切到 `puzzle-result`
+4. 若 `session.draft` 不存在：
+   - 写入 `puzzleSession`
+   - 切到 `puzzle-agent-workspace`
+
+### 5.3 失败回退
+
+如果 `sourceSessionId` 缺失或对应 session 已失效：
+
+1. 刷新拼图作品列表。
+2. 停留在创作中心。
+3. 通过现有错误 banner 提示，不新增独立说明 UI。
+
+## 6. 验收
+
+1. 编译拼图结果页草稿后，创作中心出现 `draft` 态拼图卡。
+2. 草稿卡点击后会恢复对应 `puzzleSession.messages`。
+3. 已有 `draft` 的 session 恢复后直达结果页，点击返回能看到原聊天记录。
+4. 发布后不会额外生成第二条重复作品记录。

docs/technical/UNIFIED_CREATION_DRAFT_SESSION_RESTORE_2026-04-23.md

@@ -0,0 +1,141 @@
+# 创作中心全草稿恢复 Agent 会话设计
+
+日期：`2026-04-23`
+
+## 1. 背景
+
+当前创作中心已经承载多种“先聊天收束，再进入结果页”的创作链：
+
+1. RPG / Custom World
+2. Big Fish
+3. Puzzle
+
+但三条链当前恢复能力并不一致：
+
+1. RPG 草稿已经能通过 `sessionId` 恢复 Agent 会话。
+2. Puzzle 草稿已补到通过 `sourceSessionId` 恢复 Agent 会话。
+3. Big Fish 仍停留在“有会话但没有创作中心草稿投影”的状态，用户退出登录后缺少重新进入草稿的入口。
+
+这会导致“进入创作草稿继续聊”的体验只在部分品类成立，不满足创作中心统一入口的要求。
+
+## 2. 目标
+
+本轮统一收口到以下规则：
+
+1. 只要是创作中心中的 `draft` 草稿，都必须能恢复对应 Agent 聊天历史。
+2. 恢复能力只要求在“重新进入创作中心草稿”时成立，不扩展到用户级独立聊天历史列表。
+3. 所有草稿卡片都遵循同一入口语义：
+   - 尚无结果页草稿时，进入 Agent 工作区继续聊。
+   - 已有结果页草稿时，直接进入结果页。
+   - 从结果页返回后，仍能看到原聊天记录。
+
+## 3. 统一边界
+
+### 3.1 真相源
+
+聊天历史、当前阶段、锚点、草稿真相始终在各自的 Agent session 表中：
+
+1. RPG / Custom World：`custom_world_agent_session`
+2. Big Fish：`big_fish_creation_session + big_fish_agent_message`
+3. Puzzle：`puzzle_agent_session + puzzle_agent_message`
+
+### 3.2 创作中心作品卡
+
+创作中心作品卡只承担：
+
+1. 展示草稿摘要。
+2. 保存恢复用的稳定会话标识。
+3. 作为重新进入创作链的入口。
+
+它不是新的聊天真相，也不独立承载消息历史。
+
+## 4. 统一恢复规则
+
+### 4.1 草稿卡必须带会话索引
+
+不同品类的草稿卡都必须能反查到会话：
+
+1. RPG / Custom World：使用现有 `sessionId`
+2. Big Fish：新增 `sourceSessionId`
+3. Puzzle：使用现有 `sourceSessionId`
+
+### 4.2 打开草稿时的分流
+
+前端打开草稿卡时统一执行：
+
+1. 先按会话 id 读取对应 session snapshot。
+2. 若 session 已有结果页草稿：
+   - RPG 进入 `custom-world-result`
+   - Big Fish 进入 `big-fish-result`
+   - Puzzle 进入 `puzzle-result`
+3. 若 session 尚无结果页草稿：
+   - RPG 进入 `agent-workspace`
+   - Big Fish 进入 `big-fish-agent-workspace`
+   - Puzzle 进入 `puzzle-agent-workspace`
+
+### 4.3 失败回退
+
+如果草稿卡缺少会话索引，或会话已不存在：
+
+1. 刷新对应作品列表。
+2. 停留在创作中心。
+3. 通过现有错误 banner 提示，不新增规则说明 UI。
+
+## 5. 分品类落地要求
+
+### 5.1 RPG / Custom World
+
+RPG 已具备恢复基础，本轮只把它纳入统一口径：
+
+1. `draft + sessionId` 继续作为恢复前提。
+2. 有结果页草稿时，主按钮保持 `继续完善`。
+3. 没有结果页草稿时，主按钮保持 `继续创作`。
+
+### 5.2 Puzzle
+
+Puzzle 继续沿用本轮已落地的规则：
+
+1. 编译结果页草稿时同步 upsert `draft` 作品投影。
+2. 作品投影保留 `sourceSessionId`。
+3. 草稿卡点击恢复 `puzzleSession`，优先进入结果页。
+
+### 5.3 Big Fish
+
+Big Fish 需要补齐缺口：
+
+1. 为 `big_fish_creation_session` 增加 works 读模型输出，不新建第二套聊天存储。
+2. 创作中心读取 Big Fish works 并合并展示。
+3. 草稿卡固定带 `sourceSessionId = sessionId`。
+4. `draft` 卡主按钮使用 `继续创作`。
+5. `published` 卡主按钮使用 `查看详情`，体验入口仍直接进入运行态。
+6. 在独立 Big Fish 详情页补齐前，`查看详情` 先复用结果页承载详情与返回聊天的入口，不额外新建页面。
+
+## 6. Big Fish works 最小方案
+
+### 6.1 不新增独立 Big Fish profile 表
+
+本轮 Big Fish 只补“草稿恢复聊天”闭环，不强行新建完整发布作品仓储。
+
+创作中心所需 Big Fish work summary 直接由 `big_fish_creation_session` 派生：
+
+1. `draft_json` 存在时输出草稿标题、副标题、摘要。
+2. `asset_slots` 提供封面图和资源完成度提示。
+3. `stage == Published` 时视为 `published`。
+4. 其他阶段统一视为 `draft`。
+
+### 6.2 稳定 workId
+
+Big Fish works 使用会话派生稳定 id：
+
+1. `workId = big-fish-work-{sessionId}`
+2. `sourceSessionId = sessionId`
+
+这样同一份草稿不会在创作中心重复出现。
+
+## 7. 验收
+
+1. RPG、Big Fish、Puzzle 三类草稿都能在创作中心重新打开。
+2. 退出登录后重新登录，进入同一份草稿仍能恢复对应聊天记录。
+3. Big Fish 草稿首次编译出结果页后，会在创作中心出现草稿卡。
+4. Big Fish / Puzzle 已有结果页草稿时，点击草稿卡直达结果页。
+5. 从结果页返回各自 Agent 工作区后，历史消息不丢失。