Video Content Analyzer

概述

分析视频内容并生成专业性、逻辑性总结报告。输入一个视频链接或本地视频文件，自动提取字幕/元数据/关键帧，按六大维度框架 + 知识点拆解进行深度分析，输出七主章（含可选章节）极简风格 HTML 报告。

何时使用

当用户出现以下行为时触发：
- 分享视频链接并要求分析、总结、评价
- 发送 B站/抖音/小红书/西瓜视频/YouTube 链接并提问"这个视频讲了什么"
- 直接上传 / 提供本地视频文件（.mp4/.mov/.webm/.mkv/.avi/.m4v/.flv 等）并要求分析、总结
- 因为链接提取失败而改传视频文件，要求分析
- 要求对视频内容做专业评估或逻辑梳理
- 说"分析这个视频"、"帮我总结这个视频"、"看看这个视频"、"分析这个文件"

依赖项

执行前需确保以下工具可用：

检查 ffmpeg：运行 which ffmpeg，如未安装，提示用户运行 brew install ffmpeg。
抖音 / 小红书说明：这两个平台要求前端 JS 生成签名（_signature/a_bogus、小红书 x-s/x-t），yt-dlp 无法生成签名会直接失败。脚本对这两个平台自动改用 Playwright 无头浏览器渲染页面、拦截真实媒体直链（优先使用本机 Chrome，避免强制下载 Chromium），因此首次使用可能下载 Chromium（需联网，约 170MB，国内建议镜像，仅一次）。

工作流

Step 1: 识别输入类型、平台与选择模式

0. 输入类型识别（先做这一步，决定走哪条路）
- 用户提供的是本地视频文件路径（绝对路径、file:// 开头，或对话中附带了视频文件，扩展名为 .mp4/.mov/.webm/.mkv/.avi/.m4v/.flv 等）→ 走「本地文件模式」（--file）。无需任何下载，直接分析，也不要再调用其他规则。
- 用户提供的是视频链接（http/https）→ 走「链接模式」（--url），按下方平台路由。
- 用户因链接失败改传视频文件 → 直接切到本地文件模式，流程连贯，无需外部规则介入。

1. 链接模式：从 URL 识别视频平台（参考 references/platform-guide.md）
2. 选择提取模式：
   - 链接模式
   • 轻量模式（默认）：仅提取字幕 + 元数据，不下载视频。适合 B站有字幕视频、快速概览
   • 完整模式：额外下载视频做关键帧分析。适合抖音/小红书（无字幕需转录）、需视觉分析的场景
   • 本地文件模式（视频已在本地，零下载）
   • 轻量模式：ffmpeg 抽音频 + Whisper 转录，不抽关键帧。最快，适合只要文字总结
   • 完整模式（推荐）：并行抽音频 + 抽关键帧，再做 Whisper 转录。比链接完整模式快很多
3. 判断依据：
   - 本地文件 → 推荐完整模式；只要文字稿用轻量模式
   - B站 → 优先轻量模式（有字幕的概率高）
   - 抖音/小红书 → 自动路由到浏览器提取分支（scripts/extract_browser.py）；完整模式额外下载视频做关键帧 + Whisper 转录
   - 用户明确要求"深度分析"或视频含PPT/图表 → 完整模式
   - 用户未指定 → 链接默认轻量模式（无字幕自动升级）；本地文件默认完整模式

Step 2: 内容提取

运行提取脚本：

> 注意：避免 /tmp 文件名冲突。多个视频并行或连续分析时，固定路径 /tmp/vca_extract.json 可能被覆盖。建议每次使用唯一路径，例如 /tmp/vca_extract_{随机后缀}.json。

# 轻量模式
python scripts/extract_content.py --url "VIDEO_URL" --mode lightweight --output /tmp/vca_extract_$(date +%s).json

# 完整模式
python scripts/extract_content.py --url "VIDEO_URL" --mode full --output /tmp/vca_extract_$(date +%s).json

# —— 本地文件模式（无需下载）——
# 轻量模式（只转录，最快）
python scripts/extract_content.py --file "/path/to/video.mp4" --mode lightweight --output /tmp/vca_extract_$(date +%s).json

# 完整模式（转录 + 关键帧，一条命令顺带产出关键帧 JSON，省去 Step 3 再跑一步）
python scripts/extract_content.py --file "/path/to/video.mp4" --mode full --output /tmp/vca_extract_$(date +%s).json --frames-output /tmp/vca_keyframes_$(date +%s).json

