Genarrative/docs/experience/RPG_DRAFT_IMAGE_PARALLEL_GENERATION_2026-04-24.md

RPG 底稿图片并行生成说明 2026-04-24

背景

RPG 草稿生成进入底稿素材阶段后，角色主形象与场景幕背景图都依赖同一份结构化底稿，但二者之间没有数据依赖。旧流程先生成所有角色主形象，再生成场景背景图，导致用户需要串行等待两类图片任务。

落地约束

1. 角色主形象与场景背景图必须在 API 编排层并行发起，且类内每个角色、每一幕背景也必须同时调用生图接口，不能只做到“角色大类”和“背景大类”并行。这里的场景背景图指 sceneChapterBlueprints[*].acts[*] 中每一幕的 backgroundImageSrc，不是世界封面图，也不是只按章节或地点生成一张图。
2. SpacetimeDB reducer 只负责持久化操作进度和底稿写入，不承载外部 LLM / 图片生成调用。
3. 生图前必须已经有文本设定：角色主形象使用角色对象的 visualDescription；幕背景图使用对应幕的 backgroundPromptText。缺字段时应中断并暴露底稿质量问题，不能退回 description、summary 或通用兜底词直接生图。
4. 并行分支各自基于同一份底稿副本写入素材字段，完成后只合并背景图生成产物字段，避免覆盖角色图片字段或其他草稿内容。
5. 单个大类失败仍按原有失败语义终止底稿写入，保留“生成角色主形象失败”和“生成幕背景图失败”的进度提示。

当前实现

• server-rs/crates/api-server/src/custom_world.rs 在 spawn_custom_world_draft_foundation_job 中使用 tokio::join! 同时执行：
  • generate_draft_foundation_role_visuals
  • generate_draft_foundation_act_backgrounds
• 角色分支使用 JoinSet 把所有角色主形象任务一次性投递，返回后再按角色位置写入 imageSrc 与 generatedVisualAssetId。
• 背景分支使用 JoinSet 把 sceneChapterBlueprints[*].acts[*] 的每一幕背景任务一次性投递，返回后写入 backgroundImageSrc、backgroundAssetId、generatedScenePrompt、generatedSceneModel。
• merge_generated_act_backgrounds 只把背景图字段合并回角色分支副本，再进入后续草稿卡编译和 SpacetimeDB 写入。
• 幕背景 prompt 同时兼容 backgroundPromptText、scenePromptText、visualPromptText、promptText、imagePromptText、backgroundPrompt、visualPrompt，避免 LLM 输出字段别名导致整批背景图被误判缺失。
• 每个角色主形象、每一幕背景图都必须独立自动重试，单项最多尝试 3 次。幕背景图允许部分成功：只要至少一幕成功，就必须保留已成功写入的 backgroundImageSrc 并继续生成草稿卡；全部幕都失败时才把素材阶段标记为“生成幕背景图失败”。
• 图片任务仍然一次性投递，保证角色与幕背景两类任务不回退到串行编排；但真正请求上游生图服务时必须共用并发闸门。并发数由 GENARRATIVE_DRAFT_ASSET_GENERATION_MAX_CONCURRENT_REQUESTS 或 DRAFT_ASSET_GENERATION_MAX_CONCURRENT_REQUESTS 配置，默认 4，避免固定为 2 导致多角色、多幕草稿总耗时过长。
• 幕背景图失败文案必须带第几章、第几幕和幕标题，不能只显示“第1幕 / 第2幕 / 第3幕”，否则多章节同名幕会被用户误认为同一失败项重复上报。
• 中止或部分失败前必须持久化已经成功生成的部分底稿到会话 draftProfile，不能因为某个角色或某一幕失败而丢掉其它已生成的 imageSrc / generatedVisualAssetId / backgroundImageSrc / backgroundAssetId。
• 每一幕自动生图必须记录 operation、session、第几章、第几幕、sceneId、sceneName、attempt、elapsedMs 与供应商真实错误，避免再次出现只看到“生成幕背景图失败”但无法定位哪张图、哪次请求、哪个上游原因的问题。
• 前端看到 draft_foundation operation completed 后，不能只延迟一次就读取 resultPreview；SpacetimeDB 写入、API 读模型和前端状态同步之间可能有短暂时差，必须短轮询等待结果页 profile 可用后再自动跳转到草稿页，避免卡在“底稿已整理”。
• 前端 CharacterAnimator 对带 generatedVisualAssetId 但尚无 animationMap 的自定义角色，所有状态优先渲染生成主图；只有真正发布了动作集后才按动作帧播放，避免运行或战斗状态回落到模板 sprite。

后续注意

如果后续图片供应商出现强限流，再在网关层做队列或供应商侧限流；不要在 RPG 底稿编排层恢复逐张串行，否则会重新退化成多张图片总耗时累加。

2026-04-25 补充：开局场景也必须逐幕生成背景图

本次排查发现旧草稿合成只从 landmarks 编译 sceneChapterBlueprints，导致 camp 开局场景只有 camp.imageSrc，没有进入 sceneChapterBlueprints[*].acts[*] 的幕背景生成队列。后续实现必须遵守：

1. camp 开局场景必须作为 sceneChapterBlueprints[0] 写入，sceneId 默认使用 camp.id，缺失时使用 camp-1。
2. camp.actBackgroundPromptTexts 必须包含 3 条逐幕画面描述，并和普通场景一样生成 acts[*].backgroundImageSrc。
3. 结果页场景目录可用场景图兜底展示旧草稿的幕缩略图，但新草稿不能只依赖兜底，必须让开局场景真实进入幕背景图生成链路。
4. 手动同步场景资产时，必须同时更新 sceneChapterBlueprints 与兼容字段 sceneChapters，当前主链以 sceneChapterBlueprints 为准。