69个组件目录全解析:video-spec-builder如何把每个镜头锚定到可渲染的组件ID

原创2026-10-17 22:42:591,653 阅读
文章标签:AI 技能视频提示工程

69个组件目录全解析:video-spec-builder如何把每个镜头锚定到可渲染的组件ID

你有没有过这种体验:脑子里想做一个视频,却说不清每个镜头到底拍什么、放几秒、怎么切?开源项目 video-spec-builder 就是为了解决这个问题——它像一个会追问的导演,把你的模糊想法一步步逼问成一份精确到秒的分镜脚本 video-spec.md,再交给 HyperFrames 渲染。而整套机制的核心,正是那份包含 69 个标准组件的目录:拆镜头时,每个镜头(Scene)都必须锚定到一个具体的组件 ID,比如 broll-hero.big-number。这篇文章带你彻底搞懂这 69 个组件目录,以及"镜头 → 组件 ID"这套锚定规则。

👉 一句话记住:先想清楚"这镜要观众 get 到什么",再从 69 个组件里挑一个能承载它的 ID。不挑自创、不挑含糊的形容词。

先搞清楚:video-spec-builder 到底解决什么问题

它只干一件事:把"我想做个视频"这种模糊念头,压成一份能直接渲染的脚本。 它不替你拍视频,也不替你发明创意,而是通过苏格拉底式追问,把你脑子里没想清楚的地方一个个挖出来。

整个流程可以看成一条流水线:

你:"我想做个视频"
   ↓
video-spec-builder   ← 追问 + 拆镜头(每个镜头锚定一个组件 ID)
   ↓
video-spec.md         ← 精确到秒的分镜脚本
   ↓  /hyperframes
HyperFrames           ← 按脚本渲染
   ↓
成片

装到 Claude Code / Cursor / Codex 只需要一条命令:

npx skills add feicaiclub/video-spec-builder

而它追问出来的分镜脚本,质量取决于一个东西——组件目录。下面就开始拆解。

69 个组件目录:11 个命名空间的完整地图

组件目录就是这份"画面词汇表"。它一共有 69 个组件,分布在 11 个命名空间(namespace) 里。目录只描述每个组件的用途 / 何时用 / 何时不用 / 内容期待四件事,不涉及具体视觉实现——视觉实现交给渲染端的主题文件去管。

命名空间 中文定位 数量 典型用途
aroll 出镜讲解叠加层 3 字幕高亮、关键词贴纸、概念卡
broll-hero 重锤海报 4 大字标题、大数字、引用块、反白闪屏
broll-charts 数据图表 12 折线 / 柱状 / 环形 / 桑基等图表
broll-abstract 抽象兜底 7 类比、黑盒、等式、冰山、对照
broll-flows 流程图 8 复杂流程、分支、状态机、时序
broll-structure 结构图 I 6 流程图、金字塔、漏斗、同心圆
broll-structures2 结构图 II 7 树、思维导图、矩阵、Venn、网格
broll-thinking 思考与组织 7 对比表、SWOT、鱼骨、时间线、甘特
broll-ui UI 模拟 6 终端、对话流、浏览器、代码编辑器
icons 图标 2 精选图标集、描边粗细
illustrations 场景插画 7 6 张章节封面插画 + 插画库规范

几个关键纪律,目录开头就写死了:

  • 命名规则:namespace.component-id,例如 aroll.subtitle-highlight,不允许自创。
  • 不允许多 namespace 之外自创:11 个命名空间是封闭的,不能发明第 12 个。
  • 兜底机制:找不到合适组件 → 用 broll-abstract.placeholder 占位,并登记到「开放问题」。

完整清单见 components-catalog.md。

核心机制:每个镜头如何锚定到组件 ID

这是整套方法的灵魂。拆镜头时,每个 Scene 必须回答 4 个问题,其中第二个就是组件 ID:

  1. 信息载荷 —— 这一镜让观众 get 到什么?
  2. 组件 ID —— 用 components-catalog 里哪个组件承载?
  3. 时长 —— 几秒?
  4. 转场 —— 怎么进、怎么出?

命名规则:namespace.component-id

组件 ID 永远是"命名空间 + 组件名"的两段式。这样 HyperFrames 一读到 broll-charts.line-chart,就知道它属于图表组、要按图表的规则去画,而不是当成一张海报。

  • 写分镜表时,「组件」字段只能填目录里登记过的真实 ID。
  • 不写"概念卡片""数据图"这种含糊说法,而写 aroll.concept-card、broll-charts.bar-chart。
  • 规则来源见 spec-rules.md:"每个分镜的「组件」ID 必须来自 components-catalog.md 登记的真实 ID,不许自创。"

标签 → 组件匹配表:从"想法"快速定位 ID

拆解流程里有个"镜头打标"步骤,先给镜头贴标签(如 [hook]、[data]、[concept]),再按标签直接落到组件命名空间。这张匹配表就是新手最快的"找 ID"捷径:

镜头标签 优先匹配的组件
[hook] 抓注意力 broll-hero.big-type / broll-hero.inversion-flash / aroll.subtitle-highlight
[data] 数据 / 排名 broll-charts.* / broll-hero.big-number
[concept] 概念 / 定义 broll-abstract.* / aroll.concept-card
[emotion] 情绪 / 故事 broll-hero.pull-quote
[demo] 演示 / 操作 broll-ui.* / 真人 + aroll
[versus] 对比 / 反差 broll-abstract.versus / broll-abstract.spectrum
[structure] 结构 / 层级 broll-structure.* / broll-structures2.*
[flow] 流程 / 步骤 broll-flows.*
[summary] 总结 / 收束 broll-hero.pull-quote / aroll.subtitle-highlight

