产品发布视频 - 调度入口
在步骤0之前确认路由。 此技能用于制作正在营销/发布/推广的产品视频。如果是一个通用的(非发布)网站 → 视频(网站导览/展示,并非销售产品)→
/website-to-video;一个没有产品的主题/概念 →/faceless-explainer;一个GitHub PR →/pr-to-video;一个需要添加字幕/打包的现有视频 →/embedded-captions·/graphic-overlays。超出范围(拒绝,不要伪造):实时/渲染时数据(每个值在创作时都已被嵌入),或尚不存在的素材/截图/头像(HyperFrames无法录制或捕获)。如果因为模糊的“制作一个视频”而路由至此,或不确定是产品与主题/发布与通用网站?请先阅读/hyperframes。
所有产物都写入 PROJECT_DIR = videos/<项目名称>/(在步骤0中创建)。下面的路径相对于 PROJECT_DIR。您(编排器)运行Bash步骤并调度子代理;每个阶段的具体细节存在于链接的指南/代理/脚本中 —— 请勿在此处展开它们。调度是跨平台的:在首次调度子代理之前,请阅读 <SKILL_DIR>/../hyperframes-core/references/subagent-dispatch.md 一次 —— 它将调度动词(并行扇出/后台/等待)映射到您平台的原语;下面的并发上限意味着每次波次的大小不超过上限,场景数量永远不会减少。此文件是一个具有约束力的运行手册,而非背景阅读材料:按顺序执行步骤,并使用指定的脚本或代理角色生成每个阶段的产物 —— 不要用一个即兴的流水线(手写旁白、临时TTS调用、一次手写的合成)来替代,并且不要因为请求看起来清晰就跳过暂停步骤。如果您无法执行某个步骤 → 停止并报告;即兴通过它将破坏后续所有合约。
| 阶段 | 执行 | 主要产物 | 详细流程 |
|---|---|---|---|
| 初始化 | 直接使用Bash | hyperframes.json | 步骤0(此文件) |
| 捕获 | 直接使用Bash(hyperframes capture) | capture/extracted/tokens.json | phases/capture/guide.md |
| 设计系统 | 子代理 | design-system/design.html + chunks/ | agents/design-system.md |
| 故事设计 | 子代理 | narrator_scripts.json | agents/story-design.md |
| 音频 | Bash直接(audio.mjs) | audio_meta.json | phases/audio/guide.md |
| 视觉设计 | 子代理 | section_plan.md | agents/visual-design.md |
| 准备 | Bash直接(prep.mjs) | group_spec.json | scripts/prep.mjs 头部 |
| 字幕 | Bash直接(captions.mjs group -> html) | caption_groups.json + compositions/captions.html | scripts/captions.mjs 头部 |
| 场景 | N x 子代理(并行,每个场景一个) | compositions/scene_*.html | agents/hyperframes-scene.md |
| 最终确定 | Bash前奏(等待BGM + 组装 + 转场 + 提升 + SFX验证) -> 最终确定子代理 | renders/video.mp4 | 步骤7 / agents/hyperframes-finalize.md |
前置条件(首次运行前安装)
macOS Apple Silicon 或 Linux x64:
brew install [email protected] node ffmpeg # 在Linux上,使用apt/dnf等效命令
npx hyperframes doctor # 一次性检查Chrome/依赖项是否就绪
[email protected]— Homebrew Python,而非系统/usr/bin/python3(否则PEP 668会阻止pip install);由MusicGen回退使用node >= 18+ffmpeg(audio.mjs使用ffprobe)- Chrome会在首次
npx hyperframes capture时自动下载。hoist-videos.mjs(步骤7,仅在场景声明素材时运行)重用缓存中的Chrome;如果报告缺少依赖项,请运行node <SKILL_DIR>/scripts/hoist-videos.mjs --ensure-deps一次(约5秒)
可选的API密钥(未设置 -> 使用本地回退;在步骤0.5中注入;GEMINI_API_KEY ≡ GOOGLE_API_KEY):
| 密钥 | 用途 | 默认语音/回退 |
|---|---|---|
HEYGEN_API_KEY(或 hyperframes auth login) | TTS(云端,包含单词级时间戳) | 语音:自动(第一个英文starfish语音;使用 --voice 覆盖) |
ELEVENLABS_API_KEY | TTS(云端;需要 pip install elevenlabs) | 语音 21m00Tcm4TlvDq8ikWAM(Rachel) |
| 两者均未设置,且未登录 | TTS | 本地Kokoro,语音 am_michael(对于非英文,传递 --voice) |
GEMINI_API_KEY(一个密钥用于两种用途) | 捕获视觉字幕 + Lyria BGM | 未设置 -> 字幕仅使用DOM上下文;BGM 使用本地 MusicGen(首次运行下载约300 MB) |
流程
步骤0.0 - 确认简报(一轮,然后构建)
在步骤0之前,通过一条消息确认仅影响发布视频且您无法推断的内容 —— 以推荐的默认值开头,跳过用户已给出的任何内容:角度/焦点(产品整体、主打功能、优惠/CTA)、时长(默认约30-90秒;最长约3分钟),以及 —— 如果 /hyperframes 尚未设置它们 —— 宽高比(默认16:9;9:16用于垂直/社交)和语言。预设值来自品牌捕获,而非询问。对于完全明确的请求,跳过此步直接构建。
步骤0 - 初始化视频项目
当前工作目录是代理工作区根目录;所有视频产物都放在 PROJECT_DIR = videos/<项目名称>/ 中。
命名 <项目名称>:如果用户明确给出了目录名称,则使用该名称;否则选择一个简短的kebab-case名称,如 <品牌>-promo(切勿使用工作区基名称或时间戳)。如果从URL派生,则从域名/页面标题中派生;一旦写入 capture/,名称将固定。
初始化(仅在 $PROJECT_DIR/hyperframes.json 不存在时):
PROJECT_DIR="${LAUNCH_VIDEO_DIR:-videos/<项目名称>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes init会在$PROJECT_DIR中放入一个通用的AGENTS.md/CLAUDE.md;将它们保留在原位,但不要将其通用指导视为运行时约束 —— 此技能是权威来源。
约束(每个违反都会破坏后续阶段):
- 不要在工作区根目录运行
hyperframes init(或生成AGENTS.md/CLAUDE.md);不要在PROJECT_DIR内部创建hyperframes/子项目。 - 每次子代理调度上下文都包含一行
PROJECT_DIR: <path>;子代理将其视为项目根目录。 - cwd 规范(主代理也适用):每个Bash命令都作为
(cd "$PROJECT_DIR" && ...)子shell运行 —— 切勿直接使用cd "$PROJECT_DIR" && ...(持久的cwd漂移会导致后续相对路径错误)。
步骤0.5 - API密钥指导
当 $PROJECT_DIR/.env 存在或 context.log 非空时跳过。否则检测已配置的内容(HeyGen TTS = $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen/credentials;ElevenLabs / Gemini = 它们的环境密钥),然后始终暂停并询问 —— 不要自行继续,即使检测到可工作的配置:
检测到:<摘要>。云密钥是可选的 —— 没有它们,未配置的提供商会回退到本地(TTS -> Kokoro,除非配置了HeyGen;BGM -> MusicGen)。回复:
- 粘贴密钥 -> 我会将它们写入
$PROJECT_DIR/.env- “go” -> 使用当前已配置的内容继续
- “skip” -> 对任何未配置的内容使用本地回退继续
粘贴的密钥 -> 写入/编辑 $PROJECT_DIR/.env,每行一个 KEY=value(覆盖同名的键,不对值进行判断)。“go” / “skip” -> 步骤1。
步骤1 - 捕获(阶段1)
- 从提示中解析
SKILL_DIR和任何显式的TARGET_URL;确保步骤0已运行。 - 如果
$PROJECT_DIR/context.log存在,则读取它并使用下面的恢复表跳过已完成的阶段。 - 对输入进行分类(步骤1.0)以设置
CAPTURE和VO_MODE,然后运行匹配的路径。两个路径共享相同的下游命令。
步骤1.0 - 对输入进行分类(设置 CAPTURE + VO_MODE)
| 输入形式 | 操作 |
|---|---|
| 提示中包含显式URL | TARGET_URL = 该URL;CAPTURE=yes;不询问画外音问题(旁白来自捕获的网站)。路径(A)。 |
| 用户粘贴/指向了一个脚本或简报 | (1)将原始文本保存到 $PROJECT_DIR/user_script.txt。(2)一次询问画外音问题(见下)→ 设置 VO_MODE。(3)从脚本中解析捕获目标(见下)→ 设置 CAPTURE。 |
| 一个主题/简报,没有脚本散文,没有产品 | CAPTURE=no;不询问画外音问题。路径(B)。 |
画外音问题(仅当用户提供了实际的脚本散文时)——询问一行简短内容并等待:
我应该逐字使用您的脚本作为画外音,还是将其重组为更适合屏幕的场景旁白?
- 逐字 —— 保留原始措辞;我只拆分场景并配对视觉。时长遵循脚本。
- 重组 —— 将其视为简报并重写更紧凑的旁白,每个场景1-2句话。
VO_MODE = verbatim | restructure(默认 restructure);在步骤2中传递给故事设计。
从脚本中解析捕获目标 —— 默认情况下,查找并爬取一个网站(真实的品牌标记优先于预设回退);仅在用户选择退出(“无网页/纯文本/无捕获”)时跳过。按顺序:(1)脚本中存在显式的 http(s):// URL → 使用它,宣布,CAPTURE=yes;(2)明确的品牌/产品名称 → 使用 WebSearch 搜索官方网站,在爬取前通过一行内容向用户确认解析出的URL(拒绝/没有可信内容 → CAPTURE=no);(3)无法推导出任何内容 → CAPTURE=no。
捕获 + 用户脚本共存:爬取仅提供品牌标记 + 资产 + 视觉风格;旁白主线保留在
user_script.txt中(通过VO_MODE遵守),绝不使用网站自身的文案。
(A) 捕获路径(CAPTURE=yes):
(cd "$PROJECT_DIR" && npx hyperframes capture "<TARGET_URL>" -o ./capture)
(B) 无捕获路径(CAPTURE=no) —— 合成最小捕获包;下游相同。您(主代理)选择预设(没有网站可推断;根据用户意图从19个预设中选择,或询问一个简短问题)。完整的脚本/简报会写入 visible-text.txt;colors:[] 会触发预设调色板回退(仅当用户指定了品牌颜色时才填充 colors):
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && cat > capture/extracted/tokens.json <<'JSON'
{ "title": "<品牌/标题>", "description": "<一行描述>", "colors": [], "fonts": [], "headings": [], "sections": [], "ctas": [], "svgs": [], "cssVariables": {} }
JSON
)
(cd "$PROJECT_DIR" && echo '{}' > capture/extracted/design-styles.json)
(cd "$PROJECT_DIR" && printf '%s\n' "<完整用户脚本/简报>" > capture/extracted/visible-text.txt)
如果用户已经有最终的
narrator_scripts.json,将其放在$PROJECT_DIR/中;恢复表会跳过故事设计。
两个路径的共享下游(路径B向build-design追加 --style <选择的预设>;路径A省略它以进行自动推断):
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/derive-context-pack.mjs --capture ./capture)
(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/design-system/scripts/build-design.mjs ./design-system --no-emit) # 路径B:追加 --style <选择的预设>
验证(如果任何内容缺失,停止并报告;如果存在 capture/BLOCKED.md,则表示网站阻止了爬取 —— 按照其中的指示操作):
[ -
…
[此处已截断用于翻译]