用途
video-to-template 用于把参考视频（URL 或文件）转化为可复用的 framesmith 模板，并最终产出适用于用户自己品牌的成品视频。它把此前产出 brutalist-product-promo、devtool-launch-video 和 narrated-collage-explainer 的过程打包，使下一个参考视频的处理更快。工作按阶段推进，且不应跳过任一阶段的门槛。
主要能力与工具（均位于 scripts/）
- analyze.py <url-or-file> [--transcribe]：下载视频；分析格式、镜头切换（场景评分与变化像素峰值的并集）、节奏、配色、音频类型，可选 Whisper 转录；生成带时间戳的接触表、每个镜头一张关键帧，以及含分镜骨架的 report.md。
- scaffold.py <name> --analysis …/analysis.json：生成新的模板技能，其brief中每个检测到的剪辑对应一个动态分镜镜头（使用参考关键帧并调暗），使第一分钟起时间就匹配。
- grab.mjs <url> <out> '<specs>'（node 22）：从线上站点抓取真实产品 UI：滚动以触发动画、隐藏固定条、按选择器或矩形裁剪、隔离固定图层。
- compare.py ref.mp4 ours.mp4：生成并排视频（使用参考音频）以及同一时间戳下的成对帧图表。
使用方式（分阶段流程）
- Phase 0 摄入：获取参考视频、目标品牌或产品、其真实 logo 与真实产品素材（README 演示、截图、文档）；如格式不同也需获取格式。只询问自己找不到的信息；公开产品先读其仓库或站点。门槛：能用一句话说明新视频的主题，且已拿到真实 logo。
- Phase 1 分析：运行 analyze.py，音频像语音时加 --transcribe。查看每张接触表和多张关键帧（需打开图片，仅看数字不够）。检测器只是初稿：合并被镜头内动画拆分的镜头，拆分被溶解合并的镜头。填写 report.md 中的分镜表：布局与主体、字体（字体、字号、颜色）、进出场运动、转场、文案。写一份简短风格规范：配色（目视确认；覆盖率排名会低估小面积强调文字）、映射到内置字体的字体角色（无衬线 Inter Display，代码仅用等宽 Geist Mono，像素字体 Departure Mono）、重复出现的视觉语法（构成视频的 5–8 种对象或处理类型）、转场类型、节奏（平均镜头长度，剪辑跟随节拍还是旁白）、音频。门槛：每个镜头的分镜已填写，风格规范已写。
- Phase 2 映射到引擎：为每个语法项选择引擎原语（references/engine-map.md）或计划新场景类型。检查路由器（skills/framesmith/SKILL.md）；若已有模板覆盖大部分语法，应扩展而非分叉。确定素材清单，优先使用真实素材（见 Phase 4）。
- Phase 3 脚手架与时间：在 framesmith 仓库内运行 scaffold.py，生成结果位于 skills/。渲染动态分镜并用 compare.py 与参考对比，时间应对齐。若参考含旁白：按参考的每秒词数写脚本，用 framesmith.narration.tts + transcribe_words 生成语音，并按语音提示重新定时而非固定时长；narrated-collage-explainer 展示了该模式。
- Phase 4 内容与素材：构建场景前，每行文案都需通过 no-ai-slop 技能及其评估（references/no-ai-slop/）；屏幕上文字无结尾句号。每个声明来自产品自身文档。绝不虚构推荐语、引述或真实人物的帖子；改为展示真实产物。真实素材优先：logo（绝不生成或重新诠释）、产品截图、以原生文本重新录入的终端记录（不是 GIF 裁剪）。品牌图标使用 brand-icons 技能（thesvg.org），按背景选浅色或深色变体，核对许可证并保留署名。生成的场景（gpt-image-2，low/medium）：写完整句子提示，指明材质、光照、镜头和明确背景（纯黑或白、透明，或用于抠像设备的纯 #00FF00 屏幕）；用精灵表（同一主体的网格，一个部分变化）实现循环运动。
- Phase 5 构建场景：按顺序逐个用真实场景类型替换动态分镜镜头。每个之后在 2–3 个时刻截取静帧并查看。设计规则在 references/design-rules.md，属硬性要求。
- Phase 6 审阅循环：check 必须通过：无溢出，文案不缩小至 80% 以下。查看图表，再用 compare.py 与参考对比。先修复最大不匹配：布局、再字体、再颜色、再运动。证明通用性：用不同品牌、浅色强调和长名称渲染第二个 brief。
- Phase 7 渲染与交付：使用唯一输出文件名渲染，并轮询日志而非 pgrep（references/lessons.md）。制作预览 GIF（docs/media/<name>.gif）和接触表。完成 SKILL.md（描述即触发器），向路由表添加一行，然后运行 tools/catalog.py、tools/sync_core.py --check、tools/validate.py、更新变更日志和版本号。提交；仅在用户要求时推送，且先检查仓库是否公开。开始前阅读 references/lessons.md，其中每一项都曾导致一次重新渲染。
适用场景
适合需要从参考视频快速生成品牌化视频模板与成片的场景，尤其适合产品推广、开发者工具发布视频和解说拼贴类内容。流程尤其适用于已有真实 logo 与产品素材、希望复用参考视频剪辑节奏与视觉语法的项目。
限制
技能要求严格按阶段推进并满足各阶段门槛；检测器输出的镜头切分需人工校正；文案须通过 no-ai-slop 评估；不得虚构推荐语或引述；logo 不可生成或重新诠释；品牌图标需核对许可证并保留署名。渲染后需轮询日志而非使用 pgrep。推送前需确认仓库是否公开。