video-editing-skills

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: video-editing-skills
description:
  提供 vlog 剪辑工作流：使用 analyze_video.py (OpenVINO GenAI) 分析视频、
  生成分镜脚本（storyboard.json）并合成最终视频。
  当用户提供视频目录要求制作 vlog、生成分镜或剪辑脚本，或提及 vlog剪辑、视频剪辑脚本、
  video storyboard、editing script，或需要从 storyboard.json 渲染成片时使用。
---

# 全自动视频剪辑 Agent

AI 驱动的 vlog 剪辑工作流：视频分析 → 分镜脚本生成 → 最终视频合成。

---

## 快速参考

### 关键路径

| 组件 | 路径 | 说明 |
|------|------|------|
| **analyze_video.py** | `<SKILL_DIR>\scripts\analyze_video.py` | 视频分析（OpenVINO GenAI VLM） |
| **prepare_workspace.py** | `<SKILL_DIR>\scripts\prepare_workspace.py` | 工作区准备 |
| **compose_video.py** | `<SKILL_DIR>\scripts\compose_video.py` | 视频合成 |
| **VLM 模型** | `<SKILL_DIR>\models\Qwen2.5-VL-7B-Instruct-int4` | OpenVINO VLM 模型 |
| **ffmpeg / ffprobe** | `<SKILL_DIR>\bin\ffmpeg.exe` | 视频编解码 |
| **BGM 目录** | `<SKILL_DIR>\resource\bgm\` | 背景音乐文件 |
| **BGM 索引** | `<SKILL_DIR>\resource\bgm\bgm_style.json` | BGM 分类元数据（UTF-8-sig 编码） |

### 路径变量（必须准确解析）

| 变量 | 含义 | 示例 |
|------|------|------|
| `<SKILL_DIR>` | 本 SKILL.md 文件所在目录 | 运行时动态解析，见下方伪代码 |
| `<VIDEO_DIR>` | 用户提供的视频目录 | 用户传入的实际路径 |
| `<WORKSPACE_DIR>` | 工作区 = `<VIDEO_DIR>\editing_YYYYMMDD_HHMMSS` | 由 `<VIDEO_DIR>` + 时间戳派生 |
| `<VENV_PYTHON>` | 统一 Python = `<SKILL_DIR>\.venv\Scripts\python.exe` | 由 `<SKILL_DIR>` 派生 |

**解析 `<SKILL_DIR>` 的伪代码：**
```
如果 SKILL.md 位于 X:\path\to\video-editing-skills\SKILL.md
则 <SKILL_DIR> = X:\path\to\video-editing-skills
不是 X:\path\to，不是当前工作目录，不是 git 根目录
```

**时间戳格式 `YYYYMMDD_HHMMSS`：** 年(4位)月(2位)日(2位)\_时(24h,2位)分(2位)秒(2位)。示例：`editing_20260326_143045`

### 命令模板

```bash
# 阶段 0: 平台检查
powershell -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\check_platform.ps1"

# 阶段 1: 准备工作区 + 统一 bootstrap
python "<SKILL_DIR>\scripts\prepare_workspace.py" --video-dir "<VIDEO_DIR>" --user-request "<USER_REQUEST>"

# 阶段 2: 视频分析（始终重新运行）
"<VENV_PYTHON>" "<SKILL_DIR>\scripts\analyze_video.py" --video-dir "<VIDEO_DIR>" --output "<WORKSPACE_DIR>\output_vlm.json" --model-dir "<SKILL_DIR>\models\Qwen2.5-VL-7B-Instruct-int4" --prompt "<PROMPT>"

# 阶段 3: AI 生成 storyboard.json（通过当前代理可用的文件写入工具写入）

# 阶段 4: 合成最终视频
"<VENV_PYTHON>" "<SKILL_DIR>\scripts\compose_video.py" --storyboard "<WORKSPACE_DIR>\storyboard.json"
```

### 环境准备

```bash
python "<SKILL_DIR>\scripts\bootstrap.py"                # 统一准备 .venv / requirements / ffmpeg / 模型
```

---

## 工作流概览

```
阶段 0：平台检查      阶段 1：准备          阶段 2：分析                    阶段 3：创作          阶段 4：合成
┌─────────────────┐  ┌─────────────────┐     ┌─────────────────────────┐    ┌─────────────────┐     ┌─────────────────┐
│ 检测硬件平台    │  │ 验证视频目录    │     │ 运行 analyze_video.py   │    │ 故事大纲        │     │ 时长校验        │
│ 检查宿主Python  │─►│ 创建工作区      │────►│ 验证 output_vlm.json    │───►│ 选择片段+排序   │────►│ compose_video   │
│ [失败→终止]     │  │ 准备 .venv      │     └─────────────────────────┘    │ 旁白/字幕       │     │ 最终时长校验    │
│                 │  │ 安装依赖/资源   │                                  │ BGM + JSON输出  │     └─────────────────┘
└─────────────────┘  └─────────────────┘                                   └─────────────────┘
```

每个阶段必须按顺序执行。前一阶段未通过检查点时，禁止进入下一阶段。

---

## 阶段 0：平台检查（硬性门控）

> **任何 LLM 必须遵守：脚本退出码非 0 时，立即终止全部流程。不询问用户是否继续，直接停止。**

```powershell
powershell -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\check_platform.ps1"
```

| 退出码 | 动作 |
|--------|------|
| `0` | 进入阶段 1 |
| 任何非 0 值 | **立即终止，将错误信息转述给用户** |

** 自检：** 脚本输出包含"所有检查通过"且退出码 = 0

---

## 阶段 1：准备

### 自动化方式（推荐）

```bash
python "<SKILL_DIR>\scripts\prepare_workspace.py" --video-dir "<VIDEO_DIR>" --user-request "<用户原始请求>"
```

脚本最后一行输出工作区绝对路径，后续用作 `<WORKSPACE_DIR>`。阶段 1 会同时：
- 检查 / 创建 `<SKILL_DIR>\.venv`
- 按 `<SKILL_DIR>\requirements.txt` 安装依赖到统一 `.venv`
- 检查 / 下载 `<SKILL_DIR>\bin\ffmpeg.exe` 与 `ffprobe.exe`
- 检查 / 下载 `<SKILL_DIR>\models\Qwen2.5-VL-7B-Instruct-int4`
- 写入 `<WORKSPACE_DIR>\runtime_env.json`

### 手动方式

1. **验证视频目录**：确认目录存在且包含视频文件（`.mp4`/`.mov`/`.avi`/`.mkv`/`.webm`/`.m4v`/`.wmv`）。**仅检查顶层文件，不递归子目录。**
2. **创建工作区**：`<VIDEO_DIR>\editing_YYYYMMDD_HHMMSS`（使用当前本地时间，每次必须新建）
3. **保存用户输入**：写入 `