ai-chatbot/docs/多宫格分镜视频开发清单-2026-03-12.md

多宫格分镜视频开发清单（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 放行逻辑

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