华尔街式解读片（wallstreet-explainer）

讲一笔大账：真的人、真的新闻、真的画面作证据，图形舞台把数字和关系演出来；每一镜都接住上一镜的东西往下走，观众始终知道“现在在看什么、为什么看这个”。 动的是镜头和世界，不是元素自己演：镜头在有前后层的舞台里推、拉、摇，去找正在说的那个东西；东西在原地换状态。每一下动作都对着那句话的意思。

这份 skill 是什么

• 是：一套设计思路（每一镜放什么、为什么、凭什么接下一镜）、一套动效原理（从三条同类参考片逐帧量出来：为什么它不像 PPT、不像 AI，手法清单和量化目标）、一套风格语言（舞台、巨字、抠像、圆盘、数字、图表、原文高亮的具体做法，外加一份开头钩子菜单），以及一套工具。
• 两档做法，画风是同一个：
  • 模板档（默认，先用这个）：kit/ 里 33 个场景（大数字、照片圆盘、新闻桌面、原文刷黄、人站在巨字前面、柱子、图表、地图……）。一条片 = 一张镜头表：每一镜选一个场景，填这一镜的字、数、图和“念到哪个字”。镜头怎么走、东西怎么出现、前后层、运动模糊、字号颜色，都由模板管。这样设计，是想让弱一些的模型也能稳定出片；这一点还没实测过。
  • 手写档（强模型，或者模板对不上的时候）：底座 film_base.js + 手法库 moves.js + 2.5D 小工具 stage25d.js，逐镜手写。只有一镜对不上时，在镜头表里写 scene:'custom'，手写那一镜就行。
• 模板是词汇，不是镜头顺序。每条片的画面都要从它自己的文案和素材里现想：每一镜先写 says（这一镜让观众多懂了什么），再找意思对得上的场景；只是差不多就换一个，或者手写。examples/ 里的两条片记录的是片子怎么想出来、在哪里摔过跤，不要照搬它们的镜头。
• 画风的基准是成片，不是模板：《AI到底有多烧钱》的每秒一帧（examples/ai-burn-money/frames_1fps.jpg）和 28 秒的《谷歌给苹果的两百亿》（examples/google-apple-20b/，真素材手写）。模板的默认样子就是照它们做的；做出来的片子要能和它们并排放而不突兀。
• 手写档能复用的有两样，都是为了质量稳定：底座（scripts/film_base.js，每条片都一样的那层）和手法库（scripts/moves.js，磨过、逐帧查过的动作）。手法是词汇，不是镜头：先想这一镜要说什么，再找意思最对得上的手法；只是差不多就手写。不要为了用上手法去改画面，也不要为了出片去凑手法（选法见 references/motion.md 的手法库）。
• 慢推、数字滚动、实拍上压字，参考片都在用。廉价的不是这些手法，是做法。判断用三句话：删掉它观众少懂了什么？是镜头在动、东西在换状态，还是元素自己在演入场？这一层是真的、具体的吗？

动手前先读 references/thinking.md、references/motion.md 和 references/rules.md；做模板档再读 kit/README.md。其他几份按需要读。

五条硬规矩（完整的在 references/rules.md，带编号、能检查）

1. 真东西是主角：当事人实拍、新闻原文截图、官方发布会/财报/广告画面。图形只用来演钱和关系。示例片里的占位图（kit/assets/ph/）在正式片里一张都不能留。
2. 底只有一张细斜纹深蓝织物。不要满屏 3D 物体，不要紫、青这类整屏底色，不要大团彩色光，不要浮尘。品牌色只在当事人身后出现；酒红底一条片最多一段（算总账那段）。
3. 每一镜写 says，一镜一个主角；东西朴素地出现，镜头去找它。
4. 时刻挂在字上（'@b05:英伟达'），不写死秒数；开头 0.5 秒内开口，第一帧就有东西。
5. 交片前：render.mjs --check 没有错误；--sheet 自己看过；720p 抽帧和 frames_1fps.jpg 并排比过；关键动作看过连续帧。

流程：每一站停下来给用户看

审美由用户把关。不要一口气出成片；每站给出具体的东西，等他点头再往下走。

