facundoexposito/plan-to-video

计划转视频

将书面计划转化为带旁白的讲解视频（社交帖子约 60 到 90 秒，包含多个决策的实际计划约 2 到 2.5 分钟）：钩子、问题、提案、机制，然后每个待定决策一帧（问题加 2 到 4 个选项），最后以行动号召结束。

此技能并非重新实现 HyperFrames。它决定简报、故事结构和设置，然后逐步运行已安装的 /faceless-explainer 工作流，并在默认流程容易中断的地方添加修复。请按照 /hyperframes 和 /faceless-explainer 的指示阅读；本文件告诉你需要回答什么以及需要修补什么。

首次在机器上运行： 阅读 references/setup.md 并运行其预检脚本。它会安装 HyperFrames 技能和本地语音（如果缺失）。

配置

在开始时一次性解析以下配置项，并在后续命令中重复使用。仅在无法找到值时询问用户。

名称	解析方式	默认值
VIDEOS_DIR	如果设置了 $PLAN_TO_VIDEO_DIR 则使用该值	当前工作目录（faceless-explainer 惯例）下的 ./videos
FE_DIR	存放已安装的 faceless-explainer/SKILL.md 的文件夹	参见 references/setup.md 的查找方法
MEDIA_DIR	存放已安装的 media-use/SKILL.md 的文件夹	相同的查找方法
HYPERFRAMES_PYTHON	优先使用环境变量，否则使用 references/setup.md 中的虚拟环境	~/.hyperframes-venv/bin/python
VOICE	用户的请求，其次是已记忆的语音，再其次是	Kokoro am_michael（离线）

1. 简报（简要确认，不要审问）

首先阅读源材料（计划文档、研究笔记或聊天记录）。然后在一小段消息中提出以下默认值，仅询问源材料无法回答的问题。快速确认优于问卷调查。

字段	默认值	原因
angle	listicle（路线值之一：概念讲解、操作指南、列表、叙事）	计划是“为什么重要、如何工作、N 个决策”
故事板 arc	概念讲解 with 列表	STORYBOARD.md 中的自由文本，非简报枚举
aspect	1920x1080	在笔记本电脑或通话中观看；选项卡片需要宽度
length	实际计划（含多个决策）2 到 2.5 分钟；社交帖子约 60 到 90 秒。硬上限 180 秒	faceless-explainer 的最佳时长是 30 到 90 秒；含多个决策的计划会运行更长时间。每个决策约 10 秒加上开场和结尾
language / voice	源材料的语言；英语使用 Kokoro am_michael	本地且免费。非英语 Kokoro 语音需要 espeak-ng
flow / storyboard	automation / no（自主）	当计划风险较高时，提供故事板审查
外观	如果视频是关于某个仓库，则使用项目自身的品牌，否则使用合适的预设	视频应看起来像它所解释的事物
music	none	本地 MusicGen 需要 torch；HeyGen 音乐需要登录
项目	$VIDEOS_DIR/<连字符-主题>/	每个视频一个文件夹

最多询问：谁来观看（决定了文案的技术深度），以及是否应在每个决策上标记推荐选项（强调“倾向”边缘）。

推荐选项规则：标记源材料推荐的选项。当没有单个选项胜出时，不标记任何内容；当决策是“支持多个”时，标记作为该答案一部分的每个选项。当源材料未说明时，推荐此技能自身的默认值（上表中的值），而不是虚构一个偏好。

BRIEF.md 在第 0 步编写，在 npx hyperframes init （init 拒绝非空文件夹）之后，格式遵循 /hyperframes references/brief-format.md 的描述，将用户所说的和推断出的内容分开。

2. 故事结构

默认弧线，根据源材料进行调整：

1. 使用源材料中的真实数字作为钩子（“N 个中的 M 个是 X”）。每个数字必须追溯源材料中的一行；切勿编造统计数据、价格或计数。如果源材料没有数字，则从具体的痛点开始。
2. 2 或 3 个命名的原因构成的问题，并附来源材料中的真实例子。
3. 在第 3 帧之前提出论点或提案（先价值后证据）。
4. 一个图表帧说明机制。
5. 一个路标（“构建之前有五个决策”）作为短暂的休息。
6. 每个待定问题或步骤一帧，全部使用相同的问题阶段布局（references/question-stage.md）。每帧显示问题及其 2 到 4 个选项；选项随着语音说出而出现。
7. 一个结尾的行动号召，呼应路标（“回答这五个，第一步本周就能完成”）。

将旁白写成简短的提示短语（每帧 6 到 25 个词），以便每个选项都有对应的词来揭示。如果源材料中已包含某个决策的答案，则在强调中显示已选答案，而不是询问。

3. 运行工作流，并应用以下修补

