explainer 是做什么的？
规格文件列出场景；脚本负责捕获素材、录制旁白、为每个场景构建一个 HyperFrames 子合成，并在最终输出前进行验证。
1. understand 阅读相关代码/文档/应用以了解疑问点
2. capture scripts/capture.py 截图、元素框、录制、涂黑
3. spec 你编写 explainer.json（场景 + 旁白 + 带来源的主张）
4. verify facts scripts/verify.py facts（门槛：未通过前不得配音）
5. build scripts/build_explainer.py（配音、字幕、场景；默认无角色）
6. verify scripts/verify.py all （素材、构建、渲染、音频）—— 循环直到干净
7. render scripts/render.py
路径相对于此包的根目录：即包含 .claude-plugin/ 的文件夹，比本文件高两层（先解析符号链接）。需要公共的 HyperFrames 技能（hyperframes、hyperframes-cli；以及扩展管理用的 hyperframes-registry 和 media-use）。在手动编辑生成的合成之前，先阅读一次 hyperframes。
0. 预检（始终优先）
运行 python3 scripts/setup.py doctor（添加 --json 以便解析）。它会列出每个依赖项、其用途以及针对当前机器的精确安装命令；当缺少必要项时返回退出码 1。
- 必需缺失（ffmpeg、Node.js 18+、HyperFrames 技能，以及配置了
say时的 ElevenLabs 密钥）：用一句话告诉用户每项是什么及其用途，然后提供打印的命令。仅在用户同意后才运行。切勿自行输入或索取 API 密钥：让用户在 shell 中导出ELEVENLABS_API_KEY。 - 可选缺失：向用户提供一次并说明每项能解锁什么功能。Playwright 提供带元素缩放框和整页截图的网页捕获，tesseract（OCR）提供截图上的秘密扫描，ASR（mlx-whisper / openai-whisper）提供音频检查和精确的字时间戳。如果用户拒绝则跳过；相应的检查将变为手动的
review步骤。 - HyperFrames 技能（
hyperframes、hyperframes-cli、hyperframes-registry、media-use）：如果缺失，推荐运行npx hyperframes skills。在构建或编辑任何合成之前，先阅读hyperframes（以及用于渲染问题的hyperframes-cli）。
设置（首次运行，或用户想更改某些内容时）
python3 scripts/setup.py show 输出当前配置。如果不存在配置，则询问用户（一次问一个简短问题，提供默认值）并写入：
| 问题 | 标志 | 选项 |
|---|---|---|
| 哪些部分？ | --features | explainer 单独（无需角色文件），或 character,explainer 以允许主持人 |
| 旁白语言 | --language | ISO 代码（en、es……）：选择一个清晰的 say 语音，并告诉 ASR 应期待的内容 |
| 旁白语音 | --narration-voice | voice（已配置的提供商）、say（免费，macOS）、none（仅字幕） |
| 语音提供商 | --voice | elevenlabs（来自环境变量的 ELEVENLABS_API_KEY + --voice-id）、say、none |
| 信用限制 | --max-chars、--max-seconds、--daily-credit-cap | 用户指定的数字 |
| 渲染 | --render | local、cloud、preview |
| 尺寸 | --size | 1080x1920（默认）、1920x1080、1080x1080 |
python3 scripts/setup.py init --features explainer --voice say --render local --yes
init 会首先运行 doctor 并提供相同的安装选项。如果已存在配置，它会询问是否覆盖（非交互模式下传递 --force）。setup.py voices --lang <code> 列出某语言的 macOS 语音和用户的 ElevenLabs 语音；--say-voice "<name>" 选择一个。切勿索取、打印或写入 API 密钥。
1. 理解，然后编写脚本
- 首先从源头获取事实：阅读代码、PR、文档或应用。一个错误的解释器比没有更糟。先展示事物的整体轮廓再介绍细节，用一个真实案例完整演示（实际名称、实际值），并将每个场景限制为一个想法。
- 时长（≤
styles.explainer.max_seconds）：3-5 个场景，每个约 6-12 秒，再加一个结束标题。TTS 每秒约读 2.4 个单词：保持每个场景的旁白在约 25 个词以下。
为每个视频选择样式
本包仅提供中立的默认样式。根据主题、受众和用户的品牌或偏好为每个视频选择一种样式，并在必要时询问（针对品牌、公共频道或系列视频）。不要习惯性地重复上一个视频的外观。将样式放入规格文件的 style 块中：
| 键 | 值 |
|---|---|
| palette | background、panel、ink、muted、accent、highlight（CSS 颜色；确保文字对比度 ≥ 4.5:1） |
| typography | font、mono（HyperFrames 捆绑字体）、title_scale（0.6-1.6） |
| layout | align（left、center）、radius（0-60）、background_style（solid、gradient） |
| motion | motion（calm、normal、lively）：每个动作的持续时间和缓动 |
| captions | caption_style（box、outline、plain、none）、caption_position（bottom、top） |
配置中的 brand 工具包（相同键）会逐键覆盖你的选择。主持人设置遵循视频背景，除非其自身块包含自己的 style（参见 talking-clip）。
2. 捕获素材
python3 scripts/capture.py url http://localhost:3000/login --name login
python3 scripts/capture.py url http://localhost:3000/login --name login --box "#submit" # 需要 Playwright
python3 scripts/capture.py screen --name settings --interactive
python3 scripts/capture.py record --name signup --seconds 12 # macOS
python3 scripts/capture.py add --name diagram --file ./docs/arch.png
python3 scripts/capture.py redact --name login --box 820,410,360,48 # 或 --blur
python3 scripts/capture.py list
url使用 Playwright（如果已安装，需要用于--box和--full-page），否则使用无头 Chrome。如果没有 Playwright，请以像素矩形[x, y, w, h]形式提供焦点框（从 PNG 中读取，默认比例下为 CSS 像素的两倍）。如果 Playwright 位于虚拟环境中，请使用该解释器运行脚本（.venv/bin/python scripts/capture.py ...）。--box以图像像素记录元素的框，以便场景可以直接放大到该位置。默认--scale 2可在放大时保持文字清晰。- 捕获能说明故事的最小区域；缩小到手机框架内的完整桌面屏幕会难以阅读。使用焦点框进行缩放。
- 一个完整的网站作为一个项目而非单张截图：
npx hyperframes capture <url>（hyperframes-cli）。
3. 编写规格文件
examples/explainer/explainer.json 是一个完整的工作示例。将规格文件放在素材的根目录：它引用的代码文件和捕获内容必须位于规格文件所在的文件夹内。场景类型：
| 类型 | 需要 | 显示内容 |
|---|---|---|
screen | capture，可选 focus: [{"box": "#sel" 或 [x,y,w,h], "label": "...", "at": s}] | 截图，然后摄像机移动到每个框，并带有高亮和标签 |
recording | capture（一个视频），可选 focus | 静音屏幕录制，相同的摄像机和标签 |
code | file、lines: "a-b"（≤ 24，每行 ≤ 约 49 个字符（垂直方向））、highlight: [{"lines": [a, b], "at": s}] | 代码显示在卡片上，逐行出现，关键行有标记条 |
diagram | nodes: [{"id","label","sub"?,"highlight"?}]、edges: [[a, b]]，可选 flow: [ids] | 框和箭头逐步构建，一个标记沿 flow 移动 |
title | text，可选 sub、dur | 结束或章节卡 |
运动，适用于任何场景（可选；颜色和时机来自样式，因此像样式其他部分一样根据视频变化）：
| 键 | 说明 |
|---|---|
callouts: [{"type": "circle" 或 "arrow", "box": [x,y,w,h] 或 "#sel", "at": s, "note": "..."}] | 手绘圆圈或箭头，逐渐绘制；在 screen/recording 场景中为图像像素，其他地方为帧像素 |
kinetic: [{"text", "at", "dur", "y"?, "from"?}] | 用于强调的文字猛拍效果；谨慎使用（每个视频一或两次） |
counter: {"to", "from"?, "at", "dur", "prefix"?, "suffix"?, "label"?} | 一个计数动画，最终停留在精确值上 |
顶层 transition: "wipe" 或 "fade" | 每次剪辑时的转场效果（默认为 none） |
它们遵循注册表项 count-up、caption-kinetic-slam、hw-callout-circle 和 hw-arrow（参见 /hyperframes-registry）。style.hand_font: "Caveat" 使用 npx hyperframes add 获取该手写字体。不要每个视频都使用所有功能；选择故事所需的功能。
每个带有 narration 的场景必须带有 claims：它包含的每个技术陈述，需带有 source（相对于规格文件的 path:lines、capture:<name>、https://...、doc:<name>）和 status: "supported"（在你对照该来源检查后）。"claims": [] 表示旁白没有提出技术主张。未支持的主张会被修正或删除，绝不进行配音。
默认没有角色。 解释视频就是旁白、字幕和视觉内容。仅在用户要求添加主持人时，或在你认为这能增加价值（如有主持人的系列视频、友好的入门介绍）并向用户说明理由时，才添加角色。然后添加一个 presenter 块（intro / outro，每个块包含 {"text", "plan"?, "mood"?, "style"?, "claims"}；计划遵循 talking-clip 格式）并使用 --presenter 构建。还需要 features.character。主持人场景也有字幕（除非规格文件设置了 "captions": false）。examples/explainer/explainer-with-presenter.json 是示例。
4-5. 事实门槛，然后构建
python3 scripts/verify.py facts --spec explainer.json
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer --estimate
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer [--confirm] [--presenter]
--estimate 输出时长和 ElevenLabs 信用点数；在消费前告知用户，然后使用 --confirm 构建。构建器也会运行事实检查，如果失败则停止。字幕显示脚本本身中的词语（大小写、标点、数字），时间来自 ElevenLabs 对齐、ASR 或估算。
6. 验证（必须循环）
python3 scripts/render.py out/explainer --out out/explainer.mp4 --quality draft
python3 scripts/verify.py all --project out/explainer --spec explainer.json --video out/explainer.mp4
| 阶段 | 通过条件 | 失败时 |
|---|---|---|
| facts | 每个配音的主张都有存在的来源且状态为 supported | 检查来源；修正或删除该主张 |
| assets | 捕获和代码在输出尺寸下清晰可读；OCR (tesseract) / 文本扫描未发现电子邮件、密钥、令牌或卡号 | 添加焦点框或重新捕获更小区域；capture.py redact；用占位符替换代码中的秘密 |
| build | npx hyperframes check --json 无错误或警告（除了 verify.ignore_rules） | 修正规格文件或生成的合成 |
| render | 你查看了联系表（开始、每个场景变化、场景中间、结束）：无溢出、重叠、截断或不可读文字；视觉内容与旁白匹配 | 修正、重新构建、重新渲染 |
| audio | 对渲染音频进行 ASR 的结果与脚本匹配（verify.min_asr_similarity）且时长在限制内 | 重新生成语音或缩短内容 |
如何驱动循环：
- 运行
verify.py all。每次运行算一次迭代（记录在<project>/.verify/state.json中）。 render首先总是返回review：打开它列出的联系表，检查每一帧，然后记录你所见：python3 scripts/verify.py mark render pass --project out/explainer --note "<你检查的内容>"（或fail，然后修正）。标记与那些精确文件关联；任何重新构建都会使其失效。- 如果没有安装 OCR 或 ASR，
assets/audio也将变为review：通过视觉或听觉检查，并在报告中说明。 - 修正失败项，重新构建或渲染，然后再次运行
verify.py all。退出码 0 = 可交付。 - 当迭代次数达到
verify.max_iterations（默认为 3）时，退出码为 2：停止并告知用户仍有哪些部分失败。不要静默交付。进行一次大的更改后，删除.verify/state.json以重新开始计数。
VERIFY.md 显示数字：扫描的 OCR 图像及其命中次数、ASR 相似度（包含听到和期望的词语）、以及相对于限制的时长。在报告时引用它们。场景会自动延长，以便最后一个字幕保持可读性；如果仍有 line_unread 警告，则给该场景更多 min_dur。
在运行脚本时保持用户的正常 HOME：临时 HOME 会导致 npx、Playwright 和 whisper 重新下载所有内容，并破坏 gh/npx 认证。
数字、缩略词或外来词的音频不匹配：在配置中设置 language，并在旁白中按实际发音写出这些词语（例如“fifteen”、“A P I”）。项目中的 VERIFY.md 是检查清单报告；在交付视频时包含其摘要。
7. 渲染
python3 scripts/render.py out/explainer --out out/explainer.mp4 使用 render.backend（local、cloud 或 preview）；render.max_mb 为适应上传限制而重新编码。禁止提交 mp4 或 wav 文件。