Slide Sage：AI原生演示文稿生成技能，告别繁琐PPT制作

1. 项目概述：Slide Sage，一个为AI编码工具而生的演示文稿生成技能

如果你和我一样，经常需要向团队、客户或社区汇报工作，那你一定对制作演示文稿这件事又爱又恨。爱的是它能清晰传达信息，恨的是从构思、排版、设计图表到调试代码高亮，整个过程耗时耗力。传统的工具链，无论是依赖reveal.js、Slidev这类需要本地构建的框架，还是Gamma这类在线SaaS服务，总感觉在“快速生成”和“深度定制”之间差了那么一口气。尤其是在与Claude、Cursor这类AI编码助手协作时，你描述了一个包含复杂图表和代码的幻灯片想法，AI却只能给你生成一堆零散的代码片段，你还需要手动组装、引入库、调试样式，离“开箱即用”还远得很。

Slide Sage的出现，正是为了解决这个痛点。它不是一个独立的软件，而是一个遵循Agent Skills开放标准的“技能”。你可以把它理解为一个专门为AI助手编写的、高度结构化的“插件说明书”。当你对安装了此技能的AI助手（如Claude Code、Cursor、GitHub Copilot等）说“帮我做个关于Q3数据的汇报PPT”时，AI不再是漫无目的地生成代码，而是会调用Slide Sage技能包里定义好的完整工作流：从分析你的需求，到自动选择图表库（Chart.js, ECharts）、套用设计模板、生成架构图SVG、集成代码高亮（Prism.js），最终输出一个单一的、完整的HTML文件。这个文件不依赖任何本地服务器或构建工具，双击就能在浏览器里打开，并且完美支持键盘导航、演讲者视图和PDF导出。

它的核心价值在于“AI原生工作流”。与需要你手动配置npm、写webpack配置的传统方案不同，Slide Sage将最佳实践和复杂实现细节封装成AI可理解和执行的指令集。你只需要关心“讲什么”，而“怎么呈现”交给AI和Slide Sage这个技能包来完成。这对于需要频繁、快速产出高质量、数据驱动型演示文稿的开发者、数据分析师、产品经理和技术布道者来说，无疑是一个效率利器。

2. 核心设计思路与差异化优势解析

为什么要在已经有reveal.js这样成熟方案的情况下，选择Slide Sage？仅仅因为它支持AI吗？远不止如此。它的设计哲学贯穿了从开发者体验到最终输出的每一个环节，我们可以通过几个核心维度来拆解。

2.1 技能化与上下文效率：告别“提示词工程”

传统的AI生成代码，严重依赖用户的提示词（Prompt）质量。你需要清晰地告诉AI：“用reveal.js，第三页插入一个Chart.js的柱状图，数据是...，配色要用...”。这个过程充满了不确定性，且上下文消耗巨大。Slide Sage通过SKILL.md这个核心文件，建立了一套AI与技能之间的“协议”。这个文件详细定义了：

• 输入规范：AI如何解析用户模糊的指令（如“做个微服务架构介绍”）。
• 输出规范：必须生成一个符合特定HTML/CSS/JS结构的单文件。
• 组件库：预定义了图表、图表、代码块等组件的生成模板和调用方式。
• 决策树：根据内容类型（数据、架构、代码）自动选择最合适的库（Chart.js还是ECharts？用哪个SVG模板？）。

这意味着，AI的上下文窗口不再被冗长的框架API文档占据，而是被高度精炼的“技能指令”填充。用户只需用自然语言描述需求，AI就能像调用一个封装好的函数一样，产出结构完整、风格一致的结果。这极大地降低了使用门槛，也提升了生成的确定性和质量。

2.2 真正的“单文件”哲学与零依赖部署

reveal.js或Slidev项目通常需要你初始化一个项目，安装一堆npm包，然后通过构建命令（如npm run build）才能得到一个可部署的产物。Slide Sage反其道而行之，它的终极输出就是一个.html文件。

实现原理：Slide Sage的模板系统将所有资源内联（Inline）。CSS样式、JavaScript控制器、甚至图表库（通过CDN链接）和SVG图表代码，都被直接写入这一个HTML文件中。这样做有几个显著好处：

1. 极致的便携性：文件可以放在任何地方——本地硬盘、U盘、邮件附件、网盘。接收者不需要任何环境，有个浏览器就能看。
2. 离线可用：由于关键资源是内联或使用公共CDN，即使在断网环境下（file://协议打开），基本功能和样式也能正常工作（CDN资源会有缓存）。
3. 消除环境差异：“在我电脑上好好的，怎么到你那就乱了？”——这个问题被彻底根除。一个文件，处处一致。

