Slide Sage：基于AI Agent Skills的智能演示文稿生成技能-深圳市維司達科技有限公司

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

如果你和我一样，经常需要向团队、客户或社区做技术分享、项目汇报，那么制作演示文稿（PPT）绝对是个耗时又费力的活儿。传统的PPT工具要么功能臃肿，要么在嵌入代码、图表和架构图时显得力不从心。更别提当你试图用AI助手（比如Claude、Cursor、GitHub Copilot）来帮你生成幻灯片时，它们往往只能输出一堆Markdown或纯文本，离一个可交互、美观的最终成品还差得远。

这就是我最初开发 Slide Sage 的动机。它不是一个独立的软件，而是一个遵循Agent Skills开放标准的“技能”。简单来说，你可以把它“安装”到你常用的AI编码工具里（比如Claude Code、Cursor、VS Code with Copilot），然后直接告诉AI：“帮我做一个关于微服务架构的演示文稿，要有架构图和代码示例。” AI就会调用Slide Sage这个技能，为你生成一个单文件、零依赖、功能齐全的HTML演示文稿，直接能在浏览器里打开、演示，甚至导出PDF。

它的核心价值在于“AI原生工作流”。市面上优秀的幻灯片库不少，比如reveal.js、Slidev，但它们大多需要你搭建开发环境、安装npm包、学习一套特定的语法（Markdown或Vue组件）。Slide Sage跳过了所有这些步骤，它让AI成为你的“幻灯片工程师”，你只需要描述内容，AI负责处理所有技术细节：选择图表库、应用配色、嵌入代码高亮、生成响应式布局。最终交付物就是一个.html文件，你可以通过邮件发送、用U盘拷贝，或者直接拖到浏览器里打开——完全离线，无需任何服务器或构建步骤。

2. 核心设计思路：为什么是“技能”而非“框架”？

在深入细节之前，有必要先厘清Slide Sage的设计哲学。这决定了它为什么好用，以及它和传统方案的差异。

2.1 瞄准AI工具生态的“技能化”交付

现代AI编码助手（Agent）正在从单纯的代码补全，进化成能够理解复杂任务并调用外部工具的“智能体”。Agent Skills标准就是为了规范这种交互而诞生的。一个“技能”本质上是一个包含详细指令（SKILL.md）的代码库，AI可以读取并理解如何执行特定任务。

Slide Sage将自己打包成一个技能，意味着它获得了跨平台的兼容性。只要你的AI工具支持Agent Skills（目前已有超过32种主流工具支持），你就能以几乎相同的方式安装和使用Slide Sage。这种设计避免了为每个工具单独开发插件或适配器，极大地降低了用户的接入成本。

实操心得：在早期版本，我曾尝试为每个主流AI工具写单独的插件，但维护成本呈指数级增长。转向Agent Skills标准后，我只需要维护一份核心的SKILL.md指令集和配套的参考文件，所有兼容工具都能“开箱即用”。这是项目能够快速获得广泛支持的关键决策。

2.2 单文件输出与零依赖架构

这是Slide Sage与大多数技术向幻灯片方案最直观的区别。像reveal.js或Slidev这样的方案非常强大，但它们通常需要一个构建过程（Webpack、Vite等）来打包依赖，最终生成一堆HTML、JS、CSS文件。对于非前端开发者，或者只是想快速分享一个文件的人来说，这很麻烦。

Slide Sage反其道而行之，所有内容都在一个HTML文件里：

CSS内联：所有样式，包括核心的响应式布局系统（viewport-base.css）和主题样式，都通过<style>标签内联在HTML的<head>里。
JS按需CDN引入：图表库（Chart.js/ECharts）、代码高亮库（Prism.js）等依赖，只在幻灯片真正需要它们时，才通过<script>标签从公共CDN引入。这意味着如果一个演示文稿没有图表，就不会加载Chart.js，文件更小，加载更快。
自包含的SVG图表：所有的架构图、流程图模板，都是直接以SVG代码的形式嵌入在HTML中，不依赖外部图片文件。

这样做的结果是，你得到的永远是一个独立的.html文件。你可以把它放在任何地方，用任何现代浏览器打开，它都能完美运行。这对于需要在封闭网络环境、会议现场或没有稳定网络的地方进行演示的场景来说，是巨大的优势。

2.3 渐进式上下文加载：让AI更“聪明”地工作

大型语言模型（LLM）有上下文长度限制。如果一个技能文件过于冗长，AI可能无法完整读取或理解其所有细节。Slide Sage采用了一种“渐进式披露”的策略来优化这一点。

