| name | ppt-explain |
| description | 把 PPT / PDF / Word 文档逐页转成图，逐页写旁白配音，本地 remotion 加运镜/转场/字幕渲成讲解视频。含文档解析、TTS、分镜、渲染全套脚本。 |
ppt-explain —— 文档 / PPT 逐页讲解成片
把一份已有文档（PPT / PDF / Word）变成「逐页展示 + 讲解旁白 + 运镜」的视频。不生成插画、不做手绘绘制——画面就是文档原页。与手绘专家共用一套渲染/TTS/登录骨架，独有的只是文档解析与运镜 Layout。
脚本目录（都在本 skill 的 scripts/ 下）
| 脚本 | 来源 | 作用 |
|---|
run.mjs init | 复用手绘 | 幂等装 remotion 渲染依赖 + chrome（国内镜像优先） |
workspace.mjs new --topic | 复用手绘 | 在当前工作目录建 JOBDIR，回绝对路径 |
doc-to-pages.mjs <file> --out <JOBDIR> | 本专家新增 | 文档逐页转 NN.png + 导出 source.txt（逐页文字，供整体解析） |
run.mjs synthesize "<text>" --out NN.mp3 | 复用手绘 | edge-tts（默认免费）/ vibeknow（付费高级音色）合成旁白 |
build-manifest.mjs <JOBDIR> | 本专家版（去掉 vec 依赖） | 按 NN 同号配对 png+mp3+txt → scenes.json |
run.mjs login / login-status | 复用手绘 | 设备码登录（成片闸门用；带 workbuddy channel 归因） |
render-reel.mjs --manifest ... --out ... | 本专家版（新 Layout + 登录闸门） | 未登录拒渲，登录后 remotion 出片，输出校验过的 width/height/durationSec/bytes JSON |
同号配对铁律：NN.png/NN.txt/NN.mp3 必须同一个两位序号，build-manifest.mjs 只按文件名配对，配不错。
写稿铁律：先整体解析 source.txt + 页面图 → Stage1 导演定调性+每页字数预算 → Stage2 逐页写 NN.txt（不是一页一句地攒，页页要承接）→ check-script.mjs 机器核字数达标。全自动一次性出片，中途不停下审稿（用户诉求）。详见两份 references + agent SOP。
doc-to-pages.mjs（新脚本，逐页转图）
- PDF：
pymupdf（fitz）逐页 get_pixmap(dpi=144) → NN.png。144DPI 是密度/体积平衡点。
- PPTX：走纯 JS 渲染（专家自带 Chrome +
@aiden0z/pptx-renderer，见 pptx-to-images.mjs）逐页出图，不依赖 Office/LibreOffice、不装任何东西，谁的机器都能跑。
- .ppt / .docx / .doc / .odp / .key：只用机器上已装的引擎转 PDF（已装的
soffice/LibreOffice，或 macOS 已装的 Keynote），绝不主动安装（700MB LibreOffice 会劝退用户）；都没有 → 报 NEED_PDF，提示用户自己「导出为 PDF」再上传（几秒、零安装）。
- 输出：
NN.png（页号从 01 起）+ 打印 {pages, width, height}，各页尺寸一致（同一文档天然一致）。
- 页数即视频镜头数；文档几页视频就几幕，不额外拆页。
渲染 Layout（render/layout/PptExplainLayout.tsx，新增）
- 底图 = 整页
NN.png（objectFit: contain，按画幅居中，letterbox 用近黑 #111318 给「屏幕」质感）。
- 刻意不做运镜（用户明确要求）：整页静态展示，不推近/不平移。动感只靠幕间转场。
- 转场：幕间
fade（复用 @remotion/transitions），简单克制。
- 字幕：底部安全区半透明底 + 白字，显示当前幕
narration（字号按画面高度 4%，可 --no-subtitle 关）。CJK 字体走系统栈（PingFang/YaHei/Noto），渲染机需有中文字体。
- 每幕时长 = 该页
NN.mp3 时长 + 尾部留白（默认 1.0s，别靠调大它凑时长）。
画幅 / 分辨率（与出图、渲染保持一致）
--aspect：horizontal(16:9,默认) / vertical(9:16) / square(1:1) / classic(4:3)。按文档原比例选（PPT 多为 16:9 或 4:3），错配会黑边或裁切。--resolution：默认 720p；文档字多时 1080p 更清晰但更慢。- PDF/PPT 转图 DPI 够高即可（144DPI 对 720p/1080p 都够），不像手绘要严格 check-images 尺寸档位。
登录 / 引流抓手（已定：成片就要登录）
本能力全本地可跑（转图 + edge-tts + remotion 都不需远端），没有手绘 vtracer 那种天然登录关卡。引流 gate 落在「成片」这一步：
render-reel.mjs 自带闸门：未登录直接拒渲，返回 {status:"login_required"} 退出码 3 → 专家引导用户 run.mjs login（设备码，复用 vibeknow 账号 + channel=workbuddy-ppt-explain 归因）。- 登录态 token 独立存
~/.workbuddy/vibeknow-ppt-explain/token.json（与手绘分开，各自归因）。
- 更远端的抓手（发布到 vibeknow / 分享链接 / 去水印高清 / 高级音色）用同一登录态。
