KaranO-Dev/one-take

one-take 是做什么的？

一次性询问所有内容，然后制作整部影片，涵盖每种格式，经过检查，无需更多问题。

此技能负责编排；HyperFrames 负责渲染。它需要 HyperFrames 技能（hyperframes、hyperframes-core、hyperframes-animation），配合 hyperframes-registry、hyperframes-keyframes、media-use、figma 和 humanizer 效果更佳。如果缺少 hyperframes-core，请停止并给出安装命令：npx skills add heygen-com/hyperframes。

下面的 SKILL_DIR 表示此技能所在的文件夹。脚本是纯 Node (≥ 22) 加上 ffmpeg，无需安装。

契约

1. 一次信息收集。 先检测，然后询问一次（阶段 1）。获得答案后，不再提问。唯一的例外是无法绕过或默认处理的硬性障碍，例如文件不存在或网站拒绝加载。此时，就那一个具体问题提问，然后继续。
2. 信息回答授权渲染。 它不授权发布、上传、推送或下载用户未提及的任何内容。请单独询问这些操作，且在报告之后进行。
3. 事实是计算得出的，绝非手动输入。 屏幕上的每个数字都来自 facts.json 或用户提供的来源。切勿编造统计数据、引用、徽标或推荐语。
4. 画面决定声音。 每个应被听到的动作在发生时刻调用 T.cue()。配乐由这些提示构建，确保声音和画面不会不同步。
5. 完成意味着通过质量检查。 当 qa.mjs 通过检查时，文件才算交付；或者当报告记录了失败原因（且无法在两次修复中解决）时，文件也视为交付。

阶段 0：检测（静默执行，在提问之前）

node SKILL_DIR/scripts/detect.mjs <subject paths…> --out /tmp/one-take-detect.json

• 在当前仓库以及用户提到的任何路径或网站上运行。
• 对于每个来源，返回：README 标题和标语、Git 时间跨度和提交次数、徽标、字体文件和字体家族、颜色令牌。还返回工具链信息：node、ffmpeg、缓存的 hyperframes 版本、Chrome、heygen CLI，以及音乐 API 密钥是否已设置。
• 如果目标项目中已存在 take.json，则视为恢复操作。读取它，跳过信息收集，并从第一个缺少输出的阶段继续。

阶段 1：信息收集（一条消息，一轮）

阅读 references/intake.md。在一条消息中：

1. 显示信息收集表：每个字段都根据检测结果或推荐默认值预先填写，每行一个。用户只需更改错误的部分。

2. 调用 AskUserQuestion 一次，询问最影响工作的四个决策：格式（多选）、时长、声音以及配音/字幕。问题文本告知用户，如果他们想更改表格中的任何内容，可以在任何答案中添加备注。

   如果 AskUserQuestion 不可用，则在同一张表格末尾将这四个决策作为编号选项列出，并要求用户一次性回复。

然后，不再提问：

• 写入 take.json（模式：references/take-json.md）。语言代码、格式 ID、slug 和 output.name 必须匹配 [a-z0-9][a-z0-9._-]{0,63}（不区分大小写，不含 ..），否则运行停止。在 take.json 中不要包含 hyperframes，除非用户要求：默认版本固定于 scripts/lib/platforms.mjs（HF_VERSION，0.8.223）。
• 写入 HyperFrames 的 BRIEF.md，内容包含 workflow: general-video、flow: automation、storyboard: no。这意味着后续的 /hyperframes 调用将恢复此项目，而不是重新进行信息收集。
• 在 BRIEF.md 正文中记录答案：格式、声音、字幕、平台限制。

阶段 2：来源

