# 世界草稿图片生成与预览补齐说明

更新时间：`2026-04-24`

## 1. 检查结论

当前 server-rs 的世界底稿生成链路已经在 `draft_foundation` 后台任务中补齐两类图片：

1. `playableNpcs` 与 `storyNpcs` 中的每个角色都会调用角色主形象生成链路，并把 `imageSrc`、`generatedVisualAssetId` 写回底稿。
2. `sceneChapterBlueprints[].acts[]` 中的每一幕都会调用场景图生成链路，并把 `backgroundImageSrc`、`backgroundAssetId`、生成提示词与模型信息写回底稿。

图片生成后不落本地真值，而是通过 OSS `put_object -> head_object -> confirm_asset_object -> bind_asset_object_to_entity` 确认对象，并用兼容的 `/generated-*` 路径供前端读取。

## 2. 前端缺口

结果页的场景列表此前只把每个场景的第一张幕背景图作为场景卡封面。这样虽然后端已经生成了每一幕图片，但用户只能看到第一幕，无法在结果页确认同一场景下其他幕的图片是否存在。

## 3. 本次落地

1. 在 `CustomWorldEntityCatalog` 中增加每幕图片缩略条，来源为当前场景匹配到的 `sceneChapterBlueprints[].acts[].backgroundImageSrc`。
2. 保留原来的场景卡封面策略：第一幕背景图仍作为主封面，旧的场景图字段继续作为兜底。
3. 缩略条只展示已生成图片的幕，不额外暴露章节结构文本，避免结果页变成规则说明面板。
4. 增加结果页测试，覆盖同一场景下两幕背景图都能在前端以图片形式预览。

## 4. 验收点

1. 生成世界草稿完成后，角色页签中所有可扮演角色和场景角色能展示 `imageSrc`。
2. 场景页签中，每个场景卡片仍展示主封面。
3. 场景卡片下方能横向预览该场景所有已生成幕背景图。
4. OSS 未配置或上传失败时，后端任务应失败并把错误写入 operation，而不是生成伪本地路径。

## 5. 上游图片服务失败降级

`draft_foundation` 的底稿文本结构是进入结果页和继续编辑的主产物，角色主图、幕背景图属于可后补资产。若 DashScope 或 OSS 上游临时不可用，后台任务不应把整份底稿标记为失败。

本次补充后：

1. 角色主图分支失败时，operation 记录错误信息并继续使用未带角色图的底稿。
2. 幕背景图分支失败时，operation 记录错误信息并继续使用未带幕图的底稿。
3. 已成功的并行资产分支仍会合并回底稿，不会被失败分支覆盖。
4. 后续可通过资产工坊或单项生成动作补齐缺失图片。