用途
video-add-captions 用于为 Open Recut 节目添加逐词时间对齐的字幕。它把规范转录通过 timeline.json 映射到节目时间线，生成字幕计划、SRT 文件、样式审核页面和透明字幕轨道。该技能不负责转录、剪辑、重定时、调色、重新构图或选择交付音频策略。
依赖与前置条件
/video-understand 是前置技能，必须先运行，以便字幕使用经过验证的词级转录和规范时间线。开始前需确认其已安装；若未安装，应警告用户缺少前置条件并在处理媒体前停止。
需要 ffmpeg/ffprobe 在 PATH 中、带 Pillow 的 Python，以及 Node.js >= 22（用于 .mjs 脚本和按需获取的 npx hyperframes）。hyperframes render/snapshot 驱动无头 Chrome，它管理自己的 chrome-headless-shell，当缓存不可用时回退到系统 Chrome（可通过设置 CHROME 覆盖）。处理媒体前需检查这些条件。
主要能力
- 字幕分组、样式选择、审核和透明字幕轨道生成。
- 使用 work/timeline.json 作为唯一的源到节目映射；所有范围为半开区间 [start_s, end_s)。
- 丢弃的源范围中的词会消失，保留的词移动到节目时间，提示始终在剪辑边界处断开。
- 维护的预设样式：clean、minimal、social-bold、pill、boxed、stroked、shorts。画廊组合 ID 添加维护主题，例如 pill-yellow、stroked-blue、shorts-green。Karaoke 是选项而非独立预设。
- 默认委托选择：clean，Karaoke 关闭。
- 支持 Standard（默认）和 Expressive 两种呈现模式。Expressive 仅支持 bottom-standard 和 center-emphasis。
- Expressive 提示可定义一个连续的短语级 hero_line，使用规范 level: hero，以 1.5 倍渲染金色短语。维护的词角色 keyword、number、contrast 各使用 1.22 倍；normal 保持 1.0 倍。
- 支持人工和智能体两种决策模式，共享同一哈希绑定状态机。
- 当存在活跃且审核批准的 B-roll 操作包含已批准或已验证的说话人内嵌合成时，字幕可派生 caption-spatial-context.json。
使用方式
从仓库根目录运行。设置项目路径后，在构建字幕计划前，除非当前请求已明确选择呈现模式，否则需询问用户选择呈现模式（Standard 或 Expressive）。用户明确委托选择时，选择 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
用户选择 Expressive 后，使用相同命令并添加 --presentation-mode expressive。
Expressive 需在预览生成前一次性规划整个节目：读取转录、理解产物、规范时间线、生成的字幕提示和真实源帧证据；填充所有 presentation.layout_beats，标注特殊词 semantic_role 值，必要时添加至多一个连续 hero_line，为每个 beat/hero line 写一条理由，并写整体 presentation.planner.rationale。仅当每个提示恰好覆盖一次后，将 presentation.planning_status 设为 complete。
验证完成的计划：
python "$SkillRoot\scripts\build_captions.py" --validate-plan $Plan
启动决策模式。人工模式下，将维护的离线画廊发布到项目审核目录：
$StartOutput = node "$SkillRoot\scripts\caption_interaction.mjs" start `
--state $Receipt --source $SourceVideo --captions $Plan `
--review-dir $Review --no-open true @SpatialArgs
$StartOutput | Write-Host
start 打印权威的 captions-style-review-<UUID>.html 项目页面路径和固定问题。Agent 必须取 Caption style review: 后打印的 UUID 路径，赋给 $StyleReviewPage，并用宿主 OS 的原生命令打开。用户从页面复制结构化摘要后，原样传递给 select --response。
智能体模式下，创建单独的 Agent 模式收据，使用 --decision-mode agent 和 --delegation-note，检查绑定的画廊后使用 agent-select 并记录真实理由。
适用场景
适用于需要为 Open Recut 节目添加逐词时间对齐字幕的视频制作流程，尤其是需要样式审核、透明字幕轨道或 Expressive 语义强调的场景。
限制
- 必须先运行 /video-understand。
- 需要 ffmpeg/ffprobe、带 Pillow 的 Python、Node.js >= 22。
- 不负责转录、剪辑、重定时、调色、重新构图或选择交付音频策略。
- Expressive 仅支持 bottom-standard 和 center-emphasis。
- 人工命令在智能体模式下失败，智能体命令在人工模式下失败。
- 源、计划、时间线、样式、覆盖、项目元数据、审核页面或证据的更改会使批准失效；空间上下文、上游 B-roll 修订或绑定合成更改同样如此。
- 具体收费、价格、平台支持范围等事实暂未提供。