vibe-deck

VibeDeck

步骤 0：环境检查

首先，确认 Node.js 和 npm 可用。尝试运行以下命令（使用当前平台上适用的命令）：

node --version    # or: where.exe node (Windows)
npm --version     # or: where.exe npm (Windows)

• 两者均已安装，且 Node.js ≥ 20 → 静默继续（不要向用户提及此项检查）。
• 缺少其中任一项或版本过低 → 不要继续。请改为：
  1. 运行 uname -s 和 uname -m（Windows 上运行 systeminfo），检测用户的操作系统和架构。
  2. 如果你具备网页搜索能力，搜索在用户的平台上安装 Node.js 的最新推荐方法，并提供具体命令。
  3. 如果你无法搜索，请用用户的语言显示以下消息：

     中文：VibeDeck 需要 Node.js 20 或更高版本。请访问 https://nodejs.org 下载并安装适合你操作系统的版本，安装完成后重新运行。

     English: VibeDeck requires Node.js 20 or later. Please visit https://nodejs.org to download and install the version for your OS, then try again.

  4. 到此为止，等待用户安装完成后再继续。

步骤 1：检查项目

检查当前目录中是否存在 slide-kit.config.js。

• 存在 → 这是一个现有的 slide-kit 项目。转到构建幻灯片。
• 不存在 → 尚无项目。转到创建新演示文稿，如果用户也描述了内容，则继续构建幻灯片。

---

创建新演示文稿

1. 询问标题

只询问项目标题（必填）。其他选项均显示默认值：

我将使用以下默认设置创建项目，除非你希望修改：

• 目录：./<title-slug>/
• 主题：corporate-blue（另有可选主题：minimal）
• 徽标：内置 SlideKit 徽标
• 演示者：无（稍后可在配置中设置）
• 密码：无

如果你想修改其中任何一项，请告诉我；否则我将继续。

主题详情请参阅 theme-presets.md。

2. 搭建项目脚手架

cp -r <this-skill-dir>/template/ <target-dir>
cd <target-dir>
git init

无需联网 — 模板已随此技能打包。

3. 配置

• slide-kit.config.js：按需设置 title、theme、logo、presenter
  • 自定义主色：使用 overrides.colors.primary — 自动派生其他色阶
  • 自定义徽标：复制到 public/，并以 /filename.svg 作为引用路径
• index.html：设置 <title>
• src/App.jsx：如果没有密码，则移除 PasswordGate

4. 生成 Agent 指令

阅读 instruction-template.md，替换占位符，并将内容写入 CLAUDE.md 和 AGENTS.md。

5. 安装并启动

npm install
npm run dev

报告：项目位置、主题、开发服务器 URL。

---

构建幻灯片

1. 阅读上下文（规划前务必完成）

先阅读以下三个文件 — 跳过此步骤可能导致内容重复、主题颜色错误或遗漏约定：

• CLAUDE.md（或 AGENTS.md）— 主题、约定、数据来源
• src/App.jsx — 当前幻灯片列表及顺序（已有内容）
• slide-kit.config.js — 当前主题和演示者信息

2. 理解请求

• 这张幻灯片应展示什么内容？
• 是否涉及数据？数据来自哪里？
• 叙事连贯性：新幻灯片应与前一张逻辑衔接
• 避免重复：如果某个数据点已在其他位置展示，应从不同角度呈现
• 单位一致性：确认与现有幻灯片使用相同的单位（$K 与 $M 等）
• 内容密度：查看 content-rules.md，了解最低内容密度标准 — 内容稀疏的幻灯片（少于 10 个视觉元素、卡片描述为单行）不可接受。

3. 布局决策引擎

不要猜测布局，而要系统地推导。 阅读 layout-engine.md，并按以下顺序操作：

