Skills

video-expert-analyzer

Installation
SKILL.md

Video Expert Analyzer - 视频专家分析工具

基于 Walter Murch 剪辑六法则 和 AI 自动评分系统 的专业视频分析工具。

支持平台

平台 支持状态 说明
Bilibili ✅ 完全支持 yt-dlp 下载 + B站API字幕
YouTube ✅ 完全支持 yt-dlp 下载
抖音 (Douyin) ✅ 完全支持 专用下载器（公开/分享链接无需浏览器 cookie）
小红书 (Xiaohongshu) ✅ 完全支持 专用下载器
其他平台 ⚠️ 可能支持 取决于 yt-dlp 支持情况

核心特性

✅ 真实 AI 视觉评分 - 调用多模态大模型（Gemini 3.0/Kimi 2.5）真实分析画面内容
✅ 双路径评分 - 支持「Agent 模式」（宿主 AI 直接看图）和「API 模式」（远程 API 调用）
✅ 中英双语术语 - 所有专业术语附中文释义
✅ 可配置输出目录 - 首次使用设置，后续自动使用
✅ 精选片段自动复制 - 自动复制到 scenes/best_shots/
✅ 完整分析报告 - 包含理论依据、评分理由、整体评价（非模板）
✅ 动态权重系统 - 根据场景类型自动调整评分权重
✅ 智能文件夹命名 - 以视频标题（自动裁剪）命名输出文件夹，更直观易懂

⚠️ 重要提示：本 skill 的 AI 评分功能需要多模态（视觉理解）模型才能正常工作。
请确保使用 Gemini 3.0、Kimi 2.5 等具备视觉能力的模型来调用此 skill。

模型兼容性

模型 Agent 模式 API 模式 说明
Gemini 3.0 Flash ✅ 推荐 ✅ 推荐 速度快、视觉能力强
Gemini 3.0 Pro ✅ 推荐 ✅ 支持 最强视觉理解
Kimi 2.5 ✅ 支持 ✅ 支持 中文语境优秀
Claude (Sonnet/Opus) ✅ 支持 ❌ 不支持 有视觉能力但无 OpenAI 兼容 API
纯文本模型 ❌ 不可用 ❌ 不可用 无视觉能力，无法评分

Agent 模式 = 在 IDE（Cursor/VS Code/OpenClaw）中，AI 助手直接查看帧图片评分
API 模式 = 在终端 CLI 中，通过 OpenAI 兼容 API 远程调用视觉模型

术语对照表 (Terminology)

五维评分维度 (Five Dimensions)

英文术语 中文释义 详细说明
Aesthetic Beauty 美感 构图(三分法)、光影质感、色彩和谐度
Credibility 可信度 表演自然度、物理逻辑真实感、无出戏感
Impact 冲击力 视觉显著性(Visual Saliency)、动态张力、第一眼吸引力
Memorability 记忆度 独特视觉符号、冯·雷斯托夫效应(Von Restorff Effect)、金句
Fun/Interest 趣味度 参与感、娱乐价值、社交货币(Social Currency)潜力

场景类型 (Scene Types)

类型 中文释义 特点
TYPE-A Hook 钩子/开场型 高冲击力、吸引注意力
TYPE-B Narrative 叙事/情感型 人物对话、情感表达
TYPE-C Aesthetic 氛围/空镜型 风景、慢动作、极简构图
TYPE-D Commercial 商业/展示型 产品特写、广告展示

筛选等级 (Selection Levels)

等级 中文释义 标准
MUST KEEP 强烈推荐保留 加权总分 ≥ 8.5 或 单项 = 10
USABLE 可用素材 7.0 ≤ 加权总分 < 8.5
DISCARD 建议舍弃 加权总分 < 7.0

理论术语 (Theory Terms)

英文 中文 说明
Walter Murch's Six Rules 沃尔特·默奇六法则 情感>故事>节奏>视线追踪>2D平面>3D空间
Von Restorff Effect 冯·雷斯托夫效应 独特的项目更容易被记住
Visual Saliency 视觉显著性 吸引眼球的程度
Social Currency 社交货币 内容被分享的价值
CTA 行动号召 Call to Action
SYNC 节奏同步 画面与音频节拍的契合度

