影片字幕新增是做什麼的？

相依性

/video-understand 是前置作業。請先執行它，以便字幕使用經過驗證的逐字時間軸和標準時間線。開始之前，請確認它已安裝。如果未安裝，請警告使用者缺少此必要項目，並在處理媒體前停止。

需要在 PATH 環境變數中包含 ffmpeg/ffprobe、安裝了 Pillow 的 Python，以及 Node.js >= 22（用於 .mjs 腳本和按需取得的 npx hyperframes）。hyperframes render/snapshot 會驅動無頭 Chrome——它會管理自己的 chrome-headless-shell，並在快取的 Chrome 無法使用時，回退到系統中的 Chrome（可設定 CHROME 環境變數來覆寫）。請在處理媒體前檢查這些項目。

範圍

此技能負責字幕分組、樣式選擇、審查以及透明字幕軌。它不負責轉錄、剪輯、重新定時、調色、重新構圖或選擇最終的音訊策略。

如果同時選擇了字幕和內容卡片/動態圖形，請先執行字幕。獲准的字幕佈局會定義一個預留的字幕區域，這兩個後續操作都必須保持該區域淨空。此相對順序也適用於只有一對操作為啟用狀態的情況。

請先使用 video-understand。如果已存在剪輯，請為有效節目的時間線製作字幕；不要將原始來源時間軸的秒數視為節目時間軸的秒數。

協定輸入

必要項目：

work/project.json
work/understand/transcript.json，包含逐字來源時間戳
work/understand/media.json
work/timeline.json
work/project.json 中命名的來源影片

時間線是唯一從來源到節目的映射。所有範圍都是半開區間 [start_s, end_s)。scripts/build_captions.py 使用共用的 projectlib.map_transcript_to_timeline；被丟棄的來源範圍中的單字會消失，保留的單字會移動到節目時間，並且提示總是在剪輯邊界處斷開。

持久化輸出

