Video Editing Skills

全自动视频剪辑 Agent

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

---

快速参考

关键路径

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

解析 `<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

命令模板

# 阶段 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"

环境准备

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 -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\check_platform.ps1"

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

---

阶段 1：准备

自动化方式（推荐）

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. 保存用户输入：写入 <WORKSPACE_DIR>\user_input.txt 4. 提取需求：

规则： 如果用户提供了 theme/mood/pacing/must_capture 中的任何一个，就使用需求驱动的提示词模板。全部未提供时使用默认提示词。

5. 准备统一运行时：创建 .venv 并安装 requirements，确认 ffmpeg.exe / ffprobe.exe 存在，确认模型目录完整有效 6. 写入运行时清单：写入 <WORKSPACE_DIR>\runtime_env.json，后续阶段优先参考其中的 venv_python / ffmpeg / ffprobe / model_dir

自检： 工作区目录已创建 视频文件 ≥ 1 .venv 已就绪 ffmpeg.exe / ffprobe.exe 存在 模型目录完整 runtime_env.json 已写入

---

阶段 2：分析

快速模式判断

检查 <VIDEO_DIR>\output_vlm.json 是否存在：

• 存在 → 用户明确提供了已分析结果，跳过阶段 2，直接复制到 <WORKSPACE_DIR>\output_vlm.json 并进入阶段 3
• 不存在 → 执行下方完整分析流程

快速模式用于避免重复 VLM 分析（耗时较长）。用户必须自行确保该 JSON 与当前视频目录匹配。

步骤 2.1 确认阶段 1 已完成

确认 <WORKSPACE_DIR> 已存在、.venv 已就绪、模型目录完整。若阶段 1 未执行，必须返回阶段 1。

步骤 2.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>"

默认提示词：

准确的描述这个视频片段中的主要内容，包括：场景环境、人物动作、画面构图、光线氛围、运镜方式。输出不超过100字的简要描述。

需求驱动的提示词模板（用户指定了任何 theme/mood/pacing/must_capture 时使用）：

请根据以下剪辑目标分析视频片段：主题是「<THEME>」，氛围是「<MOOD>」，节奏要求「<PACING>」。重点捕捉与「<MUST_CAPTURE>」相关的画面线索。描述中必须包含：场景环境、人物动作、画面构图、光线氛围、运镜方式，并突出与目标风格相关的信息。输出不超过100字。

步骤 2.3 验证输出

读取 <WORKSPACE_DIR>\output_vlm.json，确认非空且含 processed_videos[].segments[] 数据。

output_vlm.json 格式：

{
  "processed_videos": [{
    "input_video": "<VIDEO_DIR>\\video01.mp4",
    "segments": [{
      "seg_id": 0,
      "seg_start": 0.0,
      "seg_end": 3.0,
      "seg_dur": 3.0,
      "seg_desc": "AI生成的内容描述..."
    }]
  }]
}

自检： output_vlm.json 文件大小 > 0 processed_videos 数组非空 每个视频有 segments

---

阶段 3：创作

核心理念：叙事先行。 先从素材中发现故事，再用字幕构建完整叙事，最后为每一句叙事匹配画面。

字幕文案是视频的灵魂和主线——不是给画面"配字"，而是先写好一段完整的故事，再用画面去"演"这个故事。

步骤 3.1 素材审阅与故事发现

目标：通读全部 VLM 分析结果，理解素材全貌，找到隐藏在素材中的"故事"。

1. 通读与分类

逐条阅读 output_vlm.json 中每个视频每个段的 seg_desc，将片段归入以下类别：

同时过滤低质量片段：跳过 seg_desc 内容重复（VLM 循环输出）、过于简短（< 10 字）或无实质信息的片段。

2. 提炼故事主线

问自己三个问题：

• 这些素材讲的是什么体验？（一次旅行？一次聚会？一个日常？）
• 这段体验中最打动人的瞬间是哪几个 seg_desc？
• 如果用一句话概括这个 vlog，那句话是什么？

3. 确定叙事角度

从以下角度中选择最匹配素材内容的一种：

4. 规划情感弧线

确定情感走向：从什么情绪出发 → 经历什么变化 → 落在什么情绪上。 例如：好奇/期待 → 兴奋/沉浸 → 感悟/平静

输出：一句话主题 + 叙事角度 + 情感弧线（如：主题"公路尽头的答案" / 自由释放 / 好奇→沉浸→领悟）

---

步骤 3.2 叙事脚本与画面匹配

先写完整的字幕文案，再为每句话选画面。 这是本流程最核心的步骤。

3.2.1 规划叙事节拍

根据目标时长和节奏（默认每片段约 3s），确定总片段数，然后按以下节拍分配。

计算片段数时须考虑转场折损：相邻片段间有约 0.8s 转场重叠，每个片段的有效时长 ≈ seg_duration - transition_duration（即 3 - 0.8 = 2.2s）。 片段数 ≈ target / 有效时长，例如 30s 目标 ≈ 30 / 2.2 ≈ 14 个片段（不必精确，接近即可）。

3.2.2 一气呵成写出全部字幕

按节拍表写出所有片段的字幕文案，核心要求：

• 完整叙事：所有字幕连续读起来必须是一段有头有尾、有情感弧线的完整独白
• 每条 ≤ 15 字（中文），第一人称
• 绝不描述画面（观众自己能看到画面，字幕要说的是画面背后的感受和想法）
• 前后衔接：相邻两条字幕之间必须有逻辑连接或情绪递进，不能各说各话
• 不重复：同一个意思不要用不同的话说两遍

字幕质量自检（写完后必须执行）：

1. 把所有字幕按顺序连起来读——脱离画面是否仍然是一段有意义的叙述？ 2. 能否感受到情感从起点到终点的变化弧线？ 3. 第一句是否引发好奇或制造悬念？最后一句是否留有余韵？ 4. 有没有任何一句在直白描述画面内容？（如有，必须重写） 5. 有没有两句字幕表达了相同的意思？（如有，删除或改写其中一句）

示例——同一组摩旅素材的好与坏：

差的字幕（各说各话，没有故事）：

"出发，向着远方" → "风从耳边呼啸而过" → "山川湖海皆是风景"
→ "心之所向" → "阳光洒在山路上" → "此刻什么都不想"
→ "路在脚下" → "出发就是自由" → "风景在眼前流转"
→ "这就是生活" → "下一站更远的地方"

问题：前后不连贯，"出发""自由""风景"各重复两次，#5 在描述画面，整体像一堆随机拼凑的鸡汤。

好的字幕（完整叙事，有弧线）：

"一直想知道 公路尽头是什么"          ← 开篇：好奇，抛出悬念
"今天终于骑上了车"                   ← 铺陈：出发
"引擎声代替了闹钟"                   ← 铺陈：进入体验
"两旁的树 拼命往后退"                ← 递进：速度感
"风很大 什么都听不见"                ← 递进：沉浸
"但脑子从来没这么安静过"              ← 递进→转折：核心感悟
"远处那座山 越来越近了"               ← 递进：接近高潮
"原来只要一直往前 就真的能到"          ← 高潮：领悟
"停下来的时候 天已经变色了"            ← 收尾：时间流逝
"公路没有尽头 但每一段都值得"          ← 结尾：呼应开篇，升华

特点：连续读就是一个完整故事（好奇→出发→沉浸→领悟→感慨），每句都在推进叙事，没有重复。

3.2.3 为每句字幕匹配最佳片段

对每一条字幕，从 output_vlm.json 的可用片段中选择 seg_desc 意境最匹配的片段：

匹配原则：

• 字幕和画面互补而非重复——字幕说感受，画面给证据
• 同一 (source_video, source_segment_id) 不可复用
• 优先选 seg_desc 内容丰富的片段，跳过内容贫乏或重复的片段
• source_segment_id 必须是 output_vlm.json 中对应视频的有效 seg_id
• in_point = 该 seg_id 的 seg_start，out_point = seg_end，duration = out_point - in_point

画面节奏：

• 避免连续 3+ 个 seg_desc 描述同类场景的片段
• 动态描述与静态描述的片段交替排列
• 片段时长：最短 ≥ 1.5s，最长 ≤ 目标时长的 25%

---

步骤 3.3 整体审视与迭代

这一步决定成片质量。 把字幕+片段作为一个整体审视，发现问题就回到 3.2 调整。

审视维度

1. 叙事连贯性：按 sequence_order 读所有字幕——有没有断裂感？相邻字幕情感跳跃是否过大？如有断裂，插入过渡性的字幕+片段。

2. 画面节奏：连续片段的 seg_desc 是否单调？是否有动静交替？如果连续多个都是同类场景，调换顺序或替换片段。

3. 字幕-画面一致性：每条字幕的情绪基调是否与对应 seg_desc 描述的场景氛围方向一致？（不要求完全匹配，但不能明显矛盾，如字幕说"安静"而画面是激烈运动）

4. 开头和结尾质量：开头片段的 seg_desc 是否有吸引力？结尾片段是否适合收束？这两个位置最重要，如不理想优先替换。

如果发现问题：回到 3.2.2 调整字幕文案或 3.2.3 重新匹配片段，然后再次审视。通常迭代 1-2 轮即可。

步骤 3.4 BGM 选择

必须选择恰好一首 BGM，使用绝对路径。

步骤： 1. 读取 <SKILL_DIR>\resource\bgm\bgm_style.json（注意编码是 UTF-8-sig） 2. 根据下表匹配分类，选择该分类中的一首曲目 3. 构建绝对路径：<SKILL_DIR>\resource\bgm\<file_path>

当前 BGM 库覆盖 3 个分类（舒缓优美 1 首、温馨浪漫 2 首、轻松愉悦 7 首）：

BGM 音频行为（compose_video.py 自动处理）：

• BGM 循环播放至视频结束，自动淡入 1s + 淡出 1.5s
• 如原视频含音频（人声/环境音），自动混合保留
• BGM 通过 amix 与原视频音频混合

无匹配时回退：首选分类无合适曲目 → 查备选分类 → 仍无 → 任选一首

步骤 3.5 转场效果选择

为每个片段（除最后一个）选择到下一个片段的转场效果。转场应自然流畅，不生硬突兀。

可用转场类型：

按叙事位置选择转场：

规则：

• 默认 transition.duration = 0.8 秒
• 80%+ 片段使用 fade，其余可用 fadeblack/smooth* 偶尔点缀
• dissolve 尽量少用（效果不够自然）
• smooth* 仅在镜头有方向运动时使用
• circle* 整个视频最多 1-2 次
• 最后一个片段不加转场（无后续片段）
• 注意：转场会使总时长缩短（每个 0.8s 转场减少 0.8s 总时长）

步骤 3.6 输出 storyboard.json

始终重新生成，绝不复用。 写入 <WORKSPACE_DIR>\storyboard.json。

完整 Schema：

{
  "storyboard_metadata": {
    "theme": "摩旅自由行",
    "target_duration_seconds": 30
  },
  "clips": [
    {
      "clip_id": 1,
      "sequence_order": 1,
      "source_video": "<VIDEO_DIR>\\test(01).mp4",
      "source_segment_id": 0,
      "timecode": {
        "in_point": 0.0,
        "out_point": 3.0,
        "duration": 3.0
      },
      "voiceover": {
        "text": "风从耳边呼啸而过"
      },
      "transition": {
        "type": "fade",
        "duration": 0.8
      }
    },
    {
      "clip_id": 2,
      "sequence_order": 2,
      "source_video": "<VIDEO_DIR>\\test(00).mp4",
      "source_segment_id": 3,
      "timecode": {
        "in_point": 9.0,
        "out_point": 12.0,
        "duration": 3.0
      },
      "voiceover": {
        "text": "这一刻什么都不想"
      }
    }
  ],
  "audio_design": {
    "background_music": {
      "file_path": "<SKILL_DIR>\\resource\\bgm\\xxx.mp3",
      "style_tag": "舒缓优美"
    }
  }
}

字段说明：

• clip_id：唯一整数，从 1 开始递增
• sequence_order：播放顺序，从 1 开始递增
• source_video：绝对路径，Windows 反斜杠 \\
• source_segment_id：对应 output_vlm.json 中该视频的 segments[N].seg_id
• in_point：该 seg_id 的 seg_start 值
• out_point：该 seg_id 的 seg_end 值
• duration：必须等于 out_point - in_point，且 > 0
• voiceover.text：字幕文本，每个片段必须有字幕（不可为空）
• transition.type：转场类型（见上表），最后一个片段省略此字段
• transition.duration：转场时长，默认 0.8 秒
• file_path：BGM 的绝对路径

写入前必须验证

1. theme、target_duration_seconds 两个必需字段存在 2. 每个 clip：out_point > in_point 且 duration == out_point - in_point 且 duration > 0 3. 每个 source_video 路径指向 <VIDEO_DIR> 中实际存在的文件 4. 每个 source_segment_id 在 output_vlm.json 对应视频的 seg_id 范围内 5. 无重复的 (source_video, source_segment_id) 组合 6. 每个 clip 的 voiceover.text 非空（每个片段必须有字幕） 7. 所有字幕连续读起来是一段完整连贯的叙事（非独立的散句） 8. file_path 是绝对路径且 BGM 文件存在 9. transition.type 必须是上表中的有效值 10. 最后一个片段不含 transition 11. 粗略估算实际输出时长是否与 target 大致匹配（实际时长 ≈ sum(durations) - 转场重叠总量，偏差合理即可）

实际输出时长计算：sum(clip durations) - sum(有转场的片段的 transition.duration) 即：逐个累加每个片段的 duration，再减去除最后一个片段外所有设置了 transition 的片段的 transition.duration。 例如：14 个 3s 片段 + 13 个 0.8s 转场 → 42 - 10.4 = 31.6s ≈ 30s

注意：compose_video.py 在运行时会自动将转场时长限制为相邻两个片段中较短者的一半。

如果某个转场 duration 超过此限制，实际时长会比上述公式计算值略长。

时长偏差参考：如果实际输出时长与 target 差距较大，可考虑：

• 总时长偏长 → 酌情移除叙事贡献较低的片段
• 总时长偏短 → 酌情添加与叙事匹配的新片段

自检： 11 项验证全部通过 storyboard.json 已写入

---

阶段 4：合成

步骤 4.0 时长粗检

重新读取 storyboard.json 粗略估算片段总时长，确认与 target 大致匹配。如差距明显，可回到步骤 3.6 酌情调整。

粗算公式：actual ≈ sum(clip durations) - sum(transition durations)，与 target 对比即可。

步骤 4.1 运行合成

"<VENV_PYTHON>" "<SKILL_DIR>\scripts\compose_video.py" --storyboard "<WORKSPACE_DIR>\storyboard.json"

输出文件： <WORKSPACE_DIR>\<theme>_<duration>s_bgm.mp4 例如：摩旅自由行_30s_bgm.mp4

合成失败时：先加 --dry-run 检查生成的 ffmpeg 命令，确认路径和参数正确。

步骤 4.2 最终时长校验

用 ffprobe 测量实际视频时长：

"<SKILL_DIR>\bin\ffprobe.exe" -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "<OUTPUT_VIDEO>"

自检： 最终视频文件存在 已向用户报告实际时长 视频可播放

---

硬性规则

---

错误处理

LLM 常见错误预防