slidev-agent-skill：为AI智能体赋能，自动化创建Slidev演示文稿

1. 项目概述：为AI智能体注入制作幻灯片的“超能力”

如果你和我一样，经常让Claude、GPT-4或者Codex这类AI智能体帮你写代码、处理文档，那你肯定也遇到过这个痛点：让它们生成一个像样的幻灯片演示文稿，简直是场灾难。它们要么给你吐出一堆乱七八糟的Markdown，要么试图调用一个根本不存在的命令行工具，最后丢给你一句“抱歉，我无法执行此操作”。你不得不自己手动去安装Slidev、配置环境、调试构建错误，整个过程下来，AI带来的效率提升瞬间被抵消殆尽。

这就是slidev-agent-skill诞生的原因。它不是一个新工具，而是一个赋能层，一个专门为AI智能体设计的“技能包”。它的核心目标极其明确：让AI智能体能够像资深开发者一样，熟练、可靠地创建、编辑、构建和导出基于Slidev的演示文稿。简单来说，它把Slidev这个强大的“武器”的使用说明书和自动化扳机，打包塞进了AI的大脑里。

想象一下这个场景：你只需要对你的AI助手说“为下周的季度复盘会议创建一个关于Q2数据分析的幻灯片，使用深色主题，最后导出成PDF”。接下来，AI会自主完成所有工作：初始化项目、编写Markdown内容、应用主题、启动本地预览供你审阅、最终构建并导出成品。整个过程无需你介入任何命令行操作，也无需你记忆Slidev那些繁琐的CLI参数。slidev-agent-skill通过一套结构化的知识库（References）和经过实战检验的脚本（Scripts），为AI智能体铺平了道路。

这个技能包目前已经适配了主流的AI智能体平台，包括Anthropic的Claude Code、OpenAI的Codex/Agent生态，以及OpenClaw等。它的设计哲学是“开箱即用，跨平台一致”，你不需要为不同的AI平台准备不同的集成方案，一套代码，处处运行。

2. 核心设计思路：为什么“脚本优先”和“按需加载”是关键

在深入脚本细节之前，我们必须先理解这个项目背后的架构哲学。为什么它不直接让AI去调用原生的Slidev CLI，而是要额外封装一层脚本？为什么要把文档拆得这么碎？这源于对当前AI智能体工作模式的两个深刻洞察。

2.1 智能体的“认知局限”与确定性执行

当前的AI智能体，尤其是基于大语言模型的代码智能体，存在两个典型问题：上下文幻觉和执行不确定性。

• 上下文幻觉：智能体可能会“记得”一个过时的、错误的CLI命令格式。比如，Slidev的某个子命令参数在版本更新后发生了变化，但智能体训练数据中的信息还未更新，它就会给出错误的指令。
• 执行不确定性：即使命令正确，智能体生成的命令行也可能因为空格、路径、环境变量等细微差别而失败。比如，它可能忘记在命令前加上npx，或者错误地处理了包含空格的目录名。

slidev-agent-skill的解决方案是提供一个确定性执行层。scripts/目录下的每一个Shell脚本，都是一个封装良好、处理了各种边界情况（edge cases）的黑盒。例如，slidev-init.sh脚本内部会：

1. 检查目标目录是否已存在，避免覆盖。
2. 自动检测系统中可用的Node.js和包管理器（npm/yarn/pnpm）。
3. 使用正确的命令初始化Slidev项目（例如npm create slidev@latest）。
4. 处理安装过程中可能出现的网络超时或依赖冲突问题（通过重试机制或清晰的错误提示）。

对于AI智能体来说，它的任务从“生成一段可能出错的Slidev CLI命令”简化为“调用./scripts/slidev-init.sh my-presentation”。这极大地提高了任务的成功率。

实操心得：在设计给AI用的自动化脚本时，一定要把人类觉得“理所当然”的步骤显式化。比如，脚本应自动处理当前工作目录（PWD）的问题。如果用户在/home/user/projects下运行脚本，但脚本内部需要操作相对路径，就必须用cd "$(dirname "$0")"或类似方法确保执行上下文正确。这是AI最容易忽略的细节之一。

