deck-render

这是 expert-video 包内原子工具；制作流程读 workflows/deck-talk.md。通过 PATH 调 deck-render，不拼接脚本路径，不调用上游创作 workflow。

命令

deck-render check-setup
deck-render scaffold /absolute/project/composition --spec /absolute/project/script/deck-spec.json
deck-render check /absolute/project/composition
deck-render preview /absolute/project/composition --output /absolute/project/review/slides-v1
deck-render render /absolute/project/composition --output /absolute/project/render/slides.mp4 --workers 2 --quality delivery

• check-setup 检查 Node ≥22、ffmpeg/ffprobe、锁定 npm 依赖、Playwright Chromium headless shell 和当前系统默认中文字体（Windows 微软雅黑；Linux/macOS Noto Sans CJK SC），并运行 HF doctor。doctor 中 Whisper/Kokoro/MusicGen 属可选；本工具不用它们。
• scaffold 只写空目录。产物是根 index.html、每页一个 compositions/scene-NN.html、本地 GSAP 与图片副本、deck-spec.json。先按时间戳确定时长，再生成；之后直接编辑 HTML，不用 scaffold 覆盖设计。
• 指定 1080×1920 等竖屏尺寸时，.page 直接按竖屏画布生成；不可把横屏 HTML 用 scale(x,y) 非等比拉伸。check 会拦截 .page 的非等比缩放。
• check 顺序执行 HF lint 和 check（runtime/layout/contrast）。错误阻断；警告必须人工查看，不能把退出码 0 当作视觉验收通过。
• preview 先 check，再 snapshot，落 PNG 与 contact-sheet.jpg，不是常驻 HTTP 服务。默认按 spec 每页中点取图；手改 HTML 时序后必须同步 spec 或传 --at 2,12,24。输出目录必须为空，改版用新目录。
• render 每次先 check，再渲染；--workers 1, 24，质量 draft/looks/delivery。输出 MP4 必须与 HTML 根的宽高、fps、duration 一致；结果与耗时落同名 .render.json。已有产物需明确 --force；临时输出通过校验才替换，不覆盖输入。
• wrapper 全部 HF 子进程使用 HYPERFRAMES_NO_TELEMETRY=1，不改用户全局设置；静帧禁用 Gemini 自动描述，不触发模型付费调用。
• 退出码：0 成功；1 参数/质量检查/渲染失败；2 依赖/环境缺失，交 IT engineer。每条外部命令超时 20 分钟。

spec 契约

{
  "width": 1920,
  "height": 1080,
  "fps": 30,
  "theme": "light",
  "pip": "bottom-right",
  "scenes": [
    {"type": "title", "title": "一个清晰的命题", "subtitle": "对应口播第一段", "duration": 8, "points": ["第一条要点"]},
    {"type": "chart", "title": "示例数据，不代表业务事实", "duration": 10, "source": "演示数据", "caption": "演示数据", "data": [{"label": "甲", "value": 12}, {"label": "乙", "value": 18}]}
  ]
}