站	做什么	给用户看什么
0 选题	题目要同时满足“现在热”和“看完能带走点什么”；事实先查清、留链接	两三个题目，每个附一句钩子
1 文案	口语、第一人称，句句往下接；数字写成读法；插原声的地方先写铺垫句（references/audio.md）	全文。点头之前不做正式配音
2 导演表	见下面“导演表”一节。模板档在“手法”一列写场景名；每一镜的素材从哪来也写上	要点：开头怎么抓人、每处怎么接、要不要加铺垫句、哪几处用当事人抠像
3 素材	官方高清片 → 新闻原文 → 当事人原声 → 当事人抠像用的整段实拍（没有切点、有对得上台词的动作）。先拼联系表看过，再定入点，逐帧查切点；单段只截要用的几秒（references/sourcing.md）	3–4 张关键样帧（真素材 + 版式），方向对了再做整片
4 配音和时间线	先用 scripts/temp_voice.py 出临时语音，或用 scripts/timeline_stub.mjs 按字数估出时间线，画面全部挂在字上；换正式配音后重新对齐	—
5 开头	先挑 3 个机制不同的钩子，各做 5–8 秒粗剪给用户选（references/opening.md）；选中的再做成从 0 秒到第一个换段处的小样（15–20 秒，带声音）	3 个钩子粗剪 → 选中后的开头小样
6 全片 720p	按导演表铺完。模板档：镜头表 → --check → --sheet → 720p；手写档：每写两三镜截静帧看，关键动作看连续帧（strip.py），再跑 render.mjs --moves。交片前跑 motion_check.py，720p 抽帧和 frames_1fps.jpg 并排比	720p 全片、抽帧图，再点出两三处请他重点看
7 成片	改到满意；换正式配音，mix.py 混音；出 1080p，只渲一次	1080p

每次交付都要做到：

• 用 ffprobe 验证文件能打开。
• 自己逐镜看过静帧和联系表，关键动作看过连续帧。
• 放进一个固定的审阅文件夹，用编号加中文名命名，旧版本加 旧_ 前缀。
• 说清楚这版改了什么、哪些量过、哪些要用户自己听或看。
• 写清这条片实际用了哪一档、哪些脚本；版权素材标出来。

导演表

全片只有这一份计划。用户拿它核对画面，做的时候照它做，审片时拿它对照。每一镜写这几列：

镜	时间	文案	屏上是什么，在干什么 → 停下来时留下什么	观众多懂了什么	承担	读懂时刻 + 停留	承接	手法

• 观众多懂了什么：一句具体的话，和上一镜的不一样。写不出来，这一镜就该删或者重想。模板档里，这一列就是这一镜的 says。
• 承担：这一镜靠什么让人看懂。人物 / 实证（真素材、原文）/ 构造（圆盘、图表）/ 文字（大字、结论）/ 混合。
• 承接：上一镜留下的哪样东西被这一镜接住，接法写成 续 / 切 / 带过 / 推近 / 展开 / 换章 加上那样东西。第一镜写 —。
• 手法：模板档写场景名（kit/README.md 查）；手写档写 moves.js 里的手法名和它在这里说什么；都对不上写“手写”。先填前面几列，最后才填这一列。
• 在“屏上”一列里顺手写清镜头怎么走：每次移动的落点是谁（推到谁、摇去找谁、什么时候拉回看全），以及哪几镜用当事人抠像。
• 每一镜的素材从哪来（哪段实拍、哪篇原文、哪张照片）也记下来，交片时就是出处清单。
• 文案一字不改；一镜可以覆盖好几句话；时刻挂在词上（“说到‘七千’的那一刻”）。

写完做一次“读表”检查：遮住文案和“多懂了什么”两列，只读“屏上”一列，看还讲不讲得通。再查有没有连续好几处硬切、有没有停不够的镜头。示例见 examples/ai-burn-money/director.md。

模板档：一条片怎么做

node scripts/new_film.mjs <片子目录>                  # 建片子：lib/、assets/kit/、fonts/、script.json、film.js 起点
（写 script.json：每句 {id, text}；原声插段 bite、片名位置 title 的写法见 scripts/temp_voice.py 开头）
node scripts/timeline_stub.mjs <片子目录>/script.json  # 还没配音：按字数估时间线（之后换真配音重新对齐）
（写 film.js：await K.film([ {scene, until, says, enter, …场景参数}, … ])）
node scripts/render.mjs --dir <片子目录> --check        # 几秒：镜头表错误 + 提醒，改到没有错误
node scripts/render.mjs --dir <片子目录> --sheet        # 每镜开头/中间/末尾三帧拼成 out/sheet.png，自己先看
node scripts/render.mjs --dir <片子目录> --video --h 720

