视频添加内容卡片

将已批准的语义片段整合为统一的 HyperFrames 图形叠加层。复用共享证据与标准时间线；本技能内禁止对源素材重新转录或重新分析。

依赖项

要求系统 PATH 中存在 ffmpeg、Python，以及 Node.js >= 22（用于按需执行 npx hyperframes）。hyperframes render/snapshot 驱动无头 Chrome —— 它自行管理 chrome-headless-shell，当缓存版本不可用时，自动回退至系统已安装的 Chrome（可通过设置环境变量 CHROME 覆盖此行为）。处理媒体前请务必确认上述组件可用。

输入

• work/project.json：操作修订记录及依赖关系
• work/understand/understanding.json：经人工复核的语义片段及其支撑证据
• work/timeline.json：源时间线到成片时间线的映射；若无剪辑点，则为恒等时间线（identity timeline）
• 可选：选定的调色版本（当对比度或色彩方案需参照该调色风格时）

即使不存在剪辑点或调色版本，本技能仍有效。仅声明实际消耗的依赖项，并在 based_on 字段中记录其当前修订版本。

工作文件

work/content-cards/cards-plan.json          # 持久化编辑计划
work/cache/content-cards/index.html         # “代码即剪辑”（code-is-the-edit）构成的 HTML
work/cache/content-cards-overlay.mov        # 透明通道渲染输出（alpha render contribution）
review/03-content-cards/card-stills/        # 每张卡片对应一张代表性静帧
review/03-content-cards/content-cards-preview.mp4  # 可选：短时序预览窗口（cue windows）
review/03-content-cards/content-cards-summary.md
review/03-content-cards/content-cards-review.html  # 本地候选方案评审看板
review/03-content-cards/content-cards-review-assets/  # 每个候选卡片对应一张原始帧
review/03-content-cards/content-cards-review.json  # 经人工验证的选择结果

可复用的评审页面已提交至 skills/video-add-content-cards/assets/content-cards-review.html。 填充后的 HTML、截图、叠加层及预览渲染均可完全复现。 请将编辑计划文件置于 cache/ 目录之外。该计划必须包含所有可见字符串、时间戳、位置、视觉样式参数、渲染器构成路径（renderer composition path）、渲染器资源路径（renderer asset path）以及重建可丢弃 HTML 和 Alpha 资源所需的确切源帧率（source FPS），前提是已删除 work/cache/。 计划层级须记录一项 renderer_recipe，其中应包含源示例/模板、构成输出路径、渲染引擎，以及每个本地运行时资源的输出路径、精确版本号、来源与 SHA-256 校验值。 仅含缓存 HTML 文件或未附带持久化配方（durable recipe）的下载脚本，无法满足再生要求。

工作流

1. 起草前访谈

首先通读 understanding.json 与当前激活的时间线。统计符合条件的图形化语义片段数量，并在访谈前计算目标卡片数量建议值：

min(eligible moments, max(1, round(program minutes / 0.75)))

此数值仅为参考目标，非自动截断规则。在提出任一问题前，请先使用当前操作系统原生命令亲自打开真实动态示例。仅运行以下命令之一：

# Windows PowerShell
Start-Process (Resolve-Path 'skills/video-add-content-cards/examples/gallery-animated.html')

# macOS
open skills/video-add-content-cards/examples/gallery-animated.html

# Linux desktop
xdg-open skills/video-add-content-cards/examples/gallery-animated.html

若命令执行失败，请自行诊断并重试；不得以 URI 替代该操作，亦不可要求用户手动查找并点击该文件。该图库对比全部五种主题，且支持通过原生选择器聚焦某一列：

请严格按如下顺序，每次仅提出一个问题：

1. 本次剪辑应采用哪种主题？
2. 本次剪辑的目标卡片数量应为多少？默认提供上一步计算出的建议值。
3. 必须包含哪些卡片类型？可选项为 intro、key-quote、stat、list 与 outro；默认不选任何类型。

每问一次后请立即“呈现 + 停止”（Present + STOP）。 在获得第三个回答后，汇总确认所选主题、目标数量、必需类型及用户补充说明；随后请求最终确认。若用户取消流程，则保留已有分析结果，将操作状态维持为 draft，且不生成或渲染任何卡片。

2. 基于共享理解起草卡片

