Video Ads Assistant Lite

# 验证所有依赖
python scripts/check_environment.py

# 或手动检查关键组件
ffmpeg -version
python -c "from funasr import AutoModel; print('FunASR OK')"
python -c "from rapidocr_onnxruntime import RapidOCR; print('RapidOCR OK')"
python -c "import google.generativeai as genai; print('Gemini SDK OK')"

首次使用设置

1. 必须配置 Gemini API 密钥。在项目根目录创建 .env 文件，并写入： GEMINI_API_KEY="AIzaSy..."
2. 确保 assets/templates/template_alias_zh.json 已正确提供并可建立模板映射，同时有相应的 key_sentences.json 及关联视觉参考图配置。

工作流程（8 阶段）

重要：你必须严格按照以下 Stage 0 - 7 顺序执行，每个阶段生成固化的 schema JSON 和目录文件后再进入下一个阶段。绝不允许跨阶段读取未授权文件（详见 INTEGRATION_BOUNDARY）。所有生成资产将被强制存入 runs/<run_id> 下。

阶段 0: 输入与落盘 (Ingest)

目标：拉取/存入素材，锁定唯一基准模板。 输入：用户视频 URL/本地路径，以及从用户对话提取或手工指定的模板名称。 执行步骤：

1. 建立 runs/<run_id> 沙盒目录。
2. （如果为在线）使用 yt-dlp 将文件下载至 runs/<run_id>/raw.mp4；或将本地拷贝过来。如果视频时长 < 30s 阻断执行。
3. 从 template_alias_zh.json 中查询匹配的模板ID，并将绝对映射路径及基础属性锁定，输出成为 template_lock.json。产生 video_meta.json 记录 duration_ms 等媒体属性。

预期输出： ✅ runs/<run_id>/raw.mp4 ✅ runs/<run_id>/template_lock.json ✅ runs/<run_id>/video_meta.json (失败阻断主线并退出)

阶段 1: 全片粗析与广告段定位 (Core Location)

目标：全局建立带有时间锚的听写地图，并定位广告真正发生的核心时间轴 (core 窗)。 执行步骤：

1. 使用 ffmpeg 将全片提纯出音频 runs/<run_id>/raw.aac。
2. 调用 FunASR 实体执行全段 ASR 识别，生成带有绝对 start_ms/end_ms 的 full.srt。所有 ASR 将作为绝对底表禁止在下游重跑。
3. 使用 RapidFuzz token_set_ratio 方法 (>=65分) 比对字幕文件和已锁定的正文模板起始和结尾语句，找出广告发生的精确 core_start_ms 与 core_end_ms。

预期输出： ✅ runs/<run_id>/raw.aac ✅ runs/<run_id>/full.srt ✅ runs/<run_id>/ad_segment.json (无法框选则标记 indeterminate，阻断向下执行除报告外的环节)

阶段 2: 工作区切片 (Work Slicing)

目标：进行前置铺垫扩窗物理截断，生成专供视觉与衔接分析的素材 ad_clip.mp4。 执行步骤：

1. 依据公式计算 work 区间：work_start_ms = max(core_start_ms - 15000, 0)，work_end_ms = core_end_ms。
2. 调用 ffmpeg -ss <XX> -t <YY> -c copy 截取出包含 15 秒前传铺垫的短视频素材。这为流转核心。

预期输出： ✅ runs/<run_id>/ad_clip.mp4 (若失败记入 indeterminate，流转到大模型视觉审核时一并跳过)

阶段 3: 时间锚点精修 (Timing Anchors)

目标：修剪字幕映射范围并定点关键视觉发生句的精确位置。 执行步骤：

1. 从 full.srt 中提取落在 [work_start_ms, work_end_ms] 期间的断句，输出纯前端机器使用的 funasr_align.json。
2. 从 template_lock.json 指向的 key_sentences.json 抽出视觉期望动作特征组。并在 funasr_align 中执行 Fuzzy Match，标注出每个关键动作的物理发生戳 t_start，整合出 key_sentence_timecodes.json。

预期输出： ✅ runs/<run_id>/funasr_align.json ✅ runs/<run_id>/key_sentence_timecodes.json (若无提取锚点则关键画面的 Agent 检查阻断跳过)

阶段 4: 双文本一致性核验 (Text Consistency DIFFs)

目标：严格检查音频侧口播内容与 OCR 提取画面侧内容，是否忠实于源模板文字。本环节音频与OCR可并跑。 执行步骤：

1. [Python Exec] 运行 python scripts/stage04_audio_diff.py <run_dir>。这会生成 audio_diff_raw.json 及 smoothness_features.json。
2. [Agent Task] 读取 assets/prompts/agent_audio.md, 结合 audio_diff_raw.json 的内容进行分析。
3. [Agent Output] 在 <run_dir>/ 下写出 agent_audio_diff_reviewed.json。必须严格参照 assets/schemas/agent_audio_diff_reviewed.json 的结构填充。
4. [Python Exec] 运行 python scripts/stage04_ocr_diff.py <run_dir>。这会生成 subtitle_diff_raw.json。
5. [Agent Task] 读取 assets/prompts/agent_subtitle.md, 结合 subtitle_diff_raw.json 分析字词差异。
6. [Agent Output] 在 <run_dir>/ 下写出 agent_subtitle_diff_reviewed.json。必须严格参照 assets/schemas/agent_subtitle_diff_reviewed.json 的结构填充。

