1

docs/technical/AGENT_DRAFT_RESULT_AUTOSAVE_DB_CHECK_2026-04-21.md

@@ -0,0 +1,119 @@
+# 创作流程草稿/图片/动作自动保存数据库检查 2026-04-21
+
+更新时间：`2026-04-21`
+
+## 1. 本次检查范围
+
+本次检查只聚焦当前创作流程里下面这条链路：
+
+`结果页前端编辑 -> 自动保存 -> Agent session 主链同步 -> 作品库落库`
+
+重点核对三类内容：
+
+1. 草稿文本类修改
+2. 生成后的角色图片、地点图片、分幕图
+3. 角色动作相关资产字段
+
+## 2. 当前实际自动保存链路
+
+当前前端主入口在：
+
+- `src/components/game-shell/PreGameSelectionFlow.tsx`
+
+实际行为如下：
+
+1. 结果页编辑统一通过 `onProfileChange` 更新 `generatedCustomWorldProfile`
+2. 当结果页停留在 `custom-world-result` 阶段时，前端会对 profile 做防抖自动保存
+3. 如果当前结果页来源是 `agent-draft`，自动保存前会先执行 `sync_result_profile`
+4. `sync_result_profile` 完成后，前端不直接保存旧内存 profile，而是优先保存“从最新 session 重编译出的 profile”
+5. 作品库保存最终走 `PUT /api/runtime/custom-world-library/:profileId`
+6. Express 后端通过 `runtimeRepository.upsertCustomWorldProfile(...)` 把 profile 写入 `custom_world_profiles.payload_json`
+
+所以数据库层本身是有正常落库能力的。
+
+## 3. 本次检查前确认成立的部分
+
+以下能力在本次检查前已经成立：
+
+1. 结果页普通草稿字段编辑会触发自动保存
+2. 自动保存会真正调用后端作品库接口并更新数据库
+3. 返回创作、进入世界两条路径也会优先同步 Agent session
+4. `legacyResultProfile` 已作为阶段一桥接快照保留在 session 中
+
+## 4. 本次发现的真实风险
+
+风险不在数据库写入本身，而在：
+
+`sync_result_profile -> session 重编译结果页 profile`
+
+此前 `sync_result_profile` 只回写：
+
+1. 基础摘要字段
+2. `legacyResultProfile`
+
+但没有把结果页里已经确认过的资产字段同步回 foundation draft 对应节点。
+
+这会导致一个阶段性风险：
+
+1. 用户在结果页换了新的角色图
+2. 或者结果页里刚确认了新的动作资产字段
+3. 或者结果页里刚确认了新的地点图、分幕图
+4. 自动保存前前端先做一次 session 同步
+5. 同步完成后又从 session 重编译结果页 profile
+6. 重编译过程会把 draft 层旧资产字段再次并入结果 profile
+
+这样就可能出现：
+
+**数据库自动保存成功了，但保存进去的是“被旧 draft 资产字段回退过的版本”，不是用户刚在结果页看到的最新图/动作。**
+
+## 5. 本轮修复
+
+本轮在：
+
+- `server-node/src/services/customWorldAgentOrchestrator.ts`
+
+补了一个收窄修复：
+
+1. `sync_result_profile` 仍然保持阶段一边界，不做整套 runtime -> foundation draft 反解
+2. 但会按相同 id，把结果页里已确认的资产字段同步回 draft 层已有对象
+3. 同步范围包括：
+   - 角色 `imageSrc`
+   - 角色 `generatedVisualAssetId`
+   - 角色 `generatedAnimationSetId`
+   - 角色 `animationMap`
+   - 地点 `imageSrc`
+   - 分幕 `backgroundImageSrc`
+   - 分幕 `backgroundAssetId`
+
+这样后续再从 session 重编译结果页 profile 时，最新资产字段不会再被旧 draft 值回退。
+
+## 6. 验证补充
+
+本轮补了服务端测试：
+
+- `server-node/src/services/customWorldAgentPhase4.test.ts`
+
+新增验证点：
+
+1. `sync_result_profile` 后，最新角色主图会写回 draft
+2. 最新角色动作资产字段会写回 draft
+3. 最新地点图会写回 draft
+4. 最新分幕图会写回 draft
+
+## 7. 结论
+
+截至本轮修复后，当前创作流程里：
+
+1. 草稿文本修改可以自动保存到数据库
+2. 结果页中确认后的角色图、地点图、分幕图可以随自动保存稳定进入数据库
+3. 角色动作相关资产字段可以随 session 同步和自动保存稳定保留
+
+但仍需注意：
+
+1. 当前仍是阶段一兼容链路，核心桥接字段仍然是 `legacyResultProfile`
+2. 正式发布链 `publish_world` 还没有在当前阶段打通
+3. 前端仍依赖 `buildCustomWorldProfileFromAgentDraft()` 作为 session -> 结果页兼容编译层
+
+因此本轮结论是：
+
+**当前“前端修改 -> 自动保存 -> 数据库”主链可用；本次已补上图片与动作资产在 session 重编译阶段的回退风险。**