• 场景怎么选、每个场景的参数和例子：kit/README.md（“这句话在说什么 → 场景”的表在最前面）。
• 能跑的完整例子：kit/demo/film.js（前 22 个场景各用一次）、kit/demo2/film.js（后 11 个）。new_film.mjs <目录> --demo / --demo2 建出来就能渲。示例片用的是占位图，看写法，不看画面内容。
• --check 的提醒都要处理：要么改，要么能说出为什么不改。看不了图的模型，就靠 --check 的文字和 rules.md 的条目把关。
• 一镜对不上任何场景：scene:'custom' 手写这一镜（render(c) 里用 stage25d.js 的工具），也要写 says。

手写档：片子怎么搭（骨架，不是拿来抄的）

• 最小的样子：examples/google-apple-20b/film_index.html，一个页面，只暴露 window.ready 和 window.seek(t)，render.mjs 直接渲。
• 完整的底座：也用 new_film.mjs 建片子目录。index.html 已经引好底座、手法库、2.5D 小工具和模板库，字体在 lib/kit.css 里声明；把 film.js 里的镜头表换成手写的镜头：FB.init 以后用 shot() 一镜一镜登记，最后 return F.go()。实拍帧放在 assets/clips/<名>/，抠像放在 assets/cut/<名>/。字体和素材都要在片子目录里：render.mjs 的服务器根目录就是片子目录，../ 引用会 404。
• 底座（film_base.js）暴露 window.ready 和 window.seek(t)。seek 找到 t 所在的镜头（shot(t0, t1, fn)），调用 fn(t) 返回这一帧的 HTML，并等图片解码和字体加载完。同一个 t 永远画出同一帧，不依赖 CSS 动画和播放时钟。
• 时刻一律写成 cue(句id, '词')，从时间线里取，不写死秒数。换了配音，全片自动顺延。
• 实拍抽成帧序列，按 t 取帧，不用 <video>。帧数要登记，漏了会取到不存在的帧，出现黑屏或空框。
• 一镜 = 一个机位函数 + 几层画面：机位用 camPath(t, 起点, 移动表)，每层用 L(机位, 上一帧机位, z, html) 包起来，远的层 z 小，运动模糊自动算。
• 镜头之间要承接时，把上一镜的函数在它最后一刻的画面拿来做下一镜的开场（推过镜头、缩小挪走、撑开、横推出去）。这样上一镜的末态和下一镜的首态天然一致。手法库里的转场（pushSwap、pushThrough、blurToBase、frameFill）就是这样接的：from 传上一镜的函数。
• 手法在真片子里怎么用：examples/ai-burn-money/film_lib.js，第六版用底座和手法库重拼，和原版逐帧一致（素材不随仓库给，只用来读）。看它怎么在手写的画面里用手法、怎么写 why，不要照抄它的镜头。
• 720p 看效果，1080p 只在定稿后渲一次。

读哪份

在做什么	读
必须守的规则（编号、能检查）、“这句话 → 场景”决策表	references/rules.md
模板档：场景、参数、镜头表写法、时刻、接法、颜色	kit/README.md（图在 kit/gallery/）
想一镜该放什么、为什么、凭什么接下一镜	references/thinking.md
动起来：为什么不像 PPT/AI、手法清单、手法 → 模板写法、手法库怎么选、量化目标、相机和抠像的代码手感	references/motion.md
画面长什么样：舞台、巨字、抠像、圆盘、数字、图表、片名、字幕、实拍画框	references/style.md
两镜之间怎么接、运镜和动作的手感、走法 → 模板写法	references/grammar.md
开头	references/opening.md
找片、下片、挑入点、抠人、新闻原文、原声	references/sourcing.md
文案、配音、原声剪口、音效、混音	references/audio.md
交付前自检	references/review.md
实践中踩过的坑	references/lessons.md
两条成片是怎么想出来的	examples/ai-burn-money/（77 秒，六个版本）、examples/google-apple-20b/（28 秒，真素材手写）

