web-ppt

name

web-ppt

description

Generate presentation slides as standalone HTML files with video recording support (Playwright + TTS + FFmpeg). TTS engines: Edge TTS (local/fast) and CosyVoice 3.0 (remote GPU/high-quality/voice cloning). MUST use this skill for ANY slide-related task: creating new presentations, editing existing slides, styling/color/font changes, fixing bugs in slides, recording videos from slides, or adding TTS dubbing/subtitles. Trigger on ALL of these (even partial matches): "PPT", "幻灯片", "演示文稿", "slides", "slide deck", "pitch deck", "演示", "介绍", "demo", "路演", "发布会", "培训", "培训材料", "培训课程", "配色", "字体", "主题", "风格", "美化", "录制", "录屏", "视频", "配音", "TTS", "字幕", "旁白", "声音不同步", "音画不同步", "字太小", "字体大小", "CosyVoice", "声音克隆", "克隆声音", "换个声音", "参考音", "用我的声音". Also trigger when user mentions data-narration, wants auto-playing slides, needs product intro/onboarding/tutorial materials, or asks to "show me how X works". This skill produces modular HTML (slides.html + slides.css + slides.js) that runs in any browser — no build step, no external dependencies, no PowerPoint needed.

Web PPT — 网页演示文稿生成

生成精美的 HTML 演示文稿。零外部依赖、浏览器直接打开、支持视频录制。

按需加载子文档：本文档内联了核心守则和命令速查。详细内容见各子技能目录。

---

我需要做什么？（决策树）

用户需求
  │
  ├─ 做个 PPT / 创建演示文稿
  │    ├─ 从零开始 → 按顺序执行 4 个阶段
  │    │    Step 1: ppt-plan     → 内容策划（页数、文案、旁白）
  │    │    Step 2: ppt-design   → 视觉设计（主题、配色、字体）
  │    │    Step 3: ppt-build    → 编码生成（HTML/CSS/JS）
  │    │    Step 4: ppt-video    → 视频录制（可选）
  │    └─ 用户只给主题 → 从 Step 1 开始，每步确认后继续
  │
  ├─ 内容/文案相关 → ppt-plan（content-templates.md, narration-writing.md）
  ├─ 视觉/风格相关 → ppt-design（design-philosophy.md, preview-flow.md）
  ├─ 编码/修改相关 → ppt-build（naming-contract.md, font-size-rules.md, recording-system.md）
  └─ 视频/录制相关 → ppt-video（video.md, scripts/）

---

⚠️ 核心守则（内联，必读）

以下规则来自多次实战踩坑。违反任何一条都会导致用户反复修改。

守则 1：命名契约 — HTML 是 API 契约

CSS 和 JS 的选择器必须严格匹配 HTML 中的实际 class/id。

幻灯片包装器：.slide .slide-{type}     （如 .slide-cover, .slide-pain, .slide-grid）
子元素：      .{type}-{role}            （如 .cover-title, .pain-desc, .grid-card）
全局 UI：     固定名称                   （#subtitleBar, #recordBtn, .progress-bar）
禁止：        .card / .title / .desc    （太泛化，多 slide 会冲突）

详细规则和验证 bash 命令见 ppt-build/naming-contract.md。

守则 2：字体大小下限

PPT 字就是要大。不得低于以下最小值：

元素	最小 clamp() min	典型范围
封面标题 h1	2.5rem	2.5–5.5rem
幻灯片标题 h2	1.8rem	1.8–3.5rem
章节标签	1.2rem	1.2–1.6rem
卡片标题	1.15rem	1.15–1.5rem
正文描述	1rem	1.0–1.2rem

绝对禁止：章节标签 < 1rem、正文描述 < 0.95rem。

守则 3：Audio-First 视频生成

永远不要用固定时长（如每页 4s）生成视频。

实测：9 页 PPT 音频 61.7s，固定 4s/页视频只有 28s — 音画严重不同步。

正确流程：
  1. Edge TTS 生成每段音频 → 用 ffprobe 读实际时长
  2. 每页视频停留 = 音频时长 + 1s 缓冲
  3. ASS 字幕时间轴基于音频 offset（不是固定间隔）
  4. FFmpeg xfade + 合并音频 → final.mp4

完整脚本见 ppt-video/scripts/render.py。

守则 4：Anti-AI-Slop TOP 5

