agent-demo-film 是做什么的？
只有屏幕上的内容真实且与解说者当时所说的内容完全匹配，演示视频才值得发送。本技能让真人只需做一件事：一次性朗读脚本。其他所有工作——研究、录制、脚本编写、剪辑和构建——均由 AI 代理完成。
1 准备 ─> 2 录制 ─> 3 脚本 ─(审批)─> 4 录制 (真人) ─> 5 剪辑 ─> 6 镜头计划 ─(审批)─> 7 构建 ─> 8 验证 ─> MP4
每个项目都需要不同的录制内容和不同的故事，需要根据项目本身来确定。examples/ 目录展示了两个实际运行案例：一个有讲解的产品演示，另一个是 AI 技能的效果对比视频。在规划之前，请先阅读与当前需求更接近的那个示例。
原则
- 仅使用真实录制画面。 屏幕上的每个应用界面、AI 回复、数字和日志均来自录制或文件，由脚本复制获得，绝不手动重新输入。如果想要的某行内容不在录制中，则视频无法显示它。
- 画面跟随语音。 每个视觉元素在提到它的那个词上出现。构建中的每个时间点都来自剪辑中的词 ID，因此重新剪辑会带动画面随语音移动。
- 不声称超出词语和来源的内容。 维护一个事实清单（包含每个事实的来源文件）和一个“未声称清单”。对照论文本身检查任何研究引用（Crossref：
https://api.crossref.org/works/<doi>）。 - 合成输入。 使用虚构的用户、聊天和数据。不得出现真实姓名或记录。在录制画面中隐藏秘密和电话号码，绝不要打印密钥：登录步骤在未被记录的环境中从环境变量文件中读取密钥。
- 保留每次录制。 脚本拒绝覆盖已有的录制或剪辑源文件。原始录制文件保留在原始位置，删除操作由真人决定。
- 真人审批两次： 在录制前审批大纲和脚本，在构建前审批镜头计划。预计脚本需要多轮措辞修改，这正是该阶段的意义所在。
模型路由
大部分工作在子代理中运行，主会话保留决策权。当真人指定某个步骤使用某个模型时，则使用该模型。
| 工作 | 模型 |
|---|---|
| 大量文本阅读与研究：仓库事实表、主题研究、将录制内容分割成编辑列表、检查脚本中是否存在 AI 痕迹 | Sonnet |
| 任何涉及视频或帧的处理：裁剪取景、渲染后的帧检查、检查录制内容是否泄露秘密，以及每段提示的镜头群（每个段对应一个代理） | Haiku |
| 构建流程中缺失的新工具，例如自定义录制器 | Opus |
| 大纲、脚本、镜头计划以及需要真人审批的所有步骤 | 主会话 |
Haiku 和 Sonnet 无法听到音频。词的时间定位完全来自转录（步骤 5）。
1. 准备
阅读 references/prep.md。同时进行：一个 Sonnet 代理根据仓库编写事实表（它做什么、带来源文件的实际数据、需要避免在屏幕中显示的已知问题），同时其他 Sonnet 代理研究与故事相关的内容。然后编写大纲：包含目标时长的段落、每个段落屏幕上显示的内容、每个段落所需的录制素材、事实清单和未声称清单。
2. 录制
阅读 references/capture.md。根据项目选择录制方法：Web 应用使用 Playwright，通过 claude -p 运行的代理行为使用 scripts/run_take.sh，CLI 使用终端录制器，实时页面使用滚动录制。每次录制都会记录其标记（发送、回复、滚动停止）及时间戳，以便构建阶段能够将画面剪辑与语音对齐。Haiku 代理检查每次录制的帧。
3. 脚本
阅读 references/script.md。仅编写真人对话部分，采用与大纲对应的 ## N. 标题 段落格式，语速约为每分钟 150 词。使用真人自然的说话风格：避免营销话术和 AI 痕迹。显示脚本及录制指南，等待审批。
4. 录制（真人）
真人使用 OBS、相机应用或手机录制一个包含摄像头和麦克风音视频的文件。允许出错和重新开始，剪辑时会取最后一个完整版本。也可以录制多个文件（每个段一个文件，或稍后录制的补拍片段）。
5. 剪辑
阅读 references/cut.md。
- 在本地转录每次录制：
npx hyperframes transcribe <录制文件> --engine parakeet。 - 为词编号并根据实际静音进行修剪：
python scripts/words.py transcript.json <录制文件> vo --media <录制文件>。 - 将词组列表和脚本提供给一个 Sonnet 代理（参考
assets/SPLIT-BRIEF.md）。该代理生成edl.json：每个段要保留的词范围、要删除的填充词和错误开始，以及可能失实的行。 - 在剪辑前，向真人确认任何重复行或标记的声明。
- 确定摄像头取景：一个 Haiku 代理从采样帧中选择一个在全部录制中都能保持头部和肩部显示的裁剪区域，或者改为模糊背景（使用
scripts/blur_bg.py）。 - 剪辑：
python scripts/cut.py edl.json生成vo.wav、cam.mp4、timeline.json以及每个段对应的词文件。由于音频和视频在同一帧网格上修剪，唇形同步得以保持。
6. 镜头计划
每个段对应一个 Haiku 代理（参考 assets/CUE-BRIEF.md），将该段的时间标记词转换为字幕、镜头提示（哪个视觉元素在哪个词上出现及其来源）和闪白。然后：
python scripts/cues.py cut检查每个段的文件是否与剪辑版本一致，并将其合并到film.json中。将任何错误返回给编写该段的代理。- 为真人编写镜头计划（
examples/samatva-support/CUE-plan.md展示了格式）：段落布局、逐行动画、音频编辑以及只有真人才能做的决策。等待审批。
字幕规则：显示正确的词。悄然更正转录器的误听。对于真实的口误，用正确的词以 *(词) 的形式替换原话。将难以听清的名称、数字和术语以大字显示在字幕上方进行闪白。
7. 构建
阅读 references/hyperframes.md。将 assets/build_film.py 复制到电影文件夹中。该脚本默认从 film.json 构建一个动画分镜：每个镜头提示的文字出现在对应的词上，每个段的摄像头画中画、字幕和闪白。如果对时间把握有疑问，请先渲染此版本。然后将每个段的主体替换为实际视觉画面：根据镜头提示时间剪辑的录制素材、随着每个部分被提及而逐步构建的图表，以及显示来源的卡片。
8. 验证
阅读 references/verify.md。按顺序执行：
npx hyperframes check --json运行直到显示 0 个错误。- 在每个镜头提示时间点截图（构建器会生成
cues.json），让 Haiku 代理检查这些截图是否与镜头计划一致，并检查是否泄露秘密。 - 通过脚本比较屏幕上的文字与其来源。
- 渲染 1080p 母版和 720p 审查版。
然后发送审查版。当真人指出某个时刻（“在 1:23 我说 …”），通过补拍录制或修改镜头提示来修复，并仅重新验证发生变化的帧。
文件
scripts/words.py：将转录转换为带编号的词和词组列表，并根据实际静音进行修剪。scripts/cut.py：根据编辑列表生成vo.wav、cam.mp4和timeline.json，并在帧网格上保持同步。scripts/cues.py：检查提示代理生成的段文件，并将其合并到film.json中。scripts/blur_bg.py：对摄像头内容进行本地背景模糊处理（使用 RobustVideoMatting，CPU 运行）。scripts/run_take.sh、scripts/grade.py：用于实际claude -p代理行为的录制和评分。assets/build_film.py：起始构建器（动画分镜、摄像头、字幕、闪白）。assets/edl.example.json、assets/SPLIT-BRIEF.md、assets/CUE-BRIEF.md：编辑列表格式及两个代理的提示说明。references/：包含准备、录制、脚本、剪辑、hyperframes、验证等参考文档。examples/samatva-support/：一个 2 分 19 秒的有讲解产品演示，由三次录制剪辑而成。examples/samatva-vent/：一个简短的无声 AI 技能效果对比视频，基于实际的claude -p录制构建。