按顺序遵循 /faceless-explainer 的第 0 步到第 6 步。在每个步骤应用 references/gotchas.md 中对应的修补。跳过时容易出问题的修补：

• 第 0 步： 在 $VIDEOS_DIR 的父目录中运行 init，以便项目位于 $VIDEOS_DIR/<主题>，然后编写 BRIEF.md。未登录 HeyGen 也没问题：语音在本地 Kokoro 上运行。
• 第 2 步设计： 对于仓库，将其颜色和字体放入 capture/extracted/tokens.json，并在运行 build-frame.mjs之前将真实的 .woff2 文件暂存到 assets/fonts/ 中（这样它就会自己编写 @font-face 块）。从品牌自己的网站文件、Google Fonts 下载或 node_modules 中的字体包获取字体。如果品牌是深色而预设是浅色，则在 frame.md 中反转角色，替换嵌入字体可能缺失的预设字形，并交换属于另一个品牌的预设强调色为用户自己的颜色（references/gotchas.md，第 2 步）。
• 第 3.1 步音频： 在每个音频命令中传递 HYPERFRAMES_PYTHON，除非默认的 python3 已经可以导入 kokoro_onnx。
• 时间轴： 让音频完成，并在编写第 4 步的场景窗口之前运行 audio.mjs sync-durations，然后根据 audio_meta.json 中的真实词时间轴调整每个揭示效果的速度。（faceless-explainer 在第 5 步运行 sync-durations；故意将其提前。）
• 呼吸空间： sync-durations 将每帧设置为其准确的语音长度，导致最后一帧和路标帧突然结束。在 sync-durations 之后立即编辑 STORYBOARD.md 中的 - duration:：最后一帧 +2 到 3 秒，路标和其他呼吸帧 +1 秒。在构建数据包之前执行此操作，以便工作进程根据填充后的窗口进行动画制作。
• 字幕词： 字幕来自音频的转录，而不是来自 SCRIPT.md，因此产品名称可能被误听。在构建字幕之前，将 audio_meta.json（voices[].words[].text）中的词列表与 SCRIPT.md 进行比较，并就地纠正误听的词，保留其时间轴。
• 在第 5 步分发之前： 向每个工作进程提供在第 2 步中暂存的确切字体文件名。数据包省略了故事板的 ## Video direction 块和完整的词时间轴，因此将两者粘贴到每个工作进程的分发上下文中。为问题阶段帧提供共享规范的逐字副本。禁止 emoji。
• 第 5 步： 每帧一个工作进程，当你的代理支持子代理时可以并行执行（工作进程可以使用更快的模型），每个工作进程包含 _role.md、其数据包和分发上下文。
• 工作进程完成后： 规范化资源路径，修复是真正的查找错误的 lint 警告，运行 check，生成快照，查看联系表。

4. 质量关卡（全部在渲染之前）

• npx hyperframes lint 输出 0 个错误。studio_missing_editable_id 警告是表面问题；gsap_repeated_fromto_without_baseline 是真正的错误，需要修复（references/gotchas.md，第 6 步）。
• npx hyperframes check 通过。
• npx hyperframes snapshot --at <每帧的中点> 并实际查看联系表：深色背景上的深色文字、缺失的字体（衬线后备）、裁切掉的卡片和 emoji 方块都会在那里显示出来。
• 如果用户有风格指南（例如“不要使用破折号”），请检查每个字符串：- voiceover: 行、SCRIPT.md 行、compositions/frames/*.html 中的文本以及标题。使用冒号编写标题（## Frame 1: Hook、## Line 1: Hook (Frame 1)）；故事板和脚本解析器都接受这种格式，因此永远不需要破折号。

5. 审查、渲染、交付

faceless-explainer 的第 6 步即使在自主模式下也保留一个问题：打开 npx hyperframes preview --background 并询问“现在渲染，还是做什么修改？”。当用户要求一键渲染时，跳过此问题。然后：

npx hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4 （--skill 仅用于标记匿名渲染遥测；high 是 delivery 的别名）

仅当用户希望时才打开 MP4（macOS 使用 open，Linux 使用 xdg-open，Windows 使用 start）。报告：MP4 路径、其实际时长（ffprobe -v error -show_entries format=duration -of csv=p=0 renders/video.mp4）、带 ID 的帧列表（compositions/frames/NN-*.html）以便可以修改单个帧、联系表路径以及任何被跳过的内容（无音乐、发音错误的词、因源材料缺失而遗漏的事实）。

参考文件

• references/setup.md：新机器安装和预检（HyperFrames 技能、Kokoro 虚拟环境、ffmpeg、Chrome）。
• references/question-stage.md：用于决策和步骤帧的共享布局规范。将其粘贴到每个此类工作进程的分发上下文中。
• references/gotchas.md：按工作流步骤划分的环境和流程修复，包含命令。