open-slide 部署与使用教程

open-slide 是一个专为 AI Agent（如 Claude Code、Codex 等）设计的演示文稿框架。你只需用自然语言描述想要的幻灯片，编码 Agent 就能为你编写 React 代码，open-slide 负责渲染、导航和演示。本教程将指导你完成从安装、创建到部署一个演示文稿的全过程。

一、核心特性概览

在开始部署前，了解 open-slide 的设计理念有助于你理解其独特的工作流：

特性	说明
Agent 原生创作	通过自然语言与 AI 交互，AI 负责编写幻灯片代码。内置 `/create-slide` 和 `/slide-authoring` 技能。
画布与渲染	每页幻灯片固定为 1920 × 1080 画布。页面是任意 React 组件，不受限制的 DSL 约束。
浏览器内检查器	在开发服务器中点击任意元素添加评论（如“将标题改为红色”），评论会作为 `@slide-comment` 标记保存在源码中。运行 `/apply-comments`，Agent 会应用所有待处理的编辑。
资源管理器	管理每份演示文稿的图片、视频和字体。集成 `svgl` 目录，可搜索并拖放品牌 Logo。
专业演示模式	全屏播放，支持键盘导航，并提供演讲者模式（包含当前/下一张幻灯片预览、演讲者备注和计时器）。
导出功能	将演示文稿导出为自包含的静态 HTML 站点或打印就绪的 PDF 文件，无需服务器即可分享。
幻灯片管理器	将演示文稿组织到文件夹中，支持自定义 Emoji 和拖拽排序。
部署友好	输出纯静态构建，可一键部署到 Vercel、Cloudflare Pages 等任何静态托管服务。

二、部署步骤

步骤 1：环境准备

Node.js: 18 或更高版本。
pnpm: 推荐使用，项目基于 pnpm 和 Turbo 构建。
一个 AI 编码助手（可选但推荐）: 如 Claude Code、Codex、Cursor 等，以体验 Agent 驱动的创作流程。

你可以使用以下命令检查环境：

1 2	node --version pnpm --version

步骤 2：创建新演示文稿

使用 CLI 工具初始化一个新的演示文稿项目。这是推荐的使用方式。

# 使用 npx 直接运行（无需全局安装）
npx @open-slide/cli init my-slide

# 进入项目目录
cd my-slide

# 安装依赖
pnpm install

命令说明：

npx @open-slide/cli init 会创建一个最小化的工作区。
my-slide 是你的项目文件夹名称，你可以自由命名。
生成的脚手架已预配置了 Agent 技能（针对 Claude Code）。

步骤 3：启动开发服务器

进入项目目录后，启动开发服务器进行预览和创作。

pnpm dev

启动成功后，在浏览器中打开提示的本地地址（通常是 http://localhost:5173）。你将看到你的幻灯片演示文稿。此时，你可以：

直接编辑：在 slides/<id>/index.tsx 中直接修改 React 组件。
使用 Agent（推荐）：打开你的 AI 编码助手（如 Claude Code），指向当前项目目录，然后使用 /create-slide 技能开始自然语言对话，让 AI 为你创建或修改幻灯片。

步骤 4：使用 Agent 创作工作流（示例）

描述需求：在 AI 助手中输入类似“为我的新产品‘OpenSlide Pro’创建一套10页的启动演示文稿，风格现代、深色主题”。
AI 生成：AI 会依据 slide-authoring 技能中的画布规范（1920x1080、排版比例、调色板等），生成相应的 React 页面组件。
预览与反馈：在浏览器中预览效果。如果想修改，可以点击页面上的元素，添加评论（如“将背景改为深蓝色”）。
应用修改：在 AI 助手中运行 /apply-comments 命令。AI 会读取源码中的 @slide-comment 标记，自动完成编辑。
重复：继续预览、评论、应用修改，直至满意。

步骤 5：构建与导出

演示文稿制作完成后，你可以构建静态版本或导出为 PDF。

构建静态站点

1	pnpm build

构建产物会输出到 dist 目录。你可以将此目录部署到任何静态托管服务。

导出为 PDF

1	pnpm export:pdf

此命令会生成一个可打印的 PDF 文件，方便分享或打印。

步骤 6：部署到生产环境

由于 pnpm build 生成的是纯静态文件（HTML/CSS/JS），你可以将其部署到任何支持静态站点的平台。

部署到 Vercel / Netlify:

将项目推送到 Git 仓库（如 GitHub）。
在 Vercel/Netlify 中导入该项目。
构建命令设置为 pnpm build，输出目录设置为 dist。
点击部署即可。

部署到其他平台: 将 dist 文件夹内的所有文件上传到你的 Web 服务器或对象存储（如 AWS S3）即可。

三、常用命令速查

命令	说明
`npx @open-slide/cli init <project-name>`	创建新的演示文稿项目
`pnpm dev`	启动开发服务器
`pnpm build`	构建生产环境静态站点
`pnpm export:pdf`	导出当前演示文稿为 PDF
`pnpm check`	对所有包进行类型检查
`pnpm lint`	使用 Biome 进行代码检查

四、部署清单

步骤	操作	关键点
1. 环境准备	安装 Node.js 18+ 和 pnpm	检查版本
2. 初始化项目	`npx @open-slide/cli init my-slide`	项目名称自定义
3. 安装依赖	`cd my-slide && pnpm install`	使用 pnpm
4. 创作幻灯片	直接编辑 `slides/` 目录或使用 AI Agent	推荐结合 Agent 工作流
5. 本地预览	`pnpm dev`	在浏览器中预览并迭代
6. 构建	`pnpm build`	生成 `dist` 静态目录
7. 部署	将 `dist` 目录部署到 Vercel/Netlify 等	平台需支持静态托管

总结

open-slide 建立了一个新颖的“AI Agent - 开发环境 - 演示文稿”闭环工作流。你通过本教程已经掌握了从零开始创建一个 Agent 驱动演示文稿的全过程。其核心价值在于将繁琐的排版和样式调整交给 AI，让你能专注于内容和创意。

后续学习建议：

详细阅读项目根目录下的 AGENTS.md 或 CLAUDE.md 文件，了解 Agent 协作的硬规则和最佳实践。
探索内置的 /create-slide 和 /slide-authoring 技能，学习如何更高效地指导 AI。
尝试集成 svgl 目录中的品牌 Logo，或通过资源管理器添加自定义字体。