TrueGrowth/docs/COMIC_CREATOR_MULTI_IMAGE_LESSONS.md

连环画多图生成经验总结

这份文档沉淀 2026-04-30 这轮连环画多图生成、任务队列回填和素材库兜底的排查经验。

背景

连环画生成支持“每页生成多张候选图”，同时串行模式会用上一页图片做连续性参考。用户反馈两个现象：

• 任务队列里已经生成 12 张图，但连环画页内只显示 6 张。
• 图片预览区需要素材库兜底，万一回填丢失，可以从素材库找回图片补到当前页。

问题表现

1. “页数”和“图片数”混在一起

每页生成 2 张时，6 页会产生 12 张图片，但页面进度如果只看“有图的页数”，就只能看到 6。

经验：

• generated page count 表示多少页已经至少有一张图。
• generated image count 表示所有页候选图总数。
• UI 文案必须同时呈现两者，不能用一个数字承载两种语义。

2. 队列模式里 count 被重复消费

队列模式已经会把顶层 count=2 展开成多个任务。如果创建队列任务时又把同一个 count 透传成模型 adapter 的 n=2，就会变成：

• 队列创建 2 个任务
• 每个任务又让模型生成 2 张
• 实际产物和 UI 预期不一致

经验：

• 顶层 count 是任务编排参数。
• adapter 内的 n/count 是模型调用参数。
• 同一次生成链路中只能有一层消费批量语义。

3. 串行参考图只适合串行模式

串行生成时，第 N 页可以带上：

• 用户上传的公共参考图
• 第 N-1 页当前选中的图片

并行生成时不能依赖上一页，因为上一页可能还没生成完。

经验：

• 串行模式：referenceImages = 公共参考图 + 上一页 imageUrl
• 并行模式：referenceImages = 公共参考图
• 上一页参考图必须读最新记录里的 imageUrl，不要读闭包里的旧 page 对象。

4. 任务回填要支持多候选图

图片任务结果可能是单图 url，也可能是多图 urls。连环画页不能只保存一个 imageUrl，还要维护候选图列表。

经验：

• imageVariants 是每页候选图列表。
• imageUrl 是当前选中的图片，用于预览、导出和下一页串行参考。
• 回填时追加候选图并按 URL 去重，避免重复任务结果污染列表。

5. 素材库兜底要贴近丢图现场

如果回填链路丢了，用户最自然的恢复位置就是当前页预览区，而不是离开流程去素材库里找。

经验：

• 每页预览区下方保留一个素材库入口。
• 素材库以 SELECT 模式打开，并限制为图片素材。
• 选中图片后只保存素材 URL 到当前页候选图，不复制大对象或 base64。
• 补回成功后把当前页状态置为 succeeded，清理旧错误。

代码结构

• packages/drawnix/src/components/comic-creator/ComicCreator.tsx
  • 串行模式带上一页图片作为参考。
  • 每页预览区增加素材库兜底入口。
  • 素材库选图后追加到当前页候选图。
• packages/drawnix/src/components/comic-creator/utils.ts
  • 区分已生成页数和已生成图片数。
  • 统一追加、去重和选择候选图。
• packages/drawnix/src/components/comic-creator/task-sync.ts
  • 从任务结果构建一组候选图并回填到对应页。
• packages/drawnix/src/mcp/tools/image-generation.ts
  • 队列模式不再把顶层 count 透传成 adapter n/count。
  • 队列任务保留连环画记录和页 ID 元数据，方便异步回填。
• packages/drawnix/src/components/task-queue/TaskItem.tsx
  • 批量序号兼容 0-based 和 1-based 来源，避免显示成 3/2。

经验规则

• 多图生成里，“任务数”“页数”“图片数”必须分开命名、分开统计、分开展示。
• 队列参数和模型参数要划清边界，批量语义只能被消费一次。
• 串行连续性参考只能使用已生成的上一页当前图，并行模式不要假装有上一页。
• 多候选图结构要以 URL 轻量引用为主，避免把大文件或 base64 写进状态。
• 补救入口要放在用户发现问题的位置，减少恢复成本。

验证

• pnpm --dir packages/drawnix exec vitest run src/components/comic-creator/utils.test.ts src/mcp/tools/__tests__/image-generation.test.ts --no-file-parallelism --maxWorkers=1
• pnpm --dir packages/drawnix exec tsc --noEmit --pretty false --project tsconfig.lib.json
• git diff --check