# Deck Render

幻灯讲解视频的本地 HTML 确定性渲染工具：环境检查、逐页脚手架、质量检查、静帧联系表、MP4 渲染。

- Repository: https://github.com/TeamWiseFlow/xiaobei (8678 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add TeamWiseFlow/xiaobei --skill deck-render -g -a claude-code -y`
Codex: `npx skills add TeamWiseFlow/xiaobei --skill deck-render -g -a codex -y`
Cursor: `npx skills add TeamWiseFlow/xiaobei --skill deck-render -g -a cursor -y`
Gemini CLI: `npx skills add TeamWiseFlow/xiaobei --skill deck-render -g -a gemini-cli -y`

## Description

幻灯讲解视频的本地 HTML 确定性渲染工具：环境检查、逐页脚手架、质量检查、静帧联系表、MP4 渲染。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# deck-render

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

## 命令

```bash
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 契约

```json
{
  "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}]}
  ]
}
```

The rest: https://github.com/TeamWiseFlow/xiaobei/blob/HEAD/crews/content-producer/skills/expert-video/tools/deck-render/SKILL.md