# 多宫格分镜视频开发清单（2026-03-12）

> 面向开发落地  
> 范围：`4宫格 / 6宫格 / 9宫格` 标准切片、高清镜头图阶段、用户确认后再生视频  
> 对应需求文档：`docs/多宫格分镜视频需求补充-2026-03-12.md`

---

## 0. 开发目标

本轮不是“继续优化九宫格视频”，而是把整条链路正式升级为：

`Agent 规划多宫格 -> 标准分镜图生成 -> 自动识别切片 -> 每片生成高清镜头图 -> 用户确认镜头文案 -> 串行生成视频 -> 回写数据库与画布`

建议拆成四大模块并行推进：

1. `Agent`
2. `数据库`
3. `API`
4. `画布交互`

建议开发顺序：

1. 先完成 `数据库`
2. 再完成 `Agent`
3. 然后完成 `API`
4. 最后接 `画布交互`

原因：

- 数据结构要先定，否则前后端字段会反复改
- Agent 规则要先稳定，否则后端接口难以确定输入输出
- API 要在状态机清晰后再落
- 画布是最依赖整体状态的最后一层

---

## 1. Agent 开发清单

目标：让 Agent 不只是“识别九宫格”，而是能稳定产出 **可切片的标准多宫格图**，并在视频前承担“分镜确认门”的职责。

### 1.1 意图与宫格数判断

- [ ] 在 `lib/ai/smart-analyzer.ts` 增加多宫格分镜识别词：
  - `四宫格`
  - `六宫格`
  - `九宫格`
  - `分镜拼图`
  - `分镜图`
  - `镜头图`
- [ ] 在 `lib/ai/auto-agent-graph.ts` 增加 `storyboardGridType` 推断字段
- [ ] 默认规则：
  - 未指定镜头数但目标是视频分镜时，默认建议 `9宫格`
  - 用户明确说 4 段时，使用 `grid_2x2`
  - 用户明确说 6 段时，使用 `grid_3x2`
  - 用户明确说 9 段时，使用 `grid_3x3`

### 1.2 标准分割提示词注入

- [ ] 在 Agent 提示词优化链路里增加“宫格结构化约束注入”
- [ ] 为 `grid_2x2 / grid_3x2 / grid_3x3` 分别维护固定模板
- [ ] 明确禁止跨格、透视倾斜、拼贴边框、编号文字、水印、字幕条
- [ ] 对用户透明提示一句：
  - “我会按标准宫格版式生成，方便系统自动切片”

建议落点：

- `lib/ai/auto-agent-graph.ts`
- `lib/ai/smart-analyzer.ts`
- 如需抽离模板：新增 `lib/video-agent/grid-prompt-templates.ts`

### 1.3 分镜文案归一化

- [ ] 现有 `script-normalizer-skill` 从固定 9 段改为“按 gridType 输出 N 段”
- [ ] 规范输出字段：
  - `gridType`
  - `rows`
  - `cols`
  - `shots`
  - `confirmationRequired`
- [ ] 当镜头不足时，只生成草案，不自动补全并执行视频
- [ ] 当用户后续改某一镜头时，仅更新对应镜头

建议落点：

- `lib/video-agent/skills/script-normalizer.ts`
- `lib/video-agent/types.ts`

### 1.4 用户确认门

- [ ] 增加“确认态回复模板”
- [ ] Agent 输出镜头预览时必须明确提示：
  - 可修改任意镜头
  - 回复“确认开始生成视频”才会真正开始视频
- [ ] 在确认前，Agent 只允许执行：
  - 修改镜头文案
  - 重生单张高清镜头图
  - 重新整理宫格布局
- [ ] 在确认后，才允许发起视频任务调度

建议落点：

- `lib/ai/auto-agent-graph.ts`
- `app/(chat)/api/chat/route.ts`

### 1.5 Agent 模块验收

- [ ] 能正确判断 4/6/9 宫格
- [ ] 生图 prompt 中已自动附加标准结构约束
- [ ] 分镜输出镜头数与宫格数一致
- [ ] 未确认前不会触发视频生成

---

## 2. 数据库开发清单

目标：让“切片图 / 高清镜头图 / 视频结果 / 用户确认状态”全部可持久化、可恢复、可追踪。

### 2.1 主任务表 `VideoStoryboardTask`

当前文件：

- `lib/db/schema.ts`
- `lib/db/migrations/0048_add_video_storyboard_tasks.sql`

需要新增字段：

- [ ] `gridType`：`grid_2x2 | grid_3x2 | grid_3x3`
- [ ] `gridRows`
- [ ] `gridCols`
- [ ] `confirmationStatus`：`draft | awaiting_user_confirmation | confirmed | rejected`
- [ ] `confirmedAt`
- [ ] `confirmedByMessageId`
- [ ] `hdImageStageStatus`：`pending | running | completed | failed`

### 2.2 子任务表 `VideoStoryboardShotTask`

需要新增字段：

