视频添加内容卡片是做什么的？

将已批准的语义时刻转化为一个连贯的 HyperFrames 图形叠加层。使用共享的证据和规范时间线；不要在此技能内重新转录或重新分析源内容。

依赖项

/video-understand 是前置技能。请先运行它，以便卡片使用经过验证的语义证据和规范时间线。在开始之前，请确认它已安装。如果没有安装，请警告用户缺少此前置依赖项，并在处理媒体之前停止。

需要 ffmpeg 在 PATH 环境变量中，以及 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：源到节目的映射，如果没有剪辑，则为恒等时间线
可选的已选调色修订，当对比度或调色板需要针对该外观进行判断时

如果没有剪辑或调色，该技能仍然有效。当字幕激活时，请先运行它们，依赖于它们当前的修订，并将其占用的区域视为硬排除区域。内容卡片必须在图形运动之前添加，当两者都激活时。这些相对规则适用于每个选择的配对。仅声明实际使用的依赖项，并将其当前修订记录在 based_on 中。

在整个卡片提示期间（包括进入和退出），将每个主要或前景人物、说话者、演示者、受访者或语义重要人物的可见面部和头部轮廓视为硬排除区域。偶然的背景人物（不是叙事或视觉焦点）可以豁免；对于不确定的情况应予以保护。如果卡片与受保护的面部或头部相交，请先重新定位，然后缩放或重新设计。当没有符合要求的位置时，跳过该卡片。

工作文件

work/content-cards/cards-plan.json          # 持久的编辑计划
work/cache/content-cards/index.html         # 代码即编辑的组合
work/cache/content-cards-overlay.mov        # 透明渲染贡献
review/03-content-cards/card-stills/        # 每个卡片一个有用的静态帧
review/03-content-cards/content-cards-preview.mp4  # 可选的短提示窗口
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/ 之外。它必须包含每个可见字符串、时间、位置、视觉处理值、渲染器组合路径、渲染器资源路径以及源 FPS，这些是删除 work/cache/ 后重新生成可丢弃的 HTML 和 Alpha 资源所必需的。记录一个计划级别的 renderer_recipe，其中包含源示例/模板、组合输出路径、渲染引擎以及每个本地运行时资源的输出路径、确切版本、来源和 SHA-256。不包含持久配方的缓存 HTML 文件或下载的脚本不满足重新生成要求。

工作流程

1. 起草前访谈

首先阅读 understanding.json 和活动时间线。统计符合条件的图形时刻数量，并在访谈前计算建议的卡片数量：