注意：虽然Chart.js等库使用了CDN，但在完全离线的内网环境中，首次打开可能会因无法加载CDN资源而丢失图表功能。对于有严格离线需求的场景，Slide Sage的技能指令也包含了将特定版本库代码内联的备选方案，AI可以根据你的指令选择生成完全自包含的版本，但这会显著增加文件体积。

2.3 分层、按需的知识库系统

这是Slide Sage在工程上非常聪明的一点。它的知识库（references/目录）是模块化的，并且采用渐进式披露策略。SKILL.md是总纲，只有约400行，它定义了工作流和核心规则。当AI分析你的需求，发现需要创建“架构图”时，它才会去查阅references/diagram-patterns.md；当需要调整动画时，才会去看references/animation-guide.md。

这样做的好处：

• 节省AI上下文：AI不用一次性读完所有上万字的文档，它按需加载，使得在处理简单任务时更加高效、准确。
• 易于维护和扩展：如果你想为Slide Sage增加一个新的图表类型（比如地图），你只需要在references/viz-integration.md里添加对应的模式，并在SKILL.md中更新引用关系即可，不会影响其他功能模块。
• 清晰的关注点分离：开发者可以专注于某个特定领域（如CSS响应式系统）进行深度优化，而不必担心破坏图表生成逻辑。

2.4 面向AI优化的可视化与图表系统

Slide Sage没有重新发明轮子去造一个图表库，而是对主流库（Chart.js, ECharts, D3）进行了“AI友好化”的封装。

1. 配置模板化：它预定义了多种常用的图表配置模板（如“增长趋势折线图”、“市场份额饼图”、“性能对比柱状图”）。AI在生成时，不需要从零开始编写复杂的options配置对象，而是选择一个最接近的模板，然后替换其中的data字段。这保证了图表风格的一致性，也避免了AI因不熟悉库API而生成错误配置。
2. 无障碍设计内置：所有预设图表配色都默认使用色盲友好调色板。这不是事后补救，而是在设计之初就强制纳入的规范。AI在生成图表时，直接调用这些安全色板，无需额外指令。
3. 三层图表系统：
   • CSS/HTML图表：用于简单的流程、层级关系图，用纯CSS和HTML实现，轻量且风格与主题完美融合。
   • SVG模板：针对常见的软件架构图（如微服务、数据流水线），提供了预制的、可参数化的SVG模板。AI只需替换其中的文字标签和连接线逻辑，就能生成专业的矢量图。
   • 库生成图表：对于复杂的数据关系，则驱动Chart.js或ECharts生成。

这种分层设计让AI能够根据内容的复杂程度，选择最合适、最高效的呈现方式。

3. 安装与配置：跨工具的无缝集成

Slide Sage的安装充分体现了其“技能”的本质——它不是全局安装的软件，而是作为“知识”或“规则”注入到你的AI工具中。下面我以最常用的几个工具为例，详细说明安装过程中的细节和选择。

3.1 Claude Code / Claude Desktop 安装详解

对于Claude用户，这是最丝滑的体验。

claude skill add rhnfzl/slide-sage

执行这条命令后，Claude Code会从GitHub拉取技能仓库，并将其安装到本地。之后，在任何对话中，当你提到“演示文稿”、“幻灯片”、“presentation”等关键词时，Claude会自动加载这个技能，并在回复中应用其规则。

实操心得：

• 技能触发：安装后，你可以直接使用/slide-sage命令来显式调用，但更多时候，直接用自然语言描述需求即可，Claude会自动匹配。例如：“帮我用幻灯片总结一下这篇关于Rust并发模型的博客，要突出代码示例和性能对比数据。”
• 版本更新：技能更新后，你需要重新运行claude skill add命令来更新本地副本。目前还没有自动更新机制，建议关注项目GitHub的Release。
• 查看已安装技能：可以运行claude skill list来确认slide-sage是否在列表中。

3.2 Cursor / VS Code with Copilot 安装的两种策略

对于深度集成在IDE中的AI工具，Slide Sage提供了两种安装方式，适用于不同场景。

方案A：远程规则（推荐用于团队项目）

1. 在Cursor中，打开设置（Cmd+,或Ctrl+,），导航到Rules部分。
2. 在“Project Rules”旁边，点击+ Add Rule。
3. 选择“Remote Rule (Github)”。
4. 在弹出的输入框中粘贴URL：https://github.com/rhnfzl/slide-sage。

