【学习笔记】拆解 video-shotcraft：把 Claude Code 变成动效工作室的 152 张镜头配方卡

之前拆过 HyperFrames——HeyGen 那套「从 HTML 渲染视频」的 skill 体系。这一篇拆另一个最近很火的开源 skill：video-shotcraft（作者 Vincent Wei）。一句话定位：把 Claude Code / Codex 变成一个动效工作室——你把前端项目或网页交给它，它用 Remotion 完成分镜、动画、声音设计，产出一支电影感的产品宣传片：真实页面截图、2.5D 运镜、节奏卡点、电影级 SFX 全包含。

这个仓库 2026-07-19 才创建，六周后（截至我克隆分析的 2026-08-30 主干 c30d784）已经 6900+ star、615 fork，增速相当惊人。它火的原因不只是「能做视频」——同类工具已经不少——而是它把制作方法论本身做成了资产：152 张镜头配方卡、一套判例式审美准则、一份从素材采集到独立终检的八阶段流水线。这篇笔记是我把 SKILL.md、全部方法论文档、配方卡抽样、Gallery 索引和模板工程读完之后的结构化总结。

TL;DR：video-shotcraft 的核心不是「让 agent 写 Remotion 代码」，而是一套经验沉淀系统——每张镜头配方卡记录用途/能量/参数/已知坑，每条审美准则由「规则 + 用户原话判例 + 自检问题」三件套构成，全部来自真实返工复盘。它用三层事实源（Gallery 索引 → 配方卡 → demo 源码）保证 agent 不凭名字瞎写动画；用八阶段流水线保证方向性问题在便宜阶段解决；用干净上下文的独立 subagent 终检对抗确认偏差。对写 agent skill 的人来说，它的价值密度不在视频，而在「怎么把一个创意工种的隐性经验编码成 agent 可执行的规则」。

一、它是什么：一个自包含的制作能力库

先给全貌。仓库结构（我的归纳）：

几个容易过时的数字先钉死版本（WikiSkill 那篇的老规矩：一手数字和二手数字分层记录）：网上不少文章写「104 张配方卡 / 161 个动效预设」，那是 2026-08 扩充前的旧数。截至 2026-08-30 主干，一手数字是 152 卡 / 209 样式 / 209 条动态样片 / 149 个 SFX。152 张卡的类别分布：ui-entrance 27、typography 25、transition 19、effects 17、interaction 15、data 11、rhythm 11、camera 10、opening 10、outro 7——排版和入场占了大头，符合「产品宣传片主要是文字和 UI 在动」的实际。

作者同月还发了系列第二作 video-talkcraft（口播视频版，78 张卡，动效节拍钉在人声字级时间戳上），本文不展开。

安装就是标准 skill 姿势：npx skills add Vincentwei1021/video-shotcraft，或者克隆仓库后软链到 ~/.claude/skills/（Claude Code）或 ~/.codex/skills/（Codex）。仓库里还有一份 agents/openai.yaml 给 Codex 的 harness 读界面元数据（显示名、图标、默认 prompt）——同一份 skill 双生态适配，这个细节值得抄。

二、入口设计：先分诊三种模式，再动手

SKILL.md 的前 60 行几乎全在讲一件事：接到需求后先判断用户要哪种模式，判断不出来就停下来问，绝不默认。三种完整宣传片模式互不合并：

1. 直接使用模板：仓库内置一支已验收的 36.2 秒宣传片 Ink Press（纸墨琥珀风），agent 按文档逐镜头替换目标产品的截图、文案、品牌信息——最快、质量最有保障的路径。
2. 自主自由创作：agent 从产品理解连续推进到终检，中途不逐阶段等待确认，但把关键判断记录下来。
3. 共同创作：agent 先给出有依据的方案，用户依次确认产品简报、需求决策、视觉方向、镜头映射和最终分镜，放行后才进入制作。

配套规则相当细：用户给了项目但没选模式时，先做一次最小、只读的产品检查（不修改业务项目、不采集敏感数据、不写视频代码），然后给出三种模式各自的适用依据和推荐，明确问一句「我推荐 ×× 模式，要按这个继续吗？」。两条例外写死了边界：用户点名 Ink Press 等于模板模式已选定，不要再问；用户点名具体镜头卡等于镜头约束已选定，不要推销模板。「不要仅因 Ink Press 是现成模板就默认推荐它」这句甚至单独成段——这是在对抗 agent 最常见的懒惰路径。