2.2 上下文窗口的经济学与路由式文档加载

另一个关键设计是“按需加载”的文档系统。大语言模型的上下文窗口（Context Window）是宝贵的资源。如果你把Slidev全套官方文档（可能上百KB）全部塞进提示词（Prompt）里，不仅会浪费大量Tokens，还可能让智能体在无关信息中迷失，影响其核心任务的表现。

slidev-agent-skill采用了精巧的路由式文档加载策略。它有一个中央路由表（references/index.md），就像一个智能图书管理员。

AI智能体首先阅读SKILL.md了解本技能包的能力范围和基本工作流。当它需要执行具体任务时，会查询references/index.md这个路由表。路由表告诉它：“要完成‘导出’任务，你需要参考exporting.md和cli.md这两个文件”。于是，智能体只将这两份精简后的文档加载到其工作上下文中。

这种设计使得智能体在完成复杂工作流时，始终保持轻量、专注的“思维”状态，避免了信息过载。

2.3 四层架构模型解析

项目文档中提到的“4层模型”是其稳定性的基石：

1. 编排层（Orchestration）：以SKILL.md为代表。它定义了AI智能体使用本技能的标准操作流程（SOP），是智能体的“总指挥手册”。
2. 文档层（Documentation）：即references/目录。这是智能体的“专项知识库”，内容与官方文档同步，但被切割成任务导向的模块。
3. 执行层（Execution）：即scripts/目录。这是智能体的“自动化工具手”，将知识转化为确定性的动作。
4. 配置层（Configuration）：极简的package.json。它只包含必要的脚本（如文档同步）和开发依赖，确保技能包本身不引入复杂的依赖冲突，真正做到即插即用。

3. 核心脚本详解与实战操作指南

理解了设计理念，我们来看看这些脚本具体能做什么，以及在实际操作中需要注意什么。我会以最常见的几个工作流为例，拆解其内部机制。

3.1 从零到一：创建你的第一个AI生成幻灯片

让我们跟随一个AI智能体的视角，完成一次完整的幻灯片创作。

任务：在/home/user/workspace目录下，创建一个名为q2-review的Slidev演示文稿。

AI的行动逻辑：

1. 识别技能：用户请求涉及“创建幻灯片”。AI识别到已安装的slidev-agent-skill可以处理此任务。
2. 查阅手册：AI读取SKILL.md，了解到创建新项目应使用slidev-init.sh脚本，并需要参考core-syntax.md和cli.md。
3. 加载知识：AI从references/中加载上述两份文档，了解到Slidev的基本语法和create命令的选项。
4. 执行命令：AI生成并执行确定性命令：

   /path/to/slidev-agent-skill/scripts/slidev-init.sh q2-review

5. 脚本内部工作流：
   • slidev-init.sh首先检查/home/user/workspace/q2-review是否存在。
   • 接着，它会在后台调用npm create slidev@latest q2-review -- --template=default。注意，这里脚本帮你处理了模板选择的默认值，AI无需纠结。
   • 进入新创建的目录，运行npm install安装依赖。
   • 完成后，脚本会输出成功信息，并提示下一步可以进入目录使用slidev-dev.sh。

注意事项：

• --no-install参数：如果你已经有一个现成的Slidev项目，或者想跳过耗时的npm install步骤（例如在CI/CD环境中），可以使用此参数。脚本只会创建项目结构，不安装依赖。
• 网络环境：初始化过程需要从npm仓库拉取包。如果遇到网络问题，脚本应提供清晰的错误信息，而不是让AI（或你）面对一屏难以解读的报错。

3.2 实时编辑与预览：让AI成为你的幻灯片助手

项目创建好后，你告诉AI：“打开开发服务器，并在3030端口预览。”

AI执行：

cd q2-review ../slidev-agent-skill/scripts/slidev-dev.sh slides.md --port 3030

脚本解析：slidev-dev.sh做的事情比看上去多：

