slide-deck

/slide-deck — 起草、更新、转换并导出品牌化 React 幻灯片

使用用户的幻灯片系统，为 ${SLIDE_DECK_REPO:-$HOME/code/your-slide-deck-site}/src/app/slides/<slug>/page.tsx 编写 React/TypeScript 幻灯片。生成品牌化输出（无需单独的 HTML 流程）——需要可移植的 HTML/PDF 时，导出模式会通过 Playwright 对渲染后的 React 幻灯片进行快照，确保输出与品牌设计完美一致。

模式（在步骤 1 前选择一种）

模式	调用方式	目标
new	/slide-deck new <topic>（默认）	根据简报起草一套新幻灯片
update	/slide-deck update <slug>	修改现有幻灯片（带溢出防护）
ppt	/slide-deck ppt <path-to-pptx>	将旧版 PPTX 转换为 React 幻灯片
export	/slide-deck export <slug> [html|pdf|vercel]	将幻灯片快照导出为 HTML、PDF 或 Vercel URL

对于 update、ppt 和 export，跳转到下方对应的模式部分。对于 new，继续执行步骤 1–8。

---

步骤 1 — 收集简报（一次性全部询问）

在一条结构化消息中提问。不要逐项来回询问。

1. 主题 / 标题 — 这套幻灯片讲什么？
2. 受众 — 听众是谁？（技术人员 / 高管 / 混合受众 / 客户）应尽量具体：“创始人”范围太广；“参加 MicroConf 的 B2B SaaS 创始人”就比较合适。
3. 长度 — 大致页数：5–10 页（闪电演讲 / 简短内部分享）/ 10–15 页（简短主题演讲、路演）/ 20–25 页（主题演讲）/ 30 页以上（研讨会——品牌化幻灯片中较少见）。
4. 信息密度 — 演讲者主导型（每页 1 个想法、大字号、留白充足，必要时增加页数），还是 阅读优先型（每页 4–6 个要点、结构化网格，适合异步独立阅读）。
5. 行动号召 — 希望受众听完后做什么、思考什么或有什么感受？
6. Slug — 使用 kebab-case（例如，marketing-like-an-engineer）。
7. 内容状态 — 所有内容已准备好 / 只有粗略笔记 / 只有主题。

请记住信息密度——它会影响页数、每页文案长度，以及优先使用哪些基础组件。信息密度对应的规则见 references/narrative-and-voice.md。

步骤 2 — 提出三个叙事角度

借鉴 zarazhangrui/frontend-slides 的“展示，而非讲述”——但应用于故事，而非视觉呈现（视觉系统已固定）。

用 1–2 句话分别提出 3 个角度：

• 稳妥型 — 最容易被接受的角度。采用适合受众的常规结构。
• 大胆型 — 采用逆向或反直觉的切入方式。潜在收益更高，也有轻微风险。
• 出其不意型 — 采用意想不到的结构（故事优先、围绕一个问题展开、反论点等）。

由用户选择一个。如果用户都不满意，再提出三个——不要强行推进。

步骤 3 — 大纲

针对选定的角度：

1. 章节 — 提出 3–7 个带名称的章节（例如，Title、Hook、Problem、Framework、Examples、Close）。默认的三幕结构是可选的；仅在用户希望采用，或幻灯片用于适合采用三幕结构的主题演讲时使用。
2. 各章节中的幻灯片标题
3. 每页的一句话要点

总页数应与步骤 1 中估算的时长相符。

用表格展示大纲。用户先修改或批准，再展开内容。

步骤 4 — 扩展为幻灯片内容

对于每张幻灯片，使用用户的原语编写完整内容。原语词汇请参考 references/system.md，钩子模式和语气规则请参考 references/narrative-and-voice.md。

幻灯片类型及适用的原语：

幻灯片类型	原语	模式
标题	Eyebrow + 带 <Accent> 关键词的 <h1>	第一张幻灯片，确立品牌和主题
钩子	Heading + Body	观点、故事开场、反常识框架或具体数据
章节分隔页	Eyebrow + Heading（居中、大号）	清晰划分不同章节
框架	Heading + BulletList 或自定义布局	用户要讲解的内容
双栏	TwoCol	比较、前后对比、问题与解决方案
引言／摘录	Body（大号）	展现权威性或引发受众共鸣
资源／链接	Body + 独占一行的 URL	外链（较少使用——用户的语气要求尽量避免）
结束／行动号召	Heading + Body + 用于后续步骤的 BulletList	受众接下来应该做什么