共同创作与自主创作的边界也专门立了一节：共同创作每轮只问 1–3 个最能减少返工的问题；用户说「你全权决定」就切成自主模式并记录，「不要一边声称自主推进，一边继续要求逐阶段确认」。连成片交付后的收尾话术都是固定的 1-2-3：推荐（非强制）在简介 @ 作者、邀请把作品放进展示页（且要求用日常语言说、不许出现 issue/模板这类技术词）、告知可以导出剪映工程。

我在上一篇讲 skill 写作时说过，入口 skill 最好的形态是「分诊台」而不是「说明书」。video-shotcraft 是目前我见过把分诊做得最完备的：模式、例外、推荐依据、用户没给输入时怎么办、给了输入但没选模式时怎么办，全都显式写出来，agent 没有自由发挥出错的空间。

三、镜头配方卡：三层事实源，卡给语义、源码才是真相

配方卡是整个仓库的「词汇表」。每张卡的 frontmatter 只有六个字段：name、一句话、适用、时长、能量、标签。正文五段式：意图 → 动效核心 → 参数表 → 声音 → 已知坑 → 参考实现。拿开场卡 spotlight-hero-card 举例（摘要）：

聚光灯扫过页面锁定一张卡，斜 45° 推进后卡片弹起悬浮、光束沿轮廓两圈、贴回原位。参数表里写：相机静止全页 zoom 0.78 → 16f 推进 zoom 2.6，rotY 34° 主导 rotX 仅 8°（侧向水平机位读感优于俯拍）；rise 10f（bezier(0.2,1.25,0.3,1) 过冲）→ 悬停 54f（sin bob 振幅 4px 周期 40f）→ reseat 18f 落地 press 0.997。已知坑三条：开场多卡群舞撑不起第一印象；推进特写下文字发糊根因是纹理栅格化分辨率不是景深；逐卡 glint 闪烁被用户两次否决，光效严格只给主角。

注意最后一句「被用户两次否决」——配方卡不是设计文档的转述，而是返工历史的沉淀。

比卡片本身更值得学的是它的三层事实源设计。agent 用一张卡时被要求按顺序走三步：

1. gallery/api/library.json 索引：机器可读的卡名、样式 key、样片 URL。用户从 Gallery 复制来的镜头名（如 shot-transitions · whip-pan）先在这里校验，不存在就报告最接近的真实卡名，「不要凭名字臆造」；
2. 配方卡 md：语义、参数表、已知坑；
3. demo TSX 源码：卡片「参考实现」字段指向的确切文件，含调校过的缓动、时值配比、摘罩时机。

SKILL.md 把这条链总结成一句狠话：「配方卡给的是语义和参数表，准确的 demo 源码才是调校过的参数真相。凭卡名和理解新写＝放弃全部调校积累，实测质感差一档。」允许适配性改动，但卡片「已知坑/命门」标注的参数不得降档——质量标准只升不降。

分镜层还有一份 sequences/promo-energy-arc.md（全片能量骨架）：低开品牌 → 单主角立传（质感最高、节奏最慢）→ 字卡呼吸位与功能段交替爬升 → 发布会峰值收场。它把散落在各条准则里的节奏规则合成一张可填空的段位表（含时长占比、候选卡、呼吸字卡密度），并注明模板片与两次独立复现都收敛到同一骨架——「它是默认项，不是令」。这种「实证过的默认值 + 允许有意识偏离但要写进 spec」的写法，比我见过的绝大多数风格指南都诚实。

四、八阶段流水线：方向性问题不进昂贵阶段

references/pipeline.md 是自主自由创作的完整流水线，开篇一句话点题：「八阶段，方向性问题不进昂贵的逐镜头阶段。」

• 阶段 0 产品理解：只读检查项目，产出产品简报与「需求到执行决策表」；数据风险分级——公开演示数据确认后可用，客户/个人/内部/密钥数据一律虚构、脱敏或冻结；
• 阶段 1 视觉方向与 styleframe：先用文字给最多 3 个方向，选定的方向不渲染视频、不写 Remotion 代码，只做一个纯 HTML/CSS 的 styleframe 静帧页（2–3 张 1920×1080 关键画面）。「用渲染视频做风格提案：太贵，改方向的心理成本也高」；
• 阶段 2 功能到镜头映射：先列产品功能清单逐一对应镜头（「核心功能漏拍等于返工」），扫全部卡片 frontmatter 选首选与备选；
• 阶段 3 分镜与制作放行：按能量曲线排镜头，排时间线时先划走 hold/rest 帧预算再排动效；
• 阶段 4 最终素材采集：起本地 dev server，脚本产出「三件套」——整页 2x 截图（deviceScaleFactor: 2）、元素级透明底切片、记录每个元素 bbox 的 layout.json。全片 2.5D 运镜和「元素飞入真实槽位」都靠这套坐标表；
• 阶段 5 逐镜头实现：每镜头写死 2 个验收帧号，完成即 npx remotion still 出静帧肉眼自检；每轮修改后整片渲染 + ffmpeg 抽帧回看；
• 阶段 6 声音设计：前置条件写得触目惊心——「画面时间线锁定后才开始。画面每动一次，钉帧表就要全体重对」；
• 阶段 7 独立终检与交付：派干净上下文的 subagent 做第三方审查，逐条出带帧号证据的报告。

