video-add-content-cards

视频添加内容卡片

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

依赖项

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

要求 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：源素材到成片的映射；如果没有剪辑，则为恒等时间线
• 可选的已选调色修订版本，用于根据该视觉效果评估对比度或调色板

即使没有剪辑或调色，该技能也有效。当字幕处于启用状态时，先运行字幕技能，依赖其当前修订版本，并将字幕占据的区域视为硬性禁入区。内容卡片必须先于动态图形处理，只要两者都处于启用状态。上述相对顺序规则适用于每一组已选技能对。仅声明实际使用的依赖项，并在 based_on 中记录其当前修订版本。

在整个卡片提示期间（包括进入和退出阶段），将每位主要人物、前景人物、发言者、主持人、受访者或具有重要语义意义人物的可见面部和头部轮廓视为硬性禁入区。仅出现在背景中、并非叙事或视觉焦点的偶然人物不受此限制；无法确定时，按需保护。如果卡片与受保护的面部或头部相交，应先重新定位，然后缩放或重新设计。如果不存在合规的位置，则跳过该卡片。

工作文件

work/content-cards/cards-plan.json          # durable editorial plan
work/cache/content-cards/index.html         # code-is-the-edit composition
work/cache/content-cards-overlay.mov        # transparent render contribution
review/03-content-cards/card-stills/        # one useful still per card
review/03-content-cards/content-cards-preview.mp4  # optional short cue windows
review/03-content-cards/content-cards-summary.md
review/03-content-cards/content-cards-review.html  # local candidate review board
review/03-content-cards/content-cards-review-assets/  # one source frame per candidate
review/03-content-cards/content-cards-review.json  # validated human choices

可复用的审阅页面已提交至 skills/video-add-content-cards/assets/content-cards-review.html。 填充后的 HTML、截图、叠加层和预览渲染均可复现。 请将计划文件保存在 cache/ 之外。计划必须包含所有可见文本、时间、位置、视觉处理值、渲染器合成路径、渲染器素材路径和源 FPS，以便删除 work/cache/ 后重新生成临时 HTML 和透明通道素材。记录一个计划级别的 renderer_recipe，其中包含源示例/模板、合成输出路径、渲染引擎，以及每项本地运行时素材的输出路径、确切版本、来源和 SHA-256。仅保存缓存的 HTML 文件或下载的脚本而没有持久化配方，并不能满足可复现要求。

工作流

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 替代此操作，也不要让用户去查找并点击文件。图库会对比全部六种主题，并可通过原生选择器聚焦某一列：

主题	起始字符
almanac	暖奶油色、衬线字体、沉稳
teal	深色新闻广播风格、青色点缀
editorial	纪实风格、墨色与琥珀色
dotgrid	像素等宽字体、技术感
apex	高能量体育风格、红色点缀
air	透明的 Lexend 字体排版，无底板或遮罩层

严格按以下顺序一次只问一个问题：

1. 此次编辑应使用哪种主题？
2. 此次编辑的目标卡片数量是多少？提供计算出的建议值作为默认值。
3. 必须包含哪些卡片类型？提供 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 "Keep product names verbatim"

脚本会将保留的语义时刻映射到节目时间，并省略剪辑中移除的时刻。它会保留源范围和证据引用，将时长限制在所属片段内，并将文案、位置和视觉处理标记为 draft。stat 卡片以 metric-spotlight 开始；list 卡片以 side-by-side 开始；候选内容审核可以保留常规布局，或将列表切换为 parallel-columns。 已确认的访谈内容会以 brief 的形式存储在 cards-plan.json 中。多个值请重复使用 --must-include-type；不适用的标志则省略。为兼容性，仍接受旧版可选的简报字段，但常规访谈中不会使用这些字段。

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、普通统计卡片或不使用卡片。 对于图表布局，将冗长说明压缩为简洁的辅助文案，但不要改变其含义。图表应主要传达关键数值及其变化或关系。不要逐项列举或重述图表中已显示的数值、标签、时段或单位。

此阶段保留所有有证据支持的候选项。以简报中的目标卡片数量为准，但如果证据表明更精简或更多卡片更合适，也可以调整。

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

如果命令失败，请诊断并重试；不要让用户自行查找文件。页面会显示每一帧源视频画面、卡片 ID、节目时间、可编辑文案、视觉样式和位置。图表布局还会显示可编辑的结构化数据和点位证据引用。请根据显示的证据逐项审核所有内容，然后再批准。 每个候选项 初始均未选中，位置设为 bottom。更改位置会让灰色卡片代理覆盖在实际画面上，以便在批准前查看碰撞风险。用户选择卡片、编辑文案、选择样式和位置，点击 Copy summary，再将显示的摘要粘贴回 对话中。

展示，然后停止。 等待用户粘贴选择摘要。不要根据未经核验的候选草稿编写 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 时间轴。每张获批卡片对应一个 .clip，以计划中的 program_start_s 和 duration_s 为键。确保动画可安全跳转，并从数据属性推导时间，而非使用墙上时钟计时器。