语气基准——写出来要适合说，而不只是适合看（完整规则见 narrative-and-voice.md）：

• 幻灯片要大声讲出来。 幻灯片文字和演讲者备注都要说出来。写得像你平时说话一样。
• 保存前，大声读出每张幻灯片。 如果读起来不顺，或听起来像新闻稿，就重写。
• 处处使用缩略形式（don't、won't、you're、I'd）。只有以阅读为主的幻灯片才去掉这些形式。
• 使用“You”——不要用“the audience”“users”“people”。
• 用自然的方式说数字（说“a quarter”，而不是“23.7%”）。
• 语气坚定，以听者为视角，句子简短，名词具体。
• 不要使用填充语（“Today I want to talk about…”）——开篇就提出观点。
• （以阅读为主的内容密度模式例外：由于不会有人照着幻灯片讲，书面语气也可以——见 narrative-and-voice.md。）

步骤 5 — 演讲者备注

每张幻灯片写 3–5 行备注。备注是完整的口头讲稿——按照你实际说话的方式来写，包括停顿和插话。幻灯片文字是标题；备注则是完整的想法。

备注结构：

1. 开场——幻灯片出现时你说的话
2. 要点——这张幻灯片要表达的一个想法
3. 支撑内容——示例、数据或细节
4. 过渡——与下一张幻灯片的衔接方式
5. （可选）补充——一句俏皮话或前后呼应

标题页和章节分隔页写 2–3 条备注即可。

步骤 6 — 生成文件

写入 ${SLIDE_DECK_REPO:-$HOME/code/your-slide-deck-site}/src/app/slides/<slug>/：

1. layout.tsx — 使用演示文稿标题作为 <title> 元数据的 Next.js 布局
2. page.tsx — 幻灯片演示文稿

使用 references/template.md 中的模板作为骨架。