禁止	原因	替代
Inter, Roboto 字体	AI 审美刻板印象	Archivo Black, Syne, Manrope
#6366f1 蓝紫渐变	千人一面	根据内容构建配色
纯白/纯黑背景	缺乏层次	渐变 + radial-gradient 叠加
所有页面居中对齐	视觉疲劳	至少 3 种布局交替
每页标题 + bullet list	单调	Hero, Split, Grid, Quote 交替

守则 5：Viewport Fitting

.slide { width: 100vw; height: 100vh; height: 100dvh; overflow: hidden; display: none; }
.slide.active { display: flex; }

• 幻灯片显隐：只用 display:none / display:flex。禁止 opacity:0（元素仍占空间、可被点击）。
• 禁止 inset:0（Safari 不一致），用 top:0; left:0; width:100vw; height:100vh。
• 内容超出？拆分成多张幻灯片，绝不缩小字体或滚动。

守则 6：录制面板

截图/录屏前必须隐藏录制面板：

// Playwright 截图前
await page.evaluate("document.querySelector('.record-panel').style.display = 'none'");

录制按钮状态用 classList 切换，不用 textContent（会破坏 CSS ::after）。

---

命令速查

# 本地预览（模块化项目必须用 http.server，禁止 file://）
python3 -m http.server 8080 --directory /path/to/slides-dir
open http://localhost:8080/slides.html

# 质量验证 — Anti-AI-Slop lint + WCAG 对比度
python3 scripts/slide_lint.py --html slides.html --css slides.css

# 质量验证 — 完整 4-pass 检查
python3 scripts/slide_validator.py --html slides.html --css slides.css --json

# 自动修复（字体大小、对比度）
python3 scripts/slide_fixer.py --html slides.html --css slides.css --errors "E_FONT_SIZE_UNDERFLOW,E_CONTRAST_LOW"

# Playwright 截图（1920×1080，自动隐藏录制面板）
python3 ppt-video/scripts/capture.py --url http://localhost:8080/slides.html --output-dir ./frames

# Edge TTS 批量配音
python3 ppt-video/scripts/tts.py --voice zh-CN-YunxiNeural --texts '["旁白1", "旁白2"]' --output-dir ./voiceover

# Audio-First 一键出视频
python3 ppt-video/scripts/render.py --dir ./my-presentation

---

生成后验证清单

快速验证（必做）

• 幻灯片数量正确：grep -c 'class="slide' slides.html 等于预期数
• 无空白占位页：每张幻灯片有有意义内容
• 录制面板在截图中不可见
• 导航正常：键盘方向键、空格、触摸滑动
• 动画流畅：打开浏览器手动检查

自动化验证（脚本）

# Anti-AI-Slop 检查 + WCAG 对比度 + 字体大小
python3 scripts/slide_lint.py --html slides.html --css slides.css

# 完整 4-pass 质量验证（结构 + 排版 + 对比度 + 布局多样性）
python3 scripts/slide_validator.py --html slides.html --css slides.css

# 如有 layout_plan.json，传入进行 plan 一致性检查
python3 scripts/slide_validator.py --html slides.html --css slides.css --plan layout_plan.json --json

自动修复（可选）

# 自动修复可修复的错误（字体大小、对比度）
python3 scripts/slide_fixer.py --html slides.html --css slides.css --errors "E_FONT_SIZE_UNDERFLOW,E_CONTRAST_LOW"

---

子技能与子文档加载指引

需求	子技能入口	深入阅读
规划内容结构、页数	ppt-plan/SKILL.md	content-templates.md
写旁白文案	ppt-plan/SKILL.md	narration-writing.md
选主题配色	ppt-design/SKILL.md	design-philosophy.md, references/themes.md
视觉预览（3选1）	ppt-design/SKILL.md	preview-flow.md
Anti-AI-Slop 检查	ppt-design/SKILL.md	design-philosophy.md
写 HTML/CSS/JS	ppt-build/SKILL.md	naming-contract.md
字体大小检查	ppt-build/SKILL.md	font-size-rules.md
录制按钮/面板	ppt-build/SKILL.md	recording-system.md
Playwright 截图	ppt-video/SKILL.md	scripts/capture.py
TTS 配音	ppt-video/SKILL.md	scripts/tts.py
一键出视频	ppt-video/SKILL.md	scripts/render.py, video.md
布局代码	—	references/layouts.md
动画代码库	—	references/animations.md
完整主题方案	—	references/themes.md
CSS 陷阱速查	—	references/css-gotchas.md
字体集成方式	—	references/fonts-integration.md
字体库（24 woff2）	—	references/fonts/