核心文件SKILL.md（约400行）是AI必须阅读的“大脑”，它包含了生成幻灯片的核心工作流、决策逻辑和基础模板。但是，关于如何绘制特定类型的图表、如何使用某个动画效果等详细指南，则被拆分到references/目录下的独立文件中。

当AI分析你的需求时（例如，你要求“包含一个销售数据的柱状图”），SKILL.md中的逻辑会引导AI去查阅references/viz-integration.md文件，获取集成Chart.js的具体模式和最佳实践。如果还需要架构图，它又会去加载references/diagram-patterns.md。

这种方式确保了AI在生成复杂内容时，总能获得最精准、最详细的指导，同时又不会一次性塞满所有信息，浪费宝贵的上下文窗口。这就像给AI配备了一本随时可以查阅的详细手册，而不是要求它一次性记住整本书。

3. 核心功能深度解析与实操要点

了解了设计思路，我们来看看Slide Sage具体能做什么，以及在实际使用中需要注意什么。

3.1 数据可视化：不只是扔个图表进去

Slide Sage集成了三大主流图表库：Chart.js、ECharts和D3.js。AI会根据你的数据特点和展示需求，自动选择最合适的库。

Chart.js（默认推荐）：对于大多数业务图表（柱状图、折线图、饼图、雷达图），Chart.js是首选。它轻量、API简单，生成的图表清晰美观。Slide Sage为Chart.js预设了色盲友好配色方案，这是一个容易被忽略但非常重要的细节，确保了你的图表对所有观众都友好。
ECharts：当你需要更复杂的专业图表时，AI会转向ECharts。比如热力图（展示用户行为密度）、桑基图（展示流量或资源流转）、树图（展示层级结构）或K线图（金融数据）。ECharts在这些领域的表现远超Chart.js。
D3.js：这是“终极武器”。当你有非常特殊的、定制化的数据可视化需求，或者需要进行复杂的统计图形绘制时，AI会使用D3.js。D3提供了最底层的控制力，但生成代码也更复杂。

注意事项：虽然AI会自动选择库，但你也可以通过在指令中明确指定来获得更确定的结果。例如，你可以说：“用ECharts画一个展示服务器间网络流量的桑基图。” 这能帮助AI跳过库选择逻辑，直接生成更精确的代码。

实操示例：生成一个季度营收对比图当你对AI说：“展示我们四个季度的营收，数据是：Q1: 120万， Q2: 150万， Q3: 180万， Q4: 210万。” AI（通过Slide Sage技能）可能会生成类似以下的HTML代码块（已简化）：

<section class="slide">git clone https://github.com/rhnfzl/slide-sage.git .agents/skills/slide-sage

这会将技能克隆到项目内的.agents/skills/目录下，Cursor会自动发现它。

个人体会：我强烈推荐方法A（远程规则）。它更简单，并且能自动同步更新。当你下次打开项目时，Cursor会检查远程规则是否有更新，确保你始终使用最新版本的技能。方法B更适合需要在完全无网络环境或需要对技能代码进行深度定制的场景。

4.2 向AI描述你的需求

安装完成后，你就可以在Cursor的Chat界面（或Composer模式）中直接使用了。关键是要给出清晰、具体的指令。

一个较差的指令：“帮我做个架构介绍的PPT。”（过于模糊，AI不知道具体内容、风格和细节）

一个优秀的指令：

请使用Slide Sage技能，为我创建一个关于“新一代用户推荐系统架构”的HTML演示文稿。 要求： 1. 总共8-10张幻灯片。 2. 使用“科技蓝”风格主题（tech-blue）。 3. 第一张是标题页，标题是“下一代智能推荐引擎”，副标题是“架构设计与演进”，加上公司Logo占位符。 4. 第二张是议程（Agenda）。 5. 第三张用架构图展示我们当前的单体架构痛点（可以用一个混乱的框图表示）。 6. 第四张展示新的微服务架构图，包含：API网关、用户画像服务、召回服务、排序服务、特征存储、消息队列。请使用微服务SVG模板。 7. 第五张重点讲“召回服务”，插入一段Python伪代码展示多路召回策略。 8. 第六张用折线图展示A/B测试结果：横轴是时间（第1天到第14天），两条线分别是“旧算法CTR”和“新算法CTR”，数据点你合理模拟一下，显示出新算法的提升趋势。 9. 第七张用柱状图对比新旧架构的资源消耗（CPU、内存、延迟），数据你合理模拟。 10. 最后一张是“Q&A”和“谢谢”。 11. 为第5、7、8张幻灯片添加简短的演讲者备注。