快速开始

第 1 步：数据处理 Pipeline

# 首次配置（只需一次）
python3 scripts/pipeline_enhanced.py --setup

# 分析视频
python3 scripts/pipeline_enhanced.py https://www.bilibili.com/video/BV1xxxxx
python3 scripts/pipeline_enhanced.py "https://www.douyin.com/video/xxxxx"

第 2 步：AI 评分（二选一）

首次使用时，请选择评分模式：

🅰️ Agent 模式（推荐，IDE/OpenClaw/Cursor 用户）

如果你正在 IDE 或 AI 编程助手中使用此 skill，无需配置任何 API Key。 宿主 AI 助手（如 Gemini、Kimi）本身就具备视觉理解能力，可以直接「看图打分」。

流程： 当你（AI 助手）拥有视觉理解能力时，在 pipeline 完成后执行以下步骤：

  1. 统计场景总数：先列出 <output_dir>/frames/ 目录，确定总共有多少个场景帧。这决定了后续分批策略。
  2. 分批查看帧画面：每批 5-10 张帧图片为一个 batch（每批超过 10 张会降低单图分析质量，少于 5 张效率太低）。使用 view_file 工具批量查看 .jpg 文件。
  3. 按以下维度为每个场景打分（1-10 整数）：
    • aesthetic_beauty（美感）：构图、光影、色彩
    • credibility（可信度）：真实感、物理逻辑
    • impact（冲击力）：视觉显著性、第一眼吸引力
    • memorability（记忆度）：独特符号、冯·雷斯托夫效应
    • fun_interest（趣味度）：参与感、娱乐价值
  4. 分类场景类型：TYPE-A Hook / TYPE-B Narrative / TYPE-C Aesthetic / TYPE-D Commercial
  5. 计算加权分并筛选：加权 ≥ 8.5 → MUST KEEP，≥ 7.0 → USABLE，< 7.0 → DISCARD
  6. 将评分结果更新到 scene_scores.json 中每个场景的字段
  7. 将精选片段（MUST KEEP + USABLE）对应的 mp4 复制到 scenes/best_shots/ 并按排名命名
  8. 生成分析报告 <video_id>_complete_analysis.md
⚡ 大规模场景分批处理协议（>10 个场景时启用）

当场景数量超过 10 个时，必须使用分批分析模式。这不是建议，而是硬性要求——因为一次性处理过多场景时，AI 容易因上下文疲劳而跳过、抽样或给出模板化评分，导致分析质量崩塌。

🚫 反抽样声明（Anti-Sampling Policy）

每一个场景都是用户花了真金白银下载和切分的素材。抽样分析意味着用户会错过可能的最佳镜头——想象一下，被跳过的那个场景恰好是整个视频的高光时刻。因此：

  • 禁止抽样、跳过、合并或"代表性选取"任何场景
  • 禁止对未查看的场景给出评分（不看图就打分等于捏造数据）
  • 禁止对多个场景使用相同的描述文字（每个镜头的画面内容不同，描述必然不同）
  • 如果因为上下文限制确实无法继续，应当明确告知用户已完成到哪个场景，让用户决定如何继续，而不是悄悄跳过

分批规则：

  • 每个 batch 包含 5-10 个场景（根据总数均匀划分）
  • 按场景编号顺序处理：Batch 1 = Scene 001-010，Batch 2 = Scene 011-020，以此类推

每个 batch 执行流程：

  1. 使用 view_file 查看本批次所有帧图片
  2. 逐帧分析，每个场景必须包含：
    • 📝 唯一视觉描述（1-2 句）：描述该帧画面中实际看到的具体内容（人物/物体/动作/环境/色调）。这是证明你真正查看了图片的证据——如果描述不出画面内容，说明没有认真看图
    • 🎯 五维评分（1-10 整数）+ 场景类型 + 加权分 + 筛选等级
  3. 立即将本批次评分写入 scene_scores.json
  4. 输出子报告 batch_N_report.md（N = 批次号），包含：
    • 本批次场景编号范围
    • 每个场景的评分摘要表格（含视觉描述列）
    • 本批次 MUST KEEP / USABLE / DISCARD 数量统计
  5. 向用户汇报进度："✅ Batch N/M 完成（场景 XXX-YYY），MUST KEEP: X 个，USABLE: Y 个。继续处理下一批..."