---

文件结构

web-ppt/
├── SKILL.md                          # 本文件 — 主入口（决策树 + 核心守则 + 命令速查）
│
├── scripts/                          # 自动化验证与修复脚本
│   ├── slide_lint.py                 # Anti-AI-Slop lint + WCAG 对比度 + 字体检查
│   ├── slide_validator.py            # 4-pass 质量验证器（结构/排版/对比度/多样性）
│   └── slide_fixer.py                # 自动修复（字体大小/对比度）+ 停滞检测
│
├── ppt-plan/                         # 内容策划
│   ├── SKILL.md                      # 路由
│   ├── content-templates.md          # 演讲结构模板 + 文字密度守则
│   └── narration-writing.md          # data-narration 写法 + 字数控制
│
├── ppt-design/                       # 视觉设计
│   ├── SKILL.md                      # 路由
│   ├── design-philosophy.md          # 设计哲学 + Anti-AI-Slop 完整规则
│   └── preview-flow.md               # 视觉预览流程（3预览→用户选）
│
├── ppt-build/                        # 编码生成
│   ├── SKILL.md                      # 路由
│   ├── naming-contract.md            # 命名契约 + 并行生成 + 验证命令
│   ├── font-size-rules.md            # 字体大小下限表
│   └── recording-system.md           # 录制面板 HTML/CSS/JS 规范
│
├── ppt-video/                        # 视频录制
│   ├── SKILL.md                      # 路由 + Audio-First 概要
│   ├── video.md                      # 完整视频技术参考（695 行）
│   └── scripts/
│       ├── capture.py                # Playwright 截图（argparse）
│       ├── tts.py                    # Edge TTS 批量生成（argparse）
│       └── render.py                 # Audio-First 一键出视频（argparse）
│
└── references/                       # 全局共享文档
    ├── layouts.md                    # 布局代码库（Hero/Split/Grid/Timeline 等）
    ├── animations.md                 # 动画代码库 + Effect-to-Feeling 映射
    ├── themes.md                     # 完整主题配色方案（9 主题，WCAG 验证通过）
    ├── css-gotchas.md                # CSS 陷阱速查
    ├── fonts-integration.md          # 字体集成方式（本地/Base64/系统栈）
    ├── platform-profiles.json        # 画布场景预设（5 种）
    ├── fonts-whitelist.json          # 字体白名单 + 权重限制
    ├── layout-schema.json            # 布局方案 JSON Schema
    ├── slop-lint.md                  # Anti-AI-Slop 可执行检查表
    ├── error-codes.md                # 统一错误码 + 退出码
    └── fonts/                        # 24 个 woff2 字体文件

典型输出项目：

my-presentation/
├── slides.html            # HTML 入口：结构 + data-narration
├── slides.css             # 所有样式
├── slides.js              # 所有逻辑（导航/TTS/字幕/录制）
├── fonts/                 # 本地 woff2 字体
├── frames/                # Playwright 截图（slide_00.png …）
├── voiceover/             # TTS 音频（slide_00.mp3 … + full_audio.mp3）
├── subtitle_synced.ass    # 音频同步字幕
└── final.mp4              # 最终视频（音频+视频+字幕）

---

常见反模式速查

禁止	正确做法
opacity:0 隐藏幻灯片	display:none / display:flex（opacity 隐藏的元素仍占空间、可被点击）
inset:0 定位幻灯片	top:0; left:0; width:100vw; height:100vh（Safari 不一致）
固定 4s/页生成视频	Audio-First：音频时长驱动每页停留（见 ppt-video）
Google Fonts CDN	本地 woff2（零延迟）或系统字体栈
file:// 打开模块化文件	python3 -m http.server（浏览器安全策略阻止外部资源加载）
纯白/纯色背景	渐变 + radial-gradient 叠加（纯色缺乏层次）
所有页面同一布局	至少 3 种布局交替（Hero, Split, Grid, Quote…）
字体太小（< 1rem）	章节 ≥ 1.2rem，正文 ≥ 1rem，封面 ≥ 2.5rem
captureStream() 录制	getDisplayMedia({preferCurrentTab:true})（Chrome 已废弃 captureStream）
textContent 改录制按钮	classList.add('recording')（textContent 破坏 ::after 伪元素）
字幕用 BorderStyle=3	BorderStyle=1（3=背景框，用户说"字幕为啥要带背景条"）
--write-media 写成 -w	始终用 --write-media（-w 在某些 edge-tts 版本不生效）