结束页页脚中的 <AUTHOR_HANDLE> / <AUTHOR_SITE> 令牌来自 ${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/slide-deck/identity.yaml（键：handle、site），前提是该文件存在。否则，询问用户一次其账号名和网站，并提出将其保存到该文件，然后使用这些信息。如果用户不想添加页脚，就完全移除 <p>——绝不要发布带有他人身份信息的演示文稿。

page.tsx 必须：

• 在顶部包含 "use client"
• 从 @/components/slides/slide-deck 导入 SlideDeck 和 Slide 类型
• 仅在使用章节时，从 @/components/slides/sections 导入 SectionRange
• 从 @/components/slides/slide-primitives 导入用户使用的原语
• 声明 const slides: Slide[] = [...]
• （可选）声明 const sections: SectionRange[] = [...]，使用从 0 开始的 from／to 索引
• 导出默认组件，返回 <SlideDeck slides={slides} sections={sections} />

步骤 7 — 预览

写入文件后，检查幻灯片演示文稿开发服务器是否正在运行。

lsof -i :3000-3099 2>/dev/null | grep -E "LISTEN" | head

如果某个端口正在使用（兼容 portless——检查 package.json 中的 dev 脚本命名）：

# Suggested URL pattern
echo "Preview at: http://${SLIDE_DECK_DEV_HOST:-localhost:3000}/slides/<slug>"

如果没有开发服务器在运行，请告知用户：

cd ${SLIDE_DECK_REPO:-$HOME/code/your-slide-deck-site} && npm run dev
# then visit http://${SLIDE_DECK_DEV_HOST:-localhost:3000}/slides/<slug>

不要自动启动开发服务器（这可能会干扰其他工作）。

步骤 8 — 归档

归档目录位于 ${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/slide-deck/archive/（如果目录不存在，请创建）。切勿将归档写入技能自身的文件夹中——技能安装和升级时会从源重新同步，并清除保存在该文件夹中的内容。**迁移：**如果此技能文件夹中有包含用户条目的旧 references/decks-archive.md，请先将其移至 <archive dir>/INDEX.md。

在 <archive dir>/INDEX.md 中追加一行（如果文件不存在，请创建）：

- 2026-06-17 — [<title>](${SLIDE_DECK_REPO:-$HOME/code/your-slide-deck-site}/src/app/slides/<slug>/page.tsx) — <audience> — <one-line angle>

这些记录会不断累积——今后制作幻灯片时，可以搜索“我之前做过哪些关于 X 的演讲”，以避免重复并找到可复用的模式。

---

模式：update

修改现有幻灯片，同时避免破坏它。风险包括：幻灯片内容溢出、超出密度限制、破坏章节范围。

修改前，请检查：

1. 阅读现有的 page.tsx
2. 统计幻灯片数量并确定章节范围
3. 对每项修改应用相应的保护措施：

更改	保护措施
添加项目符号	reading-first 模式下，每个 BulletList 最多 6 项；speaker-led 模式下最多 3 项。若超出 → 拆分为两张幻灯片。
添加文本	speaker-led 模式下，若 <Body> 段落超过 2 句话 → 拆分。reading-first 模式下，若超过 5 句话 → 拆分。
添加图片	图片必须适配 1920×1080 画布。如果幻灯片上已有大量内容，请将图片移至单独的幻灯片。
添加幻灯片	更新 sections 数组——将插入位置之后所有章节的 from/to 递增。
删除幻灯片	将删除位置之后所有章节的 from/to 递减。注意检查是否有 id 引用成为孤立引用。
重写幻灯片	保留 id（用于锚点）。仅更改 content 和 notes。

修改后：

• 重新统计幻灯片数量，并确认各章节范围的总和正确
• 提交前，在开发服务器中抽查视觉效果

---

模式：ppt

将旧版 PPTX（客户端演示文稿、会议模板）转换为用户的 React 系统。

1. 使用 python3 和 python-pptx 提取内容：

   pip install python-pptx 2>/dev/null
   python3 -c "
   from pptx import Presentation
   import json, sys
   p = Presentation(sys.argv[1])
   out = []
   for i, s in enumerate(p.slides):
       title = next((sh.text for sh in s.shapes if sh.has_text_frame and sh.shapes_element.tag.endswith('}sp') == False), '')
       texts = [sh.text for sh in s.shapes if sh.has_text_frame]
       notes = s.notes_slide.notes_text_frame.text if s.has_notes_slide else ''
       out.append({'i': i, 'texts': texts, 'notes': notes})
   print(json.dumps(out, indent=2))
   " "<path-to-pptx>"
   

   完整的提取与映射流程请参阅 references/ppt-conversion.md。

2. 向用户展示提取结果摘要——幻灯片标题、内容摘录、图片数量。继续前请先确认。

3. 映射到 React 基础组件：

   • 第一张幻灯片 → 标题模式（Eyebrow + h1 + Accent）
   • 带项目符号的内容幻灯片 → Heading + BulletList
   • 对比幻灯片 → TwoCol
   • 章节分隔页（PPTX 中只有标题的幻灯片）→ 章节分隔模式
   • PPTX 中的演讲者备注 → 每张幻灯片的 notes 数组

4. 图片——将 PPTX 资源中的引用图片复制到 ${SLIDE_DECK_REPO:-$HOME/code/your-slide-deck-site}/public/slide-assets/<slug>/，并在幻灯片的 content 中通过 <img src="/slide-assets/<slug>/<filename>" /> 引用。

5. 按照新建幻灯片流程（步骤 6）编写 page.tsx + layout.tsx。

6. 保留原始 PPTX——切勿就地修改。将其与提取出的 JSON 一起保存到 ~/Documents/slide-conversions/<slug>-from-pptx/，以便审计。

---

模式：export

将在幻灯片站点开发服务器中渲染的幻灯片组快照导出为可移植的 HTML / PDF / Vercel URL。输出与品牌完美契合，因为它使用的是实际渲染的 React 幻灯片组截图。

输出选项：

• html — 独立 HTML 文件，快照以内嵌 <img> 的形式呈现，并内置键盘导航（方向键）
• pdf — 合并后的幻灯片快照
• vercel — 将独立 HTML 推送到 Vercel 项目，生成可分享的 URL

流程（完整详情见 references/export.md）：

1. 验证开发服务器：确认 ${SLIDE_DECK_DEV_HOST:-localhost:3000}/slides/<slug> 可以加载。若无法加载，请提示用户运行 cd ${SLIDE_DECK_REPO:-$HOME/code/your-slide-deck-site} && npm run dev。
2. 统计幻灯片数量：读取 page.tsx，统计 slides 数组中的条目数。
3. 运行 Playwright 快照：

   bash references/export.md script: snapshot-deck <slug> <count>
   

   • 在 1920×1080 分辨率下启动无头 Chromium
   • 加载 http://${SLIDE_DECK_DEV_HOST:-localhost:3000}/slides/<slug>?present=1（演示模式会隐藏浏览器界面）
   • 设置 localStorage["slides:/slides/<slug>"] = "0"，从第 0 张幻灯片开始
   • 循环执行：截图 → 按键盘 ArrowRight → 等待 — 共处理 N 张幻灯片
   • 将 PNG 保存到 ~/Documents/slide-exports/<slug>-<YYYY-MM-DD>/slide-<n>.png
4. 按输出类型合并：
   • html → 将快照封装到带方向键导航的精简 HTML 框架中
   • pdf → 使用 magick（ImageMagick）或 img2pdf 合并 PNG
   • vercel → vercel deploy ~/Documents/slide-exports/<slug>-<date>/
5. 报告：提供路径 / URL。

注意事项（请告知用户）：

• 动画和演示者视图不会保留 — 导出内容是静态快照。
• 如需交互式演示，请实时展示 React 版本；如需分享、导出 PDF 或便携使用，请使用导出文件。
• 快照分辨率为 1920×1080 — 在任何设备上都能呈现高质量效果，但文件大小会随幻灯片数量增加。

---

模式（快捷调用）

调用	模式	行为
/slide-deck new <topic>	new	完整流程（步骤 1–8）
/slide-deck angles <topic>	new	在步骤 2 停止（仅生成 3 个切入角度）
/slide-deck outline <topic>	new	在步骤 3 停止（仅生成大纲）
/slide-deck expand <slug>	new	从现有大纲跳至步骤 4
/slide-deck notes <slug>	update	重写现有幻灯片组的演讲者备注
/slide-deck rewrite <slug> <slide-id>	update	编辑一张幻灯片
/slide-deck update <slug>	update	进行常规修改并防止内容溢出
/slide-deck ppt <pptx-path>	ppt	将旧版 PPTX 转换为 React 幻灯片组
/slide-deck export <slug> html	export	快照并导出为独立 HTML
/slide-deck export <slug> pdf	export	快照并导出为 PDF
/slide-deck export <slug> vercel	export	快照并部署到 Vercel → 生成可分享的 URL
/slide-deck preview <slug>	—	仅检查幻灯片组 URL

可组合使用

• business-brainstorm — 如果要制作融资演示文稿，先集思广益设计方案；幻灯片组将基于简报制作
• decide — 对于围绕决策展开的演讲（例如“我该接受 VC 投资吗？”），先运行 /decide
• deep-research — 对于需要补充幻灯片组尚未包含的数据的演讲
• second-brain — 提取相关的 [[wiki]] 页面作为内容来源；幻灯片组可以引用这些页面
• watch-video — 将播客节目、Loom 或演讲录像整理成幻灯片大纲（运行 visual 模式还可捕捉关键时刻和展示的幻灯片）
• jab-hook — 演讲交付后，可将其转化为 BIP 轮换推广内容的切入角度
• frontend-skills（外部）— 用于制作非品牌化的 HTML 幻灯片组，且 React 幻灯片组仓库并非主要工作目录的情况

质量说明

• 用展示代替讲述——应用于叙事。 为演示文稿提供 3 种不同的构思方向（而不是一份打磨完善的草稿），让用户选择。在备选方案呈现之前就敲定叙事方向，做出的演示文稿往往只是中规中矩，难以令人印象深刻。
• 信息密度模式比美观更重要。 由演讲者主讲的演示文稿，每张幻灯片只有 3 个词，演讲者备注有 5 行。以阅读为主的演示文稿（供会后查阅、异步阅读）则相反。内容相同，呈现形式却截然不同。起草前先询问用户希望采用哪种模式。
• 幻灯片文字是口语的精简版。 两者都应通过朗读测试。如果幻灯片读起来像备忘录，那就不对。如果演讲者备注读起来像幻灯片，那也不对。
• 更新模式下的溢出保护。 不要一味地往现有幻灯片里塞更多内容——如果新增内容导致幻灯片超过目标词数或行数，就应提议拆分幻灯片或精简现有内容。悄悄塞入过多内容会让幻灯片显得拥挤。
• 导出时剔除演讲者视图。 Playwright 会对 ?present=0 模式进行快照，确保导出内容整洁。绝不要导出演讲者视图。
• 品牌一致性优先于可移植性。 React 演示文稿是唯一可信来源。HTML/PDF/Vercel 导出只是用于分享的快照——动画、交互和演讲者视图只存在于 React 版本中。
• 默认使用 1920×1080，预览使用 1280×720。 20 张幻灯片的全分辨率快照大小为 30-50 MB；低分辨率快照的大小减半，而画质损失极小。
• 部署涉及真金白银。 导出模式中的 vercel 路径会在部署前提示确认。域名和 Vercel 项目均已开启自动续费。