全部 batch 完成后：

  1. 🔍 覆盖率校验（必须执行）：
    • 列出 frames/ 目录中的所有 .jpg 文件数量 = 应分析总数
    • 统计 scene_scores.json 中已有评分的场景数量 = 实际完成数
    • 输出校验结果："覆盖率：实际完成数/应分析总数 = XX%"
    • 覆盖率必须 = 100%。如果不足，列出遗漏的场景编号并补充分析
  2. 汇总所有子报告，生成完整分析报告 <video_id>_complete_analysis.md
  3. 复制精选片段到 scenes/best_shots/
  4. 确认最终报告输出完成后，删除所有 batch_N_report.md 子报告
  5. 向用户输出最终摘要：总场景数、各等级分布、Top 5 精选镜头

🅱️ API 模式（独立 CLI 运行用户）

如果你直接在终端运行脚本，需要配置视觉大模型 API：

# 设置 API 密钥（必需）
export VIDEO_ANALYZER_API_KEY="your-api-key"

# 可选：自定义端点和模型
export VIDEO_ANALYZER_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai"
export VIDEO_ANALYZER_MODEL="gemini-2.0-flash"

# 运行 AI 分析
cd ~/Downloads/video-analysis/<视频文件夹>
python3 <skill_dir>/scripts/ai_analyzer.py scene_scores.json --mode api

工作流程

┌─────────────────────────────────────────────────────────────┐
│                   VIDEO EXPERT ANALYZER v2.0                 │
└─────────────────────────────────────────────────────────────┘