这个方案的优点：规则链接指向GitHub仓库的最新版本。当Slide Sage技能更新时，所有使用该规则的项目会自动受益于最新改进，无需每个开发者手动更新。非常适合团队统一技术栈和输出规范。

方案B：克隆到技能目录（推荐用于个人或离线环境）

# 在你的项目根目录下执行 git clone https://github.com/rhnfzl/slide-sage.git .agents/skills/slide-sage

这个方案的优点：

• 离线可用：技能文件完全本地化，不依赖网络访问GitHub。
• 版本锁定：你可以通过git checkout切换到特定的版本或分支，确保生成结果的稳定性，避免因技能更新导致意外变化。
• 可定制：你可以直接修改本地的SKILL.md或references/下的文件，来定制符合你公司品牌规范的模板（注意遵循开源协议）。

重要提示：VS Code + GitHub Copilot 也使用相同的.agents/skills/目录结构。你还可以将技能克隆到.github/skills/或用户级的~/.agents/skills/目录。Copilot会按顺序扫描这些路径，用户级目录的优先级通常最高。这意味着你可以在~/.agents/skills/下安装一次，所有项目都能用到，非常方便。

3.3 全局安装：一劳永逸的配置

如果你希望在所有项目中都默认拥有Slide Sage的能力，而不必在每个项目里都克隆一次，就需要进行“全局安装”。这本质上是将技能安装到AI工具的用户配置目录下。

以Claude Code为例的全局安装：

git clone https://github.com/rhnfzl/slide-sage.git ~/.claude/skills/slide-sage

各工具全局安装路径速查表：

操作流程：

1. 打开你的终端。
2. 执行上表中对应你工具的git clone命令。
3. 重启你的AI工具或IDE，确保其重新加载了技能目录。

完成全局安装后，无论你打开哪个项目文件夹，只要启动对应的AI助手，它都能感知到Slide Sage技能，并可以在对话中应用。这是我最推荐的个人使用方式，彻底省去了重复配置的麻烦。

4. 从指令到成品：Slide Sage工作流全解析

安装好技能后，真正的魔法开始了。我们通过一个完整的例子，来看看AI是如何协同Slide Sage，将你的一句口语化指令，变成一个专业演示文稿的。

假设你对已安装技能的Claude Code说：

“为我们的‘Phoenix’项目创建一个启动会演示文稿。需要包含项目目标、技术架构图（微服务风格）、核心模块的代码示例（用Go语言）、以及第一季度的里程碑甘特图。风格要现代、专业，用深色主题。”

4.1 第一阶段：需求分析与技能调度

AI接收到你的指令后，会立即激活Slide Sage技能。它首先阅读SKILL.md中的核心工作流，然后对你的指令进行解构：

1. 识别内容类型：
   • “项目目标” -> 文本幻灯片。
   • “技术架构图（微服务风格）” -> 架构图，需要调用references/diagram-patterns.md中的SVG模板。
   • “核心模块的代码示例（Go）” -> 代码幻灯片，需要调用references/code-highlighting.md，使用Prism.js的Go语言高亮。
   • “里程碑甘特图” -> 复杂图表，可能需要ECharts的时间轴条形图，需要调用references/viz-integration.md中的ECharts模式。
2. 识别样式要求：“现代、专业，深色主题” -> 对应references/style-guide.md中的某个深色预设（如“Midnight”或“Deep Blue”）。
3. 规划幻灯片结构：AI会大致规划一个顺序：标题页、项目目标（1-2页）、架构图（1页）、代码示例（可能1-2页）、甘特图（1页）、总结页。

4.2 第二阶段：资源组装与模板填充

AI开始根据规划，像搭积木一样构建HTML文件。

1. 生成基础骨架：它从references/html-template.md中获取基础的HTML5结构、视口设置、核心CSS（来自assets/viewport-base.css，会被内联）和JavaScript控制器（负责键盘导航、触摸滑动、全屏等）。
2. 应用主题：根据“深色主题”的要求，从style-guide.md中选取“Midnight”预设，将其对应的CSS变量（如--primary-color，--bg-color）注入到HTML的<style>标签中。
3. 创建幻灯片：为每一页创建一个<section class="slide">元素。
   • 文本幻灯片：直接填充<h2>,<p>等标签。
   • 架构图幻灯片：AI会打开references/diagram-patterns.md，找到“微服务”SVG模板。这个模板是一个带有占位符（如{{service_name}}，{{service_color}}）的SVG代码块。AI会将其复制过来，并用你项目中实际的服务名（如user-service，order-service）和主题色替换占位符，生成一个完全定制化的矢量图。
   • 代码幻灯片：AI会创建一个<pre><code class="language-go">块，并将你的Go代码示例放入其中。同时，它会确保在HTML的<head>里引入了Prism.js的Go语言定义文件和深色主题CSS。
   • 甘特图幻灯片：这是最复杂的一步。AI判断这是一个时间相关的条形图，决定使用ECharts。它会： a. 在<head>中添加ECharts的CDN<script>标签。 b. 从references/viz-integration.md中复制一个“时间轴甘特图”的基础配置模板。 c. 将你的里程碑数据（任务名称、开始日期、结束日期）格式化成ECharts所需的dataset.source格式，并替换到配置中。 d. 生成一个<div id="gantt-chart">容器，并编写一段初始化ECharts实例的JavaScript代码，绑定到这个容器上。

