视频添加B-Roll素材是做什么的？

向已确认的规范项目协议序列中添加少量有依据的视觉转场画面。在计划或获取任何媒体之前，请先阅读 broll-rules.md。使用 example-broll-plan.json 作为计划格式参考。

不可协商的约束

遵循 broll-rules.md 中所有编辑、来源、静帧、审核、恢复和交付规则。操作上：

使用提供的脚本进行获取、验证、标准化、收据应用和验证。切勿使用原始下载路径或替换其他素材来源。
切勿伪造人类授权。Agent审核需要明确的委托和真实有效的Agent收据。
缺失、质量弱或下载器拒绝的媒体标记为 skipped；切勿使用随机或静帧备用媒体。

要求与输入

需要 Python、ffmpeg、ffprobe 和 Pillow。对于Pexels，首先使用环境变量中的 PEXELS_API_KEY，然后在 skills/video-add-b-roll/.env 中查找。如果两者都缺失或为空，则停止并要求用户将 PEXELS_API_KEY=<key> 添加到该文件中，并在用户确认后重试。要求用户通过本地的 .env 文件提供密钥，切勿通过聊天。切勿将密钥放置在命令参数、计划、URL、日志、审核产物或回复中。

/video-understand 是前置条件。先运行它，以便B-Roll使用经过验证的逐词转录文本和规范时间线。在开始前，请验证它是否已安装。如果未安装，则警告用户缺少此前置条件，并在处理媒体前停止。

从仓库根目录运行，并解析出独立项目根目录：

$RepoRoot = (Resolve-Path '.').Path
$ProjectRoot = (Resolve-Path 'path/to/video-project').Path
$BrollEnv = Join-Path $RepoRoot 'skills/video-add-b-roll/.env'
if ([string]::IsNullOrWhiteSpace($env:PEXELS_API_KEY) -and (Test-Path -LiteralPath $BrollEnv)) {
  $PexelsKeyLine = Get-Content -LiteralPath $BrollEnv | Where-Object { $_ -match '^\s*PEXELS_API_KEY\s*=' } | Select-Object -Last 1
  if ($PexelsKeyLine) { $env:PEXELS_API_KEY = ($PexelsKeyLine -split '=', 2)[1].Trim().Trim('"').Trim("'") }
}
$BrollScripts = Join-Path $RepoRoot 'skills/video-add-b-roll/scripts'
$ProjectLib = Join-Path $RepoRoot 'skills/video-understand/scripts'
$ReviewVideo = & python -c "import sys; from pathlib import Path; sys.path.insert(0,sys.argv[2]); import projectlib; root=Path(sys.argv[1]); project=projectlib.load_json(root/'work/project.json'); assert project.get('render',{}).get('status') == 'verified', 'current upstream delivery is not verified'; path=projectlib.resolve_project_path(root,project['render']['output']); assert path.is_file(), 'current upstream delivery is missing'; print(path)" $ProjectRoot $ProjectLib
if ($LASTEXITCODE -ne 0) { throw '在B-Roll审核前，请先完成上游交付物。' }
$ReviewVideo = (Resolve-Path -LiteralPath $ReviewVideo).Path

使用以下规范输入，而不是重新转录或重新分析：

work/project.json
work/timeline.json
work/understand/transcript.json
work/understand/understanding.json
一个当前节目时间的审核视频，其像素包含活跃的剪辑和调色工作

$ReviewVideo 是那个已验证的上游交付物，而不是一个需要新创建的B-Roll渲染文件名。它必须已经匹配当前时间线的时长、尺寸和帧率。如果它不存在或已过时，请先完成上游剪辑/调色交付，然后解析并对其进行哈希，再继续。

该操作始终依赖于 understanding，以及当目标序列上 cut 和 color-grade 操作活跃时，还需要它们的修订版本。将它们的当前正整数修订版本复制到 based_on。当调色操作活跃时，同时记录调色方案和所选LUT的哈希值；标准化过程必须接收到该精确的所选LUT，并将其预应用到每个选中的B-Roll镜头。

规范序列顺序为：

cut -> color-grade -> b-roll -> captions -> content-cards -> graphic-motion

已注册的操作必须具有 changes_video_pixels: true，添加 b-roll 轨道，并保持时间线、几何和音频不变。broll_plan.register_operation() 写入此契约；不要手动构建操作。

持久化与可丢弃文件