脚本输出 JSON 包含：
- metadata: 视频元数据（标题、频道、时长、播放量等）
- subtitle_text: 字幕全文（来源：native/auto/whisper）
- video_path: 视频文件路径（仅完整模式）
- warnings / errors: 提取过程中的问题

注意：
- 抖音/小红书链接会经 Playwright 浏览器分支提取，输出 JSON 中 extraction_method 为 "browser"；其余平台为 "ytdlp"
- 如 subtitle_text 为 null 且非完整模式，提示用户切换完整模式（需 Whisper 转录）
- 如 errors 中出现「登录墙 / 验证页」「无法安装 Playwright」「未能捕获到视频直链」等，说明该内容被平台拦截：引导用户在本机浏览器登录后重试，或直接上传视频文件交由后续文件上传流程分析
- 如 errors 中有 "Metadata" 错误且非抖音/小红书，检查 URL 是否有效
- 必须先查 quality_check：输出 JSON 含 quality_check.likely_real_video 与 video_size_bytes。抖音偶发「假成功」——流程跑完无 error，但抓到的是 2~3 秒、无音轨的占位片段（如 199KB）。判据：likely_real_video == false 或文件 < 1MB。此时直接原样重试一次（前台、长超时），成功率很高（实测第二次即拿到 39MB 完整视频）。不要一看到失败就让用户换路径。
- Whisper 转录可能较慢（1-5分钟），提前告知用户

Step 3: 关键帧提取（仅完整模式）

• 本地文件完整模式：若 Step 2 已用 --frames-output /tmp/vca_keyframes_<后缀>.json，关键帧已一并提取，本步直接跳过，读取该 JSON 中的 frames[].frame_path 即可。
• 链接模式完整模式（视频已下载到 video_path）：运行关键帧提取：

python scripts/extract_frames.py --video "VIDEO_PATH" --output /tmp/vca_keyframes_$(date +%s) --threshold 0.3

脚本基于 ffmpeg 场景检测在镜头切换点抽帧，输出 JSON 包含每帧路径和时间戳。

提取后，逐帧阅读关键帧图片（使用 Read 工具），识别画面中的 PPT/图表/代码/文字内容。

Step 4: 六维度分析 + 知识点拆解

阅读提取的字幕文本、元数据和关键帧信息后，按六大维度框架进行深度分析，并按下方 schema 补全 knowledge_breakdown（知识点拆解）章节。

加载分析框架：references/analysis-framework.md 包含每个维度的详细分析方法、字段定义和输出格式。

分析重点：
- ③专业深度：调用自身领域知识交叉验证，明确指出知识性错误
- ④逻辑分析：梳理论证结构，识别逻辑谬误和隐含前提

将分析结果组织为以下 JSON 结构（写入 /tmp/vca_analysis_<唯一后缀>.json，避免覆盖其他任务结果）：

{
  "video_url": "原视频链接（从提取结果透传）",
  "metadata": { /* 从提取结果透传 */ },
  "analysis": {
    "tldr": "一句话总结",
    "basic_info": { "video_type": "...", "tags": "..." },
    "content_structure": { "summary": "...", "chapters": [...], "rhythm": "...", "info_density": "..." },
    "professional_depth": { "domain": "...", "accuracy": "...", "terminology": "...", "depth_level": "...", "sources": "..." },
    "logical_analysis": { "argument_structure": "...", "causal_chain": "...", "evidence_sufficiency": "...", "fallacies": [...], "hidden_premises": [...] },
    "value_assessment": { "overall_rating": "X/10", "information_density": "...", "credibility": "...", "timeliness": "...", "originality": "...", "audience_match": "...", "bias": "...", "emotional_tone": "..." },
    "knowledge_breakdown": {
      "summary": "一句话说清这个视频整体上在讲什么（比 tldr 更具体）",
      "points": [
        {
          "name": "知识点名称",
          "timestamp": "02:15（可选，对应字幕中的出现时间）",
          "explanation": "这个知识点到底讲了什么（通俗解释，回答「这是什么」）",
          "example": "视频中给出的具体例子/案例（引用原内容，可选）",
          "takeaway": "一句话记住它（可选）"
        }
      ],
      "quick_ref": [{"no": "01", "name": "...", "point": "一句话核心内容", "timestamp": "02:15"}]
    },
    "actionable_insights": { "key_points": [...], "recommendations": [...], "learning_path": [...], "risks": [...], "use_cases": [...] },
    "keyframe_analysis": { "summary": "...", "frames": [{"timestamp": "...", "description": "..."}] },
    "parallel_concepts": {
      "section_title": "九大定价策略详解",
      "note": "黄色提示框内容，如「第④与第⑦实为同一原理」这类整体性提醒（可选）",
      "items": [
        {
          "name": "策略/概念名称",
          "scenario": "视频中的具体场景（如角色、案例）",
          "application": "该概念在场景中如何被应用",
          "outcome": "产生的结果",
          "principle": "背后的原理机制",
          "academic": "对应的学术概念名称（含提出者/年份，如有）"
        }
      ],
      "quick_ref": [{"no": "①", "name": "...", "academic": "...", "point": "一句话核心要点"}]
    }
  }
}

