| 1 | # html-ppt · HTML PPT 工作室 |
| 2 | |
| 3 | > 一款专业级的 AgentSkill，让 AI 做出真正能打的 HTML 演示文稿。 |
| 4 | > **36 套主题**、**15 套完整 deck 模板**、**36 种页面布局**、**47 个动效** |
| 5 | > (27 个 CSS + 20 个 Canvas FX)，加上全新的 **演讲者模式** —— 像素级 |
| 6 | > 完美预览 + 逐字稿提词器 + 计时器。纯静态 HTML/CSS/JS，无需构建。 |
| 7 | |
| 8 | **作者：** lewis <sudolewis@gmail.com> |
| 9 | **协议：** MIT |
| 10 | **English docs:** [README.md](README.md) |
| 11 | |
| 12 |  |
| 13 | |
| 14 | > 一行命令装好 **36 主题 × 20 Canvas FX × 36 布局 × 15 完整 deck + 演讲者模式**。 |
| 15 | > 上图里的每一个预览都是真实的 iframe 加载真实模板文件 —— 不是截图，不是色卡。 |
| 16 | |
| 17 | ## 🎤 演讲者模式（全新） |
| 18 | |
| 19 | 在任何 deck 里按 `S` 键，弹出一个独立的演讲者窗口，包含 4 个**可拖拽、 |
| 20 | 可调整大小的磁吸卡片**：当前页预览、下一页预览、逐字稿、计时器。两个窗口 |
| 21 | 通过 `BroadcastChannel` 双向同步翻页。 |
| 22 | |
| 23 |  |
| 24 | |
| 25 | **为什么预览是像素级完美的：** 每个卡片是一个 `<iframe>`，加载的是**同一 |
| 26 | 份 deck HTML 文件**，只是 URL 多了 `?preview=N` 参数。runtime 检测到这个 |
| 27 | 参数后，只渲染第 N 页并隐藏所有 chrome —— 所以预览使用**和观众视图完全相 |
| 28 | 同的 CSS、主题、字体、viewport**，颜色和排版保证 100% 一致。 |
| 29 | |
| 30 | **丝滑翻页（零闪烁）：** 翻页时演讲者窗口通过 `postMessage({type:'preview-goto', |
| 31 | idx:N})` 通知 iframe，iframe 只是切换 `.is-active` class —— **不重新加载、 |
| 32 | 不白屏、不闪烁**。 |
| 33 | |
| 34 | **逐字稿 3 条铁律：** |
| 35 | 1. **提示信号，不是讲稿** — 关键词加粗，过渡句独立成段 |
| 36 | 2. **每页 150–300 字** — 约 2–3 分钟/页的节奏 |
| 37 | 3. **用口语，不用书面语** — "所以" 不是 "因此"，"这个" 不是 "该" |
| 38 | |
| 39 | 详见 [`references/presenter-mode.md`](references/presenter-mode.md)，或直接复制 |
| 40 | `templates/full-decks/presenter-mode-reveal/` 这个现成模板 —— 每一页都带完整 |
| 41 | 150–300 字的示例逐字稿。 |
| 42 | |
| 43 | ## 一行命令安装 |
| 44 | |
| 45 | ```bash |
| 46 | npx skills add https://github.com/lewislulu/html-ppt-skill |
| 47 | ``` |
| 48 | |
| 49 | 装好后，任何支持 AgentSkill 的 agent（Claude Code / Codex / Cursor / OpenClaw 等） |
| 50 | 都能用这套能力做 PPT。对 agent 说： |
| 51 | |
| 52 | > "做一份 8 页的技术分享 slides，用 cyberpunk 主题" |
| 53 | > "把这段 outline 变成投资人 pitch deck" |
| 54 | > "做一个小红书图文，9 张，白底柔和风" |
| 55 | > "做一份带演讲者模式的产品分享，我想要有逐字稿" |
| 56 | |
| 57 | ## 离线 / 手动安装 |
| 58 | |
| 59 | `npx skills add <url>` 需要目标机器能联网。下面三种方式，对网络的依赖依次递减。 |
| 60 | |
| 61 | **1. 从本地副本安装。** 在任意能联网的机器上取到仓库，把整个目录搬过去（git、zip、U 盘都行）， |
| 62 | 然后把 CLI 指向本地目录而不是 URL： |
| 63 | |
| 64 | ```bash |
| 65 | git clone https://github.com/lewislulu/html-ppt-skill |
| 66 | npx skills add ./html-ppt-skill |
| 67 | ``` |
| 68 | |
| 69 | `npx` 本身仍需下载一次 `skills` 包。完全隔离的机器请先在联网机器上 |
| 70 | `npm i -g skills`，或者直接用方式 2。 |
| 71 | |
| 72 | **2. 纯手工拷贝 —— 不需要 Node，也不需要 CLI。** 一个 skill 就是一个根目录下放着 |
| 73 | `SKILL.md` 的文件夹。放进你的 agent 会扫描的目录即可： |
| 74 | |
| 75 | | Agent | 项目级 | 全局 | |
| 76 | |---|---|---| |
| 77 | | Claude Code | `.claude/skills/html-ppt/` | `~/.claude/skills/html-ppt/` | |
| 78 | | Codex | `.agents/skills/html-ppt/` | `~/.codex/skills/html-ppt/` | |
| 79 | | Cursor | `.agents/skills/html-ppt/` | `~/.cursor/skills/html-ppt/` | |
| 80 | | OpenCode | `.agents/skills/html-ppt/` | `~/.config/opencode/skills/html-ppt/` | |
| 81 | | Gemini CLI | `.agents/skills/html-ppt/` | `~/.gemini/skills/html-ppt/` | |
| 82 | | Windsurf | `.windsurf/skills/html-ppt/` | `~/.codeium/windsurf/skills/html-ppt/` | |
| 83 | |
| 84 | ```bash |
| 85 | mkdir -p ~/.claude/skills |
| 86 | cp -R html-ppt-skill ~/.claude/skills/html-ppt |
| 87 | ls ~/.claude/skills/html-ppt/SKILL.md # 必须存在 |
| 88 | ``` |
| 89 | |
| 90 | 运行时只需要 `SKILL.md`、`assets/`、`templates/`、`references/`、`scripts/`。 |
| 91 | `docs/` 是约 4.6 MB 的 README 配图，离线拷贝时可以删掉。 |
| 92 | |
| 93 | **3. 完全不用 agent。** 模板就是普通静态文件，可以直接用： |
| 94 | |
| 95 | ```bash |
| 96 | ./scripts/new-deck.sh my-talk |
| 97 | open examples/my-talk/index.html |
| 98 | ``` |
| 99 | |
| 100 | ### 断网能用吗？ |
| 101 | |
| 102 | 能，只有一个前提要说清楚。主题、布局、动效、演讲者模式、PNG 导出全部是本地静态 |
| 103 | HTML/CSS/JS，零构建、运行时不发请求。唯一的远程依赖是 `assets/fonts.css`， |
| 104 | 它 `@import` 了 Google Fonts。 |
| 105 | |
| 106 | 断网时这些 import 直接失败，浏览器回落到 `assets/base.css` 里已经声明好的系统字体栈 |
| 107 | （`-apple-system` / Helvetica / Georgia / Menlo），所以 deck 照常渲染，只是字体不同。 |
| 108 | 如果要在离线环境下锁定字体，把 `assets/fonts.css` 换成指向自带字体文件的 `@font-face` |
| 109 | 规则，或者删掉这些 import、接受系统字体。 |
| 110 | |
| 111 | ## Skill 内容一览 |
| 112 | |
| 113 | | | 数量 | 位置 | |
| 114 | |---|---|---| |
| 115 | | 🎤 **演讲者模式** | **新增** | `S` 键 / `?preview=N` | |
| 116 | | 🎨 **主题** | **36** | `assets/themes/*.css` | |
| 117 | | 📑 **完整 deck 模板** | **15** | `templates/full-decks/<name>/` | |
| 118 | | 🧩 **单页布局** | **36** | `templates/single-page/*.html` | |
| 119 | | ✨ **CSS 动画** | **27** | `assets/animations/animations.css` | |
| 120 | | 💥 **Canvas FX 动画** | **20** | `assets/animations/fx/*.js` | |
| 121 | | 🖼️ **Showcase deck** | 4 | `templates/*-showcase.html` | |
| 122 | | 📸 **验证截图** | 56 | `scripts/verify-output/` | |
| 123 | |
| 124 | ### 36 套主题 |
| 125 | |
| 126 | `minimal-white`、`editorial-serif`、`soft-pastel`、`sharp-mono`、`arctic-cool`、 |
| 127 | `sunset-warm`、`catppuccin-latte`、`catppuccin-mocha`、`dracula`、`tokyo-night`、 |
| 128 | `nord`、`solarized-light`、`gruvbox-dark`、`rose-pine`、`neo-brutalism`、 |
| 129 | `glassmorphism`、`bauhaus`、`swiss-grid`、`terminal-green`、`xiaohongshu-white`、 |
| 130 | `rainbow-gradient`、`aurora`、`blueprint`、`memphis-pop`、`cyberpunk-neon`、 |
| 131 | `y2k-chrome`、`retro-tv`、`japanese-minimal`、`vaporwave`、`midcentury`、 |
| 132 | `corporate-clean`、`academic-paper`、`news-broadcast`、`pitch-deck-vc`、 |
| 133 | `magazine-bold`、`engineering-whiteprint` |
| 134 | |
| 135 |  |
| 136 | |
| 137 | 每个主题都是一份纯 CSS token 文件 —— 只需要换一行 `<link>` 就能给整份 deck |
| 138 | 换皮。在 `templates/theme-showcase.html` 里可以浏览全部（每一页用独立 iframe |
| 139 | 渲染，避免样式互相污染）。 |
| 140 | |
| 141 |  |
| 142 | |
| 143 | ### 15 套完整 deck 模板 |
| 144 | |
| 145 | 8 个从真实作品提炼的视觉语言，7 个通用场景脚手架： |
| 146 | |
| 147 | **提炼款** |
| 148 | - `xhs-white-editorial` — 小红书白底杂志风 |
| 149 | - `graphify-dark-graph` — 暗底 + 力导向知识图谱 |
| 150 | - `knowledge-arch-blueprint` — 蓝图 / 架构图风 |
| 151 | - `hermes-cyber-terminal` — 终端 cyberpunk 风 |
| 152 | - `obsidian-claude-gradient` — 紫色渐变卡 |
| 153 | - `testing-safety-alert` — 红 / 琥珀警示风 |
| 154 | - `xhs-pastel-card` — 柔和马卡龙图文 |
| 155 | - `dir-key-nav-minimal` — 方向键极简 |
| 156 | |
| 157 | **场景款** |
| 158 | - `pitch-deck` — 投资人 pitch |
| 159 | - `product-launch` — 产品发布会 |
| 160 | - `tech-sharing` — 技术分享 |
| 161 | - `weekly-report` — 周报 |
| 162 | - `xhs-post` — 小红书图文（9 页 3:4） |
| 163 | - `course-module` — 教学模块 |
| 164 | - **`presenter-mode-reveal`** 🎤 — 完整分享模板，**每一页都带 150-300 字 |
| 165 | 的示例逐字稿**，围绕 `S` 键演讲者模式专门设计 |
| 166 | |
| 167 | 每个模板都是自包含的文件夹，用 scoped `.tpl-<name>` CSS，所以多个模板可以 |
| 168 | 同时加载不会互相污染。在 `templates/full-decks-index.html` 可以看全套 gallery。 |
| 169 | |
| 170 |  |
| 171 | |
| 172 | ### 36 种单页布局 |
| 173 | |
| 174 | cover · toc · section-divider · bullets · two-column · three-column · |
| 175 | big-quote · stat-highlight · kpi-grid · table · code · diff · terminal · |
| 176 | flow-diagram · timeline · roadmap · mindmap · comparison · pros-cons · |
| 177 | todo-checklist · gantt · image-hero · image-grid · chart-bar · chart-line · |
| 178 | chart-pie · chart-radar · arch-diagram · process-steps · cta · thanks |
| 179 | |
| 180 | 每个布局都带真实的示例数据，拖进 deck 立即看得到效果。 |
| 181 | |
| 182 |  |
| 183 | |
| 184 | *大 iframe 直接加载 `templates/single-page/<name>.html` 文件，每 2.8 秒 |
| 185 | 自动切换到下一个布局。* |
| 186 | |
| 187 |  |
| 188 | |
| 189 | ### 27 个 CSS 动画 + 20 个 Canvas FX |
| 190 | |
| 191 | **CSS 动画（轻量）** — 方向性淡入、`rise-in`、`zoom-pop`、`blur-in`、 |
| 192 | `glitch-in`、`typewriter`（打字机）、`neon-glow`（霓虹光晕）、 |
| 193 | `shimmer-sweep`（流光）、`gradient-flow`（渐变流动）、`stagger-list` |
| 194 | （列表错开入场）、`counter-up`（数字滚动）、`path-draw`（路径绘制）、 |
| 195 | `morph-shape`、`parallax-tilt`、`card-flip-3d`、`cube-rotate-3d`、 |
| 196 | `page-turn-3d`、`perspective-zoom`、`marquee-scroll`、`kenburns`、 |
| 197 | `ripple-reveal`、`spotlight`、… |
| 198 | |
| 199 | **Canvas FX（电影级）** — `particle-burst`（粒子爆发）、`confetti-cannon` |
| 200 | （彩带）、`firework`（烟花）、`starfield`（星空）、`matrix-rain` |
| 201 | （代码雨）、`knowledge-graph`（力导向知识图谱）、`neural-net`（神经网络 |
| 202 | 脉冲）、`constellation`（星座连线）、`orbit-ring`（轨道环）、 |
| 203 | `galaxy-swirl`（星系漩涡）、`word-cascade`、`letter-explode`、 |
| 204 | `chain-react`、`magnetic-field`、`data-stream`、`gradient-blob`、 |
| 205 | `sparkle-trail`、`shockwave`、`typewriter-multi`、`counter-explosion`。 |
| 206 | 每一个都是手写的 canvas 模块，进入 slide 时由 `fx-runtime.js` 自动初始化。 |
| 207 | |
| 208 | ## 快速开始（手动 / 安装后 / git clone 后） |
| 209 | |
| 210 | ```bash |
| 211 | # 从 base 模板新建一个 deck |
| 212 | ./scripts/new-deck.sh my-talk |
| 213 | |
| 214 | # 也可以指定完整 deck 模板和任意输出目录。 |
| 215 | # assets 路径会按 deck 的实际位置算出来，并逐条校验能否解析。 |
| 216 | ./scripts/new-deck.sh my-talk ~/decks -t pitch-deck |
| 217 | |
| 218 | # 浏览所有内容 |
| 219 | open templates/theme-showcase.html # 全部 36 主题（iframe 隔离） |
| 220 | open templates/layout-showcase.html # 全部 36 布局 |
| 221 | open templates/animation-showcase.html # 全部 47 动效 |
| 222 | open templates/full-decks-index.html # 全部 15 个完整 deck |
| 223 | |
| 224 | # 用 headless Chrome 导出 PNG |
| 225 | ./scripts/render.sh templates/theme-showcase.html |
| 226 | ./scripts/render.sh examples/my-talk/index.html 12 |
| 227 | ``` |
| 228 | |
| 229 | ## 放图片的版式 |
| 230 | |
| 231 | 五个版式用的是真实 `<img>`，按「这一页要放几张图」挑： |
| 232 | |
| 233 | | 我有… | 版式 | |
| 234 | |---|---| |
| 235 | | 一张截图 / 示意图 / 图表 | `image-single.html` —— 完整显示，**不裁剪** | |
| 236 | | 一张想撑满整页的照片 | `image-full-bleed.html` —— 整页铺满，底部压暗保证标题可读 | |
| 237 | | 一张图 + 一段论述 | `image-text-split.html` —— 各占一半，加 `flip` 左右互换 | |
| 238 | | 3～6 张图 | `image-gallery.html` —— 等大网格，每张一句话 | |
| 239 | | 改版前 / 改版后 | `image-compare.html` —— 两侧严格同尺寸 | |
| 240 | |
| 241 | 它们共用 `assets/base.css` 里的同一个原语： |
| 242 | |
| 243 | ```html |
| 244 | <figure class="img-frame"><img src="shot.png" alt=""></figure> <!-- 裁剪填满 --> |
| 245 | <figure class="img-frame contain"><img src="diagram.svg" alt=""></figure> <!-- 完整显示 --> |
| 246 | ``` |
| 247 | |
| 248 | 比例和裁剪由**框**决定（`--img-ratio`），不由图片决定 —— 竖图、方图、超宽图 |
| 249 | 直接换 `src` 就行，版式不用改。示例图放在 `assets/demo-images/`，是手写的 |
| 250 | SVG（每个约 1KB），所以这些版式**离线也能正常渲染**。 |
| 251 | |
| 252 | ## 自定义 LOGO |
| 253 | |
| 254 | 一个属性给整份 deck 加上公司 / 产品 LOGO，不用每页粘一个 `<img>`： |
| 255 | |
| 256 | ```html |
| 257 | <body data-logo="logo.svg" data-logo-position="bottom-right" data-logo-size="40px"> |
| 258 | ``` |
| 259 | |
| 260 | `data-logo-position` 可选 `top-left` / `top-right` / `bottom-left` / |
| 261 | `bottom-right`（默认 `top-right`）；`data-logo-size` 设置高度，宽度按比例。 |
| 262 | 某一页不想要（通常是封面）就写 `<section class="slide" data-no-logo>`。 |
| 263 | 演讲者模式的预览里带 LOGO；导出 PDF 时**每一页都带**（写了 `data-no-logo` |
| 264 | 的那页除外）。 |
| 265 | |
| 266 | 想自己摆位置：在 `.deck` 里直接写 |
| 267 | `<img class="deck-logo" data-pos="top-left" src="logo.svg">`， |
| 268 | 样式在 `base.css` 里，**完全不依赖 JS**。 |
| 269 | |
| 270 | ## 键盘快捷键 |
| 271 | |
| 272 | 手机 / 平板上**向左划到下一页，向右划回上一页**，不需要键盘。 |
| 273 | 双指缩放、纵向滚动、总览网格和 notes 抽屉都不受影响。 |
| 274 | |
| 275 | ``` |
| 276 | ← → Space PgUp PgDn Home End 翻页 |
| 277 | 左划 / 右划（触摸） 翻页 |
| 278 | F 全屏 |
| 279 | S 打开演讲者窗口（磁吸卡片模式） |
| 280 | N 底部 notes 抽屉 |
| 281 | R 重置计时器（演讲者窗口内） |
| 282 | O slide 总览网格 |
| 283 | T 切换主题（自动同步到演讲者窗口） |
| 284 | A 在当前 slide 循环演示一个动画 |
| 285 | #/N (URL) 深链到第 N 页 |
| 286 | ?preview=N (URL) 预览模式（只显示单页，隐藏 chrome） |
| 287 | ``` |
| 288 | |
| 289 | ## 项目结构 |
| 290 | |
| 291 | ``` |
| 292 | html-ppt-skill/ |
| 293 | ├── SKILL.md agent 入口 |
| 294 | ├── README.md 英文 README |
| 295 | ├── README.zh-CN.md 本文件 |
| 296 | ├── references/ 详细文档 |
| 297 | │ ├── themes.md 36 主题 + 使用场景 |
| 298 | │ ├── layouts.md 36 布局 |
| 299 | │ ├── animations.md 27 CSS + 20 FX 目录 |
| 300 | │ ├── full-decks.md 15 完整 deck 模板 |
| 301 | │ ├── presenter-mode.md 🎤 演讲者模式 + 逐字稿指南 |
| 302 | │ └── authoring-guide.md 完整工作流 |
| 303 | ├── assets/ |
| 304 | │ ├── base.css 共享 tokens + 基础组件 |
| 305 | │ ├── fonts.css web 字体引入 |
| 306 | │ ├── runtime.js 键盘导航 + 演讲者模式 + 总览 |
| 307 | │ ├── themes/*.css 36 主题 token 文件 |
| 308 | │ └── animations/ |
| 309 | │ ├── animations.css 27 个命名 CSS 动画 |
| 310 | │ ├── fx-runtime.js 进入 slide 自动初始化 [data-fx] |
| 311 | │ └── fx/*.js 20 个 Canvas FX 模块 |
| 312 | ├── templates/ |
| 313 | │ ├── deck.html 最小起步模板 |
| 314 | │ ├── theme-showcase.html iframe 隔离的主题 tour |
| 315 | │ ├── layout-showcase.html 全部 36 布局 |
| 316 | │ ├── animation-showcase.html 47 动画 slide |
| 317 | │ ├── full-decks-index.html 15 deck gallery |
| 318 | │ ├── full-decks/<name>/ 15 个 scoped 多页 deck 模板 |
| 319 | │ └── single-page/*.html 36 个布局文件（带示例数据） |
| 320 | ├── scripts/ |
| 321 | │ ├── new-deck.sh 脚手架 |
| 322 | │ ├── render.sh headless Chrome → PNG |
| 323 | │ └── verify-output/ 56 张自测截图 |
| 324 | └── examples/demo-deck/ 完整可运行的示例 deck |
| 325 | ``` |
| 326 | |
| 327 | ## 设计理念 |
| 328 | |
| 329 | - **Token 驱动的设计系统。** 所有颜色、圆角、阴影、字体决策都在 |
| 330 | `assets/base.css` + 当前主题文件里。改一个变量，整份 deck 优雅地重排。 |
| 331 | - **Iframe 隔离预览。** 主题 / 布局 / 完整 deck 的 showcase 都用 `<iframe>`， |
| 332 | 确保每个预览都是真实、独立的渲染结果。 |
| 333 | - **零构建。** 纯静态 HTML/CSS/JS。只有 webfont / highlight.js / chart.js |
| 334 | (可选) 走 CDN。 |
| 335 | - **资深设计师的默认值。** 字号规律、间距节奏、渐变、卡片处理都有态度 —— |
| 336 | 绝不是 "PowerPoint 2006" 那种味道。 |
| 337 | - **中英双语一等公民。** 预导入了 Noto Sans SC / Noto Serif SC。 |
| 338 | |
| 339 | ## 协议 |
| 340 | |
| 341 | MIT © 2026 lewis <sudolewis@gmail.com> |
| 342 |