广告视频智能分镜拆解
把一条广告或短视频还原成可复盘、可改写、可继续生成的结构化资产。先检测真实换镜，再结合每个镜头的首尾帧与口播上下文进行视觉分析，最终得到 Excel、Markdown、JSON 和帧图片。
> 它把“看一遍视频”变成一条可复用的生产链：输入视频，自动拆镜头、对齐口播、理解画面，再输出可用于复盘、改写与再生成的结构化资产。
> 真实样例：一条 26.7 秒竖屏广告被拆成 9 个有效镜头。完整结果包含 18 张首尾帧、22 列可视化 Excel，以及每镜头 24 字段的结构化 JSON。
核心价值
- 将“看完视频凭感觉总结”变成逐镜头、带时间码的客观拆解。
- 同时服务广告复盘、竞品研究、脚本改写、角色复刻与 AI 视频再生产。
- 为每个镜头生成中英文图像提示词和视频镜头提示词，可直接交给主流生成模型继续创作。
- 保留结构化 JSON，便于其他 Agent、自动化流程或数据库继续消费。
- 产物默认只写本地文件，企微导出和 BGM 识别必须显式开启；但视觉分析会把每个镜头的首尾帧与对应口播发送到用户配置的模型服务。
快速开始
首次使用时依次执行：
python3 -m pip install -r "{baseDir}/requirements.txt"
cp "{baseDir}/config.example.env" "{baseDir}/.env"
编辑 {baseDir}/.env，至少填写支持图像理解的 OpenAI 兼容模型：
VIDEO_LLM_API_KEY=你的密钥
VIDEO_LLM_BASE_URL=https://你的服务地址/v1
VIDEO_LLM_MODEL=你的视觉模型名称
VIDEO_LLM_API_STYLE=chat-completions
也可使用支持 Responses API 的服务，将 VIDEO_LLM_API_STYLE 设为 responses。不要把 .env 或真实密钥发给别人、写进 SKILL.md 或提交到版本库。
数据发送与隐私
执行默认完整流程前明确告知用户：
- 场景检测、帧提取、文件导出都在本地完成。
- 视觉分析会把每个镜头的两张帧图片以及该镜头口播发送给
VIDEO_LLM_BASE_URL指向的服务。 - 整体总结会把各镜头的画面描述与口播再次发送给同一模型服务。
- 配置火山 ASR 后，会把从原视频提取或转码的完整音频发送给火山引擎语音识别接口。
--wecom会把结构化分镜和首尾帧写入用户已登录的企微环境；默认不启用。
处理客户素材、未公开视频、个人信息或其他敏感内容前，先取得用户对相应第三方处理的确认。用户不允许上传画面时，传 --no-visual；不允许上传音频时，传 --no-asr。两者都关闭时仍可在本地完成场景检测、首尾帧提取和基础分镜导出。
确保系统已安装 ffmpeg 和 ffprobe，然后运行诊断：
python3 "{baseDir}/scripts/doctor.py" --check-api
诊断通过后拆解视频：
python3 "{baseDir}/scripts/breakdown.py" "/path/to/video.mp4" -o "/path/to/output"
如果用户已经提供视频路径，直接创建独立输出目录并执行，不要让用户手动移动视频。完成后返回镜头数以及 Excel、Markdown、JSON、frames 的绝对路径。
可选口播识别
配置火山引擎大模型 ASR 后，会生成逐字时间戳并自动把口播对齐到镜头：
VOLC_ASR_APPID=你的AppID
VOLC_ASR_TOKEN=你的Token
VOLC_ASR_MAX_MB=50
没有 ASR 凭证时安全跳过口播识别，视觉拆解仍可运行。明确不需要口播时可传 --no-asr。
品牌名、人名和行业专有词可能被 ASR 误识别；正式交付或脚本改写前，必须结合画面字幕和原音频人工校对。
输出物
| 输出 | 内容 | 用途 |
|---|---|---|
分镜表.xlsx |
22 列可视化表格，内嵌每个镜头首尾帧；另有总结页 | 团队复盘、投放分析、交付 |
分镜表.md |
可直接阅读的分镜长表、整体总结、ASR 全文 | Agent 阅读、知识库沉淀 |
分镜表.json |
完整 24 字段、视频信息、总结、口播全文 | 自动化、二次开发、数据库导入 |
frames/ |
每个镜头 1 张首帧 + 1 张尾帧 | 视觉复核、故事板、参考图 |
state.json |
各阶段中间状态 | 失败恢复、断点续跑 |
*.asr.json / *.transcript.md |
逐字时间戳和口播全文（配置 ASR 时） | 字幕对齐、文案提取 |
每个镜头包含 24 个字段：
- 基础时间：镜头序号、开始时间、结束时间、时长。
- 画面理解：画面描述、景别、摄影机角度、镜头运动、焦距与景深、主体动作、光线与色调、构图特点、叙事内容。
- 音频与角色：字幕/口播、背景音乐、角色描述。
- 生成提示词：英文/中文图像提示词、英文/中文镜头提示词。
- 首尾帧：首帧描述、尾帧描述、首帧文件、尾帧文件。
真实样例结果
一次 26.7 秒、1080×1920 的竖屏广告实测得到：
- 从 16 个原始切点合并为 9 个叙事镜头。
- 提取 18 张首尾帧，识别 145 字口播并逐镜头对齐。
- 9 个镜头均生成完整 24 字段，没有空字段。
- 同时生成 Excel、Markdown、JSON 和整体广告结构总结。
上图直接截取本次真实运行的前 3 个镜头，展示了时间码、首尾帧、AI 画面理解、逐镜头口播、镜头语言和中文视频生成提示词。其余字段及全部 9 个镜头保存在完整 Excel、Markdown 与 JSON 中。
分阶段执行与恢复
长视频或不稳定网络优先分阶段运行，同一输出目录会保存状态：
python3 "{baseDir}/scripts/breakdown.py" VIDEO -o OUTPUT --phase asr
python3 "{baseDir}/scripts/breakdown.py" VIDEO -o OUTPUT --phase scenes
python3 "{baseDir}/scripts/breakdown.py" VIDEO -o OUTPUT --phase analyze
python3 "{baseDir}/scripts/breakdown.py" VIDEO -o OUTPUT --phase output
必须按 asr → scenes → analyze → output 顺序执行。ASR 未配置时仍可运行 asr 阶段，它会记录跳过状态；也可以直接传 --no-asr 一次跑完。
常用参数
--threshold 35：换镜检测阈值；越低越敏感。--min-duration 2.0：尝试合并短镜头的阈值；受max-merged与镜头顺序约束，不是严格的最短时长保证。--max-merged 5.0：合并后单镜头最长时长。--delay 0.5：镜头之间的模型调用间隔。--no-asr：跳过口播识别。--no-visual：跳过 AI 视觉分析，只生成基础镜头与帧文件。--no-summary：即使已做视觉分析，也不再调用模型生成整体总结。--no-excel：不生成 Excel。--wecom：显式尝试创建企微智能表格；需要另外安装、登录wecom-cli。
可选 BGM 识别
BGM 默认关闭，因为并非所有视觉模型都支持 input_audio。只有确认模型支持音频输入时才配置：
VIDEO_BGM_ENABLED=1
VIDEO_BGM_MODEL=支持音频输入的模型名称
接口不支持或调用失败时自动降级为“未识别”，不影响其余产物。
质量与安全规则
- 先运行
doctor.py，缺少必需依赖或视觉模型配置时不要声称环境可用。 - 不读取、打印或回传任何密钥；日志只能说明某项凭证是否已配置。
- 默认不创建企微文档、不上传原视频、不修改原视频目录。
- 检查最终 JSON 的镜头数、每镜头 24 字段、帧文件数量和 Excel 可打开性。
- 模型分析失败会重试；单镜头最终失败时保留占位数据并标记内部状态，避免整条任务丢失。
- 整体总结失败时使用确定性摘要降级，仍然交付核心分镜文件。