4.3 第三阶段：优化与输出

在将所有内容组装成一个巨大的HTML字符串后，AI还会进行最后几步优化：

1. 资源去重：检查是否重复引入了同一个库（比如因为既有Chart.js又有ECharts而引入了两次jQuery），确保<script>和<link>标签唯一。
2. 内联关键资源：为了确保最大程度的可移植性，AI会将assets/viewport-base.css的内容、Prism.js的核心CSS等直接内联到<style>标签中。
3. 添加元信息：在<head>中添加标题、作者、视口设置等。
4. 生成最终文件：AI将完整的HTML字符串输出给你，通常会建议你保存为phoenix-kickoff.html。

此时，你只需要将这个HTML文件拖到浏览器中，一个具备完整导航、动画、响应式布局和专业视觉效果的演示文稿就诞生了。你可以用空格键或方向键翻页，按F键进入全屏，按P键打开演讲者视图（会新开一个带计时器和备注的窗口），甚至直接用浏览器的“打印”功能，选择“另存为PDF”，获得一份排版完美的讲义。

5. 高级功能与定制化深度指南

Slide Sage的魅力在于，它既开箱即用，也为你留下了充足的定制空间。当你和AI助手配合熟练后，可以玩出很多花样。

5.1 深度定制主题与品牌化

虽然内置了6种预设风格，但企业应用通常需要匹配品牌色。Slide Sage的“主题构建器”功能允许你通过几个CSS变量来定义一切。

操作示例：你可以对AI说：“用我们公司的品牌色生成一个主题，主色是#0072CE（蓝色），辅助色是#FF6B35（橙色），背景用浅灰色#f8f9fa，文字用深灰色#333333。”

AI会根据references/style-guide.md中的指引，生成如下CSS变量块并插入到HTML的:root中：