python skills/video-add-content-cards/scripts/build_cards_plan.py `
  work/understand/understanding.json `
  work/timeline.json `
  work/content-cards/cards-plan.json `
  --target-card-count 6 `
  --theme editorial `
  --must-include-type stat `
  --notes "Keep product names verbatim"

该脚本将保留的语义片段映射至成片时间轴，并跳过已被剪辑移除的片段。它保留原始时间范围与证据引用，将持续时间限制在所属剪辑区间内，并将文案、位置与视觉样式标记为 draft。 确认后的访谈内容将作为 brief 存入 cards-plan.json。如需指定多个必含类型，请重复使用 --must-include-type 参数；对不适用的参数请直接省略。为兼容旧版，部分可选的 brief 字段仍被接受，但不属于常规访谈流程的一部分。

3. 做出编辑决策

在每张卡片对应的时间点查阅支撑证据。修正 ASR 输出的人名与数字，剔除薄弱候选，撰写简洁文案，选择避开人脸与字幕的安全位置，并确认视觉样式。切勿将分析器输出的文本视作最终文案。

所有屏幕显示文案均需存储于 copy.display 下（例如 eyebrow、title 和 detail），而非仅存摘要或建议标题。仅在审查合成静帧后，方可将 placement.face_clearance 设为 verified，并将该静帧的协议相对路径（protocol-relative path）存入 placement.review_still。HyperFrames 构成、Alpha 资源及精确有理帧率（rational FPS）均需存入 renderer 字段。

以下映射关系可作为起点参考：

repetition、tangent 与 risk 属于编辑判断依据，不自动生成卡片。

本阶段须保留所有证据支撑的候选卡片。以访谈简报（brief）中设定的目标数量为基准，但若证据充分，亦可采纳更精炼或更密集的卡片组合。

4. 评审并应用候选方案

待候选计划生成后，基于该计划构建项目专属浏览器评审页。传入与计划中 source_range 对齐的源视频及当前激活的时间线。脚本将各证据中点裁剪至其所属保留剪辑区间，并以每个候选卡片对应一张源帧的方式填充已提交的模板：

python skills/video-add-content-cards/scripts/build_review_page.py `
  work/content-cards/cards-plan.json `
  review/03-content-cards/content-cards-review.html `
  --video input/source.mp4 `
  --timeline work/timeline.json

请立即使用当前操作系统原生命令亲自打开已填充的评审页。仅运行以下命令之一：

# Windows PowerShell
Start-Process (Resolve-Path 'review/03-content-cards/content-cards-review.html')

# macOS
open review/03-content-cards/content-cards-review.html

# Linux desktop
xdg-open review/03-content-cards/content-cards-review.html

若命令执行失败，请自行诊断并重试；不得要求用户手动定位该文件。该页面展示每张源帧、卡片 ID、成片时间、可编辑文案及位置选项。所有候选卡片初始均未被选中，位置默认设为 bottom。更改位置时，灰色卡片代理将覆盖在真实帧上，使潜在碰撞风险在审批前即可直观呈现。用户需从中选择卡片、编辑文案、指定位置，点击 复制摘要（Copy summary），并将可见摘要粘贴回当前对话中。

呈现 + 停止（Present + STOP）。 等待用户粘贴的选择摘要。切勿基于未经校验的草案候选卡片生成 HTML。将该摘要转换为 review/03-content-cards/content-cards-review.json：为计划中每张卡片写入一条记录；对摘要中标记为已选的 ID，填入其选定的文案与位置；其余 ID 则标记为未选中，保留其当前草案文案与空位置字段。随后应用经验证的评审结果：

python skills/video-add-content-cards/scripts/apply_cards_review.py `
  work/content-cards/cards-plan.json `
  review/03-content-cards/content-cards-review.json

应用步骤将拒绝未知、重复或缺失的卡片 ID、空白的已选文案，以及无效的位置设置，且不修改原始计划。成功时，仅保留已选卡片，并将其文案、位置、视觉样式及顶层评审状态标记为 approved。继续后续步骤前，请比对已选卡片总数与简报中的目标数量。

5. 编写单一 HyperFrames 构成

使用单个 index.html 文件与暂停状态的 GSAP 时间轴。每张已批准卡片对应一个由计划中 program_start_s 与 duration_s 键控的 .clip。确保动画支持任意时间点跳转（seek-safe），且所有时序逻辑均源自数据属性，而非系统时钟计时器（wall-clock timers）。

从最接近的仓库示例入手：

• examples/index-almanac.html
• examples/index-apex.html
• examples/index-dotgrid.html
• examples/index-editorial.html
• examples/index-teal.html

所有卡片须保持统一视觉语言。采用边缘锚定（edge anchoring）、卡片或遮罩（scrim）提升可读性、基于源素材的相对尺寸缩放，并确保与所选调色风格具备足够对比度。切勿遮挡讲话人或字幕区域。

请显式传入源帧率；保留分数形式（如 24000/1001），不可四舍五入为 24 或 30。Windows 平台下使用 npx.cmd、项目本地 npm 缓存及本地资源：

$env:npm_config_cache = "$PWD/work/cache/npm"
npx.cmd hyperframes lint
npx.cmd hyperframes validate

渲染阶段严禁依赖远程字体、图片、脚本或样式表。

已批准的计划必须精确保存构成中实际使用的样式与动效参数值，而不能仅以诸如 edge-slide 的描述性标签替代。至少需记录面板几何结构与内边距、颜色、边框、字体大小/粗细/行高，以及进入（enter）、规则（rule）、文本（text）、退出（exit）阶段的持续时间、偏移量、错落延迟（stagger）与缓动函数（easing）。此举确保创意 HTML 可完全由计划再生，而非将关键决策隐匿于临时缓存中。

6. 评审小型产出物

在每个 cue 时间点附近，将卡片与对应基础视频帧合成，截取一张静帧。仅含透明通道的 HyperFrames 截图仅能验证 Alpha 通道，无法证明人脸/字幕区域是否清晰，故不足以完成审批。仅在需确认时序或转场效果时，才渲染短时序动态窗口。默认情况下无需渲染完整预览。

检查项包括：

• 文案与其 evidence_ref 完全一致；
• 源时间与成片时间映射准确；
• 文字清晰可辨且布局适配；
• 人脸与字幕区域保持清晰；
• 动画精准落在对应语音短语上；
• 卡片区域外 Alpha 通道完全透明。

呈现 + 停止（Present + STOP）。 展示各卡片静帧及任何短时序动态窗口，明确标注卡片 ID，并等待用户批准。在文案、位置或时序尚存争议时，禁止渲染完整叠加层。

每张经批准的 cue 必须在 review/03-content-cards/card-stills/ 中拥有匹配的合成静帧，其 face_clearance 值为 "verified"，且该静帧路径已存入计划文件中。评审结果需记录于 review/03-content-cards/content-cards-summary.md。

7. 渲染透明通道贡献

优先为每个 cue 单独生成一段短 Alpha MOV，避免数秒图形内容导致整段成片级透明视频。每段均需按源分辨率与精确源帧率渲染，随后声明其在成片时间轴上的作用窗口。仅当整段稀疏叠加层经证实体积更小或构成逻辑强制要求时，才允许生成单段全长叠加层。

请将本操作贡献记录于 project.json：

{
"target": {"sequence": "main", "scope": "graphics"},
"effects": {
  "changes_timeline": false,
  "changes_geometry": false,
  "changes_video_pixels": false,
  "changes_audio": false,
  "adds_track": "graphics"
},
"check": {
  "status": "pass",
  "report": "../review/03-content-cards/content-cards-summary.md"
},
"render": [
  {
    "kind": "overlay",
    "asset": "cache/content-cards/card-001.mov",
    "start_s": 12.5,
    "duration_s": 4.0
  }
]
}

共享渲染器将各短片段按 start_s 偏移、按 duration_s 截断，并在基础视频调色后进行合成。请确保本操作的 outputs 及每张卡片的 renderer.asset 与上述声明的资源保持一致。

仅当完成卡片评审后，方可将操作状态设为 approved 或 verified；且每当计划、时序或所选输入发生变更时，须更新其整型 revision 值。共享渲染器将在所有活跃操作均通过 based_on 校验后，执行最终合成：

python skills/video-understand/scripts/build_render_plan.py .
python skills/video-understand/scripts/render_project.py work/render/render-plan.json

与字幕叠加的协同处理

将字幕与内容卡片视为独立的叠加层贡献。渲染前须解决二者位置冲突，随后在共享交付流程中按声明顺序进行合成。当两者均需占据同一安全区域时，字幕固定于底部，卡片则移至顶部。