工具（scripts/）

脚本	干什么
new_film.mjs	建片子：<目录> 新片，--demo / --demo2 示例片，--sync 只把 lib/ 和 assets/kit/ 更新到最新版
timeline_stub.mjs	没有配音时按字数估时间线（和 temp_voice.py 同格式，带 stub:true）
footage.py	search 搜片 / get 下载（可只下一段、只下音频）/ sheet 带时间码的联系表 / scenes 镜头切点 / extract 抽 30fps 帧序列 / wave 看原声剪口的响度
snap_news.mjs	新闻和报告原文截图：拦广告、去浮层、等字体加载完再量关键词的框（荧光笔用，坐标写进 docs/news.json）
matte.py	实拍逐帧抠人（GPU 上 ISNet 约 0.25 秒/帧），提示藏着的切点，只存人物外框那一块。没有显卡：examples/google-apple-20b/matte_full.py（CPU，同一个模型）
matte_clean.py	抠像后处理：去细线零碎、整列抹掉贴着的椅背、写出每帧头肩中心（放人时跟住他）
matte_despill.py	抠像去色边：原片背景色（比如会场蓝幕）渗进软边，换底后一圈蓝光。软边换色、收边、压溢色，写到新目录，先 --check 看单帧
stage25d.js	页面里用的小工具：分层相机 camPath/L、关键帧机位 camKeys、3D 桌面 desk3d、方向运动模糊、景深、抠像跟人 cutP、巨字 mega、眉题、实拍退成底、按十亿取整。只是工具函数，不是镜头
film_base.js	底座：读时间线、cue(句,'词') 取时刻、实拍取帧、shot() 登记镜头、按时刻找镜头、字幕、预加载。镜头有空档、实拍没登记、找不到字时直接报错。模板档也搭在它上面
moves.js	手法库：横推换人、人身后换背景、巨字随话翻、卡片冒出来、画框推满屏、甩进来、倒成桌面、钉住换实拍、证据小卡、虚化当底、推过镜头、累加滚数。只管动作，画面由片子传。手写档直接调用，调用要写 why；模板档的接法也是用它做的
temp_voice.py	script.json → 临时配音（edge-tts）和 timeline.json（每个字的时刻、原声插段、片名位置）；有正式配音时自动换上，--asr 重新对齐
render.mjs	逐帧渲染：--check 查镜头表（模板档，几秒，不渲染）、--sheet 每镜三帧拼图、--stills 看帧、--video --range 渲一段、--h 1080 出成片（渲完自动报“第几秒画面是空的”）；--moves [--prev 上一条/out/moves.json] 查手法用量
strip.py	连续帧拼图：一个动作 8 张，查静帧看不出来的穿帮；也用来拆参考片的动作
motion_check.py	镜头运动自检：画面完全不动的时间、定住次数、镜头在动的时间、前后层、推拉比，和参考片的区间比
mix.py	配音、原声、音效、配乐（配乐给人声让路）→ -14 LUFS；--check 量各段响度

依赖：ffmpeg、yt-dlp、Python（edge-tts、numpy、opencv-python、Pillow；可选 faster-whisper；抠人要 onnxruntime-gpu 和 rembg 下载的模型）、Node 和 Playwright。安装方法见 README。

字体不随仓库给，要自己下（清单见 README）：Bebas Neue、阿里妈妈数黑体、MiSans、Montserrat，文件名以 kit/kit.css 里的 @font-face 为准。下好放进一个文件夹，在 scripts/local.json 里写 fonts_dir；new_film.mjs 建的片子里，fonts/ 是指向这个文件夹的联接，联接建不了就拷过去。Playwright、ffmpeg 不在默认位置时，也写在 local.json（playwright_from、ffmpeg）。这个文件只放本机配置，不进仓库。

配音：先用临时语音

• 先用 temp_voice.py 出 edge-tts 临时配音，排出时间线，画面照它做。
• 文案和画面都定了，再换正式配音（任何 TTS、克隆音色或真人录音都可以）：每句存成 voice/<id>.final.wav，跑 temp_voice.py script.json --asr。
• 配音一律：切掉首尾静音、保持原速、句间停顿只由 gap 决定。不要事后用 atempo 加速，切掉静音以后再加速会很急促。