这个指令清晰定义了幻灯片数量、主题、每张幻灯片的内容和形式（图表、代码、模板）。AI有了明确的蓝图，就能高效地调用Slide Sage技能中的各种组件来完成任务。

4.3 AI生成与你的交互

发出指令后，AI（通常是Cursor内置的Claude模型）会开始工作：

读取技能：它会先加载SKILL.md文件，理解Slide Sage的工作流。
分析需求：识别出你需要“科技蓝”主题、微服务架构图、Python代码高亮、折线图和柱状图。
按需加载参考：根据需求，它会去查阅references/style-guide.md获取“tech-blue”主题的配色代码，查阅references/diagram-patterns.md获取微服务图的绘制方法，查阅references/viz-integration.md获取Chart.js集成代码，查阅references/code-highlighting.md获取Prism.js配置。
生成HTML：AI将所有这些元素组合起来，生成一个完整的、单一的HTML文件。它可能会将代码分块输出，你需要同意让它写入文件（例如presentation.html）。

在整个过程中，你可以随时与AI交互，进行微调。例如：

“把第三张图的颜色调亮一点。”
“在架构图上为‘消息队列’组件添加一个tooltip，显示‘使用Kafka’。”
“把折线图的Y轴标题改成‘点击通过率(%)’。” AI会根据你的反馈，修改对应的HTML/JS/CSS代码段。

4.4 查看与演示

生成presentation.html文件后，直接在文件管理器里双击它，或用浏览器打开。你可以：

按F11进入全屏演示模式。
使用左右方向键翻页。
按S键开启演讲者模式（会弹出新窗口）。
按ESC键显示幻灯片缩略图导航。
在浏览器中按Ctrl+P（或Cmd+P）选择“另存为PDF”，生成讲义。

5. 样式系统与主题定制

一套好的幻灯片，视觉一致性至关重要。Slide Sage内置了一套灵活的样式系统，让你无需接触CSS就能获得专业的外观。

5.1 六种预设风格

Slide Sage提供了6种精心调校的预设风格，每种都包含了协调的配色方案、字体搭配和图表调色板：

风格名称	适用场景	主色调	特点
`tech-blue`	科技、企业、SaaS产品	深蓝/青色	专业、冷静、可信赖，图表使用蓝绿色系
`warm-orange`	创意、营销、启动活动	橙色/珊瑚色	充满活力、温暖、吸引眼球
`deep-purple`	设计、高端品牌、数据可视化	紫色/粉色	优雅、精致、富有设计感
`minimal-gray`	极简、学术、正式报告	灰/白	干净、克制、专注于内容本身
`forest-green`	环保、可持续发展、健康	绿色/土色	自然、平和、有机
`sunset-red`	金融、预警、关键指标汇报	红色/金色	强烈、醒目、用于突出关键数据或风险

在指令中，你只需要简单地说“使用deep-purple风格”，AI就会在生成的HTML中应用对应的CSS变量和图表配色。

5.2 主题构建器：从品牌色生成主题

如果你的公司有严格的品牌规范，预设风格可能不满足要求。Slide Sage的“主题构建器”功能可以解决这个问题。

你只需要提供1到3个品牌色（十六进制代码），AI会根据references/style-guide.md中的算法，自动生成一套完整的、协调的幻灯片主题，包括背景色、文字色、强调色以及适配的图表配色盘。

指令示例：

使用Slide Sage创建演示文稿。主题色使用我们公司的品牌色：#0033A0（主蓝）和 #FF6600（活力橙）。请基于这两个颜色生成自定义主题。

AI会调用主题构建器逻辑，计算出一系列衍生色（浅背景、深文字、图表序列色等），并生成对应的CSS变量嵌入到HTML中。

5.3 动画强度控制

动画可以提升演示效果，但过度动画会分散注意力。Slide Sage提供了三个级别的动画控制：

minimal：仅保留必要的过渡动画，如幻灯片切换的淡入淡出。适合严肃、高效的商务场合。
balanced（默认）：增加图表元素的入场动画（如柱状图从下往上增长，折线图描点画线）。能有效引导观众视线，又不会太过花哨。
dramatic：在balanced基础上，为列表项、图片等添加额外的渐入动画。适合产品发布会、营销路演等需要强烈视觉冲击力的场景。

你可以在指令中指定：“使用balanced级别的动画。”

6. 高级技巧与疑难排查

在实际使用中，你可能会遇到一些特殊情况或问题。以下是我在开发和大量使用中积累的经验。

6.1 从现有PPT或PDF转换

