1

docs/technical/AGENT_DRAFT_RESULT_ASSET_MERGE_FIX_2026-04-21.md

@@ -0,0 +1,96 @@
+# Agent 草稿结果页资产合并修复 2026-04-21
+
+更新时间：`2026-04-21`
+
+## 1. 问题现象
+
+当前创作流程里，用户在“生成草稿”后反馈：
+
+1. 角色主图没有稳定出现在结果页
+2. 场景背景图有时可见，有时角色图缺失
+3. 自动保存后的作品库条目里，分幕图可能已经存在，但场景角色主图仍为空
+
+## 2. 本次真实排查结论
+
+本轮不是单一的“没写数据库”问题，而是 `agent draft -> result profile` 桥接层存在一类更隐蔽的集合漂移问题。
+
+排查后确认：
+
+1. 最新 `custom_world_sessions.payload_json` 里的 `draftProfile.storyNpcs[].imageSrc` 已经存在
+2. 最新 `draftProfile.sceneChapters[].acts[].backgroundImageSrc` 也已经存在
+3. 对应图片文件也真实存在于仓库根 `public/` 下
+4. 最新 `custom_world_profiles.payload_json` 里，分幕图通常已保存成功
+5. 但场景角色主图可能仍为空
+
+根因在于：
+
+1. 结果页桥接层在 `draftProfile.legacyResultProfile` 存在时，仍把 `legacyResultProfile` 视为主列表
+2. 旧逻辑只会按 `id` 把 `draftProfile` 里的图片字段回贴到 `legacyResultProfile`
+3. 一旦后续草稿精修导致 `draftProfile` 的角色集合、角色 id 或角色命名发生漂移
+4. 旧 `legacyResultProfile` 就会继续主导结果页和自动保存对象列表
+5. 最新角色主图虽然已在 `draftProfile` 里生成完成，但会因为匹配失败而被整批吞掉
+
+这类问题在场景角色上最明显，因为角色集合最容易在后续精修中替换。
+
+## 3. 修复策略
+
+本轮在：
+
+- `src/services/customWorldAgentDraftResult.ts`
+
+调整桥接规则：
+
+1. `legacyResultProfile` 仍保留，继续提供运行时富字段
+2. 但角色、场景、分幕等对象集合不再默认由 `legacyResultProfile` 主导
+3. 最新 `draftProfile` 成为结果页对象列表的主来源
+4. `legacyResultProfile` 只负责给命中的对象补运行时富字段
+5. 匹配优先级为：
+   - 先按 `id`
+   - 再按名称兜底
+
+具体规则：
+
+1. `playableNpcs`：以最新 draft 集合为主，legacy 只补富字段与旧运行时字段
+2. `storyNpcs`：同上，避免旧角色列表吞掉新角色主图
+3. `sceneChapterBlueprints`：以最新 draft 幕列表为主，legacy 只补章节/幕已有运行时字段
+4. `landmarks`：优先更新最新 draft 命中的场景对象，但保留 legacy 中未被命中的剩余运行时场景，避免丢连接与残留信息
+5. `camp`：保留 legacy 基础信息，但优先取 draft 最新图片字段
+
+## 4. 修复后的链路意义
+
+修复后：
+
+1. 草稿自动资产服务生成的角色主图不会再因为旧 `legacyResultProfile` 的角色集合过时而丢失
+2. 分幕图继续可以稳定进入结果页与自动保存
+3. 作品库自动保存时，结果页编译出的 profile 更接近“当前草稿真实快照”，而不是历史 legacy 快照
+
+## 5. 新增验证
+
+本轮补了前端桥接测试：
+
+- `src/services/customWorldAgentDraftResult.test.ts`
+
+新增验证点：
+
+1. 当 `draftProfile.storyNpcs` 与 `legacyResultProfile.storyNpcs` 集合漂移时
+2. 结果页仍应优先展示最新 draft 角色
+3. 最新角色主图与最新分幕图不能被旧 legacy 快照吞掉
+
+## 6. 当前状态
+
+本轮修复后，本地已验证：
+
+1. `src/services/customWorldAgentDraftResult.test.ts`
+2. `src/components/CustomWorldResultView.test.tsx`
+3. `src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx`
+4. `npm run check:encoding`
+
+均通过。
+
+## 7. 后续建议
+
+这次问题再次说明：
+
+1. `legacyResultProfile` 继续长期作为结果页主列表来源风险很高
+2. 只做“按 id 回贴图片字段”在对象集合会漂移的链路里不够稳
+3. 后续如果继续推进后端单一真相源，应优先把结果页对象集合完全改为服务端最新 compile/preview 结果，而不是继续让前端桥接层承担最终裁决