video-analysis-workflow

name	video-analysis-workflow
description	本地视频与短视频链接分析工作流。支持抖音、小红书和本地 MP4；自动下载、预处理、分镜、逐镜头视频理解、生成 Word 报告，并支持后台任务调度、失败重试、状态查询、任务控制、镜头截图入报告，以及报告完成后自动通过飞书发送给指定接收人。用于需要长任务异步执行、避免主线程堵塞、并产出结构化视频分析报告的场景。

视频分析工作流

当前主路径已经稳定可用，推荐按 job + dispatcher 模式使用，而不是旧的一体化长进程模式。

核心工作流

1. 提交任务

使用 run.sh submit 提交本地视频或短视频链接。

2. 由 dispatcher 调度

后台 dispatcher 统一调度任务与镜头分析子流程。

3. 逐镜头分析并汇总

工作流会做：

• 下载 / 解析输入
• 预处理视频
• 分镜检测
• 逐镜头分析
• 生成报告和结构化结果

4. 查询、控制与发送结果

支持：

• list / status
• pause / resume / retry-failed / cancel
• 完成后自动飞书发送摘要与 .docx

适用场景

优先用于：

• 需要异步长任务
• 不希望主会话被长分析堵住
• 需要结构化报告、镜头截图、可查询任务状态
• 输入是本地 MP4、抖音链接、小红书链接

Reference routing

Job 生命周期与调度

读 references/job-lifecycle.md，当你需要：

• 理解 submit / dispatcher / scene worker 的主路径
• 排查卡住、重试、暂停恢复等任务控制问题

输入、输出与飞书发送

读 references/inputs-outputs-and-feishu.md，当你需要：

• 确认支持的输入类型
• 理解 job 输出结构
• 解释默认报告交付与飞书自动发送

默认入口

优先使用：

./run.sh submit
./run.sh list
./run.sh status
./run.sh dispatcher

注意事项

• 外部视频理解 API 可能慢或偶发失败，因此默认优先后台任务模式。
• 小红书下载依赖 xhs-auto-import 的下载链路。
• 报告截图来自 scene clip 中间帧，抽图失败通常不阻断整体报告生成。
• 如果只是要一次性快速理解视频内容，而不是完整异步工作流，优先 video-understand。

子代理执行策略

• 子代理适合做预检、参数整理、结果汇总、状态查询。
• 真正的后台任务提交、控制、外部发送与关键执行仍由主流程统一收口。