两个贯穿性原则把流水线黏起来：一是「验收贯穿全程，不是最后一个阶段」（每镜头的静帧自检从阶段 5 就开始，阶段 7 只是收口）；二是「最终设计 spec 与分镜共同构成制作放行」（放行后不重开已确认的创意问题）。

阶段 1 里藏着全库我最喜欢的一张表：品牌到动效参数的推导表。不凭手感挑缓动，先把品牌放到两根轴上（能量轴：沉稳对运动；调性轴：严肃对活泼），再从六个预设起步：

自检只有两条：用三个词描述成片动效，与品牌词对得上吗；同一套 tokens 必须同时管入场、转场、hold——「一个品牌一种动效嗓音，混用两套读作拼盘」。这正是多数 AI 生成视频缺的东西：不是缺动画，是缺一致的动效性格。

五、判例式审美准则：整个仓库最值钱的一份文档

references/aesthetic-rules.md 的开头就声明了自己的格式：每条准则 = 规则（一句可执行的话）+ 判例（用户原话/返工经过）+ 自检问题，三要素缺一不可。编号分五组——R（节奏）、Q（质感·运镜·构图）、S（声音）、C（文案）、P（流程），「编号一经发布不重排，新增条目只追加」。允许有意识违反，但每次违反必须写进项目说明文档。

随便抽几条感受一下颗粒度：

R3 节奏宁慢勿快：「初版默认放慢一档，主体动作弧 ≥3s，交互演示按真人操作速度」。判例：「全片六次独立反馈全部指向『放慢/停留』，从未有一次『太慢了』的反向反馈」。于是这条经验被固化成排片规则：第一版几乎总是偏快，帧预算里预先给 hold/rest 留量。

R4 卡点约束时机不放大幅度：「作用于整画面/相机层的节拍冲击（整画面 scale 泵/震屏/闪帧）视同大 slam 管理：全片 ≤3 处、钉最强 hit 清单、相邻两处间隔 ≥16 拍」。判例是 2026-08-22 的用户投诉「镜头会随节奏抖动，影响观感」——根因是把 kick 检测结果逐拍执行成了画面冲击。配套的自检问题是可执行的：「高能段任取连续 8 拍逐帧回放：整画面 scale/位移是否在逐拍脉冲？」

Q2 文字糊先查栅格化链路：3D 透视下 UI 文字发糊，根因是 Chromium 对 3D 合成层按 1920 布局宽栅格化再 GPU 放大。解法是放大走 CSS zoom（布局级缩放，让浏览器按放大后的尺寸栅格化）而不是 transform: scale，并给出坐标换算公式和排查顺序：「DoF 只做氛围，永远不是清晰度的解法（实证无效）」。判例是用户三轮追打「还是不够高清……有像素点的方块」。

Q11 要读的字有最低有效字高：字幕有效字高 ≥56px（1080p 下 ≥5.2% 帧高），验收量渲染帧上的实际像素，不看代码里的 fontSize。还给出了二分法：文字只有两态——「纹理」（明显虚化让观众不去读）或「要读」（达标字号 + 足够对比度），不存在「重排了但仍读不清」的中间态。

S1 禁的是音色，不是动作：产品宣传片禁用游戏音包音色（合成器 pluck、卡通弹跳），但画面真有点击/开关就该配它的拟音。判别问句：「这个音像真实世界里那个物件发出的声音，还是像游戏引擎里的反馈提示音？前者用，后者弃。」文档甚至点名 sfx/ui/ 目录 18 个文件里一半是合成反馈音，「不是整目录放行，恰恰是全库最需要逐个试听的一类」。

S5 音画对齐补两项偏移：渲出成片的音轨相对视频有固定滞后，根因是 AAC encoder priming（48kHz 典型约 1.28 帧@30fps），实测值、测法（归一化交叉相关）、补偿公式（from = 目标峰值帧 − 峰值滞后 − 输出偏移）全写进了文档，还跟踪了 Remotion 的 issue 编号。一条 skill 里的声音准则能精确到采样数量级，这是把它当工程项目做的态度。

