# 拼图草稿恢复 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. 发布后不会额外生成第二条重复作品记录。