演示视频
你需要一个应用的精美视频。此技能是经过测试、开箱即用的完整流程。它基于 HyperFrames（HTML→视频），但增加了那些重新发现起来很痛苦的部分：如何自行录制应用、当前机器的 ffmpeg 变通方案、精确剪辑配方、品牌设计系统以及会浪费数小时的陷阱。
这里没有任何品牌绑定。 外观是一套带有可替换令牌的设计；视频属于哪个品牌是一个步骤，而非假设——见 阶段 0B。
🚦 阶段按主题分组，而非按工作顺序
在按顺序执行以下任何操作之前，请先阅读此部分。捕获机制放在一起记录是因为它们属于同一主题，但捕获不是第一件事：
概念先行：这个视频是干什么用的？→ 叙事弧线 → PLAN.md (+ SCRIPT.md) → 批准
(这是 `video-plan` 技能，不是本技能) │
│
↓ 只有到现在才存在素材 ──────────────────────────────────────────────────────┘
阶段 0 环境 → 0B 品牌 → 1A 捕获 / 1B 导入 → 3 准备 → 4 合成
→ 5 验证 → 6 渲染
先拍摄看起来更快，但实际上并非如此：叙事弧线是审查时会变动的内容，而针对未达成共识的弧线拍摄的每一个镜头都需要重拍。阶段 0 和 0B 是你可以提早运行的两项——它们用于安装工具并确定调色板。阶段 1 中的一切都等待批准的方案。
🚀 快速试用——快速路径
🚨 由调用者选择此模式。你永远不应自行决定。 你可以用一个问题来提议。你不能从周围环境推断，以下情况尤其不是同意：
- 他们附加或解压了技能包——这只是某人安装工具的方式，而非对他们想要制作内容的声明；
- 请求听起来是探索性的，或者没有附带简报；
- 这是他们第一次请求；
- 你觉得快速路径更方便。
如果有人说“给我做一个 example.com 的视频”，他们就是在要求一个 example.com 的视频。替他们决定他们其实想要一个一次性视频，就等于是当他们期待成品时，给他们一个无声、无品牌的 1080p 草稿——而且你跳过的部分（叙事弧线、文案、品牌）正是那些之后无法补救的部分。
如果不确定，就问。 “这是一个快速冒烟测试，还是一个你实际会给人看的视频？” 一句话，就能确定你处于哪种模式。
以下的审批关卡之所以存在，是因为一个有人会看到的视频出错的代价很高。一次性运行则不是那样，而且让审核者经历一轮概念确认只是为了确认捕获是否正常，这正是好工具在头十分钟就被放弃的原因。两种失败都是真实的；只有调用者知道哪种情况适用。
一旦调用者选择了快速路径：
- 复述一遍 —— 一句话：“我将其视为冒烟测试，因此跳过审批轮次和品牌；如果需要完整流程，请说一句话。” 确认优于宣告：这为处于另一种模式的调用者提供了最后一次低成本纠正的机会。
- 两行
PLAN.md—— 一句描述叙事弧线，三到四个节拍。没有SCRIPT.md，没有签收轮次。 - 中性调色板。 无品牌提取，无审批预览。
- 无声。 无旁白，无 ElevenLabs 密钥，无脚本检查。
- 仅 1080p。 无 4K，无发布步骤。
- 仅限内部使用 —— 不向客户展示，也不发布到任何公开场所。如果之后有人想展示它，那就是另一个视频了：正确运行，而不是将批准事后附着到草稿上。
本文件中的所有其他内容仍然适用——捕获路径、验证、模糊同意中止。那些不是仪式；它们是防止有问题的视频看起来正常的东西。
🛑 概念关卡
本技能不从请求开始。它从已批准的 PLAN.md 开始（加上面对客户的任何内容的逐字 SCRIPT.md）。上述快速路径是唯一的例外，并且仅在房间外无人会看到结果时才可用。
如果没有，那就是 video-plan 技能的工作，它只需要一轮：视频的用途、演示与指南、语言、叙事弧线、节拍列表、文案。先做那个再回来。为了编写方案而阅读应用是可以的——但录制则不行。
无论方案由谁编写，你都有两件事要做，而且两者都是问题，而非宣告：
询问是否要先进行分析。 “我应该检查应用程序并提出要展示的内容，还是你已经有想法了？” 正确阅读产品确实需要时间，而调用者可能有不同的起始界面或成熟的想法。不要将他们的时间花在你的假设上。
在拍摄前获得节拍列表的首肯。 不是重新批准整个 PLAN.md——方案已经批准了——而是你即将录制具体的镜头列表：这四个节拍，按此顺序，突出显示这些东西。这只需要一条消息，并且是最后的低成本时刻。捕获之后，更改顺序意味着重拍，因为针对不同叙事弧线剪辑的节拍无法装入现有的剪辑中。
在聊天中确认捕获来源。 要录制哪个环境，因此是哪个版本的产品，由用户决定，且目标会移动。
🚦 第一个决定：素材来自哪里？
如果目标是可以访问的网页 → 自行录制。不要索要录屏。
可访问的 URL？── 是 ──┬── 是你的（或你客户的，带有简报）
│ │ └─▶ 阶段 1A · 捕获 (references/playwright-capture.md)
│ │
│ └── 是别人的网站
│ └─▶ 阶段 1A · 捕获，并加上 references/foreign-sites.md
│ (权限关卡、同意墙、粘性页眉、
│ 懒加载矩形偏移——先阅读，捕获原语在陌生 DOM 上不安全)
否 (桌面应用、Figma、原生工具、移动端、
或用户已提供 .mov)
▼
阶段 1B · 导入录屏
自己的应用和第三方网站是相同的流程，只是捕获过程不同。 合成、设计系统、验证层和画外音不变；品牌提取已经能读取任何在线网站。变化的是你默认只能访问公开内容，不能注入状态，不能写入任何内容，并且需要测量不断变动的 DOM。（认证后的第三方捕获是可能的但不推荐：需要明确的每个域批准、启用浏览器沙箱，并在结束时销毁会话文件——references/foreign-sites.md §0。）
这不是风格偏好——捕获路径能产生更好的素材，而且工作量大约减半。手动录屏迫使你从像素反向工程时间线、查找和剪切作者的重试、手动测量每个聚光灯、裁剪浏览器 Chrome 以及审计隐私。自动化捕获从一开始就没有这些问题，是无 Chrome 的，让你选择文本大小，并且可以在 UI 变化时重跑。在相同流程上测量：71 秒的录屏需要密集的帧扫描，而 28 秒的捕获每个源时间和元素矩形都可以在 beats.json 中获取——成品帧中的文本大小是 1.5 倍。
即便如此，如果用户已经录制了一些内容，在捕获之前先观看。 它编码了他们对自己产品的模型——展示哪些功能、以什么顺序以及要点是什么。这种编辑判断是捕获路径无法免费提供的。
按需阅读参考文献——不要预加载它们：
| 需求 | 阅读 |
|---|---|
| 这个视频属于哪个品牌？ (令牌、标志、字体——网站即可) | references/brand-style.md |
| 自行驱动并录制应用；2 倍速；光标；认证；beats.json | references/playwright-capture.md |
| 目标是你未拥有的网站 (权限关卡、同意墙、粘性页眉、懒加载矩形偏移、实时媒体) | references/foreign-sites.md——在捕获前阅读 |
| 在容器或 CI 中无头运行 (缺少 CJK/表情符号字体、Chromium 首次捕获时崩溃、安装后“可执行文件不存在”) | references/container-capture.md |
在更改 capture-lib.js 中的任何内容后 | node <skill>/scripts/test-foreign-sites.mjs——本地测试夹具，无网络；每个案例都是已发货的缺陷 |
| 聚光灯框错了像素，但坐标正确 | references/foreign-sites.md §4——使用 stableRect，而非 boundingBox |
| 以另一种语言重新捕获；重新调整现有剪辑的时间，无需重建时间线 | references/playwright-capture.md §9-10 |
收到一个充满重试的 .mov——挑选并剪切干净的镜头 | references/multiple-takes.md |
| ffmpeg/CLI 无法运行、“0 GB 可用空间”、bunx、权限问题 | references/pitfalls.md §6 + 运行 scripts/setup-render-env.sh |
| 精确的剪切/裁剪/速度/冻结/帧移除命令 | references/ffmpeg-recipes.md |
| 外观：窗口、聚光灯、卡片、交叉淡入淡出、冻结帧 | references/design-system.md (+ assets/template.html) |
| 构建两部分的特性指南 (概念面板、操作节拍、编排) | references/guide-track-build.md |
| 旁白 / ElevenLabs 画外音，配额 + 声音陷阱 | references/voiceover.md |
| 配音是否真的说出了脚本内容？ (品牌名称、缩写) | scripts/verify-narration.mjs——退出码 1 = 修复 |
| 应用渲染为空、500 错误或“离线” (发生在捕获之前) | references/pitfalls.md §17 |
| TIMELINE.md 契约；对“0:12 拖动”反馈的处理 | references/timeline-and-review.md |
| 我应该把聚光灯放在哪里？ (切勿目测) | references/design-system.md → “切勿目测坐标” |
| 聚光灯边缘总是切到某些东西，无论使用什么内边距 | scripts/measure-spots.mjs——改为测量布局的空白 |
| 控件真的无法框选 (某个边缘没有 6px 的条) | references/design-system.md → “有时没有框” |
| 应用的浏览器 Chrome 挡住了说明卡片的位置 | references/design-system.md → 每个节拍的卡片布局 + 在剪辑处分割卡片 |
| 冻结帧显示的是点击后的状态 (聚光灯落在空白处) | references/playwright-capture.md §16——在 _hover 标记处冻结 |
| 脚本化的聊天信息消失了；代理“完成”但实际上没有 | references/playwright-capture.md §17-18 |
| “为什么我的素材是冻结的/错位的/报错的” | references/pitfalls.md |
| 点击时出现多余的黑色圆圈；一个修复静默地什么都没做 | references/pitfalls.md §11-13 |
| 检查提示 PASS 但实际有问题 | references/pitfalls.md §15 |
| 每次渲染前 (机械审计，退出码 1 = 修复) | scripts/audit-composition.mjs |
| 主体实际上可见吗？ (聚光灯清晰度 + 卡片遮挡；退出码 1 = 修复，退出码 2 = 无法检查) | scripts/verify-material.mjs |
| 快照后：按聚光灯缩放裁剪 (全帧读取会漏掉被裁剪的文本) | scripts/crop-spots.mjs |
| 画面是否展示了旁白正在谈论的内容？ (带旁白的指南，按主题划分) | scripts/verify-topics.mjs |
| 应用记录你的操作 —— 快照前，恢复后 | scripts/app-state.mjs |
| 视频旁边的独立培训文档 (仅在要求时) | references/companion-docs.md |
在快照上工作循环，而不是渲染。 snapshot --at t1,t2,… 花费几秒；渲染花费几分钟。先在静帧上搞定构图、聚光灯坐标、文案和隐私，然后渲染一次并验证动态。
阶段 0——环境 (每台机器/会话一次)
一条命令处理所有情况——macOS 或 Linux、健康的机器、缺失或精简的 ffmpeg、缺失的 HyperFrames 或虚假的“0 GB 可用空间”statfs bug。不要手动诊断：
render_env="$(bash <skill>/scripts/setup-render-env.sh)" && eval "$render_env"
不要用 source <(…)。 Bash 报告的是 source 的状态，而非为其提供输入的进程替换的状态，因此中途失败（无网络、安装失败）的引导脚本会报告成功，并给你留下一半设置的环境变量。先捕获会暴露失败，并在失败时不应用任何设置。
它会在缺少时安装 hyperframes（锁定版本），解析一个完整的 ffmpeg，仅当此操作系统确实存在该错误时修补磁盘检查，并导出 HYPERFRAMES_FFMPEG_PATH、HYPERFRAMES_FFPROBE_PATH、PRODUCER_BROWSER_GPU_MODE 和 HYPERFRAMES_CLI。
它探测的是滤镜，而非名为 ffmpeg 的二进制文件。 流程需要 fps/pad（阶段 3 帧固定）、crop（阶段 1B 浏览器 Chrome 移除）和 freezedetect (audit-composition.mjs + 阶段 6 死音扫描)。两个精简版本通常已在 PATH 上，并且会通过简单的检查，然后在中途失败：Playwright 的捆绑版 ffmpeg 和 Remotion 的合成器捆绑版。解析顺序：系统完整 ffmpeg → brew (macOS) → ~/.hyperframes-cli 中的 ffmpeg-static/ffprobe-static 包（所有平台，无需 sudo——Linux 上的常规路径）→ 作为最后手段的包装过的 Remotion 合成器捆绑版，该版本会发出警告，因为它没有 freezedetect，因此那两个冻结检查会静默通过，你必须手动验证（陷阱 #1、#16）。
然后通过它指向的本地 CLI ($HYPERFRAMES_CLI) 进行渲染，绝不要用 bunx/npx hyperframes——那些会重新创建一个新的副本...
...（已截断以进行翻译）