| name | video-analyze |
| description | 当你需要分析视频内容（抽取关键帧、识别语音）时使用本技能。输出结构化素材，供 Agent 理解视频内容，并可与 content-adapt 配合生成发布文案。 |
| tags | ["Video","Media","ASR"] |
| aliases | ["视频分析","分析视频","抽帧"] |
功能概述
并发提取视频的视觉特征（关键帧截图）和音频特征（语音转文本），输出结构化 JSON，供 Agent 理解视频内容。
| 能力 | 说明 |
|---|
| 自适应关键帧提取 | 根据视频时长自动决定帧数（5–12 帧），均匀分布在 10%–90% 区间，避开片头片尾 |
| 语音转文本 | 使用本地 Whisper tiny 模型（约 75MB），离线运行，无需 API Key |
| 静音检测 | 当视频无音频或 ASR 无结果时，标记 audio_empty: true |
项目路径
VA_DIR=skills/video-analyze/scripts/video-analyzer
环境依赖
| 依赖 | 说明 |
|---|
| Python | >=3.10, <3.13 |
| uv | Python 包管理器；如果系统未安装，在国内服务器上优先使用国内镜像安装 |
| ffmpeg | 提取关键帧、提取音频，必须在系统 PATH 中 |
| ffprobe | 获取视频时长，通常随 ffmpeg 一起安装 |
| torch（CPU-only） | Whisper 所需；国内服务器按镜像优先安装，允许安装到可在 CPU 上运行的 torch 版本 |
| openai-whisper | 本地 Whisper ASR 依赖 |
首次初始化
本技能在你的项目中默认用于普通服务器 / 无 GPU 场景。国内服务器要求所有 uv 相关依赖优先走国内镜像，包括 uv sync、torch、openai-whisper。
推荐流程：
- 如果系统没有
uv，先安装它；国内服务器优先用国内镜像，例如：
sudo apt install -y pipx
PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple pipx install uv
- 先明确判断服务器区域，不要凭主机名、云厂商品牌或主观感觉猜测
domestic / overseas
- 明确在中国大陆机房 / 中国大陆网络环境 →
domestic
- 明确在海外机房（例如新加坡、日本、美国等）→
overseas
- 如果不确定，再使用
uv run va doctor --region auto 观察 CLI 自动判断结果，必要时由用户明确指定
- 国内服务器先执行
UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv run va doctor --region domestic；国外服务器执行 uv run va doctor --region overseas
- 如果 Python 依赖或模型缺失，再执行
uv run va bootstrap --region <domestic|overseas>
- 如果
ffmpeg 缺失，Agent 可直接用无密码 sudo 安装，然后重新执行 bootstrap
国内服务器推荐初始化
cd skills/video-analyze/scripts/video-analyzer
UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv run va doctor --region domestic
uv run va bootstrap --region domestic
国外服务器推荐初始化
cd skills/video-analyze/scripts/video-analyzer
uv run va doctor --region overseas
uv run va bootstrap --region overseas
bootstrap 内部固定执行内容
1. domestic：`UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv sync`
2. overseas：`uv sync`
3. domestic：`uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple torch`
4. overseas：`uv pip install --index-url https://download.pytorch.org/whl/cpu torch`
5. domestic：`uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple openai-whisper`
6. overseas：`uv pip install openai-whisper`
7. uv run va setup
说明：
- 国内服务器执行
uv sync 时，优先通过 UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple 使用国内镜像
- 历史上常见问题是：只给
pipx install uv 配了国内镜像，但 uv sync 仍然走默认 pypi.org，导致重依赖下载很慢；因此这里必须同时显式配置 uv sync 的镜像源
- 国内服务器要求
uv 及其后续依赖安装统一镜像优先，包含 torch 与 openai-whisper
uv sync 现在应该是快的，因为重依赖不再隐式装入- 如果国内镜像安装出的
torch 可在 CPU 上正常运行，则视为可接受结果
- 国内机器普通 Python 包优先镜像源，国外机器保持官方源优先
⛔ 在 bootstrap 结束前，不要执行 va extract
⛔ uv run va setup 只需执行一次，模型下载后会被缓存复用
区域判断规则（高优先级）
Agent 在执行 va doctor / va bootstrap 前，必须先判断当前服务器属于 domestic 还是 overseas。
判断原则：
- 优先看服务器实际地理区域 / 网络区域，不要看主机名风格
- 阿里云、腾讯云、AWS、GCP 等厂商都可能同时有国内和海外机房
- 例如：阿里云新加坡服务器属于
overseas，不能因为看起来像阿里云机器就误判为 domestic
- 不要凭主机名、实例 ID、运维命名习惯做主观判断
- 如果用户已经明确说了机器区域，优先使用用户给出的区域信息
- 如果不确定，优先使用
--region auto 让 CLI 按时区 / 语言环境做自动判断，再根据实际情况确认
推荐规则：
- 中国大陆机器 →
domestic
- 新加坡 / 日本 / 美国 / 欧洲等海外机器 →
overseas
⛔ 错误选择 region 会导致后续依赖安装链路全部走错源。
ffmpeg 检查
uv run va doctor 会直接报告 ffmpeg 和 ffprobe 是否存在。
如果你只是想手动检查，也可以执行：
which ffmpeg && echo "OK" || echo "NOT FOUND"
which ffprobe && echo "OK" || echo "NOT FOUND"
如果缺失，Agent 可直接执行：
sudo apt install -y ffmpeg
ASR 说明
- 使用本地 Whisper tiny 模型
- 离线运行，不依赖外部 ASR API
- 国内服务器默认镜像优先安装依赖
torch 只要能在当前机器上正常完成转写流程即可
命令约定
环境诊断
uv run va doctor [--region domestic|overseas]
输出 JSON，主要关注：
ffmpegffprobeuvtorch_installedtorch_versiontorch_cuda_availablewhisper_installedwhisper_model_ready
环境初始化
uv run va bootstrap --region domestic
uv run va bootstrap --region overseas
提取与分析
uv run va extract --file <视频绝对路径> [--output-dir <输出目录>] [--language zh]
| 参数 | 是否必需 | 说明 |
|---|
--file | 是 | 视频文件绝对路径 |
--output-dir | 否 | 关键帧输出目录，默认自动创建临时目录 |
--language | 否 | ASR 语言代码，默认 zh |
输出示例（stdout，JSON）：
{
"frames": [
"/tmp/va_frames_xxx/frame_01_10pct.jpg",
"/tmp/va_frames_xxx/frame_02_30pct.jpg",
"/tmp/va_frames_xxx/frame_03_50pct.jpg",
"/tmp/va_frames_xxx/frame_04_70pct.jpg",
"/tmp/va_frames_xxx/frame_05_90pct.jpg"
],
"transcript": "这里是识别出的语音文本...",
"duration": 45.2,
"audio_empty": false
}
Agent 工作流
本技能只负责：
- 检查环境
- 初始化分析环境
- 提取关键帧
- 识别语音
- 输出结构化结果
后续如何生成平台文案、是否上传、何时清理临时文件，由其他技能和上层流程决定。
执行步骤
第 0 步：先检查环境
cd skills/video-analyze/scripts/video-analyzer
uv run va doctor --region auto
判断方式：
- 先看
region 字段；如果 CLI 已判断出 domestic / overseas，默认按该结果继续
- 如果你已明确知道服务器区域（例如新加坡阿里云），则直接使用该实际区域，不要因为主机名像国内云厂商而误判
ffmpeg: false → 先执行 sudo apt install -y ffmpegtorch_installed: false / whisper_installed: false / whisper_model_ready: false → 执行 uv run va bootstrap --region <domestic|overseas>torch_cuda_available: true → 对当前项目来说不一定是错误；只要后续转写流程可正常运行即可
第 1 步：执行提取命令
cd skills/video-analyze/scripts/video-analyzer
uv run va extract --file <视频路径>
第 2 步：解析输出
命令标准输出是 JSON，核心字段：
frames：关键帧图片路径列表transcript：识别出的语音文本（可能为空）duration：视频时长（秒）audio_empty：是否无音频或无有效语音
第 3 步：查看关键帧
使用图片读取能力查看关键帧，理解视频视觉内容。
如果帧数较多，可挑几张代表性图片重点分析。
第 4 步：分析视频内容
必须先做场景分类，再做细节分析。
4a. 场景分类
先回答：这个视频属于什么类型？
常见类型：
- 商业广告 / 产品推广
- 教程 / 操作演示
- 生活记录 / Vlog
- 知识分享 / 对镜表达
- 其他
分类标准以画面主体、出现频率、占比、文本信息为主。
4b. 主体识别
在已确定场景的前提下，区分：
不要把背景插画、转场动画、偶发元素误判成视频主体。
4c. 音频判断
audio_empty = true → 纯视觉分析audio_empty = false 但文本明显是歌词 / BGM → 忽略音频，仅按视觉分析audio_empty = false 且是正常旁白 → 视觉 + 音频结合分析
4d. 输出一句话总结
输出格式建议：
[场景类型]：知识分享
[视频主体]：围绕考研规划收费问题展开，核心观点是低成本也能讲清逻辑，不必迷信高价辅导
[音频]：正常旁白
[忽略噪音]：背景装饰、转场动画
这个总结将作为 content-adapt 的输入。
临时文件
关键帧会输出到 --output-dir 指定目录，或系统临时目录。
何时清理由调用方决定。
rm -rf /tmp/va_frames_xxx/
⛔ 在用户确认发布信息之前，不要提前删除临时帧图。用户可能要求重新分析或调整。
故障排查
| 现象 | 原因 | 处理方式 |
|---|
uv: command not found | 系统未安装 uv | 国内服务器优先执行 sudo apt install -y pipx && PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple pipx install uv，然后回到标准 bootstrap 流程 |
ffmpeg not found | 系统未安装 ffmpeg | 直接执行 sudo apt install -y ffmpeg |
Cannot determine video duration | ffprobe 不可用或视频损坏 | 检查 ffprobe 是否存在；检查视频是否可播放 |
whisper 模块不存在 | openai-whisper 未安装 | 先 uv run va doctor，再执行 `uv run va bootstrap --region <domestic |
| Whisper 模型下载卡住 | 网络问题 | 重试 uv run va setup，必要时重新执行 bootstrap |
torch 国内镜像安装失败 | 镜像缺包、同步延迟或网络异常 | 可重试国内镜像；若仍失败，再根据实际环境决定是否临时改用其他源 |
ASR failed (non-fatal) | Whisper 或 torch 未正确安装 | 先 uv run va doctor，必要时重新执行 bootstrap |
安装过程中出现 triton / CUDA 大包 | 镜像解析到了不同 torch 变体 | 只要当前机器上转写可正常运行即可；若影响安装稳定性，再调整镜像策略 |
| 抽帧失败 | ffmpeg 解码失败 | 视频编码可能不兼容，建议转成 mp4 (H.264) 再试 |
降级策略
| 不可用项 | 影响 | 降级方式 |
|---|
| Whisper 不可用 | 无法转写语音 | CLI 输出 setup guide，并将 audio_empty: true，只做视觉分析 |
| ffmpeg 不可用 | 无法抽帧 | 无法降级，先安装 ffmpeg |
| ffprobe 不可用 | 无法获取时长 | 降级为固定抽取 5 帧 |
| 视频文件本身损坏 | 无法分析 | 停止分析并提示用户转码或更换文件 |
上下游数据约定
输入
| 字段 | 来源 | 说明 |
|---|
| 视频文件路径 | 用户提供 | 必须是绝对路径 |
| language | 可选 | ASR 语言代码，默认 zh |
输出
本技能结束后，Agent 至少应掌握以下数据，并可直接传给 content-adapt：
{
"frames": ["<关键帧绝对路径1>", "<关键帧绝对路径2>", "..."],
"transcript": "<ASR 文本，可为空>",
"duration": 45.2,
"audio_empty": false,
"scene_type": "<commercial_ad|tutorial|lifestyle|knowledge_sharing|other>",
"summary": "<Agent 对视频内容的一句话总结>"
}
其中：
frames / transcript / duration / audio_empty 由脚本输出scene_type / summary 由 Agent 根据分析结果补充
