104 lines
4.3 KiB
Markdown
104 lines
4.3 KiB
Markdown
# 连环画多图生成经验总结
|
||
|
||
这份文档沉淀 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`
|