字段定义和取值参考见 references/analysis-framework.md。

常规章节：knowledge_breakdown（知识点拆解）

必填章节，回答「这个视频到底讲了什么」。渲染结果对应 HTML 中的 第 6 章，位于价值评估之后、行动建议之前——先让读者看懂内容，再告诉读者怎么做。

结构为三层：
- summary：一句话说清视频整体在讲什么（比 tldr 更具体，可点出「围绕 N 个 X 展开」）
- points[]：每个知识点一张卡片：
- name + explanation（必填）：名称 + 通俗解释
- timestamp（可选）：字幕中出现的时间点
- example（可选）：视频原内容里的例子/案例，不是泛泛举例；没有就省略，不要编造
- takeaway（可选）：一句话收口，方便记住
- quick_ref（可选）：全部知识点压缩成速查表（编号 + 名称 + 核心内容 + 时间）

写作要求：拆解的是"内容本身"（讲了什么），与行动建议（该怎么用）严格区分，不要在这里写建议。

可选章节：parallel_concepts（多并列概念详解）

触发条件：视频内容为「N 个 XX」式并列结构（如「9 个定价策略」「10 个思维模型」「5 个沟通技巧」），且每个概念值得单独展开。这类视频六维度分析只能给概览，读者最想要的其实是「这 N 个分别是什么」，必须单独成章。

渲染结果对应 HTML 中的 第 9 章，位于视觉内容分析之后，包含：
- 黄色提示框（note）：整体性问题提醒，如概念重复、分类有误
- 每张概念一张卡片（items）：场景 → 应用 → 结果 → 原理 → 学术对应
- 末尾速查表（quick_ref）：编号 + 名称 + 学术对应 + 一句话要点

写作要求：academic 字段必须给出真实的学术对应概念（如 Anchoring Effect / Tversky & Kahneman 1974），不可编造；若无对应则写「无标准学术命名」。

⚠️ 与 knowledge_breakdown 的互斥规则（必须遵守，防重复）：
- 清单型视频（N 个并列概念，走 parallel_concepts）：parallel_concepts 做逐条深拆；knowledge_breakdown 只写整体认知——points 最多 1~3 条跨概念的共性规律/结构洞察，禁止逐个概念重复罗列。
- 非清单型视频（不满足 parallel_concepts 触发条件）：只填 knowledge_breakdown，parallel_concepts 不填（整个键留空）。
- 判断口诀：「每个概念值得单独一张卡」→ parallel_concepts；「视频讲了几个知识点但要合并讲」→ knowledge_breakdown。

Step 5: 生成 HTML 报告

python scripts/generate_report.py --input /tmp/vca_analysis_<你的后缀>.json --output "OUTPUT_PATH.html"

报告为极简风格 HTML，包含：
- 顶部可点击的原视频链接
- 一句话总结（TL;DR）
- 七大章节：基础信息 → 内容结构 → 专业深度 → 逻辑分析 → 价值评估 → 知识点拆解 → 行动建议
- 视觉内容分析（如有，第 8 章）
- 多并列概念详解（清单型视频，第 9 章）

输出路径：默认保存到用户桌面 ~/Desktop/视频分析报告_<标题简写>.html

Step 6: 呈现结果