这份文档的价值在于它回答了一个长期困扰 skill 作者的问题：品味怎么教给 agent？ 答案是把品味还原成判例。抽象的「要有高级感」agent 执行不了，但「用户说过不需要每个卡片都闪烁一下，所以光效只给主角一次」可以执行、可以自检、可以验收。22 条准则，每条背后都是一次真实的返工——这是拿时间换来的训练数据，只不过训练方式是写进 markdown 而不是灌进模型。

六、声音与卡点：从词汇表到 ≤3 帧的闭环

声音设计（sound-design.md）有一套自洽的体系：

• 词汇表按片种选，不按事件选：产品宣传片的五个词是 whoosh（运镜）、impact（落地）、riser（铺垫）、sparkle（光效，注意目录名是 light/）、transition（转场）。BGM 选强鼓点电子底（tech-house 类），判据是「典型的产品宣传视频」气质而不是「好听」；候选曲必须垫进成片试听，「单听曲子选型不可靠」——判例是模板片 BGM 三易其稿、34 分钟内两次被否。
• 声明式钉帧表：SFX 是一个 { from, src, volume }[] 数组，逐条注释对应画面动作，from 一律写相对表达式（SHOTS.x.from + offset），绝不写裸数字帧号——时间线平移时钉帧表自动跟随。
• 连发防机枪感三招：双样本交替、音量阶梯递减（如六连发 0.40→0.25）、间隔加速贴动画曲线。
• 两份特殊名单：21 个长于 5 秒的样本必须显式给 durationInFrames，否则会拖过动作结束还在响；7 个峰值低于 −12dB 的轻音素材，volume 是乘法系数、给到 1.0 仍会被 BGM 盖住——首选换素材或预归一化，必要时给大于 1 的增益并「以渲染产物验峰防削波」。

卡点方法论（music-beat-sync.md）则工程化到令人发指，完整链路是「拿到曲子 → 成片切点误差 ≤3 帧」：

1. 不信 beat_track 的 tempo 标量（实测报 129.2、真值 131.97，偏差 2%+），改为对 beat 时刻序列做最小二乘等距网格拟合求真实 BPM 与相位；残差 ≤±15ms 才算机器鼓点网格可信；
2. 半倍/双倍歧义必查（70 BPM 报成 140 是常事），判据不是听感是鼓点数据：正确网格下 kick 应主要落在整数拍；
3. kick/snare/hihat 三分类（分频段测瞬态）：kick 驱动冲击、snare 驱动替换/闪切、hihat 密度管微动密度。且「命中表是候选池不是触发器」——强鼓点曲 kick 几乎每拍都有，逐拍执行就是画面抖动（又指回 R4 判例）；
4. 网格先验收后分镜：四个指标（命中率 ≥98%、平均误差 <10ms、全曲漂移 <5ms、首拍有效），分析产物留档，「是每一个切点的审计链」；
5. 时间线用拍号写：一切镜头边界用 beatF(n) 表达，换曲改两个常量全片重排；源音乐分析真值与渲染输出偏移分开记账，防二次补偿；
6. 渲后回测闭环：从成片抽音轨重跑网格拟合，逐一对比设计切点与实测拍，误差 >3 帧必修；30fps 交付不声称 <5ms 视觉精度（量化误差上限由帧率决定）。

这套流程的可复现性有实证：一支 70 秒、18 镜、131.97 BPM 的强鼓点宣传片按此法制作，渲后回测全部切点误差 ≤2.2 帧（感知阈值约 3 帧）。

七、工程底座：确定性、测试、导出

确定性渲染铁律：禁 Date.now() / Math.random()，一切伪随机用固定种子（mulberry32/哈希，seed 从 index 派生），逐帧可复现。这和 HyperFrames 的核心契约是同一条——「同一个时间值，永远产出同一组像素」，两家殊途同归。

测试设施分三层：仓库根 vitest 覆盖 assets/lib/helpers 的纯函数（mulberry32、velocityAt、lagged、dampedSettle、handheld——全是确定性断言）；CI 对 demos 全部 TSX 跑 tsc --noEmit --strict；再加一个 Python 冒烟脚本把所有 demo 注册进临时 composition 逐个 remotion still 渲首帧，断言不崩——「堵住能编译不能运行的 demo」。

