4.3 KiB
4.3 KiB
Context
爆款视频生成工具当前是一个三步工作流：
- 第 1 步：分析视频，生成结构化
analysis - 第 2 步：基于
analysis+productInfo改编镜头脚本 - 第 3 步：根据镜头脚本生成首尾帧和视频
其中第 3 步已经广泛复用了现有任务队列，但第 1、2 步仍然是组件内直连异步调用。这样做的问题是：
- 没有统一任务态，用户看不到排队/处理中状态
- 页面刷新后分析/改编过程无法恢复
- 失败后没有任务级重试语义
- 历史记录只有“结果”，缺少“可恢复输入”
Goals / Non-Goals
- Goals:
- 让视频分析与脚本改编进入统一任务队列
- 让分析结果和改编结果能在任务完成后稳定回写到
AnalysisRecord - 让历史记录可恢复 YouTube URL 与本地视频输入
- Non-Goals:
- 不将本地视频上传到远端持久化
- 不引入新的云存储或后端 API
- 不重构现有视频生成素材链路
Decisions
Decision: 复用 TaskType.CHAT，通过任务元数据区分视频分析器内部动作
分析和脚本改编本质上都属于文本模型调用，不新增新的 TaskType，继续复用 TaskType.CHAT。
但普通聊天任务与视频分析器内部任务的行为不同，因此在任务参数中增加元数据，例如：
videoAnalyzerAction?: 'analyze' | 'rewrite'
videoAnalyzerRecordId?: string
videoAnalyzerSource?: 'upload' | 'youtube'
这样可以复用现有执行链，同时在 AnalyzePage / ScriptPage 监听任务完成事件，按动作类型回写对应记录。
Decision: 视频分析继续使用专用 video-analyze 工具，而不是强行改造成普通 generate_text
视频分析依赖 google.generateContent 的视频输入能力，既支持 inline_data，也支持 file_uri。
普通 generate_text 目前只覆盖文本 + 图片输入，无法直接承载视频。
因此本变更中：
video-analyze增加queue模式- 入队任务仍使用
TaskType.CHAT - 执行时由任务执行器识别
videoAnalyzerAction === 'analyze'并走专用视频分析链
Decision: 历史输入源分成“轻来源”和“本地缓存来源”
为避免把大体积 base64 直接塞进记录：
- YouTube：持久化原始 URL
- 本地上传：把视频
Blob缓存到本地缓存层，并在记录中仅保存缓存 key、文件名、MIME、大小
建议新增：
type AnalysisSourceSnapshot =
| { type: 'youtube'; youtubeUrl: string }
| {
type: 'upload';
cacheUrl: string;
fileName: string;
mimeType: string;
size: number;
};
分析页重新载入历史记录时：
- YouTube 直接回填输入框
- 本地上传通过缓存 URL 拉回
Blob，重建File，恢复预览和重新分析能力
Decision: 结果回写由页面监听任务事件完成，任务结果本身只存最小必要数据
为避免把完整 analysis 或完整镜头 JSON 既写入任务结果、又写入历史记录导致冗余过大：
- 任务结果可以保留结构化文本或最小 JSON
- 页面在收到完成事件后解析并回写
AnalysisRecord - 本地视频的首尾帧缓存提取仍在分析结果落库后异步进行
Risks / Trade-offs
- 本地视频缓存会占用浏览器本地存储空间
- Mitigation: 只缓存原始视频引用所需数据，不额外复制多份；保留后续清理入口
TaskType.CHAT复用后，任务列表里会出现“分析视频”“改编脚本”这类文本任务- Mitigation: 通过任务标题/提示词前缀/元数据区分，确保用户能识别
- 页面刷新后如果缓存被浏览器清理，本地视频恢复可能失败
- Mitigation: 降级为提示用户原视频不可恢复，但保留分析结果
Migration Plan
- 扩展
AnalysisRecord的输入源快照结构 - 为旧记录补兼容：YouTube 回退到
sourceLabel，上传记录视为“仅显示文件名，不可恢复视频” - 为
video-analyze增加 queue 模式 - 为脚本改编增加基于任务队列的执行入口
- 在分析页/脚本页监听任务完成事件并回写记录
Open Questions
- 任务列表是否需要为视频分析器内部任务显示更明确的标题文案
- 本地视频缓存是否需要在历史删除时同步清理源文件缓存