第 1 阶段: 数据处理 (pipeline_enhanced.py)
1. 📥 下载视频              → video.mp4
2. 🎵 提取音频              → video.m4a
3. 🎞️  场景检测 (detect-content) → scenes/*.mp4
4. 🎤 智能字幕提取           → video.srt
   (B站API → 内嵌字幕 → RapidOCR → FunASR 四级降级)
5. 🖼️  帧提取               → frames/*.jpg
6. 📊 生成评分模板          → scene_scores.json

第 2 阶段: AI 视觉评分 (选择一种模式)
┌────────────────────────┬────────────────────────┐
│   🅰️ Agent 模式         │   🅱️ API 模式           │
│   宿主 AI 直接看图评分  │   远程调用视觉大模型    │
│   无需 API Key         │   需要 API Key          │
│   IDE/OpenClaw/Cursor  │   独立 CLI 运行          │
└────────────────────────┴────────────────────────┘
                         ↓
7. 🤖 真实视觉分析评分     → 基于画面内容的真实评分
8. 🧮 动态权重计算         → 根据类型计算加权得分
9. ⭐ 精选镜头筛选         → 复制到 scenes/best_shots/
10. 📄 生成完整报告        → *_complete_analysis.md

分析方法论

Walter Murch 剪辑六法则

情感 Emotion > 故事 Story > 节奏 Rhythm > 视线追踪 Eye-trace > 2D平面 2D Plane > 3D空间 3D Space

一个情感真挚但画面略抖的镜头，优于一个画面完美但内容空洞的镜头。

五维评分体系 (Five-Dimension Scoring)

维度 (Dimension) 基础权重 评估要点
Aesthetic Beauty 美感 20% 构图(三分法)、光影质感、色彩和谐度
Credibility 可信度 20% 表演自然度、物理逻辑、无出戏感
Impact 冲击力 20% 视觉显著性(Visual Saliency)、动态张力
Memorability 记忆度 20% 独特符号(Von Restorff Effect)、金句
Fun/Interest 趣味度 20% 参与感、娱乐价值、社交货币

动态权重系统（根据场景类型自动调整）

类型 (Type) 权重分配 (Weighting) 适用场景 (Application)
TYPE-A Hook IMPACT 40% + MEMORABILITY 30% + SYNC 20% 开场钩子、高能时刻
TYPE-B Narrative CREDIBILITY 40% + MEMORABILITY 30% + AESTHETICS 20% 叙事段落、情感表达
TYPE-C Aesthetic AESTHETICS 50% + SYNC 30% + IMPACT 20% 空镜头、氛围营造
TYPE-D Commercial CREDIBILITY 40% + MEMORABILITY 40% + AESTHETICS 20% 产品展示、商业广告

筛选决策规则

等级 (Level) 中文释义 标准 (Criteria) 用途 (Usage)
🌟 MUST KEEP 强烈推荐保留 加权总分 > 8.5 或 单项 = 10 核心素材，极致长板
📁 USABLE 可用素材 7.0 ≤ 加权总分 < 8.5 过渡素材，辅助叙事
🗑️ DISCARD 建议舍弃 加权总分 < 7.0 或有瑕疵 建议舍弃

输出文件结构

{output_dir}/
└── {video_id}/
    ├── {video_id}.mp4                      # 完整视频 (Full Video)
    ├── {video_id}.m4a                      # 音频文件 (Audio)
    ├── {video_id}.srt                      # 字幕文件 (Subtitles)
    ├── {video_id}_transcript.txt           # 转录文本 (Transcript)
    ├── scene_scores.json                   # 完整评分数据（AI已填写）⭐
    ├── {video_id}_complete_analysis.md     # ⭐ 完整分析报告（中英双语）
    ├── scenes/                             # 场景片段 (Scene Clips)
    │   ├── {video_id}-Scene-001.mp4
    │   ├── {video_id}-Scene-002.mp4
    │   ├── ...
    │   └── best_shots/                     # ⭐ 精选片段（已复制）
    │       ├── 01_USABLE_xxx.mp4
    │       ├── 02_MUST_KEEP_xxx.mp4
    │       └── README.md                   # 双语说明文件
    └── frames/                             # 场景预览帧 (Preview Frames)
        ├── {video_id}-Scene-001.jpg
        └── ...

完整分析报告内容

生成的 *_complete_analysis.md 包含中英双语术语对照：

1. 统计概览 (Statistics Overview)

  • 各等级场景数量统计（带中文释义）
  • 各维度平均分（英文术语 + 中文释义）

2. 场景排名表 (Scene Rankings)

  • 按加权分数排序
  • 显示类型（英文 + 中文）
  • 筛选建议（英文 + 中文）
  • 核心优势

3. 术语对照表 (Terminology Reference)

完整的专业术语中英对照表，包含：

  • 英文术语
  • 中文释义
  • 详细说明

4. 各场景详细评估（每个场景包含）

  • 基础信息: 类型分类（双语）、加权得分、筛选建议（双语）
  • 内容描述: AI 自动生成的场景描述
  • 五维评分表格: | 英文术语 | 中文释义 | 得分 | 权重贡献 |
  • 入选/淘汰理由: AI 生成的理论依据
  • 剪辑建议: AI 生成的使用建议

5. 精选片段推荐 (Best Shots Recommendations)

  • 入选精选文件夹的片段列表（双语）
  • 各类别最佳镜头：
    • 最佳 Hook 候选 (Best Hook Candidate)
    • 最佳视觉 (Best Visual)
    • 最佳可信度 (Best Credibility)
    • 最佳记忆度 (Best Memorability)

6. 整体影片评价 (Overall Assessment)

  • 综合评分
  • 评价结论（双语）
  • 优势分析（各维度详细评价）
  • 改进建议（专业术语 + 中文解释）
  • 使用场景建议（社交媒体/产品展示/品牌宣传/广告投放）

使用示例

基础分析

# 配置输出目录（首次）
python3 scripts/pipeline_enhanced.py --setup

# 分析视频
python3 scripts/pipeline_enhanced.py https://www.bilibili.com/video/BV1xxxxx

# 进入输出目录运行 AI 分析
cd ~/Downloads/video-analysis/BV1xxxxx
python3 <skill_dir>/scripts/ai_analyzer.py scene_scores.json

快速分析（自定义场景检测阈值）

python3 scripts/pipeline_enhanced.py URL --scene-threshold 20

调整精选阈值

python3 scripts/ai_analyzer.py scene_scores.json 6.5  # 阈值 6.5

命令参考

pipeline_enhanced.py

选项 说明
--setup 配置输出目录
-o, --output 指定输出目录
--scene-threshold 场景检测阈值 (默认27)
--best-threshold 精选阈值 (默认7.5)

ai_analyzer.py

参数 说明
scene_scores.json 评分文件路径
--mode api API 模式（需设置 VIDEO_ANALYZER_API_KEY）
--mode agent Agent 模式（生成模板供宿主 AI 填写）
环境变量 说明
VIDEO_ANALYZER_API_KEY 视觉大模型 API 密钥（API 模式必需）
VIDEO_ANALYZER_BASE_URL API 端点（默认 Gemini）
VIDEO_ANALYZER_MODEL 模型名称（默认 gemini-2.0-flash）

依赖要求

# 系统依赖（安装 ffmpeg）
brew install ffmpeg               # macOS
winget install ffmpeg             # Windows
sudo apt install ffmpeg           # Ubuntu/Debian

# 一键安装所有 Python 依赖
pip3 install -r requirements.txt

# 或手动安装核心依赖
pip3 install yt-dlp scenedetect[opencv] requests funasr modelscope torch torchaudio

# 可选依赖
pip3 install openai              # API 模式评分
pip3 install rapidocr-onnxruntime # 烧录字幕 OCR 检测

环境检测

# 一键检测所有依赖是否就绪
python3 scripts/check_environment.py

平台特定说明

抖音视频下载

由于抖音的反爬机制，yt-dlp 无法直接下载抖音视频。本工具集成了专用的抖音下载器，可以：

  • ✅ 自动识别抖音链接（支持 douyin.com 和 v.douyin.com 短链接）
  • ✅ 自动提取视频信息（标题、作者）
  • ✅ 下载无水印视频
  • ✅ 自动提取音频用于转录

支持的抖音链接格式：

  • https://www.douyin.com/video/xxxxx
  • https://www.douyin.com/jingxuan?modal_id=xxxxx
  • https://v.douyin.com/xxxxx (短链接)

抖音下载实现原理：

  1. 使用移动端 User-Agent 访问页面
  2. 从页面 HTML 中提取 RENDER_DATA JSON 数据
  3. 解析视频直链地址（自动替换 playwm 为 play 获取无水印版本）
  4. 使用正确的 Referer 头下载视频

给 Agent 的硬性规则：

  • 处理抖音链接时，不要先尝试网页登录、浏览器 cookie、WSL 读取宿主浏览器 cookie 这条路线
  • 对公开可访问的抖音/分享链接，优先直接运行本地脚本：
    • python3 scripts/pipeline_enhanced.py "<抖音链接>"
    • 或 python3 scripts/download_douyin.py "<抖音链接>" ./video.mp4
  • 如果 Agent 提示“抖音网页版需要登录”或“WSL 无法读取 cookie”，说明它走错路了，应切回本地下载脚本
  • 优先使用用户从抖音 App 复制的分享短链（https://v.douyin.com/...）；长链也支持

Troubleshooting

终端命令卡顿

如果在 IDE 中执行 cp 或 Python 脚本时终端无响应，这通常是 IDE 终端代理的问题。解决方案：

  • 方案 A: 打开 macOS 自带 Terminal.app 手动运行命令
  • 方案 B: 使用 copy_by_index.py 脚本通过 JSON 索引批量复制文件

FunASR 首次下载慢

FunASR 首次运行需下载约 2-3GB 的 Paraformer 模型。如果下载缓慢：

  • 设置镜像: export MODELSCOPE_CACHE=~/.cache/modelscope
  • 或使用 B站 API 字幕（无需本地模型，速度极快）

Agent 模式评分注意事项

  • 必须使用具备视觉能力的多模态模型（参见「模型兼容性」表）
  • 纯文本模型（如 GPT-3.5、Claude Haiku）无法执行 Agent 模式评分
  • 建议每批查看 3-5 张帧图片，避免单次加载过多

抖音链接在 WSL / 远程环境报 cookie 错误

如果 Agent 在 WSL、远程容器或无桌面浏览器环境里说“无法读取抖音链接，因为网页版需要登录且 cookie 读不到”，按下面处理：

  • 不要继续折腾网页登录
  • 直接运行 scripts/pipeline_enhanced.py 或 scripts/download_douyin.py
  • 如果用户给的是长链，优先让用户从抖音 App 重新复制一次分享链接，拿到 v.douyin.com 短链后再跑
  • 只有私密、删除、地区受限或已失效内容，才可能真的无法直接下载

更新日志

v2.2.0 (2026-03-24)

  • ⚡ 大规模场景分批处理协议：>10 个场景时强制分批（5-10个/batch），每批输出子报告 + 进度汇报，全部完成后汇总并清理
  • 🚫 反抽样策略：禁止跳过/合并场景，强制输出唯一视觉描述作为查看证据
  • 🔍 100% 覆盖率校验：完成后校验帧数 vs 已评分数，覆盖率必须 = 100%
  • 📝 重写 description 触发词：增加 8 个中文关键词 + 小红书平台
  • 🌐 补充 Windows/Linux 的 ffmpeg 安装说明
  • 🗑️ 删除过时的 QUICKSTART.md、清理运行日志
  • ⚠️ 模型兼容性发现：Kimi 2.5 在 >30 镜头时出现偷懒行为（疑似服务端工具调用次数限制）；GPT 5.4 可完成 127 镜头连续分析（预热后 11 分 48 秒）；Gemini/Opus 尚未测试

v2.1.0 (2026-02-27)

  • ✅ 智能字幕提取：对齐 video-copy-analyzer，支持 B站API→内嵌→RapidOCR→FunASR 四级降级
  • ✅ 新增小红书支持：集成 xiaohongshu_downloader.py
  • ✅ 新增 requirements.txt：一键安装所有依赖
  • ✅ 新增模型兼容性矩阵：明确不同模型的适用模式
  • ✅ 重写 check_environment.py：检测 v2.1 实际依赖
  • ✅ 清理废弃文件：移除旧版 pipeline、Whisper 转录等6个废弃脚本
  • ✅ 新增 Troubleshooting 章节

v2.0.0 (2026-02-27)

  • ✅ 重写 AI 评分系统：移除假数据模拟，接入真实视觉大模型
  • ✅ 双路径评分：Agent 模式（宿主 AI 直接看图）+ API 模式（远程调用）
  • ✅ 修复场景检测：detect-adaptive → detect-content，镜头切分更精准
  • ✅ 将语音转录引擎从 Whisper 替换为 FunASR (Paraformer-zh)
  • ✅ 中文场景转录速度大幅提升（10分钟音频约22秒完成）
  • ✅ 移除 --whisper-model 参数（FunASR 使用固定 paraformer-zh 模型）
  • ✅ 内置 VAD 自动分段 + 标点恢复

v1.4.0 (2026-02-06)

  • ✅ 新增抖音视频下载支持
  • ✅ 自动识别抖音链接并切换下载方式
  • ✅ 支持抖音短链接和长链接
  • ✅ 自动获取无水印视频

v1.3.0 (2026-02-05)

  • ✅ 新增中英双语术语对照
  • ✅ 所有专业术语附中文释义
  • ✅ 报告中的术语表格双语显示

v1.2.0 (2026-02-05)

  • ✅ 新增 AI 自动分析功能
  • ✅ 动态权重评分系统
  • ✅ 自动生成完整分析报告
  • ✅ 自动复制精选镜头

v1.1.0 (2026-02-05)

  • ✅ 新增可配置输出目录功能
  • ✅ 精选片段自动保存
  • ✅ 生成详细分析报告模板

v1.0.0 (2026-02-05)

  • 初始版本
  • 基础视频分析功能

基于 Walter Murch 剪辑六法则 (Walter Murch's Six Rules of Editing)
AI 自动评分系统 (AI Automatic Scoring System)
动态权重算法 (Dynamic Weighting Algorithm)
中英双语术语对照 (Bilingual Terminology Reference)

Installs
27
Repository
albedo-tabai/vi…analyzer
GitHub Stars
165
First Seen
Mar 10, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn