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