1. CLI解析：它使用_slidev_common.sh中定义的函数，智能地寻找系统中可用的Slidev CLI。可能是全局安装的slidev，也可能是项目本地node_modules中的npx slidev。这解决了“命令找不到”的经典问题。
2. 参数传递：它将--port 3030以及其他可能有的参数（如--theme，--open）原样传递给底层的Slidev CLI。
3. 后台服务：启动服务后，脚本通常不会阻塞（除非特定参数要求）。它会输出访问URL（如http://localhost:3030），方便AI将其反馈给用户。

实操心得：slidev-dev.sh脚本的一个高级用法是配合--theme参数。你可以让AI在启动预览时直接指定一个主题，例如--theme seriph。这对于需要快速切换主题风格进行演示的场景非常有用。脚本确保了主题包如果未安装，Slidev CLI会给出明确的安装提示，而不是直接崩溃。

3.3 构建与导出：生成可交付的最终产品

编辑完成，你需要一份可以分享的PDF文件。

AI执行：

# 先构建静态网站（可选，用于部署） ../slidev-agent-skill/scripts/slidev-build.sh slides.md --out dist # 导出为PDF ../slidev-agent-skill/scripts/slidev-export.sh slides.md --format pdf --output q2-review.pdf --dark

核心难点与脚本的解决方案： 导出功能，特别是PDF导出，是Slidev使用中最容易出错的环节，主要卡在Playwright这个无头浏览器依赖上。

• 问题：Slidev的PDF导出依赖于Playwright来渲染页面。如果系统没有安装playwright-chromium，导出命令会失败，报错信息对AI或新手可能不友好。
• slidev-export.sh的解决方案：
  1. 自动安装：脚本提供了--install-playwright参数。当AI使用此参数时，脚本会在导出前自动检查并运行npx playwright install chromium，确保环境就绪。
  2. 错误处理：即使没有使用上述参数，如果脚本检测到Playwright错误，它也会在错误信息中给出明确的修复建议，例如“运行此命令时添加--install-playwright参数或手动执行npm i -D playwright-chromium”。
  3. 路径修补：脚本内部处理了一个Slidev CLI已知的Bug：当导出Markdown格式时，如果输出文件名是简单名称（如notes.md），CLI可能会生成错误路径。脚本会自动将其重写为out/notes.md来规避此问题。

其他导出选项：

• --format pptx：生成Microsoft PowerPoint文件。这对于需要进一步在PPT中编辑或必须使用PPT格式交付的场合至关重要。
• --format png：将每一页幻灯片导出为单独的PNG图片。适合用于插入其他文档或制作宣传海报。
• --with-clicks：在导出PDF/PPTX时，包含分步动画（clicks）的每一帧作为独立页面/幻灯片。这是制作演讲者备注或详细教程的利器。
• --range 1,3-5,10：只导出指定的页面范围，非常灵活。

3.4 主题深度定制：从应用到创造

Slidev的强大之处在于其可定制性。slidev-agent-skill通过两个脚本降低了主题操作的难度。

场景一：弹出现有主题进行修改你觉得某个主题不错，但想微调一下字体和颜色。

../slidev-agent-skill/scripts/slidev-theme-eject.sh slides.md --dir my-custom-theme

这个脚本会将当前幻灯片正在使用的主题（包括所有布局、样式、组件）完整地“弹出”到my-custom-theme目录中。之后，你可以直接修改这个目录里的文件，Slidev会自动加载本地主题，无需发布到npm。AI可以据此指导你进行具体的CSS或Vue组件修改。

场景二：从零搭建一个全新主题你想为公司打造一个品牌专属主题。

../slidev-agent-skill/scripts/slidev-theme-scaffold.sh my-company-theme

这个脚本会生成一个符合Slidev主题包规范的标准项目结构，包括package.json、index.ts、layouts/、styles/等目录和模板文件。AI可以基于这个脚手架，帮助你编写主题的逻辑和样式。

避坑指南：主题弹出（eject）功能依赖于Slidev CLI的内部命令，不同版本间可能有变化。slidev-theme-eject.sh脚本内部使用了--entry参数来确保与当前主流CLI版本的兼容性。如果你发现弹出失败，首先检查Slidev的版本，并考虑更新slidev-agent-skill中的脚本逻辑。好的脚本应该对这类底层变化有所容错。

4. 集成到不同AI智能体平台：配置与实践