0. 意图分类 — 这是什么类型的幻灯片？（数据 / 概念 / 展示 / 参考 / 工具 / 叙事）。不同类型对内容密度的容忍度不同——展示类幻灯片可以有意做得密集，数据类幻灯片则不行。
1. 内容清点 — 统计指标、图表、文本块、表格行数和列表项数
2. 单一要点检查 — 明确幻灯片唯一的核心要点。对于概念类幻灯片，“理解 X”可以自然地结合定义、组成部分和比较——这仍是一个要点，而不是三个。
3. 语义匹配 — 使用内容到布局的映射表选择布局
4. 容量检查 — 确认内容符合布局限制（限制因意图类型而异）。如果不符合：调整或拆分，但不要仅仅因为展示类或参考类幻灯片内容密集就拆分。
5. 复合布局 — 如果内容类型混合（例如，图表 + 指标），使用 layout-engine.md 第 4 阶段的复合模式

可用布局 — 代码见 layout-templates.md：

布局	最适用场景
FullChart	单个大型图表 + KeyMessage
SplitView	并排比较
MetricGrid	包含 N 个指标卡片的仪表板
ComparisonView	前后对比、深度相近的比较
DataTable	工具比较、功能矩阵、定价
TimelineFlow	路线图、里程碑、分阶段计划
CardGrid	4–6 个带图标和文本的功能项
CardRow	单行展示 2–4 个项目
ConceptSlide	说明类 / 文本密集型，无数据
Composite	混合内容 — 见 layout-engine.md 第 4 阶段

内置幻灯片模板（从 src/slides/ 导入）：

模板	用途
SlideCover	封面页（自动读取 config.title）
SlideDivider	章节分隔页 / 过渡页
SlideAgenda	目录
SlideThankYou	结束页 / 问答页

4. 构建幻灯片

• 布局：所有内容幻灯片都必须使用 SlideLayout — 它会强制采用 Title → KeyMessage → Content 的顺序。见 layout-templates.md
• 图表：chart-components.md
• 样式：style-guide.md
• 内容：content-rules.md
• 颜色：import { colors } from '../theme'

5. 注册（检查清单）

import SlideXxx from './slides/SlideXxx'

// In <Deck>:
<Slide title="Page Title"><SlideXxx /></Slide>

继续之前，请确认：

• 已在 App.jsx 顶部添加 import
• <Slide title="..."> — 已设置 title（导航器依赖此属性，切勿省略）
• 已放置在 <Deck> 中的正确位置（符合叙事顺序）
• 如果幻灯片使用外部数据，已设置 footnote 属性

6. 故事线审查（添加幻灯片后）

每次添加新幻灯片后，都要重新阅读 App.jsx 中完整的 <Deck>，并确认整体叙事：

• 逻辑流畅：每张幻灯片是否都能自然承接上一张？观众是否会对转场感到困惑？
• 循序渐进地呈现信息：概念是否在被引用之前介绍？（例如，“什么是 Skill？”必须放在“推荐 Skill”之前）
• 顺序符合受众特点：面向非技术受众时，应从简单到复杂、从熟悉到陌生排列（例如，VS Code/Copilot 放在 CLI 工具之前）
• 没有孤立的幻灯片：每张幻灯片都应属于明确的章节。如果某张幻灯片不适合任何章节，它可能不属于这套演示文稿
• 章节均衡：每个章节应包含 2–5 张幻灯片。只有 1 张幻灯片的章节显得不完整；有 8 张以上幻灯片的章节则需要拆分
• 标题扫描测试：按顺序只读幻灯片标题，故事线是否仅凭标题就讲得通？如果不通，请将标题改得更具描述性

7. 布局验证（构建后）

构建每张幻灯片后，目视检查布局或使用布局检查清单：

• 底部无留白：内容填充幻灯片高度的 ≥ 80%
• 内容不拥挤：使用 justify-center 或 justify-between，而不是 justify-start
• 卡片高度一致：网格卡片使用 h-full 填满所在单元格
• 卡片内部对齐：标题位于顶部（shrink-0），正文使用 flex-1 justify-center — 模式和常见错误见 content-rules.md > 卡片布局对齐
• 每个网格单元格一张卡片：不要使用标签 + 卡片包装；直接将模型放入单元格
• 列间均衡：内容不均？拆分为 3 列、垂直堆叠或居中填充
• 文本层级：28px 标题 → 10px 区块标签 → 14px 卡片标题 → 12px 正文 → 10px 辅助文本
• 区块间距：区块之间使用 mt-2 或 mt-3，不要用 mt-auto
• 卡片间距比例：卡片之间的间距约为卡片内部内边距的 1.6 倍（例如，py-2.5 → gap-4）。详见 content-rules.md > 卡片间距
• 不使用表情符号：使用 lucide-react 图标，而不是表情符号字符。将其作为组件引用存储在数据数组中（icon: Mail），并渲染为 <item.icon size={14} />