对于图表提示，只通过暂停状态的时间轴，按合成中的绝对时间制作动画。条形图从同一零基线开始显现；饼图扇区按数据点顺序显现，几何尺寸与数值成比例；折线按 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 必须保持场景和文字容器透明：不得使用纯色或半透明底色矩形、胶囊形底色、局部色块、装饰性色条或全画面遮罩。主要文字使用白色，辅助小字使用浅灰色。可以使用 Lexend 字重、文字阴影、细描边、间距和对齐，但不得添加装饰线、圆点或填充的几何装饰。不得遮挡说话者或字幕。

明确传入源 FPS；保留 24000/1001 等小数帧率，不要四舍五入为 24 或 30。在 Windows 上使用 npx.cmd、项目本地 npm 缓存和本地资源：

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

渲染时不得依赖远程字体、图像、脚本或样式。对于 air，将 assets/fonts/Lexend-VariableFont_wght.ttf 复制到项目合成资源中，并像记录其他运行时资源一样，在 renderer_recipe 中记录其输出路径和 SHA-256。

获批计划必须保留合成中使用的确切样式和动画数值，而不能只记录 edge-slide 这样的文字标签。至少记录面板几何尺寸和内边距、颜色、边框、字体大小／字重／行高，以及进入／规则／文字／退出的时长、偏移量、错开间隔和缓动方式。这样就能根据计划复现创意 HTML，而非将决策隐藏在一次性缓存中。

6. 审核小型素材

在每个提示词的中段附近截取一帧静帧：将卡片叠加到该时间戳对应的实际基础视频帧上；如果当时有已批准的字幕叠加层，则先合成字幕。仅含透明背景的 HyperFrames 截图只能证明 Alpha 通道，无法证明人脸避让，不能作为充分的审批依据。只要入场、退场或移动元素靠近受保护的人脸或头部，也要检查一段较短的合成动态窗口。如果任何一帧与受保护区域重叠，审批前先重新放置卡片。默认情况下不要渲染完整预览。

检查：

• 文案忠实于其 evidence_ref；
• 源时间与节目时间映射正确；
• 文本清晰易读且没有溢出；
• 对于图表提示词，关键数值及其变化仍是主要视觉信息，辅助文案不会重述图表所示的数据集；
• 已批准的视觉处理方式与规范卡片类型一致；
• air 没有底板、装饰线、填充的几何点缀或全画面遮罩；
• air 使用白色主文本和浅灰色辅助文本；
• 在整个提示词期间，受保护的人脸、可见头部轮廓和字幕均保持清晰；
• 动画与口播内容同步；
• 卡片区域之外的 Alpha 通道保持透明。

展示并停止。 展示卡片静帧和任何较短的动态窗口，指出卡片 ID，然后等待审批。文案、位置或时间尚有争议时，不要渲染完整叠加层。

每个已批准的提示词都必须在 review/03-content-cards/card-stills/ 中有对应的合成静帧，设置 face_clearance: "verified"，并在计划中记录静帧路径。在 review/03-content-cards/content-cards-summary.md 中记录审核结果。

在人脸避让审核之前，用户必须已选定卡片及其初始位置。至少要对提示词开始、中段和结束附近的画面进行采样，并检查说话者有明显移动的任何画面，作为最低证据门槛。最终审批仍要求整个提示词期间均无遮挡。只有在人脸轮廓、眼睛、鼻子、嘴巴和表情区域始终无遮挡时，才设置 face_clearance: "verified"。启用字幕时，使用包含实际渲染字幕叠加层的静帧，并设置 caption_clearance: "verified"；未启用字幕时，设置 caption_clearance: "not-applicable"。保存合成静帧路径、决策模式和非空的理由。如果任何采样画面发生重叠，先移动卡片，再缩小其面积或减少标签密度，然后选择其他版式；如果仍无法确保安全，则移除卡片。绝不要为了给卡片腾出空间而隐藏、移动、改写字幕或降低字幕的可读性。

7. 渲染透明叠加内容

优先为每个提示词渲染一个较短的 Alpha MOV，这样几秒钟的图形就不会生成覆盖整个节目的透明视频。每个文件都以源视频的尺寸和精确帧率渲染，然后声明一个带节目时间窗口的渲染贡献。只有在确实更小或合成确有需要时，才使用单个完整时长的稀疏叠加层。

在 project.json 中记录此操作贡献。将 content-cards 放在 captions 之后、motion-graphics 之前；如果字幕已启用，则在 depends_on/based_on 中包含 captions：

{
"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

与字幕组合

将字幕和卡片视为独立的叠加内容。字幕处于上游，其占用区域不可供卡片使用。渲染前解决位置冲突，然后在共享交付阶段按声明的顺序进行合成。当卡片会占据字幕区域时，将其移至其他安全区域；切勿覆盖或移位字幕。

同时添加字幕和卡片时，按以下顺序保留人工审核关卡。首先，完成字幕预设审核及其现有的 呈现 + 停止。然后运行内容卡片候选审核及其 呈现 + 停止，由用户批准卡片并选择其初始位置。只有完成该选择后，Agent 才能编写组合画面并执行人脸／字幕避让检查。之后仍须进行合成静帧审核，并展示避让证据以供最终批准。