影片加入 B-Roll 是做什麼的？

將少量有證據支持的視覺插入鏡頭，加入已理解的標準專案協定序列中。在規劃或取得任何媒體之前，請先閱讀 broll-rules.md。使用 example-broll-plan.json 作為計劃格式的參考。

非協商性合約

遵循 broll-rules.md 中的所有編輯、來源、靜止影像、審查、復原與交付規則。操作上：

使用提供的腳本進行獲取、驗證、正規化、收據應用與驗證。絕不使用原始下載路徑或替代的股票來源。
絕不編造人為權威。代理審查需要明確授權與真實的代理收據。
遺失、無效或下載器拒絕的媒體將標記為 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 'Complete the active upstream delivery before B-roll review.' }
$ReviewVideo = (Resolve-Path -LiteralPath $ReviewVideo).Path

使用這些標準輸入，而非重新轉錄或重新分析：

work/project.json
work/timeline.json
work/understand/transcript.json
work/understand/understanding.json
一個目前的節目時間審查影片，其畫格需包含正在進行的剪輯與調色工作

$ReviewVideo 是那個現有且已驗證的上游交付影片，並非一個需要發明的檔案名稱或新的 B-roll 渲染。它必須已經與使用中的時間軸具有相同的時長、尺寸與 FPS。如果它遺失或過時，請先完成上游的剪輯/調色交付，然後解析並進行雜湊處理後再繼續。

操作總是依賴於 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               # 持久性代理聊天路由決策
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          # 持久性代理 ROI 決策
work/b-roll/speaker-inset-preview.json              # 持久性精確預覽綁定
work/b-roll/speaker-inset-clearance.json            # 持久性代理遮擋檢查
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                  # 持久性代理排名與前 3 名
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。確認審查影片符合使用中時間軸的時長、尺寸與合理 FPS。將文字記錄、時間軸、審查影片與使用中的調色輸入進行雜湊處理，存入 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，那麼一個經過核准、全部為 skipped 的計劃就是一個有效的空操作。

在撰寫草稿時，請勿新增 speaker_inset_style。在候選獲取之後，透過明確的代理聊天呈現決策來選擇普通路線或發言人插入路線。後者會自動安裝嚴格的專案層級圓角矩形樣式：width_ratio: 0.39、灰色邊框、長寬比、圓角半徑、邊距與字幕安全底部區域。預設與錨點不屬於樣式的一部分。代理在檢查精確選定的媒體後，記錄 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。

使用輪詢查詢合併、提供者 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": "<candidate-analysis.json 的標準 SHA-256>",
  "mode": "agent",
  "actor": "<真實代理名稱>",
  "timestamp": "<時區感知時間戳記>",
  "overall_rationale": "<非空理由>",
  "near_duplicate_groups": [{
    "group_id": "<穩定群組 ID>",
    "match_type": "same_series",
    "actor": "<真實代理名稱>",
    "timestamp": "<時區感知時間戳記>",
    "members": [
      {"shot_id": "<鏡頭 ID>", "candidate_id": "<候選 ID>"},
      {"shot_id": "<其他鏡頭 ID>", "candidate_id": "<其他候選 ID>"}
    ],
    "rationale": "<在兩個文字記錄時刻之間特定的可見重複>"
  }],
  "shots": [{
    "shot_id": "<鏡頭 ID>",
    "candidates": [

…

[為翻譯而截斷]

影片加入 B-Roll