69个组件目录全解析:video-spec-builder如何把每个镜头锚定到可渲染的组件ID
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:
- 信息载荷 —— 这一镜让观众 get 到什么?
- 组件 ID —— 用 components-catalog 里哪个组件承载?
- 时长 —— 几秒?
- 转场 —— 怎么进、怎么出?
命名规则: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,说"我想做个视频",剩下的交给它追问。