剪映工程导出是 2026-08 的新能力：成片可导成剪映草稿——底片按镜头切段（可变速/重排/调色），字幕重建为原生文本轨（文字/字号/颜色可编辑），SFX/BGM 独立音轨。基于 pyJianYingDraft，Mac 剪映 11.2 实测通过，Windows 实现了但未真机验证。这个功能直接回应了「AI 生成的视频我还想再手动改改」的真实需求，也和国内的剪映生态对齐了。

Headless/CI 渲染三坑（README 实测记录）：低核机器加 --concurrency=1；新版 Chrome 删了旧 headless 模式，改用 chrome-headless-shell 二进制；remotion.media 被墙时用 --browser-executable 指本地路径。

版权姿态也处理得干净：很多镜头手法研究自 ClickUp、Perplexity、Slack、Notion、Figma 等官方宣传片，但 ATTRIBUTION 写明「所有实现均为从零重写，仓库不含任何原片片段、截图、美术资产或品牌元素」，并附了一段认真的法律边界说明（手法属于方法范畴、具体表达受版权保护、来源公开不等于授予复刻许可）。音频来自 Mixkit（免费商用）；提醒 Remotion 自身的许可独立于本 skill——个人与小团队免费，公司可能需要付费。

八、对写 agent skill 的启示

把 video-shotcraft 和 HyperFrames 放在一起看很有意思：同样是「代码生成视频」，HyperFrames 的护城河在运行时（自研可 seek 的动画引擎、框架托管媒体）；video-shotcraft 站在 Remotion 上，护城河在方法论（配方卡、判例、流水线）。对大多数 skill 作者来说，后者更可复制——我们不一定能写渲染引擎，但都可以沉淀自己的返工记录。几条可迁移的：

1. 把「参数真相」和「语义描述」分离。配方卡故意不追求自包含：语义在卡上，调校过的参数在 demo 源码里，索引用机器可读的 JSON 校验。用户/agent 只需要说出名字，剩下由三层事实源保证不跑偏。任何「按名字复用某个资产」的 skill 都该有这个结构。
2. 判例式规则比抽象原则可执行。「高级感」「克制」「呼吸感」教不会 agent；「用户两次否决逐卡发光，所以光效只给主角一次 + 自检问句」可以。写规则时附带判例（用户原话、返工经过）和自检问题，是让 agent 继承品味而不是背诵口号的办法。
3. 验收是流程设计，不是终点站。每镜头预写验收帧号、静帧肉眼自检、每轮修改整片重渲、独立 subagent 干净上下文终检——「制作者对自己的产出有确认偏差，首检永远不能交给用户」。
4. 便宜阶段解决方向性问题。styleframe 用 HTML 静帧而不是渲染视频；产品检查只读不写；确认物（简报、决策表）都是文字表单。「先想清楚再动手」不是态度要求，是成本结构设计。
5. 入口即分诊。三种模式 + 两条例外 + 默认禁止项，把「agent 该问什么、该停在哪、什么时候不许自由发挥」全部显式化。skill 的触发词写得再准，也挡不住入口处的错误默认。
6. 允许偏离，但要求留痕。能量骨架「是默认项不是令」、审美准则「可以有意识违反但必须写进项目文档」——好的 skill 不是把 agent 框死，而是让每次偏离都留下可审计的理由。这和 WikiSkill 论文里「经验先沉淀、再进化」的思路遥相呼应：判例文档本身就是这个 skill 的 wiki 层。

九、上手建议

如果你想试：先去在线 Gallery 逛一圈——209 条动态样片可搜索、筛选、多选复制卡名，挑好镜头再回来提需求，比空口描述动画高效得多。三条路线按需选：要快、要稳，用 Ink Press 模板路线；要参与决策，走共同创作；想看 agent 的上限，直接说「自由创作」。单张卡也能单独用（「参考 spotlight-hero-card 给这个页面设计一个特写镜头」）。

两个注意：一是 Remotion 的公司用许可需要自查；二是 README 里那句提醒值得记着——装好后别让 agent 上来就出片，它的价值恰恰在那套「先产品检查、再模式分诊、再分镜」的结构化流程里，跳过流程直接渲染，等于放弃了它和「一把梭生成视频」工具的全部差异。

最后留个观察：这个仓库的构建、迭代与验收「全程由 AI coding agent 完成，用的正是这个 skill 所传授的工作流」——skill 教 agent 做视频，做视频的过程又产出新的判例反哺 skill。从 104 卡到 152 卡的扩充就是这么滚出来的。一个能自我供给训练数据的创作工具，这大概才是六周近七千星之外，它真正值得研究的地方。