- [ ] `sourceTileAssetId`
- [ ] `hdImageUrl`
- [ ] `hdImageAssetId`
- [ ] `hdImagePrompt`
- [ ] `hdImageStatus`：`pending | running | completed | failed`
- [ ] `videoStatus`：`pending | waiting_confirmation | running | completed | failed`
- [ ] `userApproved`
- [ ] `userApprovedAt`
- [ ] `displayOrder`

### 2.3 统一资产挂接

如果要和当前资产图谱方案一致，需要补以下资产类型：

- [ ] `storyboard_tile`
- [ ] `storyboard_hd_image`
- [ ] `storyboard_video`

并保证都能反查：

- `taskId`
- `shotIndex`
- `chatId`
- `canvasNodeId`

建议落点：

- `lib/db/schema.ts`
- `docs/上下文长期记忆-图片目标定位-资产图谱表结构设计.md`
- 如果已有资产表实现，补充对应写入逻辑

### 2.4 查询与状态同步

- [ ] 更新 `lib/video-agent/task-store.ts`
- [ ] 新增高清图阶段的状态更新方法：
  - `markVideoStoryboardShotHdRunning`
  - `markVideoStoryboardShotHdCompleted`
  - `markVideoStoryboardShotHdFailed`
- [ ] 新增确认状态方法：
  - `markVideoStoryboardAwaitingConfirmation`
  - `markVideoStoryboardConfirmed`
  - `markVideoStoryboardRejected`
- [ ] `syncVideoStoryboardTaskStatus` 要能区分：
  - 高清图阶段
  - 等待确认阶段
  - 视频阶段

### 2.5 数据库模块验收

- [ ] 一个任务能同时追踪切片图、高清镜头图、视频结果
- [ ] 系统重启后还能恢复等待确认中的任务
- [ ] 单镜头重生不会破坏主任务顺序

---

## 3. API 开发清单

目标：把“检测切片、高清镜头图生成、确认放行、视频调度”拆成清晰接口，而不是全部压在一个聊天接口里。

### 3.1 配置结构扩展

当前文件：

- `lib/video-agent/config.ts`

需要新增配置：

- [ ] `supportedGridTypes`
- [ ] `enableHdImageStage`
- [ ] `hdImageModelWhitelist`
- [ ] `hdImageConcurrency`
- [ ] `confirmationTimeoutHours`
- [ ] `requireUserConfirmationBeforeVideo`，默认 `true`

### 3.2 新增/改造内部 pipeline

当前骨架：

- `lib/video-agent/pipeline/ruxa-nine-grid-pipeline.ts`

需要改造为更通用的多宫格 pipeline：

- [ ] 输入不再只接受 9 宫格
- [ ] 输出包含 `gridType / totalShots / hdImages`
- [ ] 先做切片，再做高清镜头图，不直接串行发视频
- [ ] 任务结束点从“视频全部完成”改为“进入待确认态”

建议：

- 保留原文件，内部升级
- 或新增 `lib/video-agent/pipeline/storyboard-grid-pipeline.ts`

### 3.3 新增确认接口

建议新增：

- [ ] `POST /api/video/storyboard/tasks/:taskId/confirm`
- [ ] `POST /api/video/storyboard/tasks/:taskId/reject`
- [ ] `PATCH /api/video/storyboard/tasks/:taskId/shots/:shotIndex`
- [ ] `POST /api/video/storyboard/tasks/:taskId/shots/:shotIndex/regenerate-hd`

职责：

- `confirm`：把任务状态切到 `confirmed`
- `reject`：退回 `draft` 或 `rejected`
- `PATCH shot`：更新单镜头文案
- `regenerate-hd`：重生单张高清镜头图

### 3.4 视频调度接口

已有方向：

- admin 查询：`app/api/admin/video-storyboard-tasks/...`
- 重跑：`app/api/admin/video-storyboard-tasks/[taskId]/rerun/route.ts`

需要补充正式业务接口：

- [ ] `POST /api/jobs/video-storyboard-dispatch`
  - 只处理 `confirmationStatus=confirmed` 的任务
- [ ] 调度器读取待执行镜头时，跳过未确认任务
- [ ] 增加“只重跑失败视频镜头”的业务接口

### 3.5 聊天主入口联动

当前聊天入口：

- `app/(chat)/api/chat/route.ts`

这里需要做的不是“直接生成视频”，而是分流：

- [ ] 命中多宫格 storyboard 时，走多宫格 pipeline
- [ ] pipeline 完成高清图阶段后，把确认消息回写到聊天流
- [ ] 用户确认语义命中后，再调用 confirm 接口或内部 confirm 逻辑

### 3.6 API 模块验收

- [ ] 创建任务后能进入 `awaiting_user_confirmation`
- [ ] 用户确认接口触发后才会进入视频调度
- [ ] 单镜头修改和重生高清图都能单独调用

---

## 4. 画布交互开发清单