虽然技能包本身是平台无关的，但集成到不同的AI智能体环境时，仍有一些细微差别需要注意。

4.1 Claude Code

Claude Code对技能（Skills）的管理非常直观。它通常有一个固定的技能目录（如~/.claude/skills/）。

1. 安装：按照README，克隆项目到该目录即可。Claude Code会自动扫描并识别该技能。
2. 使用：在对话中，当你提到“创建幻灯片”或相关关键词时，Claude会主动提示你是否要使用slidev-agent-skill。确认后，它就会遵循SKILL.md定义的工作流来操作。
3. 关键点：确保Claude Code有权限执行你克隆目录下的shell脚本。在Unix-like系统上，可能需要运行chmod +x scripts/*.sh。

4.2 OpenAI Codex / 自定义AI Agent

对于基于OpenAI API自建的智能体，集成方式更灵活。

1. 环境准备：将技能包克隆到Agent工作区的一个固定路径，例如~/agent/skills/slidev/。
2. 系统提示词（System Prompt）设计：这是关键。你需要在给Agent的系统指令中，明确加入关于此技能的描述和使用规则。例如：

   “你拥有一个名为‘slidev-agent-skill’的技能，用于创建和处理Slidev演示文稿。相关文档位于~/agent/skills/slidev/references/，可执行脚本位于~/agent/skills/slidev/scripts/。当用户请求创建、编辑、构建或导出幻灯片时，你应优先查阅SKILL.md了解流程，然后根据需要加载参考文档，最后通过调用相应的shell脚本来执行任务。不要直接猜测Slidev CLI命令，除非脚本无法满足需求。”

3. 文件访问：确保你的Agent框架有权限读取技能包内的文件（用于加载参考文档）和执行其中的脚本。

4.3 OpenClaw

OpenClaw作为一个开源框架，其技能集成通常通过配置文件完成。

1. 安装：克隆到框架约定的技能目录。
2. 配置：在OpenClaw的配置文件中（可能是config.yaml或类似文件），你需要声明这个技能，并指定其SKILL.md的路径和可执行脚本的路径。
3. 工具调用：当OpenClaw Agent决定使用此技能时，它会通过框架的工具调用（Tool Calling）接口来执行对应的脚本，并捕获输出返回给用户。

跨平台一致性秘诀：slidev-agent-skill成功的关键在于其“脚本优先”的设计。无论底层AI平台如何调用外部工具（是通过子进程、SSH还是容器），它们最终都是去执行那几个确定的.sh文件。只要脚本本身是健壮、无状态的，集成工作就变得非常简单。

5. 维护、调试与问题排查实录

即使有了完善的脚本，在实际操作中仍可能遇到问题。以下是我在测试和使用过程中积累的一些常见问题及其解决方法。

5.1 文档同步失败

问题：运行npm run sync:references后，本地文档没有更新，或者报网络错误。排查：

1. 检查网络：脚本使用curl或wget从sli.dev拉取文档。确保你的机器可以访问该网站。
2. 检查脚本权限：sync-references.mjs是一个Node.js脚本。确保你有执行权限，并且项目已安装必要的Node依赖（通常只有axios或node-fetch）。
3. 查看上游变更：有时Slidev官方文档的URL结构或HTML格式可能发生变化，导致同步脚本的解析器失效。需要检查sync-references.mjs中的选择器（selector）逻辑是否需要更新。

5.2 脚本执行权限问题（Linux/macOS）

问题：AI尝试执行脚本时，报错Permission denied。解决：

# 进入技能包目录 cd /path/to/slidev-agent-skill # 为所有Shell脚本添加执行权限 chmod +x scripts/*.sh

对于Windows系统，虽然文件扩展名.sh可能不直接关联，但在Git Bash或WSL环境下，同样需要执行权限。如果通过Node.js的child_process调用，则权限检查取决于Node进程的权限。

5.3 Playwright 安装超时或失败

问题：使用--install-playwright参数或在脚本中自动安装Playwright时，下载速度极慢或失败。深层原因：Playwright会下载完整的Chromium浏览器，体积较大（约100MB+）。在某些网络环境下可能失败。解决方案：

1. 使用镜像源：在运行脚本前，设置环境变量使用国内镜像加速：

   # 对于npm npm config set registry https://registry.npmmirror.com # 对于Playwright自身（如果支持） PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright npx playwright install chromium

   你可以在slidev-export.sh脚本中，在安装命令前加入这些环境变量判断逻辑，使其更智能。
2. 手动预安装：在部署AI Agent的服务器或环境上，提前手动安装好Playwright。

   npm i -D playwright-chromium npx playwright install chromium

3. 脚本容错：在脚本中增加重试逻辑。如果第一次安装失败，等待几秒后重试一次。

5.4 Slidev 版本兼容性问题

问题：脚本调用的CLI参数在新版或旧版Slidev中不工作。设计策略：这是封装脚本面临的最大挑战。slidev-agent-skill采取的策略是：

1. 依赖项目本地CLI：脚本优先使用项目node_modules/.bin下的Slidev命令，这保证了脚本使用的CLI版本与项目本身的Slidev依赖版本一致。
2. 参数抽象：脚本对外提供一套稳定的参数接口（如--format pdf），在内部根据检测到的Slidev CLI版本，可能将其转换为不同的底层命令格式。
3. 版本检测与提示：在脚本开头，可以加入版本检测逻辑。如果检测到不支持的版本，给出清晰的错误提示，建议用户升级或降级Slidev。

5.5 AI智能体“不按套路出牌”

问题：AI有时会忽略脚本，试图直接生成原生Slidev CLI命令。根因：这通常是由于系统提示词（System Prompt）不够明确，或者AI在训练数据中对“直接写命令”的权重更高。强化方法：

1. 在系统提示词中反复强调：“对于Slidev相关操作，必须使用slidev-agent-skill提供的脚本。禁止直接生成slidev或npx slidev命令。脚本路径是...”
2. 在技能描述（SKILL.md）中提供反面示例：明确写出“错误的做法”和“正确的做法”，帮助AI进行对比学习。
3. 利用AI平台的技能元数据：在Claude Code等平台，技能可以定义更丰富的元数据（如触发词、功能描述），确保AI在正确的场景下激活该技能。

6. 扩展思路：将这个模式应用到其他开发工具

slidev-agent-skill的成功范式完全可以复制到其他领域。其核心是“结构化知识” + “确定性脚本”的组合拳。

设想一下为以下工具创建类似的Agent Skill：

• vitest-agent-skill：让AI智能体能够运行单元测试、生成测试覆盖率报告、管理测试套件。脚本可以封装vitest run、vitest ui、vitest coverage等命令，并处理配置文件（vitest.config.ts）的读取和解析。
• docker-compose-agent-skill：让AI能够管理多容器应用。脚本可以处理docker-compose up -d、docker-compose logs、docker-compose down等，并将复杂的服务定义和网络配置以结构化文档提供给AI参考。
• storybook-agent-skill：让AI可以初始化Storybook、创建新的Stories、构建静态文件。脚本封装CLI，文档则解释.stories.js的编写规范和组件控件的用法。

创建你自己的Agent Skill的关键步骤：

1. 识别痛点：找到那个你经常让AI做，但AI总是做不好的开发任务。
2. 封装脚本：编写健壮的Shell脚本（或Python、Node.js脚本），处理该任务的所有边缘情况。确保脚本有清晰的--help信息。
3. 提炼知识：将官方文档打碎，重构成任务导向的小文档。制作一个路由表（index.md），将任务映射到所需的文档片段。
4. 编写总纲：创建一个SKILL.md，用最简洁的语言告诉AI：这是什么技能、什么时候用、怎么用（先查路由表，再加载文档，最后执行脚本）。
5. 测试与迭代：在不同的AI智能体上测试，观察它们是否能正确理解和使用你的技能。根据反馈调整提示词和脚本逻辑。

这个项目的价值远不止于“让AI做幻灯片”。它展示了一种人机协作的新范式：人类负责设计可靠的工具和流程（脚本和知识结构），AI负责灵活地组合和调用这些工具来完成复杂任务。我们不再需要教会AI每一个细节，只需要为它搭建好稳固的“脚手架”。