kepu-quickcut

科普快剪——知识点 → 选叙事模板 → 出 1080×1920 竖版科普短视频 MP4。五种已验证叙事模板：汉字演变、时间线、白板手绘、水彩绘本、机制机器。确定性渲染（画面=seek(t)函数），字永远不错、任何帧可精确复现、改哪改哪。触发词：科普视频、竖版短视频、汉字演变、时间线视频、白板手绘动画、水彩绘本风、机制机器、系统流程、Agent工作流、知识点转视频、10秒科普。

科普快剪（kepu-quickcut）

把一个知识点做成 10 秒竖版（1080×1920）科普视频。核心原则：模板引擎，不是自由生成——不许从零写动画，必须基于 templates/ 里的叙事模板填槽改造。这保证字不出错、风格统一、批量出集可行。

何时用 / 何时不用

✅ 适用：汉字/诗词/成语等中文文化科普、历史或概念时间线、生活原理对比、月相/自然现象等绘本感知识 ❌ 不适用：口播真人视频、带 BGM 的卡点视频（版权风险，默认无声）、3D 场景（重）、地图路线（用现成 map-motion skill）

工作流（严格按顺序）

第 1 步：选模板

模板	文件	叙事结构	适合内容
汉字演变	templates/hanzi-evolution.html	五幕：古文字形态依次生长 → 尾屏诗句点破	单个汉字的字源+诗词串联
时间线	templates/timeline.html	镜头沿横轴推进，节点依次点亮，大年份同步翻动，尾屏点破	编年史、技术演进、个人里程碑
白板手绘	templates/whiteboard.html	A/B 对比：火柴人两方案 → 曲线/柱图 → 红笔圈点破句	二选一对比、习惯养成、方法论
水彩绘本	templates/storybook.html	分层错拍开场 → 主体依次变换 → 尾屏哲理点破	自然现象、月相、季节、温情感知识
机制机器	templates/machine.html	开场先亮骨架 → 零件逐个点亮、小球沿管道流动 → 反馈回路（可选）→ 尾屏点破	系统/机制/流程：Agent 工作流、RAG、数据流水线

选型纪律：动笔前先想内容与哪个叙事结构天然契合，不硬套。

第 2 步：填槽（改 HTML，不改架构）

每个模板里标了参数槽：文案、颜色、节点/幕次数据、点破句。规则：

• 只改槽位数据，不动渲染逻辑（seek 函数、水彩算法、rough 注册流程）
• 点破句 ≤ 14 字，一行放得下；是全片的"眼睛"，花最多时间打磨它
• 每个模板遵守自身克制清单（见各文件头部注释），高级感来自不做什么

第 3 步：抽帧自检（必须，不可跳过）

bash

NODE_PATH=<playwright-core 所在的 node_modules> node scripts/capture.js preview 抽帧

用一小段脚本采 3-5 个关键帧（t 取各幕中点 + 尾屏），逐一目检： 文字是否溢出/被裁、形态是否正确（尤其窄月牙类易自交）、层与层是否露底、尾屏是否干净无叠影。

第 4 步：用户确认

把关键帧给用户看，确认叙事节奏和文案。未经确认不进入渲染。

第 5 步：渲染成片

bash

node scripts/capture.js <anim.html> <frames_dir>        # 300 帧，约 43 秒
python scripts/assemble.py <frames_dir> <out.mp4>       # h264，可直接发

环境要求（零安装验证过的方案）

• Chromium：Playwright 缓存 ~/Library/Caches/ms-playwright/chromium_headless_shell-*/（capture.js 自动发现）
• 合成：Python + opencv-python（自带 openh264）。注意：Playwright 的 ffmpeg 只有 VP8，mp4/h264 必须走 opencv
• 依赖 playwright-core（require 路径用 NODE_PATH 指向已有 node_modules）

叙事铁律（来自《经济机器是如何运行的》纪录片）

1. 开场先亮骨架：任何模板的开场（0–1s）先给观众"全片骨架预告"——用最少的画面告诉观众"这片子总共几个环节/几幕"，脑子里先有地图，再逐个填细节。违反这条，观众看到第 3 幕才知道这片有几幕，理解成本翻倍。
2. 从最小原子讲起：拆知识点时先锁定"最小可感单元"（一次交易 / 一个动作 / 一步调用），再往上叠成系统。

渲染铁律（踩坑换来的，违反必翻车）

1. 一切画面都是 window.seek(t) 的纯函数。禁用 random()/requestAnimationFrame/setTimeout 做画面；要随机感用固定种子伪随机（如 mulberry32(seed)），要"活感"用多频正弦叠加
2. rough.js：rc.svg() 返回的 <g> 必须手动 appendChild 再注册动画（漏了整个不渲染）；所有 rough path 设 pathLength='1'，dashoffset 动画笔画生长零换算；seed 固定
3. 水彩叠层：40 层 × 4.5% alpha 坑洼多边形；多色叠涂必须共用同一份坑洼轮廓（各自扰动会边缘错位露底成"缝"）；扰动幅度宁小勿大（窄形状易自交）
4. 大标签/年份切换与镜头转场严格同步：淡出窗口对齐转场中段，否则空档或叠影
5. 尾屏登场前整个舞台先淡出，遮罩不透明度 ≥0.95
6. hachure 排线填充去 PPT 味：柱状图/色块一律 fillStyle:'hachure'
7. 古文字/手绘形态用手绘 SVG 路径，不依赖字体；手写感字体 macOS 可用 HanziPen SC / Hannotate SC；商用发布只用 OFL 字体（候选：马善政楷书）
8. 文字安全区：左右 ≥60px，点破句不贴底边
9. 尾屏专属元素挂在 stage 组外（reg 传 parent=svg 根）：点破句红圈等尾屏元素若挂进舞台组，会跟舞台一起淡出消失
10. "点亮"用同 seed 蓝框重描：零件框画黑底框 + 同 seed/roughness 的蓝框（仅颜色不同→路径完全重合），点亮时蓝框笔画生长正好盖住黑框，天然"从黑变蓝"
11. 流动粒子停靠点放管道中段，不放零件中心：否则段间停留时持续遮挡零件文字；穿框瞬间的短暂重叠是"流经"动效，可接受

发布前检查

• 抽帧目检全过（无溢出、无露底、无叠影）
• 用户确认过关键帧
• 成片可读性验证（cv2 能打开、帧数/fps/尺寸正确）
• 默认无声（BGM 不碰版权曲库）