预期输出： ✅ runs/<run_id>/audio_diff_raw.json & agent_audio_diff_reviewed.json ✅ runs/<run_id>/subtitle_diff_raw.json & agent_subtitle_diff_reviewed.json ✅ runs/<run_id>/rapidocr_align.json & smoothness_features.json

阶段 5: 流畅性与衔接 (Fluency & Transitions)

目标：通过多模态感知评测“广告开始铺垫是否自然顺畅”、“口播是否卡顿严重”。 执行步骤：

1. [Python Exec] 运行 python scripts/stage05_fluency.py <run_dir>。这会抽取对应音频片段 ad_clip.aac。
2. [Agent Task] 读取 assets/prompts/agent_fluency.md，将抽取的音频 ad_clip.aac 输入自身的多模态听觉分析能力，结合 funasr_align.json 分析口播质量与衔接过渡。
3. [Agent Output] 在 <run_dir>/ 下写出 agent_fluency.json。必须严格参照 assets/schemas/agent_fluency.json 配置所有字段，包括建议重写或重录动作。

预期输出： ✅ runs/<run_id>/agent_fluency.json

阶段 6: 音画字幕一致性与视觉元素 (Vision & Sync Check)

目标：不仅核对字幕发生时间，同时核查对于模板要求重点表现的镜头物品（如手机、运动鞋等）是否在关键句时间点物理出现。 执行步骤：

1. [Python Exec] 运行 python scripts/stage06_vision.py <run_dir>。脚本会比对生成基础同步报表 ocr_result.json，并在突发关键帧处抽帧输出 frames_index.json 与实体图片至 frames/。
2. [Agent Task - OCR Sync] 读取 assets/prompts/agent_ocr.md，审核刚才脚本生成的 ocr_result.json 对于同句的物理判定是否过度死板，过滤并容差伪问题。
3. [Agent Output - OCR Sync] 写出 agent_ocr_result.json 依照 assets/schemas/agent_ocr_result.json。
4. [Agent Task - Vision] 读取 assets/prompts/agent_vision.md。查看 frames/ 下的所有三连爆发抽帧，并与模板视觉资产对比，判定物体是否实际露面。
5. [Agent Output - Vision] 写出 agent_vision_result.json 依照 assets/schemas/agent_vision_result.json。

预期输出： ✅ runs/<run_id>/frames/*.jpg 及 frames_index.json ✅ runs/<run_id>/ocr_result.json 及 agent_ocr_result.json ✅ runs/<run_id>/agent_vision_result.json

阶段 7: 数据分发与汇总报告 (Reporting Loop)

目标：将所有前置评判数据全部聚合，如果有疑似“违规”和“建议返工”的点位，一并打碎物理切割留证，最终聚合出业务报表面板。 执行步骤：

1. [Python Exec] 运行 python scripts/stage07_report.py <run_dir>。此脚本主要负责切割报错片段并存放至 clips/，生成 clips_tasks.json 与 clips_index.json。
2. [Agent Task] 作为最后的统筹系统，阅读 assets/prompts/agent_master.md，你将读取 Stage 1至 Stage 6 以及 Clips 的所有最终态 JSON 审阅件（凡遇断帧未果，遵由 indeterminate 继承链）。
3. [Agent Output] 结合你卓越的业务分析能力，写出供展示的 report.md 以及底层归档标准物 final.json，还有给技术看的 archive_index.json。参考对应的 schemas 确保没有结构缺失。

预期输出： ✅ runs/<run_id>/clips_tasks.json & clips_index.json ✅ runs/<run_id>/clips/*.aac(mp4) ✅ runs/<run_id>/report.md & final_text.md ✅ runs/<run_id>/final.json & archive_index.json

顶层状态约定 (Verdict Rule)

整个管线流采取最严格容错的 Indeterminate 保护机制：

• 任何通过大模型 LLM 生成的数据遇到超时（Timeout > 30000ms）、接口崩溃、资源熔断时，严禁使用 False/Fail 来直接中断流水线，而是抛出 Indeterminate 状态存放到各业务模块。
• 本项目整体大定调为：当且仅当出现明确的 "fail" 项时，全局被标败（Fail）；如果全是 "pass" 或 "ignore" 则全局过（Pass）；若夹杂了证据不明的 "indeterminate" 但没有任何 "fail"，全局总体继承为 Indeterminate 供终验。

完成后输出样例

完成所有 Stage 后，主控制台应输出日志播报：

✅ 视频广告素材分析全部完成！

📁 输出沙盒目录: runs/202611.../

📄 核心凭证清单:
  - report.md                     (业务核读面板：Markdown 格式总览报告)
  - final.json                    (被机器直接吸收用的标准汇总终态契约)
  - clips/*                       (问题片段自动隔离留存区)
  
🔗 流转下一步: 请打开 report.md 参考处理建议，或将 final.json 脱水传往主数据系统。

功能拓展及维护指南开发说明

我们为所有 Agent/模型设计的所有提示词与交互限制均从脚本内脱离并在 assets/prompts 下统管：

• 音频多词差异收敛: agent_audio.md
• OCR遗漏消噪收敛: agent_subtitle.md
• 录播转结连贯体验: agent_fluency.md
• 音画同步容差过滤: agent_ocr.md
• 爆点视觉抓捕对齐: agent_vision.md
• 全局报表与最终合并: agent_master.md

绝不允许任何开发成员私下把 Prompt 硬编码至 .py 环境逻辑链中。作为 IDE 的内联分析单元 (Agent)，你需要负责亲自读取这些 Markdown, 查阅对应输出 JSON 容器 schemas，结合计算出的物理资产输出判决定级。