Initial TrueGrowth source import

docs/COMIC_CREATOR_MULTI_IMAGE_LESSONS.md

@@ -0,0 +1,103 @@
+# 连环画多图生成经验总结
+
+这份文档沉淀 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`