• Git 事实。 运行 node SKILL_DIR/scripts/facts.mjs --repo <path> [--repo …] [--since …] --out <project>/facts.json。它收集提交次数、时间跨度、活跃天数、最长连续活跃天数、最忙的一天、按语言划分的代码行数、新增和删除的行数、以及最常出现的提交词语，同时记录首次和最后一次提交的主题。作者姓名和电子邮件永远不会被记录。仅使用用户允许的事实。
• 网站。 对于要显示的 URL，运行 npx hyperframes capture <url> -o <project>/src/assets/cap。如果遇到 ok:false 或 BLOCKED.md，则停止：这是一个阻塞问题。
• 参考。 对于每个参考，在 STORYBOARD.md 中写一行你从中汲取的内容：节奏、类型、颜色、转场。对于 Figma 链接，首先运行 /figma。
• 品牌。 将 SVG 徽标和字体文件复制到 src/assets/brand 和 src/assets/fonts，在 take.json 的 fonts 字段中声明它们，并将颜色令牌提升到模板的 :root 中。

阶段 3：方向与故事板

在编写任何视觉内容之前，阅读 references/direction.md。编写 STORYBOARD.md：

• 方向，一段话：核心理念、标志性动作、字体配对、调色板、每个选择所基于的参考。
• 速度优先。 选择 BPM，使目标时长是整小节数（4/4）。然后为每个场景分配小节数、一个 energy（0–1，驱动配乐的编曲）以及它的入场方式（in）。
• 场景表： id、小节数、能量、屏幕上的内容、动画、提示点、文案。
  • 最后一个场景是结束卡片，标记为 end: true，并有足够的小节数使其完整保持 3 秒或以上。
  • 标记可用于精简版的场景为 optional（1–9，数值越高优先级越高）。
• 文案 放在 copy/<lang>.json 中，每行文本一个键。如果可用，通过 /humanizer 运行。确保标题足够简短，以便在屏幕上显示的时间内可以阅读两次。

阶段 4：构建

• 将 SKILL_DIR/templates/index.html 复制到 <project>/src/index.html，并根据故事板重写其中的场景。
• 阅读 references/kit.md（T.* API）和 hyperframes-core 的强制性规则。对于动画，阅读 hyperframes-animation 的规则和蓝图。在手动构建任何命名效果之前，先在 hyperframes-registry 中搜索。

确保每种格式和质量检查都诚实的规则：

• 场景是顶层 <section class="clip scene" data-scene="id">，不能嵌套，不能使用内联 style。
• 通过 --u（短边的 1%）以设计像素为单位设置尺寸。可读文本绝不能低于 --t-min（3.4u ≈ 1080 下的 37 像素）。
• 将可读文本保留在 .safe 区域内，即该格式的平台 UI 区域。
• 使用 .f-tall、.f-wide、.f-square、.f-portrait 规则按格式重新布局，而不是通过缩放一种布局。
• 在下一个场景的转场覆盖之前，清除一个场景的文字（在 s.end 附近使用 T.sink/T.leave）。在揭示效果下的文字会导致布局检查失败。
• 每个场景都必须有动画：使用 T.drift 让镜头横穿场景。在结束卡片之前，没有任何内容是静止的。
• 在结束卡片完成的那一刻调用 T.endCard(t)。最后一帧必须仍然显示它：不要在保持画面上淡出到黑色。
• 提示所有应该被听到的内容（references/sound.md 列出了类别）。大多数套件辅助函数默认会添加提示；传递 cue: false 可以使某个时刻静音。
• 数字来自 T.facts 或文案。T.count 需要一个有限数字，如果没有则会抛出异常，因此缺少事实会停止检测，而不是在屏幕上显示捏造的数字。
• 以 window.__timelines["main"] = T.done(); 结束脚本。T.done() 注册时间线一次（在所有补间添加之后），模板会在该行重复它。首先构建所有补间，而不是在字体加载完成或其他异步回调内部：HyperFrames 静态检查会拒绝过早的注册。

阶段 5：草稿检查

node SKILL_DIR/scripts/run.mjs <project> --draft

这会针对每种格式 × 语言执行：构建 → 检测（从无头 Chrome 获取提示、文本大小、结束卡片标记）→ 配乐 → hyperframes check → 草稿渲染 → 编码 → 质量检查 → REPORT.md。

