# 分镜图生成质量提升计划

**目标：** 解决分镜图生成时出现宫格布局、角色外貌不一致、背景不一致等问题，并规划后续质量提升路径。

**技术栈：** Node.js (Express), better-sqlite3, Vue 3, Element Plus, Gemini / NanoBanana 图片 API

---

## 已完成（2026-03-14）

### 问题一：场景四视图生成后不显示

**原因：** `imageClient.createAndGenerateImage` 是为角色图片设计的函数，缺少 `scene_id` 参数支持，导致：
- 图片存储路径 hardcode 为 `characters/`（应为 `scenes/`）
- `image_generations` 表不写入 `scene_id`
- 生成完成后不回写 `scenes` 表的 `image_url` / `local_path`

**修复：**
- `imageClient.js`：`createAndGenerateImage` 新增 `scene_id` 参数，动态判断存储目录（`scenes` / `characters` / `images`），生成完成后回写 `scenes` 表
- `sceneService.js`：调用时传入 `scene_id: sceneId`

---

### 问题二：分镜图生成结果仍为宫格布局

**原因：** 传入的场景/角色参考图是 2×2 四视图合图，图片 AI 看到宫格参考图后会模仿其布局格式输出宫格图，且提示词中没有明确的"单张输出"约束。

**修复：**
- `imageService.js`：单张分镜生成时，在 Step 2.5 记录参考图映射，通过 Gemini parts 结构传递说明
- `imageClient.js`：重构 Gemini 多模态输入结构为正确顺序：
  ```
  [总说明文字] → [参考1说明] → [参考图1] → [参考2说明] → [参考图2] → [生成指令+主提示词]
  ```
  而非原来的"prompt 在前，图片附后"的错误顺序

---

### 问题三：角色外貌不一致（参考图格式干扰）

**原因：** 作为参考图传入的是 2×2 四视图合图（含头像/正面/侧面/背面 4 格），图片 AI 难以从合图中准确提取角色外貌，且四格合图的视觉格式会干扰输出布局。

**修复：**
- `imageService.js`（`splitQuadGridToImages`）：INSERT 时增加 `character_id` 字段，让角色拆分面板可按 ID 查询
- `imageService.js`（Step 2 参考图解析）：优先查询拆分后的单张面板作为参考：
  - 场景：`quad_panel_0`（左上格 = 建立远景，最能代表环境）
  - 角色：`quad_panel_1`（右上格 = 正面全身图，最能代表角色外貌）
  - 无拆分面板时 fallback 到四视图合图
- 角色最多取 3 个（避免超出模型参考图限制），Gemini 参考图上限从 3 改为 4（场景1 + 角色3）

---

### 问题四：参考图标签与实际传图数量不对齐

**原因：** 当角色有 `extra_images` 且无主图时，`extra_images` 仍会被推入 refs 但无对应主标签，导致后续角色编号错乱；`refLabels` 数量可能超过 Gemini 实际接收的图片数，让模型产生困惑。

**修复：**
- `extra_images` 推入逻辑移入 `if (primaryRef)` 块内，确保无主图时不产生孤立的 extra 标签
- `refLabels.slice(0, refs.length)` 强制对齐条数
- Gemini parts 构建时，按实际传入图片数裁剪标签

---

## 待完成（优先级排序）

### P1：分镜 prompt 二次优化

**背景：** 当前分镜描述（由文本 AI 生成的首帧/关键帧/尾帧提示词）是针对"分镜内容描述"设计的，直接发给图片 AI 效果打折。

**方案：** 在 `imageService.js` Step 3 之前增加一个文本 AI 优化步骤：
- 输入：原始分镜提示词 + 风格 + 宽高比 + 参考资产名称列表
- 输出：针对图片生成模型优化的提示词（增强细节描述、统一风格词汇、加入参考资产名称映射）
- 模型：使用轻量文本模型（如 deepseek-v3），成本低
- 缓存：优化后的 prompt 回写 `image_generations.prompt`，同一分镜重新生成时可复用

**预期收益：** 图片细节更丰富，风格更一致，角色名称与参考图映射更清晰

---

### P2：批量宫格生成（同一分镜多帧）

**背景：** 当前每一帧独立调用图片 API，导致同一分镜的首帧/关键帧/尾帧在风格、光线、色调上可能不一致。

**方案：** 复用现有 `quad_grid` / `nine_grid` 基础设施：
- 在分镜图生成时，将同一分镜的多帧组合为宫格提示词，一次生成宫格图
- 生成完成后调用 `splitQuadGridToImages` 自动拆分为独立帧
- API 调用次数从 N 次降为 1 次

**预期收益：** 同一分镜内视觉一致性大幅提升，API 成本降低

---

### P3：参考图智能过滤

**背景：** 当前把分镜绑定的所有角色/场景参考图都传入，部分角色/场景可能在当前帧中根本未出现，增加无效噪声。

**方案：** 在 Step 2 解析参考图后，调用文本 AI 判断：
- 输入：分镜描述 + 候选资产列表（名称 + 简介）
- 输出：与本帧内容直接相关的资产列表
- 只传相关资产的参考图

**预期收益：** 减少无关参考图干扰，提高角色/场景还原度

---

### P4：参考图压缩

**背景：** 传参考图前无压缩处理，可能触发 API 请求大小限制。

**方案：** 在 `callGeminiImageApi` 中对参考图 buffer 做压缩：
- 单张目标：≤ 3MB（JPEG quality 递减压缩）
- 总大小：≤ 10MB（按大小降序优先压缩大图）
- 使用 `sharp` 处理（项目已依赖）

---

### P5：多 Agent 大纲生成

**背景：** 当前大纲/剧本生成为单次 AI 调用，无法做到自动审核、迭代修改。

**方案：** 基于 Vercel AI SDK 的 Tool Use，实现三 Agent 协作：
- **故事师**：分析输入主题，生成故事线（存 `storylines` 表）
- **大纲师**：根据故事线生成各集大纲（存 `outlines` 表）
- **导演**：审核大纲与故事线一致性，提出修改建议并执行

工具调用链：`主Agent → 故事师 → saveStoryline → 大纲师 → saveOutline → 导演 → updateOutline`

---

### P6：分镜自动生成 Agent（shotAgent）

**背景：** 当前分镜需要用户手动拆分，或依赖单次 AI 调用，缺少自动化流程。

**方案：**
- **segmentAgent**：从剧本中自动拆分场景片段（含情绪、动作描述）
- **shotAgent**：根据片段生成分镜提示词（含景别、角度、运镜、角色、对话）
- 前端通过 WebSocket 接收流式进度更新