Slide Sage的scripts/目录下提供了Python工具，可以帮助从现有的PowerPoint（.pptx）或PDF文件中提取文本和图片。但这不是一个一键转换工具。

正确的工作流是：

运行脚本提取内容：python scripts/extract-pptx.py your_deck.pptx。这会生成一个结构化的文本文件（如your_deck_content.txt）和一个包含所有图片的文件夹。
将这个文本文件的内容喂给AI，并给出指令：“请根据your_deck_content.txt中的内容，使用Slide Sage重新制作一个HTML演示文稿，保持原有的结构和要点，并美化其设计。”
AI会读取文本内容，理解原有幻灯片的逻辑，然后利用Slide Sage的能力生成一个全新的、交互式的HTML版本。你可以同时要求它“将提取的图片image1.png,image2.jpg嵌入到相应的幻灯片中”。

重要提示：这个提取过程可能不完美，特别是对于复杂的图表或SmartArt图形。它主要提取文字和图片。因此，转换后的幻灯片通常需要你与AI进行一些校对和调整，尤其是数据图表部分，最好让AI根据提取出的数据用Chart.js重新绘制。

6.2 处理复杂或自定义图表

当内置的Chart.js/ECharts模板无法满足你的极端需求时，你有两个选择：

引导AI使用D3.js：在指令中明确要求。“用D3.js绘制一个自定义的力导向图，来展示我们社交网络中用户的关系。” AI会尝试生成D3代码，但这通常更复杂，成功率取决于模型的代码生成能力。
手动提供SVG/代码：如果你已经有了一幅用其他工具（如Draw.io, Excalidraw）画好的矢量图，或者一段生成特定可视化的代码，你可以直接将其提供给AI。“在这张幻灯片里，插入以下SVG代码：[你的SVG代码]”。AI会帮你把它妥善地嵌入到HTML框架中。

6.3 常见问题速查表

问题现象	可能原因	解决方案
AI没有调用Slide Sage技能	技能未正确安装或加载	1. 检查技能是否安装在正确的目录（如`.agents/skills/`）。 2. 在Cursor中，检查Settings -> Rules，确认规则已启用。 3. 在指令中明确提及“使用Slide Sage技能”。
生成的HTML在浏览器中图表不显示	1. CDN网络问题。 2. 浏览器控制台报错。	1. 检查网络连接。 2. 按F12打开开发者工具，查看Console是否有JS错误。可能是图表数据格式错误，AI生成的JS代码有语法问题。将错误信息反馈给AI让它修复。
演讲者模式（按S键）没反应	浏览器安全策略阻止弹出窗口	允许浏览器弹出窗口。在演示前，最好先点击一下幻灯片页面，确保焦点在页面上，然后再按S。
幻灯片样式错乱	AI可能错误地混合或修改了内联CSS	在指令中更明确地指定主题，如“严格使用`minimal-gray`预设主题，不要修改其CSS变量。”
文件过大	插入了过多高分辨率图片或复杂SVG	1. 要求AI在嵌入图片前使用`scripts/process-images.py`进行压缩。 2. 对于复杂SVG，考虑是否能用更简单的CSS图表替代。
在老旧浏览器上显示异常	使用了较新的CSS特性（如CSS Grid, Flexbox）	Slide Sage面向现代浏览器设计。如果必须兼容IE等老旧浏览器，需在指令中说明，AI会尝试生成兼容性更强的CSS，但功能会受限。

6.4 性能与最佳实践

单文件大小：一个包含10张幻灯片、3个图表和若干代码段的典型演示文稿，HTML文件大小通常在200KB-1MB之间，加载极快。
离线使用：由于所有资源（样式、脚本通过CDN）都在线，首次打开需要网络加载图表库。若要完全离线使用，可以在生成后，手动将CDN链接（如https://cdn.jsdelivr.net/npm/chart.js）替换为下载到本地的文件路径，但这需要一些手动操作。对于绝大多数场景，在线CDN的可用性和速度都是最好的选择。
版本控制：.html文件是纯文本，非常适合用Git进行版本控制。你可以清晰地看到每次演示文稿的内容迭代，比二进制.pptx文件友好得多。

我个人最深的一个体会是，Slide Sage最大的优势不是替代了PPT，而是改变了制作PPT的流程。它把我们从繁琐的排版、调样式、找图标中解放出来，让我们能聚焦在最核心的事情上：组织和表达内容。你负责思考“我要讲什么”，AI负责解决“怎么把它漂亮地呈现出来”。这种协作模式，对于需要频繁进行技术沟通的开发者、项目经理和产品设计师来说，效率提升是颠覆性的。