TrueGrowth/docs/VIDEO_CHARACTER_REFERENCE_PARALLEL_LESSONS.md

视频角色参考图并发生成经验

更新日期：2026-05-02

背景

爆款视频和爆款 MV 在“全部→生成视频”前，会先为缺少参考图的角色自动生成角色参考图。旧流程使用 for...of + await 串行等待：角色 A 完成后才提交角色 B。角色参考图之间没有数据依赖，串行只会放大整条批量生成的等待时间。

本轮把两个工具的 Step 0 改为并发生成所有缺失角色参考图；镜头视频生成逻辑保持原样，不引入新的镜头间依赖。

经验

1. 先确认并发点有没有真实依赖

角色参考图生成只依赖角色描述、全局分析信息和当前模型参数。不同角色之间不需要互相读取结果，因此可以并发。

这和镜头视频不同。镜头内部仍然有“首帧图 → 视频”的硬顺序，不能因为批量提速就跳过首帧生成。

2. 并发回写不要逐个覆盖记录

串行时代码可以在每个角色完成后读取 latestRecordRef.current.characters 并立即 applyRecordPatch。并发后如果仍然逐个回写，多个任务完成顺序不可控，容易用旧快照覆盖其它角色刚写入的 referenceImageUrl。

更稳的做法：

1. 每个并发任务只返回 { charId, url }。
2. 等所有角色任务结束后过滤成功结果。
3. 基于最新角色列表按 charId 合并。
4. 最后只做一次 applyRecordPatch。

3. 停止逻辑要覆盖“刚拿到 taskId”的瞬间

并发流程里，任务 ID 返回和进入轮询之间也可能发生停止。任务一旦创建成功，就应立即加入 activeBatchTaskIdsRef。进入等待前再检查 batchStopRef：

• 如果已停止，立刻 cancel 当前 task。
• 无论是否进入等待，finally 都要从活跃集合移除。
• 爆款视频页还要同步更新 activeCount，避免 UI 显示卡住。

4. 失败要局部吞掉，不阻塞其它角色

角色参考图只是后续首帧的一致性增强。某个角色参考图生成失败时，不应让整个批量生成直接崩掉。并发任务内部 catch 错误并返回 null，其它角色继续等待；后续镜头仍按已有参考图和提示词推进。

5. 高并发文件处理里只传 URL 引用

角色参考图并发阶段不要读取图片二进制，不转 base64，不复制大素材对象。任务结果只提取 task.result.url 并写回轻量字段。这样角色数变多时，前端内存压力主要来自少量 Promise 和字符串引用，不会因为图片内容堆积导致内存峰值。

6. 两个工具要保持同构

爆款视频和爆款 MV 的第三步流程非常接近。改其中一个时要同步检查另一个：

• 是否都有角色参考图自动补齐 Step 0。
• 是否都维护活跃 task 集合。
• 是否都避免并发回写覆盖。
• 是否都保留各自特有参数，例如 MV 的 knowledgeContextRefs 和 autoInsertToCanvas: false。

7. 首尾帧一致性要从源头和生成两端一起约束

角色一致性差时，只改最终图片生成 prompt 不够。爆款视频和爆款 MV 的首帧、尾帧字段先由脚本/分镜 prompt 生成，之后才进入 buildFramePrompt。如果源头字段没有写清同一人物、同一发型、同一套衣服，后续生成阶段再补约束也容易被当前关键帧文字带偏。

更稳的做法：

1. 在脚本/分镜 prompt 阶段要求 first_frame_prompt 和非空 last_frame_prompt 写入完整角色锚点，包括身份、脸型五官、发型、体型、年龄感、服装款式、颜色、材质和配饰。
2. 在 buildFramePrompt 阶段再次声明优先级：角色参考图和角色描述高于当前关键帧文字；若冲突，保留参考图中的人物与服装，只调整姿态、表情、动作、镜头角度、光线和背景。
3. 手动打开首帧/尾帧生成弹窗时，首帧和尾帧都要带上当前镜头的角色参考图。不要出现“首帧有角色参考图，尾帧只有文字 prompt”的不对称链路。
4. 批量生成和手动生成要共享同一套约束，否则用户单独重生尾帧时最容易换脸、换发型或换衣服。

这类修复不需要新增数据结构。优先把已有的 characters[].description、character_ids 和 referenceImageUrl 用足，避免引入额外状态和迁移成本。

检查清单

• 缺少参考图的角色是否一次性并发提交，而不是逐个等待。
• 角色任务结果是否先收集，再按最新角色列表合并回写。
• 停止按钮是否能取消所有已创建的角色参考图任务。
• 任务取消后活跃集合和 UI 计数是否会清理。
• 单个角色失败是否不会阻塞其它角色和后续镜头流程。
• 并发流程是否只保存 URL，不读取或缓存大文件内容。
• 首帧和非空尾帧字段是否从脚本/分镜阶段就写入同一人物、同一服装锚点。
• 最终 buildFramePrompt 是否明确角色参考图优先于当前关键帧文字。
• 手动首帧和尾帧弹窗是否都带入当前镜头角色参考图。

一句话

角色参考图之间无依赖，就让它们并发；首尾帧一致性要从脚本字段源头和最终生成 prompt 两端一起锁住。