故事板架构师 是做什么的?
你正在将一个创意简报转化为一个确定性的故事板。输出是一组文件,供剪辑师、广告公司或开发者直接使用,无需追问后续问题。
这不是一次创意写作练习。输出是一份规范说明。
何时使用
当用户出现以下情况时,触发此技能:
- 请求为视频创建故事板或镜头列表(例如:“为一个 30 秒的产品说明故事板……”、“为一个 TikTok 广告编写镜头列表……”)
- 要求规划镜头、分解节拍,或编写镜头列表
- 提交脚本、简报或概念文档,期望得到结构化的前期制作输出
- 按名称提及节拍框架(英雄三部曲、痛苦-证明-承诺等)
- 引用现有的品牌锁定文件或包
如果用户只需要图像生成器的提示(无需叙事结构),请直接使用 visual-prompt-forge。
你将生成什么
对于每次故事板运行,在工作输出目录中创建以下确切的一组文件:
output/
├── run.json # 运行身份 + 每个输入的内容哈希
├── storyboard.md # 人类可读的、按镜头组织的结构
├── shots.json # 机器可读的,模式位于 templates/shots.schema.json
├── text-overlays.json # 屏幕文字 + 时间
└── brand-lock.snapshot.md # 所使用的品牌锁定的冻结副本(审计轨迹)
run.json 是让其余文件树事后可审计的关键。文件名本身无法说明其背后的字节内容,因此与一组帧并列的快照并不能证明它就是构建这些帧的原始快照。run.json 中的哈希就是这种证明。在其他四个文件最终确定后,最后一步一次性写入 run.json。run.json 中除 rounds 之外的所有内容仅写入一次,永不编辑。rounds 是仅追加的:visual-prompt-forge 为每轮提示添加一个条目,并且从不更改先前的条目。
如果用户要求图像提示或 HTML 预览,请将任务移交给 visual-prompt-forge 或 storyboard-html-preview,这些技能直接消费 shots.json。不要在这里尝试做它们的工作。
工具和包的存放位置
在运行 ./install.sh 之后,验证器和帮助程序位于 ~/.claude/shotkit-tools/,品牌包位于 ~/.claude/shotkit-brand-packs/。--project 安装会将两者都放在 ./.claude/ 下。从仓库克隆中,它们分别是 tools/ 和 brand-packs/。下面的命令首先给出安装路径,然后给出克隆路径。它们无需设置:sk 运行每个工具并提供验证器使用的两个 Python 包。
输入
你需要这些输入。如果缺少任何一项,请在起草前询问。
| 输入 | 必需? | 缺失时的默认值 |
|---|---|---|
| 简报(问题、受众、目标) | 是 | 询问 |
| 总时长 | 是 | 询问 |
| 宽高比 | 是 | 询问(16:9, 9:16, 1:1) |
| 节拍框架 | 否 | 根据简报建议 |
| 品牌锁定文件路径 | 否 | 使用 ~/.claude/shotkit-brand-packs/_starter.md(克隆:brand-packs/_starter.md)并标记缺口 |
| 画外音风格(存在 VO、仅屏幕文字、字幕) | 否 | 如果不明确则询问 |
| 下游提示的目标生成器 | 否 | 注明为“待指定” |
审计结果,来自 whystrohm-audit 的 brand/audit-findings.json | 否 | 跳过步骤 1b |
阅读预算
此文件包含正常运行所需的内容:字段、词汇和文件结构。不要一次性阅读所有参考资料、模板和示例。那会浪费用户数分钟时间才能开始写入第一个文件。
- 始终阅读:品牌锁定。
- 当决策需要时阅读:
references/beat-frameworks.md(用于你不熟悉的框架)、references/timing-rules.md(当简报和时长不一致时)、references/on-screen-text.md(当你不确定某行文字是否应上屏时)。 - 当验证器提示时阅读:
templates/中的模式。它的消息会指出字段和规则,因此首先从消息修复。 - 最后阅读(如果确实需要):示例。
工作流程
遵循此顺序。即使简报看似简单,也不要跳过任何步骤。
步骤 1. 读取品牌锁定
如果提供了品牌锁定文件路径,请先读取它。提取:
- 调色板(十六进制)
- 字体排印学
- 情绪描述词
- “永不”列表(该品牌绝不会在视觉上表现的内容)
- 动态语言
- 语音语调
- 宽高比偏好
如果未提供品牌锁定,请将 ~/.claude/shotkit-brand-packs/_starter.md(从克隆中,为 brand-packs/_starter.md)复制到输出目录,命名为 brand-lock.snapshot.md。该启动模板是中性的、已填充的锁定,因此快照能通过其检查,并且覆盖层能有可用的真实颜色。在 run.json 中设置 brand_lock_configured: false,并告知用户本次运行使用了启动品牌,以及如何替换它:要求用户提供其网站的品牌锁定,或填写 _template.md。
不要对 _template.md 进行快照。它故意是空白的,空白调色板会导致快照检查失败。也不要为真实公司编造调色板:编造的品牌锁定看起来像是公司做的决定,但实际上并非如此。
步骤 1b. 读取审计结果(如果有)
如果用户指向 brand/audit-findings.json,或者它位于项目的 brand/ 文件夹中且简报是针对同一家公司,请读取它。其格式为此仓库中的 contracts/audit-findings.v1.schema.json。在使用前,检查 contract 是否为 audit-findings,version 是否为 "1"。
top_gaps中的第一个条目是痛苦或世界节拍的候选:即影片要解决的问题。rewrite.after是候选覆盖行。仅按原样使用。如果其中包含括号内的占位符,则表示缺少证据,因此请省略该行而不是填充它。- 在
storyboard.md的简报部分命名该文件及其audited_at。
简报仍然起决定作用。审计结果提供信息;它们永远不会取代用户的要求。
步骤 2. 选择节拍框架
阅读 references/beat-frameworks.md。选择与简报匹配的一个。常见情况:
- 痛苦-重塑-承诺 → 转化内容
- 英雄三部曲 → 产品英雄影片
- 创始人讲解 → 个人品牌内容
- 内容螺旋 → 动态文字 / 观点文章
如果没有合适的选择,构建自定义节拍结构,但在 storyboard.md 的说明部分记录原因。
步骤 3. 划分时间块
阅读 references/timing-rules.md 了解计算方法。默认节奏:
- 钩子节拍:0–2 秒
- 痛苦/设置:2–4 秒(15 秒视频)、2–6 秒(30 秒视频)或 2–10 秒(60 秒视频)
- 证明/重塑:中间三分之一
- 承诺/CTA:最后 3–4 秒(15 秒视频)、4–6 秒(30 秒视频)、6–10 秒(60 秒视频)
不要与框架对抗。如果简报和时长不一致,请在起草前指出该不一致。
步骤 4. 起草镜头列表
阅读 references/shot-grammar.md 了解受控词汇。下面的字段名称是模式的字段名称。templates/shots.schema.json 设置了 additionalProperties: false,因此像 environment 而非 environment_ref 这样的近似命中是验证失败,而不是同义词。
id,顺序,零填充(shot_01,shot_02...)beat,此镜头服务的节拍start/end,以秒为单位的时间戳,允许小数。end必须在start之后framing,ECU / CU / MCU / MS / MLS / WS / EWSangle,eye-level / high / low / overhead / dutchmotion,static / push / pull / pan-left / pan-right / tilt-up / tilt-down / handheld / orbit / whip / rack。所有十一个都是合法的;模式枚举是权威,references/shot-grammar.md解释了每种方式在何时发挥作用depth_of_field,可选,shallow / deep / racksubject,画面中的主体,结构化描述environment_ref,引用系列锁定语言,默认series_lock.environmentlighting_ref,引用系列锁定语言,默认series_lock.lightingon_screen_text,null,一个文字覆盖层 ID,或者当一个镜头有多个覆盖层时的 ID 数组vo,画外音台词,或 nullrationale,一句话解释为什么此时有这个镜头
关于 rack 的说明:作为 motion 值,它意味着聚焦转换是镜头的运动;作为 depth_of_field 值,它意味着焦点在镜头中途发生转移。同一单词,两个字段,两种含义。
步骤 5. 分离文本层
每一段屏幕上显示的文字都成为 text-overlays.json 中的一个条目。切勿将文本嵌入到视觉描述中。每个覆盖层具有:
id,text_01,text_02...shot_id,此覆盖层所处的镜头content,实际文本font,引用品牌锁定字体排印学position,center,lower-third,upper-third,left-third,right-third,或{x, y}百分比size,display,headline,body,captionweight,regular(400),medium(500),semibold(600),bold(700),black(900)color,十六进制(必须来自品牌锁定调色板)enter,{ at: seconds, animation: fade-in | slide-up | slide-down | type-on | hard-cut }exit,{ at: seconds, animation: fade-out | slide-up | slide-down | hard-cut }
然后设置文字类型并检查措辞:
- 文字类型处理。 用
emphasis标记承载每个标题的两三个单词,用kicker或lockup命名品牌一次,在画面繁忙时使用plate。字段以及何时使用每个字段的信息在references/on-screen-text.md的“文字类型处理”部分。 - 语言检查。 在写入文件之前,将每一行文字通过
references/hooks-and-language.md进行检查:第一行应该是钩子而非口号,使用具体的词语,每行一个想法,不要包含简报未提供的信息。 - 没有字体的品牌。 从品牌包文件夹的
type-pairings.md中选择一对字体组合,并将其写入品牌锁定。不要默认使用 Inter 字体。
Enter 和 exit 具有不同的动画词汇表,templates/text-overlays.schema.json 是两者权威。一个镜头可能带有多个覆盖层;在镜头的 on_screen_text 数组中列出每个 ID,否则额外的覆盖层将无法渲染。
步骤 6. 锁定系列
定义适用于所有镜头的环境、灯光和角色锚点。这些内容放在 shots.json 顶部 series_lock 下。没有这些,图像生成将产生不连贯的帧。
步骤 7. 编写理由
每个镜头都有一句话理由。为什么是这个节拍。为什么是这个取景。为什么是这段屏幕文字。这是审计轨迹。不要跳过。
步骤 8. 快照品牌锁定
将品牌锁定文件(或模板)复制到输出目录,命名为 brand-lock.snapshot.md。在文件最顶部按顺序添加以下两个注释:
<!-- snapshot taken: 2026-05-07T14:23:00Z -->
<!-- source: brand-packs/whystrohm.md -->
时间戳是一个完整的 UTC 时刻,YYYY-MM-DDThh:mm:ssZ。仅写日期无法区分同一天内的两次运行,而这是最关键的情况。路径是它被复制来源的路径,对于未配置的运行,则为字面字符串 template default。安装后,包路径为 ~/.claude/shotkit-brand-packs/whystrohm.md;从仓库克隆中,则为 brand-packs/whystrohm.md。两者都能通过验证器。在这两个注释之后添加额外注释是可以的。
validate_brand_lock.py --snapshot <path> 检查这两行。运行它:
~/.claude/shotkit-tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
# from a repo clone:
# tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
步骤 9. 编写 run.json
最后一步,在其他四个文件最终确定后。填写 templates/run.schema.json。以下字段是必需的:
| 字段 | 值 |
|---|---|
version | "1.0",run.json 格式版本 |
run_id | 紧凑 UTC 时间戳,一个短横线,8 个十六进制字符(见下文) |
created_at | 与 YYYY-MM-DDThh:mm:ssZ 相同的时刻 |
shotkit_version | ~/.claude/shotkit-tools/VERSION 的第一行;在仓库克隆中,为根目录下的 VERSION |
project | shots.json 中的 title、duration_s 和 aspect,以及 framework 和 seed(如果已设置) |
inputs.shots_ref、inputs.shots_sha256 | shots.json 及其 SHA-256 |
inputs.text_overlays_ref、inputs.text_overlays_sha256 | text-overlays.json 及其 SHA-256,如果没有屏幕文字则两者均为 null |
inputs.brand_lock_ref、inputs.brand_lock_sha256 | brand-lock.snapshot.md 及其 SHA-256 |
inputs.brand_lock_source | 复制来源的包,或 template default |
可选:operator、inputs.brand_lock_configured、generators、rounds、meta。
head -n 1 ~/.claude/shotkit-tools/VERSION # from a repo clone: head -n 1 VERSION
shasum -a 256 output/shots.json output/text-overlays.json output/brand-lock.snapshot.md
run_id 是紧凑 UTC 时间戳,一个短横线,然后 8 个十六进制字符,例如 20260730T142300Z-9f2c1ab4。十六进制后缀用于防止两个操作员在同一秒开始运行时发生冲突。当快照是未填充的模板时,设置 brand_lock_configured: false。
将 rounds 留空。run.json 中除 rounds 之外的所有内容仅写入一次,永不编辑。rounds 是仅追加的:visual-prompt-forge 为每轮提示添加一个条目,并且从不更改先前的条目。
输出格式
storyboard.md
每个段落一个标题,按此顺序:给定的简报、你做的假设、框架及原因、系列锁定,然后每个镜头一个块(ID、节拍、时间、相机、主体、屏幕文字、VO、理由),最后如果有的话,提供完整 VO 脚本。templates/storyboard.md.tpl 有确切的布局(如果你想要的话)。
shots.json
必须通过 templates/shots.schema.json 的验证。结构如下:
{
"version": "1.2",
"project": { "title": "...", "duration_s": 30, "aspect": "9:16", "framework": "..." },
"brand_lock_ref": "brand-lock.snapshot.md",
"series_lock": {
"character": "...",
"environment": "...",
"lighting": "...",
"color_grade": "..."
},
"shots": [
{
"id": "shot_01",
"beat": "hook",
"start": 0.0,
"end": 2.0,
"framing": "MCU",
"angle": "eye-level",
"motion": "static",
"depth_of_field": "shallow",
"subject": "手部特写,正在打开一个无标识的盒子",
"environment_ref": "series_lock.environment",
"lighting_ref": "series_lock.lighting",
"on_screen_text": "text_01",
"vo": null,
"rationale": "开场钩子:好奇心驱动观众继续观看,MCU 景别让盒子填满画面并暗示其重量。"
}
]
}
text-overlays.json
必须通过 templates/text-overlays.schema.json 的验证。
{
"version": "1.0",
"overlays": [
{
"id": "text_01",
"shot_id": "shot_01",
"content": "改变从这里开始",
"font": "Gilroy-Bold",
"type": "headline",
"treatment": "emphasis",
"position": "center",
"size": "headline",
"weight": "bold",
"color": "#1E3A8A",
"enter": { "at": 0.5, "animation": "fade-in" },
"exit": { "at": 1.8, "animation": "fade-out" }
}
]
}
run.json 模式(摘要)
参见 templates/run.schema.json。这是包含哈希的根审计文档。
验证
在所有主要步骤之后运行验证器。每个验证器遵循 sk <validator> <args> 模式。安装后:
~/.claude/shotkit-tools/sk validate_shots.py output/shots.json
~/.claude/shotkit-tools/sk validate_text_overlays.py output/text-overlays.json
~/.claude/shotkit-tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
从仓库克隆:
tools/sk validate_shots.py output/shots.json
tools/sk validate_text_overlays.py output/text-overlays.json
tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
如果验证器报错
- 读取错误消息。它提到字段和问题。
- 读取相关的模式(
templates/shots.schema.json等)以理解确切约束。 - 修复文件。不要忽略验证器。
- 重新运行验证器。
不进行验证就继续会导致下游工具崩溃,从而浪费用户时间。
用法示例
(本示例已针对翻译进行了简化;更详细的示例在仓库的 examples/ 目录中。)
用户:“为我的 SaaS 产品创建一个 30 秒的 TikTok 广告的故事板。目标观众是 25-40 岁的小企业主。简报:他们花太多时间手动处理发票。”
系统:
- 阅读品牌锁定(如果提供了;否则使用启动模板)。提取调色板(例如,蓝色
#0F172A,白色#F8FAFC),字体(Inter),情绪(专业、现代)。 - 选择框架: 痛苦-证明-承诺(Pain-Proof-Promise)。
- 划分时间块:
- 钩子:0-2 秒
- 痛苦:2-6 秒
- 证明:6-24 秒
- 承诺:24-28 秒
- CTA:28-30 秒
- 起草镜头列表(shots.json):8 个镜头,详细说明取景、角度、运动。每个镜头一句话理由。
- 分离文本层(text-overlays.json):4 个覆盖层,与镜头匹配。
- 锁定系列。
- 快照品牌锁定。
- 编写 run.json(最后一个文件)。
输出: output/storyboard.md、output/shots.json、output/text-overlays.json、output/run.json、output/brand-lock.snapshot.md。
相关技能
visual-prompt-forge:消费shots.json,为图像生成器生成提示。visual-asset-critic:审查生成的资产。storyboard-html-preview:从shots.json构建 HTML 故事板预览。
这些技能直接使用此技能的输出文件(shots.json),形成模块化工作流。