html-ppt-skill 实战指南：用 36 主题 × 15 完整模板 × 47 动效搭建带演讲者模式的 HTML 演示文稿
html-ppt-skill 实战指南：用 36 主题 × 15 完整模板 × 47 动效搭建带演讲者模式的 HTML 演示文稿
本文围绕 GitHub 加速计划镜像仓库
html-ppt-skill的中文官方文档（README.zh-CN.md）展开，完整讲解这套 AgentSkill 的安装、核心资源、演讲者模式、放图版式、自定义 LOGO 与 PNG 导出等全部关键能力。读完你将掌握：一行命令把技能装进任意 Agent，用 token 驱动换皮、布局拼装、动效装饰三步产出一份可交互、可演讲、可导出的专业 HTML 演示文稿，并能用S键打开带逐字稿的演讲者视图完成双屏演讲。
html-ppt-skill 是一套面向 AI Agent 的演示文稿创作技能（AgentSkill），交付的是纯静态 HTML/CSS/JS 资源：36 套主题、15 套完整 deck 模板、36 种单页布局、47 个动效（27 个 CSS + 20 个 Canvas FX），以及全新的演讲者模式（像素级完美预览 + 逐字稿提词器 + 计时器）。项目采用 MIT 协议，作者为 lewis。整套体系零构建、运行时不发请求，任何支持 AgentSkill 的 Agent（Claude Code / Codex / Cursor / OpenClaw 等）安装后即可调用。
设计理念：为什么这套体系"零构建"也能很专业
在深入使用前，先理解它的四条底层设计原则（见 README.zh-CN.md 与源码）：
- Token 驱动的设计系统。所有颜色、圆角、阴影、字体决策都定义在 assets/base.css 的
:root变量里，由当前主题文件覆盖。改一个变量，整份 deck 优雅地重排。例如默认 token 中--accent: #3b6cff、--radius: 18px、字体栈--font-sans: 'Inter','Noto Sans SC',-apple-system,...，而cyberpunk-neon主题（见 assets/themes/cyberpunk-neon.css）则把--accent换成#ff2bd6、把--font-display换成JetBrains Mono，并额外声明--accent-ink: #0b1024保证文字对比度达标。 - Iframe 隔离预览。主题 / 布局 / 完整 deck 的 showcase 都用
<iframe>渲染，确保每个预览都是真实、独立的渲染结果，样式互相不污染。 - 零构建。纯静态 HTML/CSS/JS，只有 webfont / highlight.js / chart.js（可选）走 CDN。
- 中英双语一等公民。
fonts.css预导入 Noto Sans SC / Noto Serif SC，中文 deck 无需额外配置。
安装：一行命令，以及三种离线方案
官方推荐安装方式是通过 skills CLI 拉取仓库：
npx skills add https://github.com/lewislulu/html-ppt-skill
装好后，对 agent 直接说需求即可，例如：
"做一份 8 页的技术分享 slides，用 cyberpunk 主题" "把这段 outline 变成投资人 pitch deck" "做一个小红书图文，9 张，白底柔和风" "做一份带演讲者模式的产品分享，我想要有逐字稿"
npx skills add <url> 需要目标机器能联网。仓库提供了三种对网络依赖依次递减的离线安装方式（详见 README.zh-CN.md）：
1. 从本地副本安装。 在任意能联网的机器上取到仓库，把整个目录搬过去，再把 CLI 指向本地目录：
git clone https://github.com/lewislulu/html-ppt-skill
npx skills add ./html-ppt-skill
2. 纯手工拷贝——不需要 Node，也不需要 CLI。 一个 skill 就是一个根目录下放着 SKILL.md 的文件夹，放进 agent 会扫描的目录即可：
| Agent | 项目级 | 全局 |
|---|---|---|
| Claude Code | .claude/skills/html-ppt/ |
~/.claude/skills/html-ppt/ |
| Codex | .agents/skills/html-ppt/ |
~/.codex/skills/html-ppt/ |
| Cursor | .agents/skills/html-ppt/ |
~/.cursor/skills/html-ppt/ |
| OpenCode | .agents/skills/html-ppt/ |
~/.config/opencode/skills/html-ppt/ |
| Gemini CLI | .agents/skills/html-ppt/ |
~/.gemini/skills/html-ppt/ |
| Windsurf | .windsurf/skills/html-ppt/ |
~/.codeium/windsurf/skills/html-ppt/ |
mkdir -p ~/.claude/skills
cp -R html-ppt-skill ~/.claude/skills/html-ppt
ls ~/.claude/skills/html-ppt/SKILL.md # 必须存在
运行时只需要 SKILL.md、assets/、templates/、references/、scripts/；docs/ 是约 4.6 MB 的 README 配图，离线拷贝时可以删掉。
3. 完全不用 agent。 模板就是普通静态文件，可以直接用：
./scripts/new-deck.sh my-talk
open examples/my-talk/index.html
断网能用吗？
能，只有一个前提要说清楚。主题、布局、动效、演讲者模式、PNG 导出全部是本地静态 HTML/CSS/JS，零构建、运行时不发请求。唯一的远程依赖是 assets/fonts.css，它 @import 了 Google Fonts。断网时这些 import 直接失败，浏览器回落到 assets/base.css 里已经声明好的系统字体栈（-apple-system / Helvetica / Georgia / Menlo），deck 照常渲染，只是字体不同。要在离线环境锁定字体，把 fonts.css 换成指向自带字体文件的 @font-face 规则，或删掉这些 import、接受系统字体。
Skill 内容一览
| 数量 | 位置 | |
|---|---|---|
| 🎤 演讲者模式 | 新增 | S 键 / ?preview=N |
| 🎨 主题 | 36 | assets/themes/*.css |
| 📑 完整 deck 模板 | 15 | templates/full-decks/ |
| 🧩 单页布局 | 36 | templates/single-page/*.html |
| ✨ CSS 动画 | 27 | assets/animations/animations.css |
| 💥 Canvas FX 动画 | 20 | assets/animations/fx/*.js |
| 🖼️ Showcase deck | 4 | templates/*-showcase.html |
| 📸 验证截图 | 56 | scripts/verify-output/ |
36 套主题：一行 <link> 换整份 deck 的皮
全部主题列表：minimal-white、editorial-serif、soft-pastel、sharp-mono、arctic-cool、sunset-warm、catppuccin-latte、catppuccin-mocha、dracula、tokyo-night、nord、solarized-light、gruvbox-dark、rose-pine、neo-brutalism、glassmorphism、bauhaus、swiss-grid、terminal-green、xiaohongshu-white、rainbow-gradient、aurora、blueprint、memphis-pop、cyberpunk-neon、y2k-chrome、retro-tv、japanese-minimal、vaporwave、midcentury、corporate-clean、academic-paper、news-broadcast、pitch-deck-vc、magazine-bold、engineering-whiteprint。
每个主题都是一份纯 CSS token 文件，覆盖 assets/base.css 的 :root 变量。换皮只需改一行 <link>：
<link rel="stylesheet" id="theme-link" href="../assets/themes/aurora.css">
在 templates/theme-showcase.html 可以浏览全部主题（每一页用独立 iframe 渲染，避免样式互相污染）。运行时按下 T 键即可循环切换主题，主题列表通过 <html data-themes="tokyo-night,dracula,corporate-clean"> 声明（见 assets/runtime.js 的 theme cycle 逻辑）；预览模式下切换主题还会通过 postMessage({type:'preview-theme'}) 同步到演讲者窗口的 iframe 内。
主题选型参考（来自 SKILL.md 与 references/themes.md）：商务/投资 pitch 用 pitch-deck-vc、corporate-clean、swiss-grid；技术分享用 tokyo-night、dracula、catppuccin-mocha、terminal-green、blueprint；小红书图文用 xiaohongshu-white、soft-pastel、rainbow-gradient、magazine-bold；学术/汇报用 academic-paper、editorial-serif、minimal-white；硬核/发布场景用 cyberpunk-neon、vaporwave、y2k-chrome、neo-brutalism。
15 套完整 deck 模板：直接改内容即可交付
8 个从真实作品提炼的视觉语言，7 个通用场景脚手架（见 README.zh-CN.md）：
提炼款
xhs-white-editorial— 小红书白底杂志风graphify-dark-graph— 暗底 + 力导向知识图谱knowledge-arch-blueprint— 蓝图 / 架构图风hermes-cyber-terminal— 终端 cyberpunk 风obsidian-claude-gradient— 紫色渐变卡testing-safety-alert— 红 / 琥珀警示风xhs-pastel-card— 柔和马卡龙图文dir-key-nav-minimal— 方向键极简
场景款
pitch-deck— 投资人 pitchproduct-launch— 产品发布会tech-sharing— 技术分享weekly-report— 周报xhs-post— 小红书图文（9 页 3:4）course-module— 教学模块presenter-mode-reveal🎤 — 完整分享模板，每一页都带 150–300 字的示例逐字稿，围绕S键演讲者模式专门设计
每个模板都是自包含的文件夹，用 scoped .tpl-<name> CSS，所以多个模板可以同时加载不会互相污染。在 templates/full-decks-index.html 可以看全套 gallery。
重要：使用完整模板时一定要通过脚手架 ./scripts/new-deck.sh my-talk -t pitch-deck 来生成，不要手工复制——模板内部的 ../../../assets/ 是相对于它自己位置的路径，手工拷贝会落在错误的目录深度。脚手架会按 deck 的实际落点重算 assets 前缀，并逐条校验每个引用都能解析（见下文"快速开始"）。
36 种单页布局：从模板复制 <section> 而不是从零手写
布局清单：cover · toc · section-divider · bullets · two-column · three-column · big-quote · stat-highlight · kpi-grid · table · code · diff · terminal · flow-diagram · timeline · roadmap · mindmap · comparison · pros-cons · todo-checklist · gantt · image-hero · image-grid · chart-bar · chart-line · chart-pie · chart-radar · arch-diagram · process-steps · cta · thanks。
每个布局文件（templates/single-page/*.html）都带真实的示例数据，拖进 deck 立即看得到效果。标准做法是：打开匹配的布局文件 → 复制 <section class="slide">…</section> 块 → 粘贴进自己的 deck → 替换示例数据 → 设置 data-title（供总览网格使用）→ 添加 <div class="notes"> 写演讲备注。
放图片的版式：五个版式 + 一个 .img-frame 原语
五个版式用的是真实 <img>，按"这一页要放几张图"挑：
| 我有… | 版式 |
|---|---|
| 一张截图 / 示意图 / 图表 | image-single.html —— 完整显示，不裁剪 |
| 一张想撑满整页的照片 | image-full-bleed.html —— 整页铺满，底部压暗保证标题可读 |
| 一张图 + 一段论述 | image-text-split.html —— 各占一半，加 flip 左右互换 |
| 3～6 张图 | image-gallery.html —— 等大网格，每张一句话 |
| 改版前 / 改版后 | image-compare.html —— 两侧严格同尺寸 |
它们共用 assets/base.css 里的同一个原语（.img-frame 拥有宽高比和裁剪，<img> 用 object-fit 填满它）：
<figure class="img-frame"><img src="shot.png" alt=""></figure> <!-- 裁剪填满 -->
<figure class="img-frame contain"><img src="diagram.svg" alt=""></figure> <!-- 完整显示 -->
比例和裁剪由框决定（--img-ratio 默认 16/10，--img-pos 控制 object-position），不由图片决定——竖图、方图、超宽图直接换 src 就行，版式不用改。.img-scrim / .img-cap / .img-tag 分别是压暗层、图注和角落胶囊标签。截图、示意图、LOGO 一律用 .img-frame.contain（letterbox 而非裁剪，避免丢失信息）。示例图放在 assets/demo-images/，是手写的 SVG（每个约 1KB），这些版式离线也能正常渲染。注意：image-grid.html 和 image-hero.html 是纯渐变占位布局（无 <img>），想要 bento 墙的形态但不提供图片时使用。
47 个动效：27 个 CSS 动画 + 20 个 Canvas FX
CSS 动画（轻量） — 方向性淡入、rise-in、zoom-pop、blur-in、glitch-in、typewriter（打字机）、neon-glow（霓虹光晕）、shimmer-sweep（流光）、gradient-flow（渐变流动）、stagger-list（列表错开入场）、counter-up（数字滚动）、path-draw（路径绘制）、morph-shape、parallax-tilt、card-flip-3d、cube-rotate-3d、page-turn-3d、perspective-zoom、marquee-scroll、kenburns、ripple-reveal、spotlight 等，共 27 个命名动画（完整列表见 assets/animations/animations.css，运行时也维护了一份同名数组用于 A 键循环演示）。
使用方式：给任意元素加 data-anim="fade-up"（或 class="anim-fade-up"）；列表/网格用 anim-stagger-list 做错序入场；翻页时 assets/runtime.js 的 go() 会自动重新触发当前 slide 内所有 <a href="https://link.gitcode.com/i/543eed02b305647afe98c65052a02ae6" target="_blank">data-anim] 元素的动画。用法建议（来自 [references/authoring-guide.md）：封面用 rise-in / blur-in，正文 hero 元素用 fade-up，统计页用 counter-up，章节页用 perspective-zoom / cube-rotate-3d，结尾用 confetti-burst，每页只挑一个强调动画，其余保持克制。
Canvas FX（电影级） — particle-burst（粒子爆发）、confetti-cannon（彩带）、firework（烟花）、starfield（星空）、matrix-rain（代码雨）、knowledge-graph（力导向知识图谱）、neural-net（神经网络脉冲）、constellation（星座连线）、orbit-ring（轨道环）、galaxy-swirl（星系漩涡）、word-cascade、letter-explode、chain-react、magnetic-field、data-stream、gradient-blob、sparkle-trail、shockwave、typewriter-multi、counter-explosion。每一个都是手写的 canvas 模块，位于 assets/animations/fx/。
用法：<div data-fx="knowledge-graph">…</div>，并引入 assets/animations/fx-runtime.js。从源码看，fx-runtime.js 会把 FX_LIST 里的 20 个模块（外加 _util）按序动态加载，slide 进入时通过 initFxIn() 调用 window.HPXname 初始化，离开时调用返回句柄的 stop() 清理（实例记录在 window.__hpxActive 这个 Map 里），因此特效的生命周期与翻页严格绑定，不会跨页泄漏。
演讲者模式：按 S 键的完整提词系统（本项目核心新特性）
在任何 deck 里按 S 键，弹出一个独立的演讲者窗口（原页面保持观众视图不变），包含 4 个可拖拽、可调整大小的磁吸卡片：当前页预览、下一页预览、逐字稿、计时器。两个窗口通过 BroadcastChannel 双向同步翻页。详细指南见 references/presenter-mode.md，现成模板在 templates/full-decks/presenter-mode-reveal/。
为什么预览是像素级完美的
每个预览卡片是一个 <iframe>，加载的是同一份 deck HTML 文件，只是 URL 多了 ?preview=N 参数。assets/runtime.js 的 getPreviewIdx() 检测到这个参数后进入单页锁定模式：只渲染第 N 页、隐藏所有 chrome（进度条、notes 抽屉、总览网格等）。所以预览使用和观众视图完全相同的 CSS、主题、字体、viewport，颜色和排版保证 100% 一致；外层再用 CSS transform: scale() 把 1920×1080 画布等比缩放到卡片宽高，不变形。
丝滑翻页（零闪烁）
iframe 初次加载后就常驻。翻页时演讲者窗口通过 postMessage({type:'preview-goto', idx:N}) 通知 iframe，iframe 内的 runtime 只切换 .is-active class —— 不重新加载、不白屏、不闪烁。主题切换同理，通过 preview-theme 消息更换 <link id="theme-link">。两个窗口（观众页 + 演讲者弹窗）则通过以 html-ppt-presenter-<pathname> 命名的 BroadcastChannel 同步 go 与 theme 事件，在任一窗口按 ← → 翻页，另一边自动同步。
四个磁吸卡片
- 🔵 CURRENT — 当前页像素级完美预览（iframe 加载
?preview=N） - 🟣 NEXT — 下一页预览，同样像素级完美；到最后一页时显示 "END OF DECK"
- 🟠 SPEAKER SCRIPT — 逐字稿，字号 18px，支持
<strong>（橘色加粗）、<em>（蓝色强调）、<code>等 inline 样式，可滚动 - 🟢 TIMER — 计时器 + 页码（如
3 / 8）+ Prev / Next / Reset 按钮
交互规则：拖动卡片 header（带彩色圆点和标题的顶部条）移动位置；拖动右下角三角手柄调整大小；位置/尺寸自动保存到 localStorage（每个 deck 独立 key），下次打开恢复；底部 "重置布局" 按钮恢复默认排列。源码层面还做了防御处理：恢复的布局会经过 sanitizeLayout() 钳制回视口内，卡片默认几何（CSS 兜底）保证即使内联脚本被 CSP 拦截，四个卡片也立即可用。
逐字稿写作三铁律
- 提示信号，不是讲稿 — 关键词加粗，过渡句独立成段。错误写法是整段念稿式的"大家好，欢迎来到今天的分享。今天我将要给大家介绍……"；正确写法是把核心词用
<strong>加粗、每段 1–3 句、结尾自然引出下一页。 - 每页 150–300 字 — 约 2–3 分钟/页的节奏。少于 150 字提示不够，讲到一半会卡；多于 300 字根本来不及扫完。
- 用口语，不用书面语 — "所以" 不是 "因此"，"这个" 不是 "该"。书面语与口语对照：因此→所以、该方案→这个方案、然而→但是/不过、进行优化→优化一下、我们将会→我们会/接下来、综上所述→所以简单来说。写完读一遍，听起来像说话才对。
必备 HTML 结构
S 键演讲者视图是 runtime.js 内置的，所有 full-deck 模板都自动支持。给任意已有模板加演讲者模式只需两件事：每张 slide 末尾加 <aside class="notes">（或 <div class="notes">）写逐字稿；确认引入了 assets/runtime.js。标准结构：
<!DOCTYPE html>
<html lang="zh-CN" data-themes="tokyo-night,dracula,corporate-clean">
<head>
<meta charset="utf-8">
<title>...</title>
<link rel="stylesheet" href="../../../assets/fonts.css">
<link rel="stylesheet" href="../../../assets/base.css">
<link rel="stylesheet" id="theme-link" href="../../../assets/themes/tokyo-night.css">
<link rel="stylesheet" href="../../../assets/animations/animations.css">
<link rel="stylesheet" href="style.css">
</head>
<body>
<div class="deck">
<section class="slide" data-title="Cover">
<h1>你的标题</h1>
<p>副标题</p>
<aside class="notes">
<p>讲稿段落 1（加<strong>加粗关键词</strong>）。</p>
<p>讲稿段落 2（过渡句独立成段）。</p>
<p>讲稿段落 3（自然收尾，引出下一页）。</p>
</aside>
</section>
<!-- 更多 slide ... -->
</div>
<script src="../../../assets/runtime.js"></script>
</body>
</html>
重要铁律：.notes 类默认 display:none，只在演讲者视图可见。任何面向演讲者的描述性文字（"这一页展示了……"、"这里可以补充……"）必须放进 <div class="notes">，绝不能写成 slide 上可见的 <p> / <span>——slide 里只允许放面向观众的内容。
双屏演讲的标准流程
- 打开
index.html，按S→ 弹出演讲者窗口 - 把观众窗口（原页面）拖到投影 / 外接屏，按
F全屏 - 把演讲者窗口（弹窗）留在面前的屏幕
- 在任一窗口按 ← → 翻页，两边自动同步
- 演讲者窗口里看逐字稿 + 下一页 + 计时器
常见错误清单（来自 references/presenter-mode.md）
- ❌ 把逐字稿写在 slide 可见位置（观众会看到）→ ✅ 写进
<aside class="notes"> - ❌ 忘记引入
runtime.js（没有 S 键、没有演讲者视图、没有翻页） - ❌ 逐字稿用书面语（念出来像 AI 机器人）
- ❌ 每页 50 字（提示不够，照样忘词）/ 每页 500 字（眼睛扫不过来）
用 AI 生成逐字稿的标准 prompt
"请为每一张 slide 写一段 150-300 字的逐字稿，放在
<aside class="notes">里。要求：1. 用口语，不要书面语（所以/但是/接下来，不是因此/然而/综上所述）；2. 把核心关键词用<strong>加粗；3. 过渡句独立成段（每段 1-3 句）；4. 读起来像说话，不像念稿；5. 结尾要有自然的过渡，引出下一页。"
演讲者模式的键盘快捷键：S 打开演讲者窗口；← → / Space / PgDn 翻页（即使在演讲者视图里）；T 切换主题（自动同步到演讲者窗口）；R 重置计时器（仅演讲者视图）；F 全屏；O 总览；Esc 关闭所有浮层。推荐搭配：主题选 tokyo-night（深色，技术分享首选）/ corporate-clean（浅色，商务汇报）/ dracula（深色备选）；动效克制使用，fade-up / rise-in 最自然；页数参考 30 分钟 = 8–12 页、45 分钟 = 12–16 页、1 小时 = 16–22 页。
自定义 LOGO：一个属性给整份 deck 加上品牌标识
一个属性声明在 <body> 上即可，不用每页粘一个 <img>：
<body data-logo="logo.svg" data-logo-position="bottom-right" data-logo-size="40px">
| 属性 | 默认值 | 说明 |
|---|---|---|
data-logo |
— | 图片 URL，相对 deck 自己的 HTML 文件解析。必填。 |
data-logo-position |
top-right |
top-left / top-right / bottom-left / bottom-right |
data-logo-size |
44px |
任意 CSS 长度；设置 LOGO 的高度，宽度按比例 |
data-logo-opacity |
.9 |
1 为全强度 |
data-logo-alt |
"" |
Alt 文本 |
- 某一页不想要（通常是封面）就写
<section class="slide" data-no-logo>。 - 想微调内边距，在
.deck-logo上用--logo-inset-x/--logo-inset-y。 - 想自己摆位置（比如要放进 chrome 槽位）：在
.deck里直接写<img class="deck-logo" data-pos="top-left" src="logo.svg">，样式在 assets/base.css 里，完全不依赖 JS。 - 演讲者模式的预览里带 LOGO；导出 PDF 时每一页都带（写了
data-no-logo的那页除外）——从源码看，打印时 runtime 会把 LOGO 的 URL 与位置镜像到.deck的自定义属性（--logo-print/data-logo-print），再由@media print里的.slide::after逐页绘制，这正是为什么打印版每页都有 LOGO 而 header/footer/进度条却不打印。
键盘快捷键总览
手机 / 平板上向左划到下一页，向右划回上一页，不需要键盘。双指缩放、纵向滚动、总览网格和 notes 抽屉都不受影响。
← → Space PgUp PgDn Home End 翻页
左划 / 右划（触摸） 翻页
F 全屏
S 打开演讲者窗口（磁吸卡片模式）
N 底部 notes 抽屉
R 重置计时器（演讲者窗口内）
O slide 总览网格
T 切换主题（自动同步到演讲者窗口）
A 在当前 slide 循环演示一个动画
#/N (URL) 深链到第 N 页
?preview=N (URL) 预览模式（只显示单页，隐藏 chrome）
URL 深链（#/N）和预览模式（?preview=N）是 headless 渲染和演讲者预览的底层机制：前者让 render.sh 能逐页截图，后者让演讲者窗口能只渲染指定页。
快速开始：脚手架与 PNG 导出
# 从 base 模板新建一个 deck
./scripts/new-deck.sh my-talk
# 也可以指定完整 deck 模板和任意输出目录。
# assets 路径会按 deck 的实际位置算出来，并逐条校验能否解析。
./scripts/new-deck.sh my-talk ~/decks -t pitch-deck
# 浏览所有内容
open templates/theme-showcase.html # 全部 36 主题（iframe 隔离）
open templates/layout-showcase.html # 全部 36 布局
open templates/animation-showcase.html # 全部 47 动效
open templates/full-decks-index.html # 全部 15 个完整 deck
# 用 headless Chrome 导出 PNG
./scripts/render.sh templates/theme-showcase.html
./scripts/render.sh examples/my-talk/index.html 12
new-deck.sh 的完整用法
scripts/new-deck.sh 用法为 new-deck.sh <name> [output-parent-dir] [-t <template>]：<name> 必填；输出父目录缺省为 <skill>/examples，可以是绝对路径或相对当前目录的相对路径；-t 可指定 deck（默认）、某个 full-deck 名（如 pitch-deck）、某个 single-page 名（如 arch-diagram），或任意 .html 文件 / full-deck 目录的路径。
从源码看，脚本做了三件关键的事：一是把模板复制到目标位置；二是用 relpath() 计算从 deck 目录回退到 skill 根的相对前缀，并用 rewrite_assets() 重写所有 assets/ 引用——这解释了为什么 templates/deck.html 用 ../assets/、templates/single-page/*.html 用 ../../assets/、templates/full-decks/*/index.html 用 ../../../assets/，而绝不能手工改这个深度；三是对 index.html 里每一个本地 href / src / url() 引用做存在性自检（lexjoin() 按浏览器语义拼接路径），任何一个断链都会让脚本以非零状态退出并报错。
render.sh 的完整用法
scripts/render.sh 用法为 render.sh <html-file> [N|all] [out-dir]：默认渲染第 1 页为单张 PNG；传数字 N 则通过 #/k 深链逐页渲染 N 张；传 all 则自动统计 .slide 数量；可指定输出目录（多页时缺省为文件同目录下的 <name>-png/）。输出默认 1920×1080，小红书 3:4 场景可在脚本里改 --window-size（如 1242×1660）。脚本要求本机装有 headless Chrome（默认 macOS 路径 /Applications/Google Chrome.app/Contents/MacOS/Google Chrome），并以"文件是否真的写出"作为成功信号（Chrome 即使没写出文件也常返回 0）。
项目结构速览
html-ppt-skill/
├── SKILL.md agent 入口
├── README.md 英文 README
├── README.zh-CN.md 本文件
├── references/ 详细文档
│ ├── themes.md 36 主题 + 使用场景
│ ├── layouts.md 36 布局
│ ├── animations.md 27 CSS + 20 FX 目录
│ ├── full-decks.md 15 完整 deck 模板
│ ├── presenter-mode.md 🎤 演讲者模式 + 逐字稿指南
│ └── authoring-guide.md 完整工作流
├── assets/
│ ├── base.css 共享 tokens + 基础组件
│ ├── fonts.css web 字体引入
│ ├── runtime.js 键盘导航 + 演讲者模式 + 总览
│ ├── themes/*.css 36 主题 token 文件
│ └── animations/
│ ├── animations.css 27 个命名 CSS 动画
│ ├── fx-runtime.js 进入 slide 自动初始化 [data-fx]
│ └── fx/*.js 20 个 Canvas FX 模块
├── templates/
│ ├── deck.html 最小起步模板
│ ├── theme-showcase.html iframe 隔离的主题 tour
│ ├── layout-showcase.html 全部 36 布局
│ ├── animation-showcase.html 47 动画 slide
│ ├── full-decks-index.html 15 deck gallery
│ ├── full-decks/<name>/ 15 个 scoped 多页 deck 模板
│ └── single-page/*.html 36 个布局文件（带示例数据）
├── scripts/
│ ├── new-deck.sh 脚手架
│ ├── render.sh headless Chrome → PNG
│ └── verify-output/ 56 张自测截图
└── examples/demo-deck/ 完整可运行的示例 deck
结语
html-ppt-skill 的价值在于把"专业演示文稿设计"沉淀成了可直接被 Agent 调用的静态资源系统：主题即 token、布局即模板片段、动效即声明式属性，而演讲者模式则把"做 PPT"延伸到"讲 PPT"的完整闭环。上手路径很清晰——先用 ./scripts/new-deck.sh 脚手架生成 deck，按需挑选主题与布局，最后用 S 键与 render.sh 分别完成演讲与交付。项目协议为 MIT © 2026 lewis，更多细节可继续查阅 references/themes.md、references/layouts.md、references/animations.md、references/full-decks.md 与 references/authoring-guide.md。