Genarrative/docs/technical/AGENT_DRAFT_RESULT_ASSET_MERGE_FIX_2026-04-21.md

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 结果，而不是继续让前端桥接层承担最终裁决

---

8. 2026-04-21 补充：新建共创会话 500 根因

后续联调里又发现一条与资产合并无关、但会直接阻断创作入口的后端问题：

1. 点击“创建新 RPG 游戏”时，POST /api/runtime/custom-world/agent/sessions 返回 500
2. 表面上前端只看到“服务器内部错误”，实际根因在路由层

本次补查确认：

1. server-node/src/routes/customWorldAgent.ts 这组路由内部直接使用 request.userId!
2. 但路由文件本身在 2026-04-21 修复前没有挂 requireJwtAuth(...)
3. 结果是 HTTP 请求虽然带了登录 token，但 request.userId 并不会被注入
4. 后端继续拿 undefined 作为 userId 创建 / 读取 agent session，最终在仓储写库阶段触发 500

修复方式：

1. 在 createCustomWorldAgentRoutes(...) 顶部统一补上 router.use(requireJwtAuth(context.config, context.userRepository))
2. 让 session 创建、读取、发消息、执行 action、读取 operation / card 详情全部走同一层鉴权注入

这次补丁的意义不是新增功能，而是把 custom-world agent 路由和其他 rpg-entry / rpg-profile / rpg-runtime 受保护接口重新对齐，避免再出现“路由里依赖 request.userId，但入口没挂鉴权”的低层断线问题。