1. 在对话中输出简要分析概览（TL;DR + 核心要点 + 综合评分）
2. 使用 present_files 展示生成的 HTML 报告文件
3. 清理本次使用的临时文件（/tmp/vca_extract_<后缀>.json、 /tmp/vca_analysis_<后缀>.json、 /tmp/vca_keyframes_<后缀>/ 等）

异常处理

不触发 / 能力边界

本技能仅做内容分析，不触发以下场景：
- 实时直播流分析（仅处理已发布的点播视频）
- 需要逐帧精细标注的视频剪辑 / 特效制作
- 非视频类内容（纯音频 / 图片 / 文档 / 网页）分析——交给对应专门技能
- 绕过平台付费墙、版权限制或登录鉴权获取受限内容：本技能遵守平台规则，遇到登录墙仅提示用户本机登录后重试或改传本地文件，不尝试破解
- 视频创作 / 剪辑 / 二创生成（本技能只分析已有视频，不生产新视频）

数据安全与隐私

• 本地优先：所有视频下载、音频转录、关键帧提取均在用户本机临时目录完成，不对外上传视频内容
• 浏览器会话隔离：Playwright 使用独立临时用户目录，不读取用户日常浏览器 Cookie / 登录态；提取完成后临时目录可按需清理
• 仅取公开元数据：提取的标题 / 作者 / 互动数均为视频页公开信息，不采集用户私信、账号密码等敏感数据
• 第三方依赖：yt-dlp / Playwright / Whisper 均为开源工具；ffmpeg 为系统二进制。下载行为仅发生在用户明确提供链接后的提取过程
• 合规提示：请仅分析你有权分析的内容（自有视频、已公开授权视频），遵守相关平台服务条款与著作权法

降级与重试机制

• 依赖重试：yt-dlp 下载携带 --retries 3 自动重试；网络抖动导致的单点失败会自愈
• 浏览器回退：Playwright 优先使用本机已装 Chrome（channel="chrome"）；若 Chromium 未下载或下载失败，自动回退本机 Chrome 而非整体放弃
• 媒体兜底：实时媒体直链捕获失败时，回退 yt-dlp 整页下载；两者皆失败则在 errors 中说明，引导上传文件
• 安装回退：PyPI 官方源安装失败时自动回退清华镜像（pypi.tuna.tsinghua.edu.cn）；Chromium 下载建议设 PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright 国内镜像
• 无语音内容：纯音乐 / 舞蹈等无语音视频，Whisper 无法产出有效字幕，报告中注明"该视频无语音内容"，改以元数据 + 关键帧分析

结果校验链路

提取脚本（extract_content.py）在产出 JSON 时附带轻量自检：
- video_path 是否真实存在且时长 > 0（区分"真实正片"与"无声预览"）
- subtitle_text 是否为空或疑似乱码（无语音视频）
- warnings / errors 是否非空（登录墙、安装失败、直链未捕获等）

AI 在 Step 4 分析前应读取上述字段：视频仅为无声预览时提示用户改用上传文件；字幕为空时明确标注"未获取字幕"而非编造；errors 含登录墙时引导本机登录或上传文件。报告生成（generate_report.py）会呈现 warnings / errors 供用户判断提取质量。

常见问题（FAQ）

Q：为什么抖音 / 小红书链接偶尔抓不到？
A：这两个平台有反爬与登录墙，浏览器渲染提取仍可能被拦截。脚本会在 errors 提示，此时最稳的方式是直接上传视频文件（本地模式零下载、零反爬）。

Q：为什么提示要装 ffmpeg？
A：ffmpeg 是系统级音视频工具，无法用 pip 自动安装。macOS 运行 brew install ffmpeg、Linux 运行 apt install ffmpeg、Windows 用官网或 Chocolatey 安装后即可。

Q：Whisper 转录很慢 / 需要联网吗？
A：首次运行会下载模型（约 140MB，仅需一次，国内建议设 HF_ENDPOINT=https://hf-mirror.com 镜像）；转录在本地 CPU 完成，无需联网，但可能耗时 1–5 分钟。

Q：轻量模式和完整模式区别？
A：轻量仅取字幕 + 元数据（适合 B站等有字幕视频）；完整额外下载视频做关键帧视觉分析（适合抖音 / 小红书无字幕、或含 PPT / 图表的视频）。

Q：能分析本地视频吗？
A：能。用 --file 本地模式，无需任何下载，ffmpeg 并行抽音频 + 关键帧，最安全最稳。

资源文件