laohan-donghua

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。

核心理念

1. 一个 index.html，一个 render。 禁止分开渲染再 ffmpeg overlay
2. 从零构建，不复制模板。 按 DESIGN.md 从零写每个场景 HTML
3. 时间戳驱动。 官方 npx hyperframes transcribe 拿真实时间戳
4. 每个场景不同视觉风格。 在 DESIGN.md 框架内做变体
5. 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 必须让位给项目内权威流程：

1. docs/AI_TALKING_HEAD_OVERLAY_SYSTEM.md
2. 生成项目的 PROJECT_BRIEF.md
3. 生成项目的 SCRIPT_ANALYSIS.md
4. 生成项目的 ASSET_PLAN.md
5. 生成项目的 AI_SCENE_INDEX.md / STYLE_PROFILE.md / style-profile.json
6. 生成项目的 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

强制规则：

1. 跳过任何 Gate → 停止执行，回到未完成的步骤。没有例外。
2. 默认由 agent 自主推进，不要每步都让用户记命令或确认。只有源视频内容问题、素材缺失会改变真实性、Studio/MP4 预览放行、最终渲染放行时才问用户。
3. "我觉得大概是这样" ≠ 通过。必须有具体的表格/文件/命令输出。

用户侧（模型不参与）

1. 口播稿定稿
2. 录制真人出镜视频
3. 剪掉错误片段，得到干净口播视频

实际输入验收（必须先做）

真实拍摄素材经常不是干净成片。开始 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   # 找到系统最优 workers/quality 设置

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 中运行以下工具验证文字不溢出：

// 方法 1：自动计算最佳字号
var result = window.__hyperframes.fitTextFontSize("显示的文字", {
  maxWidth: 800,      // 容器宽度（overlay bg 通常 960px，内容区 600-800px）
  fontFamily: "Noto Sans SC",
  fontWeight: 900
});
// result.fontSize → 设到 CSS 中

// 方法 2：精确文字测量（无 DOM reflow）
var prepared = window.__hyperframes.pretext.prepare("显示的文字", "900 64px 'Noto Sans SC'");
var layout = window.__hyperframes.pretext.layout(prepared, 800, 1.3);
// layout.width, layout.height → 检查是否超出容器

原则：先确定容器宽度 → 用 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">  <!-- data-duration 可选，框架不使用，仅作文档参考。实际时长由 anchor tween 的 tl.duration() 决定 -->
  <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; /* 宽度按需设计，右侧留空给 face-wrapper */
  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 });

  // BUILD（入场）
  tl.fromTo('.title', { autoAlpha: 0, y: 30 },
    { autoAlpha: 1, y: 0, duration: 0.5, ease: 'power2.out' }, 0.1);

  // BREATHE（ambient）
  const cycles = Math.ceil(DURATION / 4) - 1;
  tl.to('.vignette', { opacity: '+=0.08', duration: 2,
    repeat: cycles, yoyo: true, ease: 'sine.inOut' }, 1.5);

  // Anchor tween（必须）
  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 — 三种模式（固定，不改） */
    #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">

    <!-- Poster frame（GSAP-managed, not a clip） -->
    <img id="poster" src="assets/clip-poster.jpg"
         style="position:absolute;top:0;left:0;width:1920px;height:1080px;object-fit:cover;">

    <!-- Face video (muted, audio from sibling <audio>) -->
    <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>

    <!-- Last frame（GSAP-managed, not a clip） -->
    <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 track -->
    <audio src="assets/audio.wav" data-start="0" data-duration="TOTAL"
           data-volume="1" data-track-index="2"></audio>

    <!-- Ambient background（全时长舞台层：grid 漂移 + 粒子 + vignette） -->
    <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>

    <!-- Scene overlays（每个 mount div 必须有 data-track-index + data-width + data-height） -->
    <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>
    <!-- ...更多场景... -->

    <!-- Captions（word-level 逐词字幕，独立 sub-composition） -->
    <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 = <总时长>;

    // ── Face-wrapper 三种模式（固定参数，不改） ──
    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;

    // 初始状态：HERO（开场全屏人脸）
    mainTl.set("#face-wrapper", HERO, 0);

    // ── Face 过渡时间表 ──
    const transitions = [
      { t: 17.0,  mode: SIDE  }, // s1 开始
      { t: 21.8,  mode: HERO  }, // s1 结束
      // ...按场景填充...
      { t: 174.3, mode: INSET }, // outro 开始（INSET 替代 fade out）
    ];
    transitions.forEach(({ t, mode }) => {
      mainTl.to("#face-wrapper",
        { ...mode, duration: MODE_DUR, ease: "expo.inOut" }, t - 0.15);
    });

    // ── Poster → video handoff ──
    mainTl.to("#poster", { opacity: 0, duration: 0.15, ease: "power2.out" }, 0.1);
    // ── Lastframe hold after video ends ──
    mainTl.set("#lastframe", { opacity: 1 }, TOTAL - 0.5);

    // ── Ken Burns 缓慢缩放 ──
    mainTl.to("#face-video", { scale: 1.03, duration: TOTAL, ease: "none" }, 0);

    // ── Pad to TOTAL ──
    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（命令参数详解）

# 11. 静态检查
npx hyperframes lint                                    # 修 error，triage warning（含对比度检查）

# 12. 运行时检查（lint 看不到 JS 异常、音频同步等运行时问题）
npx hyperframes validate                                # headless Chrome 运行时验证

# 13. 布局检查
npx hyperframes inspect                                 # headless Chrome 视觉布局

# 14. 动画编排分析（新场景或重大改动时运行）
node .claude/skills/hyperframes/scripts/animation-map.mjs compositions/ --out compositions/.hyperframes/anim-map
# 输出：per-tween 摘要、ASCII 时间线、stagger 检测、dead zone 标记、元素生命周期、场景快照

# 15. Gate 1: Studio preview（强制）
npx hyperframes preview                                 # localhost:3002
# → 用户确认布局后才进下一步

# 16. Draft 渲染 + 抽帧验证
npx hyperframes render --quality draft --output renders/draft.mp4
# 抽帧验证（snapshot 优先，ffmpeg fallback）：
npx hyperframes snapshot --at <scene1-t>,<scene2-t>,<scene3-t> --timeout 10000
# fallback（snapshot 不可用时）：
# mkdir -p renders/frames
# for t in <scene1-t> <scene2-t> ...; do
#   ffmpeg -y -ss $t -i renders/draft.mp4 -frames:v 1 -q:v 2 "renders/frames/t${t}.png"
# done
# 每个 PNG 必须 Read 确认无黑帧/裁切/溢出

# 17. Gate 2: MP4 preview（强制）
# npx serve renders -p 8080 -n → 用户确认节奏+音频同步

# 18. Standard 渲染
npx hyperframes render --quality standard --output renders/final.mp4
# 性能选项（按需）：
#   --workers <n>    并行 worker（默认 CPU/2 上限4，短视频用 1）
#   --gpu            硬件编码（Mac: VideoToolbox）
#   --docker         确定性渲染（跨平台一致，AI agent 推荐）

渲染策略：优先整体渲染（官方方法）。如黑帧严重，降级为逐场景渲染 + 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 美化、边缘 feather
• references/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 权威定义