work/b-roll/broll-plan.json                         # 持久化领域计划
work/b-roll/presentation-decision.json               # 持久化Agent聊天路由决策
work/b-roll/broll-interaction.json                  # 持久化应用收据
work/b-roll/broll-selection.json                    # 持久化已批准的精确选择和已消费页面绑定
work/b-roll/speaker-inset-analysis.json             # 持久化场景/证据包
work/b-roll/speaker-inset-agent-input.json          # 持久化Agent ROI决策
work/b-roll/speaker-inset-preview.json              # 持久化精确预览绑定
work/b-roll/speaker-inset-clearance.json            # 持久化Agent遮挡检查
work/b-roll/broll-revision-request-<UUID>.json      # 持久化未批准的请求字节
work/b-roll/candidate-search.json                   # 持久化查询和提供者顺序
work/b-roll/candidate-analysis.json                 # 持久化确定性证据
work/b-roll/candidate-ranking.json                  # 持久化Agent排名和前三
work/cache/b-roll/candidate-analysis/media/         # 可丢弃的分析变体
work/cache/b-roll/candidate-analysis/frames/        # 可复现的样本和裁剪
work/cache/b-roll/candidates/                       # 冻结的已获取媒体
work/cache/b-roll/speaker-inset/                    # 可复现的证据和预览
work/cache/b-roll/normalized/                       # 可复现的无声叠加层
review/03-b-roll/candidate-analysis-<UUID>/          # 不可变的分析包
review/03-b-roll/candidate-analysis-<UUID>.md        # 分析和基线摘要
review/03-b-roll/candidate-analysis-<UUID>/candidate-index.html
review/03-b-roll/b-roll-review-<UUID>.html          # 不可变的候选审核
review/03-b-roll/b-roll-review.html                 # 最新便利别名
review/03-b-roll/stills/                            # 首/中/尾帧验证
review/03-b-roll/contact-sheet.jpg
review/03-b-roll/boundary-reel.mp4
review/03-b-roll/b-roll-summary.md

将计划和收据放在 work/cache/ 之外。将候选和标准化文件视为可复现但受哈希值绑定的输入。

工作流程

1. 建立当前依赖项

读取活跃序列、操作修订版本、时间线、转录文本、理解结果、活跃调色方案和所选LUT。确认审核视频与当前时间线的时长、尺寸和有理帧率匹配。将转录文本、时间线、审核视频和活跃调色输入的哈希值记录到 input_hashes 中。

使用 broll_plan.active_dependencies(project) 派生确切的依赖列表。更改的时间线、转录文本、依赖修订版本、调色方案、LUT、审核视频、候选清单或已审核的素材会使下游工作过时；刷新计划并重复审核，而不是沿用旧的收据。

2. 创建动态社交计划

手动创建 work/b-roll/broll-plan.json；脚本负责精确性，而非编辑判断。对于每个提议的镜头：

按时间顺序选择一个正的、半开区间、不重叠的程序范围；
通过 work/timeline.json 将其映射到精确的 source_ranges；
至少保留一个映射到的确切转录词，包括源/程序范围和片段ID；
说明具体的 editorial_reason 和 visual_intent；
设置 brief.search_context，包含具体的 topic、visual_direction 和 1-12个唯一关键词；
设置每个 semantic_role 为 direct、supportive 或 atmospheric；
编写两到三层字面上的英文查询：一个 direct subject/action 查询，一个 defensible context/process 查询，以及（当第三个查询有用时）一个 theme-enhancing variant；
初始状态为 planned，获取后变为 candidates_ready，若无相关候选则使用 skipped。

保持 brief.density 为 dynamic-social。计划的覆盖范围从对映射的转录和时间线进行完整的A-Roll扫描开始，然后是手动编写的、按时间顺序、不重叠的、编辑上有效的范围。将 0.40 到 0.70 视为软目标。低于 0.40 时，进行第二次扫描，仅添加或扩展可辩护的范围。超过 0.70 时，内部审查A-Roll的遮挡。切勿添加不相关的填充素材或为了达到目标而削弱相关性、权利、质量或其他资格门槛。诸如 tech 或 entertainment 之类的通用主题词仅可用于优化查询；它们永远不能替代候选与转录文本声明之间每个镜头的可见关系。如果没有镜头值得添加B-Roll，一个经过批准的、全部跳过（all-skipped）的计划也是有效的空操作。

在起草阶段不要添加 speaker_inset_style。在候选获取之后，显式的Agent聊天演示决策将选择普通或画中画（speaker-inset）路线。后者会自动安装严格的项目级圆角矩形样式：width_ratio: 0.39，灰色边框，宽高比，圆角半径，边距和字幕安全底部区域。预设和锚点不属于样式。Agent在检查了确切的选定媒体后记录 project_layout_strategy 以及每个镜头的 layout_recommendation。切勿引入面部检测器、分割模型、跨剪辑身份跟踪器或猜测的ROI。将演讲者ROI像素拟合到窗口中，保持宽高比进行覆盖缩放；切勿将其拉伸至配置的宽高比。水平居中裁剪并锚定到顶部，以便完整头部和面部优先于下半身覆盖。

