# 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`，但入口没挂鉴权”的低层断线问题。