目标：用户在画布里先看到“有顺序的高清镜头图”，确认后再看到视频结果，整个过程不能乱序。

### 4.1 画布节点阶段化展示

当前相关文件：

- `components/canvas/CanvasChatPanel.tsx`
- `store/canvas/index.ts`
- `types/canvas/index.ts`

当前已有九宫格视频的画布处理偏向直接视频节点，需要改成两阶段：

- [ ] 阶段 A：高清镜头图阶段，创建 `image` 占位节点
- [ ] 阶段 B：视频生成阶段，更新为 `video` 节点或追加视频节点

### 4.2 新增流式事件类型

建议扩展现有 `data-videoStoryboard` 事件：

- [ ] `hd_start`
- [ ] `hd_shot_completed`
- [ ] `hd_shot_failed`
- [ ] `awaiting_confirmation`
- [ ] `confirmation_received`
- [ ] `video_start`
- [ ] `video_shot_completed`
- [ ] `video_shot_failed`

当前 `CanvasChatPanel` 里已有：

- `start`
- `shot_completed`
- `shot_failed`
- `completed`

需要按“高清图阶段”和“视频阶段”拆开。

### 4.3 画布布局规则

- [ ] 4宫格时按 `2x2` 落位
- [ ] 6宫格时按 `3x2` 落位
- [ ] 9宫格时按 `3x3` 落位
- [ ] 高清镜头图和视频节点都保持同一镜头顺序
- [ ] 节点标题要显示：
  - `镜头 1`
  - `镜头 2`
  - `镜头 3`

### 4.4 用户确认交互

建议增加一块轻量确认 UI：

- [ ] 在聊天消息里展示镜头草案确认卡
- [ ] 每个镜头支持：
  - 编辑文案
  - 重新生成高清图
- [ ] 提供总按钮：
  - `确认开始生成视频`
  - `返回修改`

如不做复杂卡片，至少要：

- [ ] 在聊天流里清晰列出镜头 1~N 文案
- [ ] 用户回复确认前，画布只显示高清图，不显示视频进度

### 4.5 画布持久化

- [ ] 高清镜头图节点写入当前 `canvasProject.canvasData`
- [ ] 视频结果节点与镜头图保持可追溯关系
- [ ] 刷新页面后仍能恢复：
  - 哪些镜头已生成高清图
  - 当前是否在等待确认
  - 哪些镜头视频已开始/完成

### 4.6 画布模块验收

- [ ] 画布能先显示镜头静帧，再显示视频
- [ ] 顺序始终稳定，不乱插
- [ ] 用户修改单镜头后，只更新对应节点

---

## 5. 推荐实施阶段

### Phase A：状态机和数据结构

- [ ] 扩表
- [ ] 更新 `task-store`
- [ ] 扩 `types`

### Phase B：多宫格检测与高清镜头图阶段

- [ ] 扩 `nine-grid-detector` 为多宫格 detector
- [ ] 增加 `tile-hd-redraw-skill`
- [ ] pipeline 停在 `awaiting_user_confirmation`

### Phase C：用户确认门

- [ ] 增加 confirm/reject/update-shot API
- [ ] 增加 Agent 确认模板
- [ ] 增加聊天侧确认逻辑

### Phase D：视频调度与画布联动

- [ ] 仅对 confirmed 任务发视频
- [ ] 画布上分阶段展示高清图和视频
- [ ] 单镜头修订和重跑

---

## 6. 重点文件清单

### Agent

- `lib/ai/smart-analyzer.ts`
- `lib/ai/auto-agent-graph.ts`
- `app/(chat)/api/chat/route.ts`

### 数据库

- `lib/db/schema.ts`
- `lib/db/migrations/0048_add_video_storyboard_tasks.sql`
- `lib/video-agent/task-store.ts`

### API / Pipeline

- `lib/video-agent/config.ts`
- `lib/video-agent/types.ts`
- `lib/video-agent/pipeline/ruxa-nine-grid-pipeline.ts`
- `lib/video-agent/skills/nine-grid-detector.ts`
- `lib/video-agent/skills/script-normalizer.ts`
- `lib/video-agent/skills/storyboard-mapper.ts`
- `lib/video-agent/skills/video-sequencer.ts`

### 画布交互

- `components/canvas/CanvasChatPanel.tsx`
- `store/canvas/index.ts`
- `types/canvas/index.ts`

---

## 7. 本轮建议先做什么

如果要最快推进，我建议先开这 5 个子任务：

1. 扩 `schema + task-store`，把 `gridType / confirmationStatus / hdImage*` 字段补齐
2. 扩 `types + detector`，把 9 宫格改成通用多宫格
3. 新增 `tile-hd-redraw-skill`
4. 让 pipeline 停在 `awaiting_user_confirmation`
5. 给聊天流加 `confirm` 放行逻辑

这样做完后，即使视频阶段还没完全改好，用户也已经能看到“多宫格切片 -> 高清镜头图 -> 确认”的完整闭环。