8. 数据提取（如有需要）

• 使用 scripts/extract-xlsx.js 检查 Excel 结构
• 编写自定义提取脚本，并验证总数是否匹配
• 保存到 src/data/<name>.js
• 绝不伪造数据

---

修改现有幻灯片

当用户要求更改、重新排序或移除现有演示文稿中的幻灯片时：

1. 先阅读上下文

与构建幻灯片时相同 — 操作前先阅读 CLAUDE.md、App.jsx 和 slide-kit.config.js。

2. 编辑幻灯片

• 打开幻灯片组件文件（例如，src/slides/SlideRevenue.jsx）
• 在保留现有布局模式的同时，完成所请求的更改
• 如果更改涉及数据，请更新 src/data/ 文件并验证总数仍然匹配
• 编辑后，运行布局验证检查清单（构建幻灯片的第 7 步）

3. 重新排序幻灯片

• 在 App.jsx 中重新排列 <Slide> 条目 — 这是唯一控制顺序的文件
• 重新排序后，运行下面的编辑后验证

4. 移除幻灯片

• 从 App.jsx 中移除 <Slide> 条目
• 检查是否有其他幻灯片引用了被移除幻灯片引入的数据或概念 — 如果有，将相关上下文移到更早的幻灯片中
• 如果不再导入该幻灯片组件文件，则将其移除
• 运行下面的编辑后验证

5. 替换幻灯片布局

如果用户希望将某张幻灯片从一种布局改为另一种布局（例如，FullChart → SplitView）：

• 阅读 layout-templates.md，查看新布局的代码模板
• 使用新布局重写组件，同时保留数据和 keyMessage
• 验证图表/内容是否适合新布局的比例

6. 编辑后验证（任何修改后都必须执行）

每次编辑、重新排序或移除后，在报告完成前都必须执行以下所有操作：

清理导入 — 逐行检查 App.jsx：

• App.jsx 顶部的每条 import 都在下方的 JSX 中实际使用。移除未使用的导入（包括已移除幻灯片遗留的 config、组件或数据导入）
• 没有幻灯片组件文件导入已不存在的模块

故事线审查 — 重新阅读 App.jsx 中完整的 <Deck> 并验证：

• 逻辑流畅：每张幻灯片是否都能自然承接上一张？
• 渐进式展开：概念是否都在被引用前引入？
• 没有孤立幻灯片：每张幻灯片都属于清晰的章节
• 标题扫描测试：按顺序只读幻灯片标题 — 仅凭标题，故事是否讲得通？

向用户报告最终幻灯片顺序和标题，以便他们确认。

作为单个 HTML 分享

当用户想将演示文稿作为单个便携式 HTML 文件分享时（用于电子邮件、即时消息或离线查看）：

npm run build:single

这会生成 dist-single/index.html——一个包含所有内联 JS、CSS 和 SVG 的独立文件。无需服务器；只需在任意浏览器中打开即可。

工作原理：vite.single.config.js 使用 vite-plugin-singlefile 将所有资源内联。Logo SVG 作为模块导入（而不是引用 /public），因此也会被打包。

**适合建议的情况：**如果用户说“分享”“发给某人”“通过电子邮件发送演示文稿”“让它便于携带”“单个文件”“离线”或“不需要服务器”。

限制：

• 文件大小约为 380KB（ECharts + React 包）——通过电子邮件或即时消息分享没问题，但不适合托管到网站
• public/ 中的自定义 Logo（例如 config.logo = '/my-logo.png'）会由构建插件自动内联为 data URI，无需额外操作

---

重要规则

• 绝不编造数据——所有数字都必须来自源文件
• 创建项目时，同时生成 CLAUDE.md 和 AGENTS.md
• slide-kit.config.js 是运行时配置的唯一事实来源
• 幻灯片组件：src/slides/Slide<PascalCaseName>.jsx
• 数据文件：src/data/<kebab-case-name>.js