匹配纪律也很明确:不允许自创组件;某镜头实在没有合适组件 → 重写文案或改标签,而不是发明一个新组件。这套逻辑写进了 scene-breakdown.md 的「四、组件匹配」一节。

真实案例:一个镜头从"想法"到"组件 ID"

看 examples/video-spec-spacex.md 里的成品分镜表,每个镜头都老老实实填了「组件」字段。以第 3 镜为例:

Scene 03 · 10.0s–15.0s · 抛出命题

  • 类型:B-roll · 大字海报
  • 组件:broll-hero.big-type
  • 旁白文案:"这 22 年里,SpaceX 其实只做了一件事——把火箭,做成出租车。"
  • 屏显文案:hero 大字「把火箭做成出租车」,"出租车"三字用 accent 色

一句话就懂机制:先知道"这镜要让观众记住核心命题"(信息载荷),再挑一个能撑满全屏、用字体本身做段落分隔的组件 broll-hero.big-type(大字海报)。目录里这个组件的 何时用 写得很清楚:章节封面、整支视频核心论点的"标题镜头"、段落之间的视觉清场——正好命中。

再看一个数据镜头,第 5 镜用了 broll-hero.big-number(大数字)来放大"87%"这个决定性数字,spec 示例 里旁白就是"87% 的开发者认为提示工程会被上下文工程取代"。一个数字、一个能撑满画面的组件 ID,就这么锚死了。

找不到合适组件怎么办:placeholder 兜底

新手最容易犯的错,是想用一个目录里没有的组件,于是"自创"一个。目录明确禁止了这种做法。正确姿势是:

  • 实在找不到 → 用 broll-abstract.placeholder 占位,它专门给"缺素材"的镜头兜底,标注后续要补什么素材、什么规格、谁负责、何时补。
  • 同时在「开放问题」里登记这一镜,等素材或决策补齐后再回填真实组件 ID。

对应目录条目见 broll-abstract.placeholder。记住:宁可占位,不可自创——这是保证整份 video-spec.md 都能被渲染端识别的底线。

从 video-spec.md 到渲染:组件 ID 如何变成画面

组件 ID 不是终点。它写进分镜表后,HyperFrames 在渲染时会按 ID 去主题文件里查这个组件的精确渲染规格(字号、间距、动效时长、颜色变量等)。

以仓库自带的 Spec Mono 主题为例,spec-mono-components.md 给每个组件都写了细则:

  • broll-hero.big-type:Barlow Semi Condensed 800 · 4K 下 180-220px,主字入场 1100ms。
  • broll-hero.big-number:数字 280-360px · accent 色 · tabular-nums,"%" 符号弹入。
  • broll-charts.line:线 3px accent · round join,末端标数字。

也就是说:目录负责"选哪个组件",主题文件负责"这个组件长什么样"。两层各司其职,组件 ID 就是它们之间的"合同编号"。主题本身由项目根目录的 design.md 定义,渲染端只认这一个文件。

如何安装并开始使用

整个链路是两个 skill 接力:上游 video-spec-builder 把想法变成脚本,下游 HyperFrames 把脚本变成视频。安装:

# 安装渲染端(下游)
npx skills add heygen-com/hyperframes
# 安装本 skill(上游)
npx skills add feicaiclub/video-spec-builder

装完后,在 Codex 或 Claude Code 里用大白话说"我想做一个 3 分钟的产品演示",它就开始追问。聊完之后它会把所有内容写进 video-spec.md——每个镜头、每段时长、每个组件 ID 都填得明明白白。之后想改某个镜头,直接说"第 3 镜太慢,放慢一点",它会检测改动是否影响其他镜头再更新。

💡 分镜表的字段骨架来自 video-spec-template.md,"组件"字段那一行明确写着:填 components-catalog.md 里的真实组件 ID。

关键文件导航

你想做什么 看这个文件
查 69 个组件的用途 / 何时用 / 何时不用 components-catalog.md
学习"逐字稿 → 分镜"的拆解方法 scene-breakdown.md
看一份完整的真实 spec video-spec-spacex.md
了解分镜表字段该怎么填 video-spec-template.md
查"不许自创组件 ID"等硬规则 spec-rules.md
查组件在 Spec Mono 主题下的渲染规格 spec-mono-components.md
看 skill 的完整工作流定义 SKILL.md

常见问题

Q:为什么非要把镜头锚定到组件 ID?写个"这里放个图"不行吗? A:不行。渲染端 HyperFrames 是"按 ID 查规格"来画画面的。你写"放个图",它不知道该画折线图还是环形图。锚定到 broll-charts.donut 这种精确 ID,脚本才能被稳定、可复现地渲染出来。

Q:69 个组件记不住,怎么选? A:不用背。按 镜头打标 → 标签匹配表 走:先贴标签,再落到命名空间;拿不准就看目录里每个组件的「何时用 / 何时不用」两栏,它们会直接把你指向正确的邻居组件(很多条目末尾都写了"→ 该用哪个")。

Q:目录里没有我想要的组件,可以自定义吗? A:不能自创。要么重写镜头文案换标签,要么用 broll-abstract.placeholder 占位并登记到开放问题。封闭的 11 个命名空间保证了脚本始终"可渲染"。


小结:video-spec-builder 把"模糊想法 → 可渲染脚本"这件事做成了流水线,而 69 个组件目录就是这条流水线的"词汇表"。记住三件事——每个镜头锚定一个真实组件 ID、命名规则是 namespace.component-id、找不到就占位不自创——你就掌握了这套锚定机制的全部核心。装好 skill,说"我想做个视频",剩下的交给它追问。

登录后查看全文
video-spec-builder