work/captions/
|-- captions-plan.json
|-- caption-spatial-context.json（僅適用於符合條件的 B-roll 合成畫面）
`-- caption-interaction.json
work/cache/captions/
|-- preview-project/
|-- preview-snapshots/
|-- overlay-project/
`-- overlay-frames/frame_000001.png ...
review/05-captions/
|-- captions.srt
|-- captions-style-review-<UUID>.html
|-- captions-style-review.html
|-- captions-review.html
|-- preview-early.png
|-- preview-middle.png
|-- preview-late.png
|-- preview-no-caption.png
|-- captions-evidence.json
`-- captions-summary.md

產生的 HTML、複製的運行時檔案、抽取的來源幀和疊加幀是快取。計畫、可選的空間上下文、SRT、決策收據和審查證據是持久化的。

字幕計畫

work/captions/captions-plan.json 是標準的字幕計畫，目標為 overlay，並使用節目時間。它記錄了：

timeline_id、program_duration_s 和來源轉錄路徑；
提示分組設定；
已批准的樣式、決策模式、理由、圖庫選擇和完整的已解析樣式；
來源支持的審查證據和批准者；
具有兼容性欄位 start、end、text、lines 和 words 的提示；
每個提示的 program_range 和 source_ranges；
每個映射單字的節目/來源範圍和 clip_id；
包含精確有理數 FPS 和雜湊運行時資產的本地渲染器配方。

產生器也接受舊的頂層提示陣列。這僅是一個獨立的兼容性適配器；它無法表達時間線來源或重新產生已批准的協定貢獻。

Standard 是預設的呈現模式。Standard 計畫不需要 presentation 欄位，也不應僅僅為了添加一個而遷移。Expressive 是一個明確的呈現模式，而不是預設：使用 --presentation-mode expressive 來請求它。建置步驟隨後會添加穩定的提示 ID、預設單字 semantic_role 值，以及一個草稿 presentation 規劃外殼；它不會猜測佈局變體。

Expressive 僅支援 bottom-standard 和 center-emphasis。在填入外殼之前，請閱讀 reference/caption-rules.md。現有的渲染器只消費完整的 presentation.layout_beats；它不會推斷位置或在一個節拍內更改佈局。

Expressive 提示也可以定義一個連續的短語級別 hero_line。請使用標準的 level: hero；它會以 1.5x 大小將該短語以金色顯示在自己的行上。舊版的 level: strong 仍然被接受作為輸入別名，並以相同方式渲染，但新的代理編寫的計畫不得輸出它。維護的單字角色 keyword、number 和 contrast 各自使用 1.22x；normal 保持 1.0x。這些處理方式與預設正交，不會建立新的樣式 ID。請閱讀 reference/caption-rules.md 了解架構、溢出政策和卡拉 OK 規則。

當一個有效的、經審查批准的 B-roll 操作包含已批准或已驗證的說話者插圖合成畫面時，字幕可以從凍結的上游計畫、證據、標準化合成畫面以及明確的子鏡頭 display_mode 中衍生出 caption-spatial-context.json。這不會修改或重新選擇 B-roll 佈局。它會在 Expressive 規劃之前對齊提示邊界，並僅解析維護的 preset-bottom、frame-center、panel-center 和邊界僅有的 panel-bottom 放置方式。僅當出現 unsplittable_word_boundary 且相鄰於一個中下方的焦點面板時，才允許 panel-bottom；它會將穩定的提示置於結構化說話者矩形下方預留的條帶內。這樣的提示會與其相交的每個視覺上下文進行檢查，而不僅僅是包含單字中點的上下文。如果沒有此上下文，所有現有的 Standard 和 Expressive 放置行為將保持不變。

樣式

維護的預設有 clean、minimal、social-bold、pill、boxed、stroked 和 shorts。圖庫組合 ID 會添加維護的主題，例如 pill-yellow、stroked-blue 和 shorts-green。卡拉 OK 是一個選項，而不是單獨的預設。

預設委派選擇：clean，關閉卡拉 OK。僅當目標或素材證明其合理性時，才選擇更具表現力的預設。將特定於工作的更改儲存在覆寫 JSON 中；不要為了一般性的樣式回饋而編輯產生器。

Expressive 同時支援 semantic-only（關閉卡拉 OK）和 semantic-plus-karaoke（開啟卡拉 OK）。在兩種配置中，語義強調都會持續整個提示。在共存模式下，語義強調和活動的卡拉 OK 單字在所有高亮模式中都使用 style.wordHighlight.activeColor 作為它們的前景顏色；背景高亮仍然是附加效果。有效的縮放比例是 max(semantic scale, karaoke active scale)，絕不是它們的乘積。Expressive 絕不會渲染底線，包括用於兼容的 contrast 語義角色。

現有的審查合約繼續使用 semantic-only 作為主要的 Expressive 證據，並將 semantic-plus-karaoke 單獨綁定。兼容性承載欄位仍然命名為 experimental_comparison；未經批准協定遷移，請勿重新命名。

請閱讀：

reference/caption-rules.md 在更改分組限制之前；
reference/caption-style-themes.md 了解樣式詞彙；
reference/caption-feedback-mapping.md 了解覆寫映射。

決策模式

兩種正常的模式共享相同的基於雜湊的狀態機：

human：將確切的複製圖庫摘要傳遞給 select，顯示所有真實的預覽證據，並將確切的複製批准或修訂摘要傳遞給 confirm 或 adjust。綁定到審查頁面的命令不接受單純的批准短語。
agent：僅在使用者明確委派字幕決策時使用。以非空的委派說明開始，然後使用帶有非空理由的 agent-select 和 agent-confirm。

人類模式命令在代理模式中失敗，代理模式命令在人類模式中失敗。沒有空間上下文的 Standard 模式需要四個維護的來源支持圖像；Expressive 和複合感知審查使用它們的動態證據合約。對來源、計畫、時間線、樣式、覆寫、專案元資料、審查頁面或證據的更改會使批准失效；空間上下文、上游 B-roll 修訂或綁定合成變更也會導致相同結果。重建受影響的工件並再次審查它們。

標準工作流程

從儲存庫根目錄執行。設定專案路徑：

$RepoRoot = (Resolve-Path ".").Path
$SkillRoot = Join-Path $RepoRoot "skills\video-add-captions"
$ProjectRoot = (Resolve-Path "<project-root>").Path
$Work = Join-Path $ProjectRoot "work"
$SourceVideo = "<absolute path from work/project.json>"
$Plan = Join-Path $Work "captions\captions-plan.json"
$SpatialContext = Join-Path $Work "captions\caption-spatial-context.json"
$SpatialArgs = @()
$SpatialReviewArgs = @()
$Receipt = Join-Path $Work "captions\caption-interaction.json"
$Review = Join-Path $ProjectRoot "review\05-captions"
$Cache = Join-Path $Work "cache\captions"
$PreviewProject = Join-Path $Cache "preview-project"
$ComparisonProject = Join-Path $Cache "preview-project-expressive-karaoke"
$OverlayProject = Join-Path $Cache "overlay-project"
$OverlayFrames = Join-Path $Cache "overlay-frames"
New-Item -ItemType Directory -Force -Path (Split-Path $Plan),$Review,$Cache | Out-Null

在建置字幕計畫之前，詢問使用者選擇呈現模式，除非當前請求已經明確選擇了一個。以使用者當前對話語言呈現問題，同時保持 Standard 和 Expressive 識別碼不翻譯。將下方此檔案中的英文來源提示保留，在當前會話中呈現本地化的選擇，然後呈現並停止：

選擇字幕呈現模式：

1. Standard：使用穩定的傳統放置方式，適合大多數內容。
2. Expressive：根據意義在底部和中央放置之間切換，並強調關鍵字和數字。

回覆 Standard、Expressive 或 "使用預設 (Standard)。"

在使用者回應之前，請勿執行 build_captions.py。如果使用者以任何措辭明確委派選擇，則選擇 Standard。在建置計畫之前，說明 Standard 被選為保持兼容性的預設。

建置節目時間提示和審查 SRT：

python "$SkillRoot\scripts\build_captions.py" `
  "$Work\understand\transcript.json" `
  $Plan `
  "$Review\captions.srt" `
  --timeline "$Work\timeline.json" `
  --source-transcript "understand/transcript.json" `
  --max-chars 42 --max-lines 2 --max-dur 6 --gap 0.6

在使用者選擇 Standard 後，上面的指令會產生不變的 Standard 計畫。在使用者選擇 Expressive 後，使用以下參數執行相同的指令：

  --presentation-mode expressive

在產生草稿提示後，以唯讀方式檢查活動的 B-roll 操作及其綁定計畫。僅在操作處於活動狀態、其狀態為 approved 或 verified、review.status 為 approved、說話者插圖分析/代理輸入/預覽/許可綁定完成，且至少有一個已驗證或標準化的鏡頭具有維護的合成佈局時，才啟用複合感知放置。空間建置器使用明確的子鏡頭 display_mode: enabled 來表示說話者幾何形狀；pure_broll 和缺少說話者證據絕不暗示說話者矩形。

當符合條件時，在填入任何 Expressive layout_beats 或 hero_line 之前，將草稿提示對齊到每個 B-roll 視覺邊界。對齊僅在單字間隙處分割，並原子性地寫回；單字內的邊界會保持單字完整，並記錄強制性的審查證據：

python "$SkillRoot\scripts\caption_spatial_context.py" align `
  --project-root $ProjectRoot --plan $Plan --out-plan $Plan