<style> :root { /* 品牌色 */ --primary-color: #0072CE; --secondary-color: #FF6B35; /* 背景与文字 */ --bg-color: #f8f9fa; --text-color: #333333; --text-color-light: #666666; /* 推导出的其他颜色（如边框、悬停色） */ --border-color: color-mix(in srgb, var(--primary-color) 20%, transparent); --code-bg: color-mix(in srgb, var(--bg-color) 90%, #000); /* 图表调色板（基于品牌色生成） */ --chart-color-1: var(--primary-color); --chart-color-2: var(--secondary-color); --chart-color-3: #8BC34A; /* 自动生成的和谐色 */ } </style>

技巧：为了让品牌色在图表中也生效，你需要明确告诉AI：“将这个主题变量也应用到所有图表中”。AI会确保在初始化Chart.js或ECharts时，将options.color或theme设置为这些CSS变量。

5.2 利用脚本实现内容自动化

项目中的scripts/目录包含了一些Python工具，虽然Slide Sage的核心不依赖它们，但它们能解决特定痛点。

• extract-pptx.py：这个脚本使用python-pptx库，可以将现有的PowerPoint文件（.pptx）中的文本、形状和图片提取出来，并输出为结构化的文本或JSON。你可以先运行这个脚本提取内容，然后将输出结果喂给AI：“这是我从旧PPT里提取的内容，请用Slide Sage的技能，重新将其制作成一个更现代、交互式的HTML演示文稿。” 这实现了从传统PPT到AI原生幻灯片的平滑迁移。
• process-images.py：如果你有一批图片需要统一处理（如调整尺寸、压缩、转换为WebP格式），这个脚本可以帮你快速完成，确保插入幻灯片的图片既清晰又不会导致文件过大。

使用前提：你需要一个安装了Python 3.11+和相应库（pip install python-pptx Pillow pymupdf）的环境。这些脚本是辅助工具，Slide Sage的HTML生成本身完全不需要Python。

5.3 演讲者模式与双屏演示

演讲者模式是专业演示的刚需。Slide Sage的实现非常简洁实用。当你在生成的HTML演示文稿中按下P键（或F1键查看所有快捷键），它会打开一个新的浏览器窗口。

演讲者窗口包含：

• 当前幻灯片：较大比例的显示。
• 下一张幻灯片预览：让你永远知道接下来要讲什么。
• 演讲者备注：显示你在对应幻灯片<section>中添加的<aside class="notes">标签内的内容。你可以在让AI生成幻灯片时就说：“在架构图那一页加上备注：‘此处需要强调服务间的异步通信机制。’”
• 计时器：帮助你控制演讲时间。
• 幻灯片进度：当前页/总页数。

背后的原理：这是通过references/presenter-mode.md中定义的JavaScript实现的。它监听主窗口的slidechanged事件，并通过BroadcastChannelAPI或localStorage事件将幻灯片索引同步到演讲者窗口。这种方式无需服务器，纯前端实现，安全且高效。

5.4 响应式设计与无障碍访问

Slide Sage生成的演示文稿在references/viewport-system.md的指导下，具备良好的响应式能力。

• 移动端适配：在手机等小屏幕设备上，字体大小会自适应调整，复杂的多栏布局会堆叠成单栏，确保可读性。
• prefers-reduced-motion支持：在系统设置了“减弱动画”的用户设备上，幻灯片切换的过渡动画会被自动禁用或简化，体现了对前庭障碍用户的关怀。
• 键盘导航完备：除了方向键，还支持Page Up/Page Down、Home/End键，满足了不同用户的操作习惯。

这些特性不是事后添加的，而是在核心CSS模板和JS控制器设计阶段就考虑进去的。AI在生成时，只是引用了这些已经内置了最佳实践的模块。

6. 常见问题、排查技巧与性能优化

在实际使用中，你可能会遇到一些小问题。这里我总结了一份从社区反馈和个人经验中提炼的排查清单。

6.1 技能未触发或AI不理解指令

6.2 生成的HTML文件打开后样式或功能异常

6.3 性能与文件体积优化

一个包含多张复杂图表和代码的Slide Sage演示文稿，HTML文件可能会达到几百KB甚至几MB。

• 图片优化：这是最大的体积来源。务必要求AI在插入图片时使用压缩后的WebP或高质量JPEG格式，并通过<img width="800" height="450">属性指定精确尺寸，避免浏览器缩放。

  给AI的指令技巧：“插入图片architecture.png，并将其优化为宽度800像素的WebP格式内嵌。” （AI会调用process-images.py的逻辑来描述，但实际处理仍需你事先完成）。

• 按需引入库：确保AI没有引入不必要的库。例如，如果只有简单的柱状图，用Chart.js就够了，不必引入更庞大的ECharts。
• 代码高亮精简：Prism.js支持按语言加载。如果演示文稿只有Go和Python代码，可以要求AI只引入这两种语言的定义文件，而不是全量包。
• 内联权衡：将CSS和JS内联增加了单文件便利性，但不利于浏览器缓存。对于需要频繁更新的演示文稿，可以考虑让AI生成引用外部资源的版本（但这会牺牲单文件特性）。通常，对于一次性或分发的演示，内联是更好的选择。

6.4 与现有工作流集成

你可能会想，我已经有Markdown笔记或Notion文档了，怎么用它来生成幻灯片？

最佳实践：

1. 内容准备：将你的Markdown或文档内容整理成清晰的章节，每个章节对应一张幻灯片的主要内容。
2. 指令生成：将整理好的内容粘贴给AI，并附上明确的格式化指令：“以下是我的项目文档。请将其转换为一个Slide Sage演示文稿。每个二级标题##作为一张新幻灯片的标题，其下的内容作为该幻灯片的主体。在‘系统架构’部分，请生成一个微服务架构SVG图。在‘代码示例’部分，请用Prism.js高亮Go代码。”
3. 迭代优化：第一版生成后，你可以直接对HTML文件提出修改意见：“把第三张和第四张幻灯片顺序调换一下”，或者“把这张饼图的颜色改成更鲜艳一些”。AI可以基于现有的HTML文件进行修改。

Slide Sage不是一个封闭的黑盒，它是一套让AI理解“如何制作好幻灯片”的开放规范。你越了解它的组件和设计逻辑（通过阅读其references/下的文档），就越能精准地指挥AI，创造出完全符合你心意的演示作品。它降低的是重复劳动的复杂度，释放的是你在内容创意和逻辑梳理上的精力。