| 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：录制面板
截图/录屏前必须隐藏录制面板：
await page.evaluate("document.querySelector('.record-panel').style.display = 'none'");
录制按钮状态用 classList 切换，不用 textContent（会破坏 CSS ::after）。
命令速查
python3 -m http.server 8080 --directory /path/to/slides-dir
open http://localhost:8080/slides.html
python3 scripts/slide_lint.py --html slides.html --css slides.css
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"
python3 ppt-video/scripts/capture.py --url http://localhost:8080/slides.html --output-dir ./frames
python3 ppt-video/scripts/tts.py --voice zh-CN-YunxiNeural --texts '["旁白1", "旁白2"]' --output-dir ./voiceover
python3 ppt-video/scripts/render.py --dir ./my-presentation
生成后验证清单
快速验证（必做）
自动化验证（脚本）
python3 scripts/slide_lint.py --html slides.html --css slides.css
python3 scripts/slide_validator.py --html slides.html --css slides.css
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 版本不生效） |