在每次重大编辑后验证计划草案：

python -c "import sys; from pathlib import Path; root=Path(sys.argv[1]); sys.path.insert(0,sys.argv[2]); import broll_plan,projectlib; plan=projectlib.load_json(root/'work/b-roll/broll-plan.json'); timeline=projectlib.load_json(root/'work/timeline.json'); transcript=projectlib.load_json(root/'work/understand/transcript.json'); project=projectlib.load_json(root/'work/project.json'); errors=broll_plan.validate_plan(plan,timeline,transcript,project=project,project_root=root,verify_files=True); print('\n'.join(errors) if errors else 'B-roll plan valid'); raise SystemExit(bool(errors))" $ProjectRoot $BrollScripts

3. 分析、排名和冻结候选

候选分析是在 candidates_ready 之前的咨询性证据。它不选择媒体、批准镜头、添加收据或更改生命周期。为每个镜头保留现有的两到三个字面查询。

对于本地视频，编写真实的来源信息并通过现有的获取路径导入：

python "$BrollScripts/pexels.py" import-local `
  "$ProjectRoot/input/example-owned-footage.mp4" `
  "$ProjectRoot/work/cache/b-roll/candidates/example-owned-footage.mp4" `
  "$ProjectRoot/work/b-roll/example-local-provenance.json"

将返回的记录复制到镜头的 candidates 中。候选分析读取该确切的冻结缓存文件；它不会将其复制到另一个提供者或分析系统中。当计划不应查询Pexels时，使用 --local-only。

使用轮询（round-robin）查询合并、提供者ID去重以及每个镜头最多八个唯一提供者视频来收集Pexels结果。选择与时间线匹配的方向：

$CandidateAnalysis = Join-Path $BrollScripts 'candidate_analysis.py'
python $CandidateAnalysis search `
  $ProjectRoot `
  "$ProjectRoot/work/b-roll/broll-plan.json" `
  "$ProjectRoot/work/b-roll/candidate-search.json" `
  --orientation portrait `
  --per-page 8

对于仅本地分析，添加 --local-only。搜索记录保留每个字面查询、其原始提供者顺序、轮询顺序以及两种Pexels变体。分析变体是短边至少为480像素的最小方向匹配文件，或者当没有任何文件符合条件时，是最大的有效方向匹配文件。交付变体仍为最高分辨率的方向匹配文件。

仅下载并完全解码分析变体，在10/30/50/70/90百分比处采样，并编写确定性机器证据：

python $CandidateAnalysis analyze `
  $ProjectRoot `
  "$ProjectRoot/work/b-roll/broll-plan.json" `
  "$ProjectRoot/work/b-roll/candidate-search.json" `
  "$ProjectRoot/work/timeline.json" `
  "$ProjectRoot/work/b-roll/candidate-analysis.json"

分析包含硬性检查、客观警告、采样帧和中心裁剪的哈希值、联系表、亮度/裁剪/边缘/运动证据以及重复证据。它保留镜头级别的精确拒绝和严格感知阈值，然后添加项目级别的精确身份、严格感知组以及非抑制性的 possible_series 提示。硬性拒绝仅限于 reference/broll-rules.md 中的客观失败项。

检查确切的转录证据、五个帧、裁剪模拟、警告和重复证据。使用以下格式编写 work/cache/b-roll/candidate-ranking-input.json：

{
  "schema_version": 1,
  "analysis_sha256": "<canonical SHA-256 of candidate-analysis.json>",
  "mode": "agent",
  "actor": "<real Agent name>",
  "timestamp": "<timezone-aware timestamp>",
  "overall_rationale": "<non-empty rationale>",
  "near_duplicate_groups": [{
    "group_id": "<stable group id>",
    "match_type": "same_series",
    "actor": "<real Agent name>",
    "timestamp": "<timezone-aware timestamp>",
    "members": [
      {"shot_id": "<shot id>", "candidate_id": "<candidate id>"},
      {"shot_id": "<other shot id>", "candidate_id": "<other candidate id>"}
    ],
    "rationale": "<specific visible repetition across the two transcript moments>"
  }],
  "shots": [{
    "shot_id": "<shot id>",
    "candidates": [
      // ...（其余部分被截断）

视频添加B-Roll素材