feat: restore agent sessions from creation drafts

2026-04-23 21:23:46 +08:00
parent 349a397888
commit 53a9cdd791
11 changed files with 949 additions and 18 deletions
--- a/docs/technical/UNIFIED_CREATION_DRAFT_SESSION_RESTORE_2026-04-23.md
+++ b/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 工作区后，历史消息不丢失。