對於符合條件的專案，準備每個後續關卡使用的可選參數：

$SpatialArgs = @("--spatial-context", $SpatialContext)
$SpatialReviewArgs = @("--spatial-context", $SpatialContext, "--project-root", $ProjectRoot)

當沒有符合條件的合成畫面時，跳過所有四個空間指令，並保持 $SpatialArgs 和 $SpatialReviewArgs 為空。不要建立或附加空上下文。

在開始樣式選擇或產生預覽之前，代理必須一次性規劃整個 Expressive 節目：

閱讀轉錄稿、可用的理解工件、標準時間線、產生的字幕提示，以及任何證明佈局更改合理的真實來源幀證據。
填入所有 presentation.layout_beats，註釋異常的單字 semantic_role 值，在必要時為一個提示添加最多一個連續的 hero_line（使用標準的 level: hero），為每個節拍/英雄行寫一個理由，並寫下整體的 presentation.planner.rationale。
只有在每個提示都被精確覆蓋一次後，才將 presentation.planning_status 設定為 complete。
在產生預覽之前驗證完成的計畫：

python "$SkillRoot\scripts\build_captions.py" --validate-plan $Plan

對於符合條件的合成畫面，僅在最終提示 ID 和 Expressive 候選項完成後，才建置、驗證並附加上下文。這會保留上游佈局，並將其當前修訂和雜湊綁定到字幕計畫中：

python "$SkillRoot\scripts\caption_spatial_context.py" build `
  --project-root $ProjectRoot --plan $Plan --out $SpatialContext

python "$SkillRoot\scripts\caption_spatial_context.py" validate `
  --project-root $ProjectRoot --plan $Plan --context $SpatialContext

python "$SkillRoot\scripts\caption_spatial_context.py" attach `
  --project-root $ProjectRoot --plan $Plan --context $SpatialContext

不要要求使用者逐個提示選擇位置。使用者會審查現有的 HTML 證據，並僅修正少數異常的節拍。在規劃後開始互動，可以保持現有的字幕計畫雜湊綁定的權威性。

啟動一個決策模式。對於人類模式，將維護的離線圖庫發佈到專案審查目錄，而無需要求使用者定位檔案：

$StartOutput = node "$SkillRoot\scripts\caption_interaction.mjs" start `
  --state $Receipt --source $Sou

…

[翻譯因內容截斷而受限]

影片字幕新增