| name | laohan-donghua |
| version | 10.0.0 |
| description | 从口播稿+真人视频生成带B-roll overlay的最终视频。一个index.html+一次render出成片。Use when 用户说生成B-roll、做视频片段、配图动画、Hyperframes动画、教程配图、给视频加特效、做overlay、加动效。 |
Hyperframes B-roll Overlay 视频
从口播稿+真人视频，生成带 B-roll overlay 动画的最终成片。一个 index.html，一次 render。
核心理念
- 一个 index.html，一个 render。 禁止分开渲染再 ffmpeg overlay
- 从零构建，不复制模板。 按 DESIGN.md 从零写每个场景 HTML
- 时间戳驱动。 官方
npx hyperframes transcribe 拿真实时间戳
- 每个场景不同视觉风格。 在 DESIGN.md 框架内做变体
- B-Roll 覆盖率按内容密度决定。 AI/教程密集型通常 30-45%，策略评论 25-35%，个人叙事 15-25%，UI 证据型可到 40-55%
B-roll 目的与 source mode 硬规则
B-roll 第一目标是提升观感、可读性、代入感、节奏感和理解速度，不是给每一句口播取证。对标账号里的数字卡、仪表盘、数据墙不默认等于真实数据；学习的是界面表现、动画华丽程度、转场、字体、特效、节奏和信息层级。
每个 B-roll 场景必须先选一个 source mode：
| source mode | 默认场景 | 处理方式 |
|---|
illustrative | 观点、教学步骤、个人经验、类比、用于强调的数字/数据 | 默认模式。做成更强的原创动画、数字墙、流程图、概念面板；不要要求用户证明。 |
public-source | GitHub stars、官方文档、公开 benchmark、release、论文、公开趋势/新闻 | 需要时联网查公开来源，保存 URL/标题/访问日期/提取事实，再做原创卡片或图表。 |
user-provided proof | 用户自己的后台、花费、私有截图、评论、聊天、账号状态、真实发布数据 | 只有确实需要证明用户私有结果时才向用户要素材。 |
没有真实 proof 素材不是默认卡点。比如“研究了 3 天”“一个月烧了 50 亿 token”这类表达，如果用户没有截图，默认做成示意动画；只有用户明确要证明真实花费/用量时才要截图或数据。超越参考账号的主战场是表现层，不是证明层。
不适用场景
- 从零做视频（无口播稿+无视频） →
/make-a-video
- 纯动画/PPT（无真人出镜） →
/hyperframes
- 竖屏短视频（9:16） → 先明确目标画布和 face-wrapper 架构，再继续；不要默认按 16:9 裁切
make-a-video 是完整视频创作流程（8-gate，从选题到渲染），laohan-donghua 是 B-roll overlay 专项流程（18-step，口播稿+真人视频→overlay 成片）。两者并行，不嵌套。
委托关系
| 职责 | 委托给 | 何时调用 |
|---|
| Composition 编写规则 | /hyperframes | 写 HTML 前 |
| CLI 命令 | /hyperframes-cli | lint/render |
| 媒体处理 | /hyperframes-media | 转录 |
| GSAP 动画 | /gsap | 复杂动画 |
| Catalog blocks 安装 | /hyperframes-registry | 需要官方预制组件时 |
| 规则约束 | rules/hyperframes.md | 自动加载 |
| Render Contract + workspace | CLAUDE.md | 自动加载（11 条硬规则 + 项目结构） |
| 架构/设计参数 | references/ | 构建时查阅 |
写 composition 前，先调用 /hyperframes 获取框架规则。
HyperFrames student-kit 项目内优先级
如果当前工作目录是 /Users/hanzhmacbookair/Documents/hyperframes/hyperframes-student-kit 或其 video-projects/* 子项目，本 skill 必须让位给项目内权威流程：
docs/AI_TALKING_HEAD_OVERLAY_SYSTEM.md- 生成项目的
PROJECT_BRIEF.md
- 生成项目的
SCRIPT_ANALYSIS.md
- 生成项目的
ASSET_PLAN.md
- 生成项目的
AI_SCENE_INDEX.md / STYLE_PROFILE.md / style-profile.json
- 生成项目的
OVERLAY_PLAN.md
在该项目内，禁止继续引用不存在的 scene-index.md；禁止写死 30% 覆盖率；禁止把参考账号下载帧、封面、logo 或精确布局作为项目素材。
执行流程
🚧 流程门控（每步必须通过才能继续）
| Gate | 位置 | 必须产出 | 未通过则 |
|---|
| G1 | 步骤 4 后 | 场景规划表（编号+口播段落+提取文字+布局+情绪+语义类型） | 禁止进入步骤 6 |
| G2 | 步骤 8 后 | 时间戳校准表（帧对齐 data-start/duration，场景间 ≥0.3s 间隔） | 禁止构建 compositions |
| G3 | 步骤 10 后 | 全场景构建检查清单全部 ✅ | 禁止 lint |
| G4 | 步骤 12 后 | lint 0 error + validate 通过 + inspect 无溢出 | 禁止 preview |
| G5 | 步骤 15 后 | 用户在 Studio 明确说"可以" | 禁止 draft render |
| G6 | 步骤 16 后 | 每个 hero 帧 Read 确认无黑帧/裁切/溢出 | 禁止 standard render |
| G7 | 步骤 17 后 | 用户在 MP4 明确说"可以" | 禁止 final render |
强制规则：
- 跳过任何 Gate → 停止执行，回到未完成的步骤。没有例外。
- 默认由 agent 自主推进，不要每步都让用户记命令或确认。只有源视频内容问题、素材缺失会改变真实性、Studio/MP4 预览放行、最终渲染放行时才问用户。
- "我觉得大概是这样" ≠ 通过。必须有具体的表格/文件/命令输出。
用户侧（模型不参与）
- 口播稿定稿
- 录制真人出镜视频
- 剪掉错误片段，得到干净口播视频
实际输入验收（必须先做）
真实拍摄素材经常不是干净成片。开始 overlay 前，先判断输入属于哪类：
| 问题类型 | 例子 | 处理 |
|---|
| 媒体格式问题 | 非 H.264、无音轨、奇数尺寸、异常 fps、竖屏/方屏 | 先转码或选对应 face-wrapper 架构，再继续 |
| 口播内容问题 | 口误、重说、咳嗽、长停顿、重复 take、废话段 | 不要用动画遮盖；先让用户剪映导出干净版，或输出粗剪时间戳清单让用户确认 |
| 文稿不匹配 | 口播稿和实际说法不一致 | 以 transcript 时间戳为准，先修正 SCRIPT.md，再规划 overlay |
| 素材缺失 | 提到网页/数据/聊天/产品但没有截图或录屏 | 先判定 source mode：普通观点/教学/强调数字用原创示意动画；公开事实可联网查源；只有私有结果必须证明时才让用户补素材 |
如果项目提供输入检查脚本，先运行它。例如 HyperFrames student-kit：
npm run input:inspect -- <video.mp4>
硬规则：内容问题没有处理前，不进入步骤 4 的 overlay 场景规划。动画不能拯救坏口播。
阶段一：只要口播稿
步骤 4：读口播稿 → 插入点设计 + 内容规划 + 场景规划
📖 读取：口播稿全文
📖 查阅：项目内 AI_SCENE_INDEX.md / style-profile.json；非 student-kit 项目则使用本 skill 的 references/ 作为备用技法库
这是最关键的步骤。三层规划决定视频质量。
4a. 语义分类 + 默认技法映射：给口播稿每段标记内容类型，并匹配默认技法（模型可覆盖，但默认选择已覆盖 80% 场景）：
| 类型 | Overlay？ | 默认技法 | 来源 |
|---|
| 数据/数字 | ✅ | Counter count-up + 数字 glow | may-shorts-6 scene1 |
| 列举/枚举 | ✅ | Stagger list + strike-through（否定项） | may-shorts-6 scene3 |
| 概念解释 | ✅ | Chrome gradient sweep + text-shadow glow | may-shorts-6 scene6 |
| 对比/VS | ✅ | 分栏卡片 + mask-image feather | — |
| 重点强调 | ✅ | Slam + micro-tremor + scan-line sweep | may-shorts-18 scene1 |
| 冲击/反转 | ✅ | Hero slam + spark burst + glow pulse | may-shorts-18 scene5 |
| 标签/功能名 | ✅ | Chip/pill badge pop + glow pulse | may-shorts-18 scene2 |
| 紧张/倒计时 | ✅ | Letter-spacing breath + vignette breathing | may-shorts-18 scene5 |
| 工具介绍 | ✅ | 命令行/步骤列表 + accent 色 glow | — |
| 总结/CTA | ✅ | 全屏 endcard + shimmer sweep | may-shorts-6 scene8 |
| 纯叙述/过渡 | ❌ | 保持真人全屏（HERO 模式） | — |
| 情感/故事 | ❌ | 保持真人全屏 | — |
4b. B-Roll 覆盖率计算：
先按内容类型选择覆盖率：
- AI/教程密集型：30-45%
- 策略评论：25-35%
- 个人叙事：15-25%
- UI 证据型：40-55%
总视频时长 × 选定覆盖率 = overlay 总时长范围
overlay 总时长 ÷ 场景数 = 平均场景时长（普通 2-4.5s，证据场景 4-8s）
场景数由内容密度决定，不是均分。密集段落可以连续多个场景，稀疏段落保持全屏。
4c. 内容提取：为每个 overlay 场景提炼显示文字。
不是整句口播稿搬上去，是提炼后的关键词/短语。文字量决定布局：
| 提取文字量 | 适合布局 | 典型字号 |
|---|
| 1 个关键词 | hero 大字居中 | 80-120px |
| 1 标题 + 2-3 标签 | 上标题下列表 | 标题 64px, 标签 36px |
| 1 标题 + 1 数字 | 左文右数据 | 标题 56px, 数字 96px |
| 3-5 个并列项 | 横向卡片/竖向列表 | 32-40px |
输出格式：
场景 | 口播段落 | 提取的 overlay 文字 | 文字量 | 建议布局 | 情绪
s1 | "终端输一行..." | "opencli" + "一行命令搞定" + "标题·播放量·时间" | 3 标签 | 列表式 | 震撼
s2 | "想抓知乎热榜..." | "知乎热榜" + "50条" + "链接+摘要" | 标题+数据 | 数据展示 | 专业
4d. 视觉结构匹配：根据内容类型 + 文字量，从项目内 AI_SCENE_INDEX.md / style-profile.json 找视觉结构模式；没有这些文件时才用本 skill 的 references/ 技法库。
这不是复制模板——是参考空间分配和布局方式。用实际文字长度重新设计具体位置和字号。
完成条件：
- 场景清单（编号 + 口播段落 + 提取文字 + 建议布局 + 情绪）
- overlay 总占比符合选定内容密度目标
- 每个场景有明确的文字内容和布局方向
🚧 GATE 1：场景规划表未输出 → 禁止进入步骤 6。必须包含所有列。产出物是一个完整的 markdown 表格。
步骤 5：创建 DESIGN.md
📖 读取：项目本地 .agents/skills/hyperframes/ 或 .claude/skills/hyperframes/；如果当前是 student-kit 项目，优先使用 STYLE_PROFILE.md / style-profile.json
📖 参考：DESIGN.ais-example.md（完整结构模板）
从 visual-styles.md 选择最匹配口播内容的风格。教程类 AI 工具测评通常适合 Swiss Pulse（数据驱动）或 Data Drift（AI/未来感）。
DESIGN.md 必须包含：
- Style Prompt（一句话风格描述）
- Colors（token + hex + role）
- Typography（标题/正文/标签 各用哪个字体）
- Motion Rules（energy / easing entry/exit/ambient / duration entrance/hold/transition）
- What NOT to Do
完成条件： DESIGN.md 包含上述全部段落
阶段二：需要口播视频
步骤 6：环境检查
📖 读取：项目本地 .agents/skills/hyperframes-cli/SKILL.md 或 .claude/skills/hyperframes-cli/SKILL.md（doctor 命令详情）
cd video-projects/<project-slug>
npx hyperframes doctor
npx hyperframes benchmark
CLI 必须从项目目录运行。检查 assets/ 中视频是否为 H.264 MP4，非 H.264 需先 re-encode：
ffmpeg -i raw.mov -c:v libx264 -preset medium -crf 20 -c:a aac -b:a 192k -movflags +faststart assets/clip.mp4
步骤 7：转录
📖 读取：项目本地 .agents/skills/hyperframes-media/SKILL.md 或 .claude/skills/hyperframes-media/SKILL.md（transcribe 命令详情）
字幕系统选择（固定优先级）：
| 优先级 | 方案 | 条件 | 说明 |
|---|
| ★ 首选 | word-level 逐词字幕 | 官方转录输出含 word timestamps | 三态颜色（未读→accent→白色）+ 逐词 scale 弹跳 + 8 方向 text-shadow 描边。参考 may-shorts-6 captions.html |
| ↓ 降级 | sentence-level 整句字幕 | word 数据缺失 | 28px 毛玻璃条底板 |
用官方转录拿时间戳：
npx hyperframes transcribe assets/<video>.mp4 --model small --language zh --json
字幕文本来源：用 Whisper 转录原文，手动修正识别错误（如"翻热节"→"翻热点"）。不用口播稿精简版。字幕是屏幕底部的口播内容，不是场景动画里的文字。
中文识别准确率校验（可选）：如官方识别质量不满意，用硅基流动做对照参考：
curl -s -X POST https://api.siliconflow.cn/v1/audio/transcriptions \
-H "Authorization: Bearer $SILICONFLOW_API_KEY" \
-F "model=FunAudioLLM/SenseVoiceSmall" -F "file=@assets/<video>.mp4"
注意：硅基流动返回纯文本（无时间戳），只能用于校验中文识别准确率，不能替代官方 --json 输出。
步骤 8：精确校准时间戳
读 transcript.json，将步骤 4 的场景清单中每个 overlay 匹配到精确的口播段落：
- 起始时间 = 对应口播句子的开始
- 结束时间 = 对应口播句子的结束
- 帧边界对齐：时间 snap 到 0.0333s 倍数（30fps）
- 场景间留 0.3-0.5s 间隔（避免连续 overlay 太密）
完成条件： 每个场景有精确的帧对齐 data-start/data-duration，overlay 总占比符合步骤 4b 的内容密度目标
🚧 GATE 2：时间戳校准表未输出 → 禁止构建 compositions。产出物是一个完整的时间戳表，每行有 data-start、data-duration、帧对齐确认。
步骤 9：构建 compositions
📖 必读：references/broll-architecture.md（架构约束 + 常见错误速查）
📖 查阅：references/broll-techniques.md（24 种常用动画技法 + 3 大基础设施系统，按场景需要选用）
📖 查阅：references/broll-design-reference.md（face-wrapper 4 种架构、8 种视觉风格、face 美化）
📖 参考：项目内 AI_SCENE_INDEX.md / style-profile.json（按内容类型 + 文字量匹配视觉结构模式）
📖 必读：项目本地 .agents/skills/hyperframes/references/typography.md 或 .claude/skills/hyperframes/references/typography.md（字体排版规则，每个场景都有文字）
📖 参考：项目本地 .agents/skills/hyperframes/references/css-patterns.md 或 .claude/skills/hyperframes/references/css-patterns.md（文字强调效果）
📖 规则：rules/hyperframes.md（自动加载，承重 GSAP 规则）
对每个场景创建 compositions/<scene-name>.html。从零按 DESIGN.md 构建。
推荐 Layout Before Animation 方法论（官方）：先写最终状态的静态 CSS（hero frame），再用 gsap.from() 添加入场动画。
场景视觉设计：
- 每个场景在 DESIGN.md 框架内做变体（同色系不同布局）
- 按
AI_SCENE_INDEX.md / style-profile.json 匹配内容类型的视觉结构
- 变体方式：布局方向（左对齐/居中/卡片）、强调元素（数字/标签/图标）、动画节奏
文字尺寸验证（用官方工具，不靠猜）：
在 Studio preview 中运行以下工具验证文字不溢出：
var result = window.__hyperframes.fitTextFontSize("显示的文字", {
maxWidth: 800,
fontFamily: "Noto Sans SC",
fontWeight: 900
});
var prepared = window.__hyperframes.pretext.prepare("显示的文字", "900 64px 'Noto Sans SC'");
var layout = window.__hyperframes.pretext.layout(prepared, 800, 1.3);
原则：先确定容器宽度 → 用 fitTextFontSize 算字号 → 写入 CSS。不要反过来先猜字号再发现溢出。
完整场景示例（改文字/颜色即用，不需要从片段组装）：
| 示例文件 | 覆盖内容类型 | 包含技法 |
|---|
references/example-a-data.html | 数据/数字 | panel + counter count-up + underline + vignette breathing + anchor |
references/example-b-list.html | 列举/枚举 | panel + stagger list + strike-through + mask-image + vignette breathing + anchor |
references/example-c-concept.html | 概念解释 | panel + chrome gradient sweep + clip-path reveal + text-shadow glow + vignette breathing + anchor |
references/example-d-negate.html | 否定/反转 | X-mark pop + global strike + mask-image feather + vignette breathing |
references/example-e-affirm.html | 肯定列表 | check-list stagger + dual-accent + mask-image feather + vignette breathing |
references/example-f-punch.html | 短冲击强调 | burst flash + punch card + text-stroke outline（<1s，带退场） |
references/example-g-cta.html | CTA/Outro | logo crystallize + shimmer sweep + underline scale + wordmark fade |
references/example-h-stamp.html | 价格/印章强调 | stamp badge（旋转弹入）+ banner bar（横向展开）+ backdrop blur |
用法：复制最匹配的示例 → 改 data-composition-id、文字内容、颜色、DURATION → 按需增减元素。
最小模板（极简骨架，仅用于无法匹配上述 8 种示例时）：
<template id="<scene-name>-template">
<div data-composition-id="<scene-name>" data-start="0"
data-duration="<时长>" data-width="1920" data-height="1080">
<div class="bg"></div>
<div class="vignette"></div>
<div class="title">标题</div>
</div>
<style>
[data-composition-id="<scene-name>"] .bg {
position: absolute; top: 0; left: 0; width: 960px; height: 1080px;
background: linear-gradient(160deg, #0a0e1a, #0d1225);
mask-image: linear-gradient(to right, #000 0%, #000 calc(100% - 80px), transparent 100%);
}
[data-composition-id="<scene-name>"] .vignette {
position: absolute; top: 0; left: 0; width: 960px; height: 1080px;
pointer-events: none;
background: radial-gradient(ellipse at 50% 50%, transparent 30%, rgba(0,0,0,0.5) 100%);
opacity: 0.2;
}
[data-composition-id="<scene-name>"] .title {
position: absolute; top: 120px; left: 80px;
font: 900 96px/1 "Noto Sans SC", sans-serif; color: #f5f5f5;
}
</style>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<script>
(() => {
const DURATION = <时长>;
const tl = gsap.timeline({ paused: true });
tl.fromTo('.title', { autoAlpha: 0, y: 30 },
{ autoAlpha: 1, y: 0, duration: 0.5, ease: 'power2.out' }, 0.1);
const cycles = Math.ceil(DURATION / 4) - 1;
tl.to('.vignette', { opacity: '+=0.08', duration: 2,
repeat: cycles, yoyo: true, ease: 'sine.inOut' }, 1.5);
tl.to({}, { duration: DURATION }, 0);
window.__timelines['<scene-name>'] = tl;
})();
</script>
</template>
构建检查清单：
□ 根 div 有 data-start="0" + data-duration + data-width + data-height
□ 内部元素没有 class="clip" / data-start / data-duration / data-track-index
□ CSS 全部用 [data-composition-id="xxx"] scope
□ 文件有 <template> 包装 + <script src="gsap.min.js">
□ 背景最低 3 层：渐变底 + vignette + 至少一个漂移/呼吸元素
□ 所有彩色文字有匹配色 text-shadow glow
□ 按 DESIGN.md motion token 选 easing/duration
□ 两阶段：build（入场）+ breathe（ambient）
□ overlay 模式不写退场/resolve 动画（outro 除外）
□ 禁止 Math.random() / Date.now() / repeat: -1
□ 文字尺寸已用 fitTextFontSize 或 pretext 验证，不溢出容器
□ 每个场景的文字内容来自步骤 4c 的内容提取表
□ INSET 场景 bg 用全宽（1920px 或 inset:0），SIDE 场景用 960px + mask-image
步骤 10：构建 index.html
📖 必读：references/broll-architecture.md（mount div 属性要求）
📖 查阅：references/broll-design-reference.md（face-wrapper 4 种架构和过渡时序）
完整模板：
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=1920, height=1080" />
<title><项目名></title>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@400;500;700;900&family=Space+Grotesk:wght@700;900&display=block"
rel="stylesheet" />
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
html, body { width: 1920px; height: 1080px; overflow: hidden;
background: #050b13; font-family: "Noto Sans SC", sans-serif; color: #fff; }
#root { position: relative; width: 1920px; height: 1080px; overflow: hidden; }
#face-wrapper {
position: absolute; top: 0; left: 0; width: 1920px; height: 1080px;
transform-origin: 0 0; transform: translate(0px, 0px) scale(1);
z-index: 0;
}
#face-video {
display: block; width: 100%; height: 100%; object-fit: cover;
filter: contrast(1.04) saturate(1.02) brightness(0.99);
}
#face-wrapper::after {
content: ""; position: absolute; inset: 0; pointer-events: none;
background: radial-gradient(ellipse at center, transparent 60%,
rgba(5,11,19,0.3) 88%, rgba(5,11,19,0.7) 100%);
}
.scene-layer {
position: absolute; top: 0; left: 0; width: 1920px; height: 1080px;
}
</style>
</head>
<body>
<div id="root" data-composition-id="<project-id>" data-start="0"
data-width="1920" data-height="1080">
<img id="poster" src="assets/clip-poster.jpg"
style="position:absolute;top:0;left:0;width:1920px;height:1080px;object-fit:cover;">
<div id="face-wrapper">
<video id="face-video" src="assets/talking_head.mp4"
muted data-start="0" data-duration="TOTAL" data-track-index="1"
playsinline></video>
</div>
<img id="lastframe" src="assets/clip-lastframe.jpg"
style="position:absolute;top:0;left:0;width:1920px;height:1080px;object-fit:cover;opacity:0;">
<audio src="assets/audio.wav" data-start="0" data-duration="TOTAL"
data-volume="1" data-track-index="2"></audio>
<div class="scene-layer" data-composition-id="ambient-bg"
data-composition-src="compositions/ambient-bg.html"
data-start="0" data-duration="TOTAL" data-track-index="0"
data-width="1920" data-height="1080"></div>
<div class="scene-layer" data-composition-id="s1-hook"
data-composition-src="compositions/s1-hook.html"
data-start="17.0" data-duration="4.8" data-track-index="3"
data-width="1920" data-height="1080"></div>
<div class="scene-layer" data-composition-id="captions"
data-composition-src="compositions/captions.html"
data-start="0" data-duration="TOTAL" data-track-index="4"
data-width="1920" data-height="1080"></div>
</div>
<script>
window.__timelines = window.__timelines || {};
const mainTl = gsap.timeline({ paused: true });
const TOTAL = <总时长>;
const HERO = { x: 0, y: 0, scale: 1, opacity: 1 };
const SIDE = { x: 480, y: 0, scale: 1, opacity: 1 };
const INSET = { x: 1340, y: 760, scale: 0.27, opacity: 1 };
const MODE_DUR = 0.32;
mainTl.set("#face-wrapper", HERO, 0);
const transitions = [
{ t: 17.0, mode: SIDE },
{ t: 21.8, mode: HERO },
{ t: 174.3, mode: INSET },
];
transitions.forEach(({ t, mode }) => {
mainTl.to("#face-wrapper",
{ ...mode, duration: MODE_DUR, ease: "expo.inOut" }, t - 0.15);
});
mainTl.to("#poster", { opacity: 0, duration: 0.15, ease: "power2.out" }, 0.1);
mainTl.set("#lastframe", { opacity: 1 }, TOTAL - 0.5);
mainTl.to("#face-video", { scale: 1.03, duration: TOTAL, ease: "none" }, 0);
mainTl.set({}, {}, TOTAL);
window.__timelines["<project-id>"] = mainTl;
</script>
</body>
</html>
关键规则：
<video> 不加 class="clip"- poster/lastframe 由 GSAP 管理 opacity（不是 class="clip" + data 属性）
- mount div 缺
data-track-index / data-width / data-height 任一 = 黑帧
- index.html 不用
<template> 包装（只有 sub-composition 文件才用）
- Face-wrapper 过渡时间表与场景 data-start 对齐，
t - 0.15 提前
- Google Fonts CDN 保留（Studio preview 需要，渲染时编译器自动嵌入）
- 字幕用独立 captions.html sub-composition（track-index 4），不用 inline .cap div
- outro 用 INSET 模式（结尾最后 ~0.6s 可 fade out face 让锁屏画面独占）
- ambient-bg 常开（track-index 0，全时长舞台层）
🚧 GATE 3：步骤 9 的构建检查清单全部 ✅ 后才能进入 lint。逐场景检查，任何一项未通过 → 返回修改对应 composition。
步骤 11-18：验证管线
📖 读取：项目本地 .agents/skills/hyperframes-cli/SKILL.md 或 .claude/skills/hyperframes-cli/SKILL.md（命令参数详解）
npx hyperframes lint
npx hyperframes validate
npx hyperframes inspect
node .claude/skills/hyperframes/scripts/animation-map.mjs compositions/ --out compositions/.hyperframes/anim-map
npx hyperframes preview
npx hyperframes render --quality draft --output renders/draft.mp4
npx hyperframes snapshot --at <scene1-t>,<scene2-t>,<scene3-t> --timeout 10000
npx hyperframes render --quality standard --output renders/final.mp4
渲染策略：优先整体渲染（官方方法）。如黑帧严重，降级为逐场景渲染 + ffmpeg overlay 合成。黑帧预防见 rules/hyperframes.md 的结构性预防清单。
两个 preview gate 强制：Gate 1 确认布局，Gate 2 确认节奏+音频。lint 通过 ≠ 渲染正确。
Overlay 专属规则
以下规则仅适用于 B-roll overlay 模式，通用规则见 rules/hyperframes.md。
Face-wrapper 模式选择（固定优先级）
| 模式 | 参数 | 何时用 | 说明 |
|---|
| SIDE | x:480, y:0, scale:1 | 日常讲解场景（默认） | 左右分屏，960px 内容区 + 右侧全尺寸人脸 |
| INSET | x:1340, y:760, scale:0.27 | outro/CTA、多栏对比、需要全屏宽度的内容 | 小窗人脸，释放完整画面空间 |
| HERO | x:0, y:0, scale:1 | 无场景 overlay 时、冲击/强调时刻 | 全屏人脸 |
禁止：中途直接 fade out face（用 INSET 替代，保留人格存在感）。结尾最后 0.6s 可以 fade out（may-shorts-6 在 CTA 锁定后 fade face 让锁屏画面独占结尾）。
使用逻辑：
- SIDE → INSET 转换用于 outro（人脸缩小但一直在）
- INSET 场景的 bg 必须用全宽（1920px 或
inset: 0），因为人脸只占右下角
- 多栏/多内容需要全屏宽度时选 INSET，不是 SIDE
场景视觉规则
📖 详细规则见 rules/hyperframes.md overlay 美学规范章节。核心要点：
- bg 深色渐变（非纯黑
#000），vignette opacity 0.15-0.3，不需要 grain overlay
- SIDE 场景 bg 960px + mask-image feather（60-100px 右边缘），INSET 场景全宽（1920px 或 inset:0）
- 所有彩色文字加匹配色 text-shadow glow（如
0 0 30px rgba(accent,0.5)）
- overlay 不写退场/resolve 动画（outro 除外）— face-wrapper 缩回 scale 1.0 自然掩盖
- outro 可以有退场 fade（0.8-1.2s）
字幕系统规则
📖 详细规则见 rules/hyperframes.md Captions 章节。核心要点：
- 首选 word-level 逐词字幕（独立 captions.html sub-composition），降级用整句字幕
- 字幕文本用 Whisper 转录原文 + 手动修正（不是口播稿精简版）
- 逐词三态颜色：未读(dim) → 当前(accent) → 已读(white) + scale 1.06 微弹跳 back.out(3)
- 8 方向 text-shadow 描边（非毛玻璃底板）
- 特殊关键词可标 accent 色切换（如"warn"切橙色）
场景密度策略
| 原则 | 说明 |
|---|
| B-Roll 占比符合内容密度目标 | 总 overlay 时长 / 总视频时长；AI/教程密集型通常 30-45%，策略评论 25-35%，个人叙事 15-25%，UI 证据型可到 40-55% |
| 每 10-15s 至少一个场景 | 避免长时间无动画 |
| 场景时长跟口播段落匹配 | 不能太短（看不完）也不能太长（想关掉） |
| 长口播段落拆分多个场景 | 不在一个场景里塞 15s+ 内容 |
项目目录
video-projects/<project-slug>/
DESIGN.md ← 视觉设计（含 motion token）
index.html ← 主编排（video + audio + scenes）
compositions/ ← 场景 HTML
assets/ ← 视频/音频/转录
renders/ ← 渲染产物（gitignore）
知识参考
本 skill 自带：
references/broll-architecture.md — sub-composition 结构、CSS scope、常见错误references/broll-design-reference.md — face-wrapper 4 种架构、8 种视觉风格、face 美化、边缘 featherreferences/broll-techniques.md — 24 种常用动画技法 + 3 大基础设施系统（ambient-bg/captions/face-wrapper）
项目级（自动加载）：
docs/AI_TALKING_HEAD_OVERLAY_SYSTEM.md — student-kit 内 AI/tech 口播增强权威流程CLAUDE.md — Render Contract（11 条硬规则）+ workspace layout + 全部 CLI 命令。构建前必读rules/hyperframes.md — B-roll overlay 完整规则 + 渲染器踩坑 + 性能优化MOTION_PHILOSOPHY.md — 官方美学体系（10 Laws + pre-flight checklist）DESIGN.ais-example.md — 完整 DESIGN.md 结构模板video-projects/may-shorts-6/ — 官方 overlay 参考项目AI_SCENE_INDEX.md / style-profile.json — student-kit 项目内 AI/tech 场景模式库（按语义触发、素材需求、face mode 速查）
委托 skill：
/hyperframes — Composition 编写规则，写 HTML 前调用/hyperframes-cli — init / lint / inspect / preview / render / doctor/hyperframes-media — 转录 / TTS / 背景移除/hyperframes-registry — 安装 catalog blocks（npx hyperframes add <name>）/gsap — GSAP 动画参考
官方源码仓库（本地权威文档）：
/Users/hanzhmacbookair/Documents/hyperframes/hyperframes-repo/docs/ — 超越 skill 文件的官方文档
guides/rendering.mdx — workers/GPU/Docker/质量设置guides/gsap-animation.mdx — GSAP 官方规则guides/performance.mdx — 性能优化guides/common-mistakes.mdx — 7 个常见错误concepts/determinism.mdx — 确定性渲染原理concepts/data-attributes.mdx — data 属性完整参考reference/html-schema.mdx — HTML Schema 权威定义