HyperFrames 以 scripts/lib/platforms.mjs 中固定的 HF_VERSION（0.8.223）版本运行，或者使用 take.json 中指定的 hyperframes 版本。首次运行时会通过 npx 获取它，构建过程会从 jsDelivr 将 GSAP 3.14.2 获取到 ~/.cache/one-take/。下载后以及每次从缓存读取时，都会根据固定的 sha256 值检查 GSAP 文件。不匹配的文件永远不会被使用：错误的下载不会缓存，而缓存中损坏的文件会被删除，构建停止。重新运行以获取新副本。

然后：

• 打开每张 *.sheet.jpg 联系方式表并查看。
• 阅读 REPORT.md。
• 修复失败和任何看起来错误的地方：重叠、裁剪、死帧、文字过小、剪辑不连贯。

最多有 两次 修复检查。每次修复都重新运行 run.mjs --draft；使用 --only <format>-<lang> 仅重新运行有更改的部分。

阶段 6：最终版

node SKILL_DIR/scripts/run.mjs <project>

这是每个输出的全质量渲染。交付物位于 renders/（或 output.dir）。每个输出包含：

• <name>.mp4：x264 CRF 12、AAC 320k、faststart
• .cover.jpg：结束卡片
• .sheet.jpg
• .qa.json

配乐分轨和 marks.json 保留在 out/<format>-<lang>/score/ 中。

阶段 7：报告

回复中包含：

• REPORT.md 中的输出表格（文件、大小、时长、判定）
• 主要格式的联系方式表
• 关于声音的一行说明
• 未解决事项（如果有）

提供后续步骤但不执行：发布文案、更多语言、精简版、发布。除非用户要求，否则不会发布或推送任何内容。

声音模式

sound.mode	说明
score（默认）	score.mjs 根据小节网格上的场景能量合成铺底、乐队和鼓：根据 mood 和 key 生成和弦进行，对底鼓进行侧链压缩，在每个提升处加入上升音，在每个到达点加入冲击音。效果音轨由提示构建，根据屏幕上的发生位置进行调音和声像定位。混音、限幅，然后进行两次 loudnorm 处理以达到 lufs（默认 −14），真实峰值 −1.5。原创，无需授权。
track	用户提供的文件。使用 score.mjs --analyze <file>（或 npx hyperframes beats）获取 BPM 和第一个节拍，将 bpm 设置为该值，并将场景放置在其小节上。效果音轨在其上播放。
library	使用 /media-use 的 resolve --type bgm（需要 heygen CLI）或其生成器。结果作为 track 使用，其许可在 sound.licence 中记录。
none	完全没有音频元素。

对于画外音，将其放在 src/assets/audio/vo.wav，可以通过 npx hyperframes tts 使用 Kokoro 生成，或使用用户的录音。配乐会在画外音下方进行闪避处理（duckDb，默认 −9）。对于字幕，使用 npx hyperframes transcribe vo.wav --model <model> 进行时间轴处理。硬编码字幕是放置在 .safe 区域内且字号为 --t-cap 或更大的场景文字。对于边车字幕，从相同的转录结果编写 <name>.srt，并放置在每个输出旁边。

文件

• scripts/detect.mjs、facts.mjs：现有内容及数据
• scripts/build.mjs：一个来源 → out/<format>-<lang>/ HyperFrames 项目。填充尺寸、安全区域和场景时序，内联 TAKE（文案、事实、场景），打包套件和 GSAP 3.14.2（经过 sha256 检查），为精简版删除场景
• scripts/probe.mjs：无头 Chrome 检查，读取随时间变化的提示、文本大小和位置，以及标记
• scripts/score.mjs：合成配乐、分轨、混音、母带、marks.json；--analyze 用于分析音轨的节奏
• scripts/encode.mjs、qa.mjs、report.mjs、run.mjs：交付、检查、报告以及完整运行
• scripts/selftest.mjs：检查工具链，然后证明质量检查会失败于一个故意构建失败的测试文件
• scripts/lib/：共享辅助函数（Git、包含 HF_VERSION 和名称检查的平台、WAV、DSP）
• kit/take.js：动画套件（references/kit.md）
• templates/index.html：起始舞台
• references/：intake.md、take-json.md、direction.md、sound.md、formats.md、qa.md、kit.md