min(符合条件的时刻数, max(1, round(节目分钟数 / 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 桌面
xdg-open skills/video-add-content-cards/examples/gallery-animated.html

如果命令失败，请诊断并重试。不要用 URI 替代此操作，或要求用户找到并点击该文件。画廊比较了所有六个主题，并可以使用其原生选择器聚焦一列：

主题	起始字符
`almanac`	暖奶油色，衬线体，深思熟虑
`teal`	深色广播风格，青色点缀
`editorial`	纪录片风格，墨色和琥珀色
`dotgrid`	像素单体，技术风
`apex`	高能量运动风，红色点缀
`air`	透明 Lexend 排版，无底板或遮罩

每次只问一个问题，按此顺序：

此编辑应使用哪个主题？
此编辑应使用多少目标卡片数？提供计算出的建议值作为默认值。
必须包含哪些卡片类型？提供 intro、key-quote、stat、list 和 outro；默认为无。

提问后 + 停止。在第三个答案之后，总结主题、目标数量、必需类型以及用户提供的任何备注；请求确认。如果用户取消，则保留分析结果，将操作状态设为 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 "保留产品名称原样"

该脚本将保留的语义时刻映射到节目时间，并省略被剪辑移除的时刻。它保留源范围和证据引用，将持续时间限制在包含的片段内，并将副本/位置/视觉处理标记为 draft。stat 以 metric-spotlight 开始；list 以 side-by-side 开始；候选审查可以保留正常布局或将列表切换为 parallel-columns。确认的访谈存储在 cards-plan.json 中作为 brief。对于多个值重复 --must-include-type；省略不适用的标志。较旧的可选 brief 字段仍然接受是为了兼容性，但不是正常访谈的一部分。

3. 做出编辑选择

阅读每个卡片时间点的证据。更正 ASR 名称和数字，淘汰弱候选，编写简洁的副本，选择能避开受保护面部、可见头部轮廓和字幕的位置，并批准视觉处理。切勿将分析器文本视为最终副本。

将所有屏幕上文本存储在 copy.display 下（例如 eyebrow、title 和 detail），而不仅仅是摘要或建议的标题。仅在对合成的静态帧根据上述受保护面部和头部定义进行审查后，将 placement.face_clearance 设置为 verified，并将该静态帧的协议相对路径存储在 placement.review_still 中。将 HyperFrames 组合、Alpha 资源和精确的有理 FPS 存储在 renderer 下。

使用以下映射作为起点：

语义种类	卡片类型
hook	intro
key-point, quote, question	key-quote
stat	stat
list	list
cta	outro

repetition、tangent 和 risk 是编辑证据，不是自动的卡片。

保留五种规范的卡片类型。将以下可选布局存储在 visual_treatment.layout 下，而不是创建新的顶层卡片类型：

规范卡片类型	允许的布局
`stat`	`default`, `metric-spotlight`, `bar-chart`, `pie-chart`, `line-chart`
`list`	`default`, `side-by-side`, `parallel-columns`

仅当一个有证据支持的数字、百分比、金额、倍数、年份或持续时间值得强调时，才使用 metric-spotlight。将数字放在简洁的上文和下文之间，适应长值而不重叠，并保持数字在视觉上居中于这些标签之间。对于二到四个平行的、对比的、对立的或对应的简短概念，使用 side-by-side 或 parallel-columns。首选短短语；使用审查来选择适合可用画面并避开拍摄对象的布局。

仅当保留的转录提供完整、有证据支持的数据集时，才使用图表。在创作图表数据之前，请阅读 reference/chart-data.md。手动将维度、度量、单位、周期、有序点以及每个点的转录证据存储在 data 下；切勿从分析器摘要推断值或组合来自不同视频的点。对于 2-6 个可比类别，使用 bar-chart；对于已被证明全体的 2-6 个互斥部分，使用 pie-chart；对于 3-8 个有意义的有序点，使用 line-chart。当必需的值、标签、分母、时间顺序或单位缺失时，使用 metric-spotlight、普通 stat 卡片或不使用卡片。对于图表布局，将冗长的解释压缩为简洁的支持性副本，同时不改变其含义。图表应主要传达关键值及其变化或关系。不要列举或重述图表中已可见的值、标签、周期或单位。

在此阶段保留所有有证据支持的候选。目标是简要中的目标卡片数，但当证据支持时，允许更强或更稀疏的集合。

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 `
  --captions-plan work/captions/captions-plan.json

当项目没有活动的字幕操作时，省略 --captions-plan。当有活动的字幕计划时，审查帧会显示其实际占用的顶部、中心或底部区域。

立即使用当前操作系统的原生命令亲自打开填充后的审查。仅运行一个命令：

# 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 桌面
xdg-open review/03-content-cards/content-cards-review.html

如果命令失败，请诊断并重试；不要要求用户定位文件。页面显示每个源帧、卡片 ID、节目时间、可编辑副本、视觉处理和位置。图表布局还显示可编辑的结构化数据和点证据引用。在批准之前，对照其显示的证据审查每个值。每个候选默认未选中，位置设置为 bottom。更改位置会在真实帧上移动灰色卡片代理，以便在批准之前可见碰撞风险。用户选择卡片、编辑副本、选择处理和位置，点击 复制摘要，然后将可见的摘要粘贴回对话中。

提问后 + 停止。 等待粘贴的选择摘要。不要从未经检查的草稿候选创作 HTML。将摘要转换为 review/03-content-cards/content-cards-review.json：为每个计划卡片写入一个条目，将摘要 ID 标记为已选择，并带有其选择的副本、视觉处理和位置，并将所有其他 ID 标记为未选择，带有其当前草稿副本和空位置。将审查选择存储为名为 visual_treatment 的字符串字段。然后应用已验证的审查：

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。在继续之前，将得到的选择数量与简短目标进行比较。

对于选择的图表布局，应用步骤还会验证完整的结构化数据，并将 data.status 标记为 approved。任何无效的选择图表会在计划被复制之前拒绝整个审查。选择非图表布局会移除未使用的草稿图表数据。应用后，面部和字幕的清除状态保持待定，直到组合与真实合成帧进行检查。

5. 创作一个 HyperFrames 组合

使用一个 index.html 和一个暂停的 GSAP 时间线。每个批准的卡片成为一个由计划的 program_start_s 和 duration_s 键控的 .clip。保持运动可寻址，并从数据属性（而非挂钟计时器）派生时间。

对于图表提示，仅在该暂停时间线中以绝对组合时间进行动画。条形图从一个零基线揭示；饼图扇区按点顺序揭示，几何形状与值成比例；折线路径在其点出现之前按 X 轴顺序绘制。使用相对于源的尺寸和固定布局框，以便寻址、标签和动态值永远不会导致布局跳跃。建议的持续时间为条形图和饼图 5-6 秒，折线图 6-8 秒，始终限制在保留的片段内。

从最接近的存储库示例开始：

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

在所有卡片中保持同一视觉语言，使用相对于源的尺寸，并保持与所选调色的足够对比度。五个不透明面板主题可以使用卡片或遮罩来保证可读性。air 必须保持场景和文本容器透明，仅依靠字体、大小和与背景的颜色对比。在切换镜头或画面中，不允许 air 卡片遮挡拍摄对象的面部。

按计划顺序将渲染帧逐个放入 work/cache/content-cards/index.html。在所有剪辑和轨道上保持相同的 <video> 和 <canvas> 引用尺寸。可选地包含一个标记为 content-cards 的第三个 <clip> 轨道，该轨道包含一个完成所有叠加功能的 <div>。

在所有卡片上放置一个短暂的进入动画（0.2-0.33 秒）。所有静态卡片获得 0.15 秒的退出淡出。图表卡片获得 0.33 秒的退出淡出。将 GSAP 时间线锚定在第一个剪辑开始处，以便 gasped flock seek_only_start 或等效的 seek 行为跳转到特定剪辑，而无需遍历所有之前的剪辑。

对于所有提示，包括静态提示，所有可见元素必须在其 .clip 的持续时间内保持动画。所有提示必须正确淡入其第一个卡片，并将其动画持续时间匹配为 duration_s - (enter + exit)。所有提示必须在 duration_s 结束时完全淡出。

按计划顺序将渲染帧逐个放入 work/cache/content-cards/index.html。对所有剪辑和轨道使用相同的 <video> 和 <canvas> 引用尺寸。可选地包含一个标记为 content-cards 的第三个 <clip> 轨道，该轨道包含一个完成所有叠加功能的 <div>。然后打开合成并使用其原生 seek 命令预览：

python skills/video-add-content-cards/scripts/render_composition.py preview `
  --plan work/content-cards/cards-plan.json `
  --html work/cache/content-cards/index.html

此命令启动一个 HTTP 服务器，打开预览 URL，并挂起直到用户关闭。预览只工作在步骤 5 的未锁定合成上。当预览可见时，检查每个剪辑。在关闭预览之前，不要开始渲染、快照或要求用户确认。

如果 render_composition.py preview 失败，检查依赖项、文件路径问题或无法访问的端口。不要替代此原生预览命令或要求用户定位文件。

6. 渲染并快照

在预览满足预期后，生成透明叠加（alpha）RGB+Alpha QuickTime：

python skills/video-add-content-cards/scripts/render_composition.py render `
  --plan work/content-cards/cards-plan.json `
  --html work/cache/content-cards/index.html `
  --overlay work/cache/content-cards-overlay.mov `
  --fps 29.97

FPS 必须与卡片计划 renderer.rational_fps 匹配。此步骤将 HyperFrames 组合编码为具有优秀 Alpha 通道的无损动画。

其次，为每个卡片生成一个有用的静态帧：

python skills/video-add-content-cards/scripts/render_composition.py snapshot `
  --plan work/content-cards/cards-plan.json `
  --html work/cache/content-cards/index.html `
  --output review/03-content-cards/card-stills/ `
  --fps 29.97

此步骤在每个卡片的 program_start_s + duration_s * 0.3 处捕捉帧到 PNG。在继续之前，打开一些仍然与面部和头部排除区域定义重叠的静态帧。对于有风险的静态帧，重新打开合成 HTML，调整位置外部的安全边距，重新渲染组合，然后重新快照。

7. 打包并集成

将最终叠加文件路径写入计划：

{
  "based_on": {
    "understand": "profane_cyclone",
    "captions": null
  },
  "plan": [ ... ],
  "renderer": {
    "composition": "work/cache/content-cards/index.html",
    "alpha_asset": "work/cache/content-cards-overlay.mov",
    "rational_fps": [2997, 100]
  },
  "review": { ... },
  "summary": { ... }
}

当项目的其余部分需要时，集成步骤会将透明叠加应用到底层视频，而不是此技能的一部分。

确认

/video-understand 是强制性的。 如果缺失，在提出任何问题之前停止，说明该问题。如果 ffmpeg、Python 或支持的 Node 版本缺失，在操作媒体之前停止并说明。

当满足最短卡要求时无需确认。使用 npx hyperframes 获取 Chrome 是自动的。

在步骤 4 的用户选择输入之后，不再进行进一步的人类确认步骤。

视频添加内容卡片