paper-slide-deck

论文幻灯片生成器

将学术论文和内容转换为专业的幻灯片图像，并自动提取图表。

用法

/paper-slide-deck path/to/paper.pdf
/paper-slide-deck path/to/paper.pdf --style academic-paper
/paper-slide-deck path/to/content.md --style sketch-notes
/paper-slide-deck path/to/content.md --audience executives
/paper-slide-deck path/to/content.md --lang zh
/paper-slide-deck path/to/content.md --slides 10
/paper-slide-deck path/to/content.md --outline-only
/paper-slide-deck  # Then paste content

设置（一次性）

TypeScript 脚本（merge-to-*、detect-figures、extract-figure、 apply-template）需要 Node 依赖项。安装一次即可：

cd ${SKILL_DIR}/scripts && npm install

这会安装 canvas、pdfjs-dist、pptxgenjs 和 pdf-lib（package-lock.json 会固定版本）。如果脚本因 missing Node dependency "<name>" 退出，请运行上面的 命令。Python 生成器（generate-slides.py）会在首次运行时自动安装 google-genai。

还需安装 PyMuPDF（pip install pymupdf）——对于嵌入位图（X 光片、CAM 热力图、照片） 的页面，这是可靠的图表提取备用方案；此类页面使用 extract-figure.ts 中的 pdfjs + canvas 路径会失败，并报错 Error: Image or Canvas expected。对于医学影像论文，这是常见情况， 而非例外，因此请将 PyMuPDF 视为必需项，而非可选项。

还需安装 Pillow（pip install Pillow）——当 Gemini 返回 image/webp 时， 每张幻灯片都需要通过 Pillow 转换为 PNG；如果未安装，所有图像都会报错 "converting it needs Pillow (pip install Pillow)"，直至安装完成。请将其与 PyMuPDF 一样视为必需项。

图像生成与无 API 密钥方案

图像生成需要 GOOGLE_API_KEY/GEMINI_API_KEY（Gemini API）或 Gemini Web 技能。如果没有密钥，也无法使用网页选项，该技能仍可在 降级模式下运行——不要中止：

1. 使用 --outline-only 生成大纲和提示词（不生成图像）。
2. 对于源 PDF，使用 detect-figures.ts + extract-figure.ts + apply-template.ts 提取真实图表/表格（无需 API 密钥——纯渲染）。
3. 将现有幻灯片（来源于 extract 的页面）合并为 PPTX/PDF，并将 prompts/ 交给用户，以便日后有可用密钥时生成图像。

脚本目录

重要：所有脚本都位于此技能的 scripts/ 子目录中。

Agent 执行说明：

1. 将此 SKILL.md 文件所在目录的路径设为 SKILL_DIR
2. 脚本路径 = ${SKILL_DIR}/scripts/<script-name>.ts
3. 将本文档中的所有 ${SKILL_DIR} 替换为实际路径

脚本参考：

脚本	用途
scripts/generate-slides.py	通过 Gemini API 生成 AI 幻灯片（Python）
scripts/merge-to-pptx.ts	将幻灯片合并为 PowerPoint
scripts/merge-to-pdf.ts	将幻灯片合并为 PDF
scripts/detect-figures.ts	自动检测 PDF 中的图表/表格（启发式；请核实页码）
scripts/extract-figure.ts	将完整 PDF 页面渲染为 PNG（可选 --crop；PyMuPDF 备用方案）
scripts/apply-template.ts	应用图表容器模板

选项

选项	描述
--style <name>	视觉风格——风格库和自动选择规则见 references/style-selection.md
--audience <type>	目标受众：初学者、中级用户、专家、高管、普通受众
--lang <code>	输出语言（en、zh、ja 等）
--slides <number>	目标幻灯片数量
--outline-only	仅生成大纲，跳过图像生成

风格与布局选择：选择风格时，请阅读 references/style-selection.md （可显式指定，也可根据内容信号自动选择——包括关于乱码数学公式/数字的学术信号注意事项）。仅在编写 大纲的 // LAYOUT 提示（每张幻灯片对应的 Layout: <name>）时，阅读 references/layout-gallery.md。

设计理念

此幻灯片适用于阅读和分享，而非现场演示：

• 每张幻灯片都必须无需口头讲解即可自明
• 滚动浏览时，内容应具备清晰的逻辑流程
• 每张幻灯片都应包含所有必要背景信息
• 针对社交媒体分享和离线阅读进行优化

文件管理

输出目录

每个会话都会创建一个以内容 slug 命名的独立目录：

slide-deck/{topic-slug}/
├── source-{slug}.{ext}    # Source files (text, images; source-paper.pdf for papers)
├── figures.json           # Figure-detection results (academic PDFs)
├── outline.md             # Final outline (with IMAGE_SOURCE blocks)
├── outline-{style}.md     # Style variant outlines
├── extracted/             # Raw PDF page extractions (pre-template)
├── figures/               # Extracted figure crops (pre-template)
├── prompts/
│   └── {NN}-slide-{slug}.md, ...
├── {NN}-slide-{slug}.png  # Final slide images in the deck ROOT — both AI-generated
│                          #   and extracted-figure slides; ext may be .jpg
├── {topic-slug}.pptx
└── {topic-slug}.pdf

Slug 生成：

1. 从内容中提取主要主题（2-4 个词，使用 kebab-case）
2. 示例：“Introduction to Machine Learning” → intro-machine-learning

冲突解决

如果 slide-deck/{topic-slug}/ 已存在：

• 追加时间戳：{topic-slug}-YYYYMMDD-HHMMSS
• 示例：intro-ml 已存在 → intro-ml-20260118-143052

源文件

将所有源文件复制并命名为 source-{slug}.{ext}：

• source-article.md（主要文本内容）
• source-diagram.png（对话中的图片）
• source-data.xlsx（附加文件）

支持多个来源：对话中的文本、图片和文件。

工作流

步骤 1：分析内容

1. 保存源内容（如果是粘贴的内容，则保存为 source.md）

2. 按照 references/analysis-framework.md 进行深入的内容分析

3. 确定风格（使用 --style 或根据特征自动选择）

4. 检测语言（源语言与用户偏好语言）

5. 规划幻灯片数量（使用 --slides 或动态规划）

6. 对于学术论文（含图表的 PDF）：运行自动图表检测：

   npx -y bun ${SKILL_DIR}/scripts/detect-figures.ts --pdf source-paper.pdf --output figures.json
   

   此操作会输出一个 JSON 文件，其中包含检测到的所有图表/表格、页码和说明文字。

   说明文字检测基于启发式规则——请务必核实，尤其是首页的预告图。 按行匹配 Figure N 可以可靠地找到独占一行的说明文字 （单栏布局），但无法识别说明文字与正文交错排列在双栏首页上的图表——而这往往是论文中最重要的架构/概览图。运行 detect-figures 后，请专门核对源文件中的 Figure 1：如果论文文本提到了 figures.json 中没有的 Figure N，请通过 // IMAGE_SOURCE 块手动添加，并使用 PyMuPDF 后备方案提取。不要假设 figures.json 内容完整。

步骤 2：生成大纲变体

1. 如果用户明确传入了 --style <name>，则直接使用该风格，并跳过下方的变体问题（明确选择后再询问属于多余操作）。否则，根据内容分析生成 3 个风格变体大纲
2. 按照 references/outline-template.md 的结构进行
3. 为学术论文自动填充 IMAGE_SOURCE：
   • 读取步骤 1 中的 figures.json
   • 根据 references/analysis-framework.md 第 8 节中的规则，将图表映射到幻灯片
   • 自动向适当的幻灯片添加 // IMAGE_SOURCE 块：
     • 架构/流程图 → 方法幻灯片（Source: extract）
     • 结果表格 → 定量结果幻灯片（Source: extract）
     • 对比图片 → 定性结果幻灯片（Source: extract）
     • 概念图/简单示意图 → 留给 AI 生成（Source: generate 或省略）
4. 为每个变体保存为 outline-{style}.md

步骤 3：用户确认

使用单个 AskUserQuestion 提出所有适用选项：

问题	询问时机
风格变体	仅当未传入 --style 时（3 个选项 + 自定义）；明确传入 --style 即为答案
语言	仅当源语言 ≠ 用户语言时

选择后：

• 将选定的 outline-{style}.md 复制为 outline.md
• 如果用户有要求，则用另一种语言重新生成
• 用户可以编辑 outline.md 进行微调

如果使用 --outline-only，则在此处停止。

步骤 4：生成提示词

1. 读取 references/base-prompt.md
2. 与大纲中的风格说明合并
3. 添加幻灯片专属内容
4. 如果大纲指定了 Layout:，则在提示词中加入布局指导：
   • 参考布局特征进行图片构图
   • 示例：Layout: hub-spoke →“中心概念位于中央，相关项目向四周辐射”
5. 保存到 prompts/ 目录

第 5 步：图像生成方式选择

生成图像之前，请询问用户选择生成方式：

使用 AskUserQuestion，选项如下：

选项	标签	说明
1	Gemini API（推荐）	通过 Python 使用 Google 官方 API。需要设置 GOOGLE_API_KEY 环境变量。
2	Gemini Web（基于浏览器）	⚠️ 使用逆向工程得到的 Web API。无需 API 密钥，但可能会失效。

如果没有可用的 API 密钥，不要继续推荐选项 1——请提供设置部分中的降级无密钥方案（--outline-only + 提取 + 提示词交接）。

选项 1：Gemini API（Python）

1. 验证 API 密钥：检查 GOOGLE_API_KEY 或 GEMINI_API_KEY 环境变量
2. 运行生成脚本：

   python3 ${SKILL_DIR}/scripts/generate-slides.py <slide-deck-dir>
   

   模型 ID 在此处声明一次：gemini-3-pro-image（Nano Banana Pro，GA；较旧的 -preview ID 已弃用）。仅在需要时使用 --model <id> 覆盖。

脚本行为（详情见脚本文档字符串）：

• 自动安装 google-genai；如果找不到提示词文件，则报错退出（返回非零值）
• 通过退避重试失败的生成（总计尝试 3 次，间隔依次为 10 秒和 15 秒）
• 跳过已生成的幻灯片（大于 10 KB，任意图像扩展名）
• 将每张幻灯片保存到演示文稿根目录——与提取的图表幻灯片存放在同一位置，因此只需一个合并步骤即可处理两者
• 使用真实的图像扩展名保存，并将 WebP 响应转换为 PNG（合并脚本仅接受 png/jpg/jpeg）

选项 2：Gemini Web Skill

请阅读 references/gemini-web.md，了解同意确认、逐张幻灯片调用和代理设置。此方式需要 baoyu-danger-gemini-web skill，并且用户必须明确同意逆向工程 API 免责声明。

第 5.5 步：处理 IMAGE_SOURCE（自动提取图表）

对于学术演示文稿，已根据第 1 步中的图表检测结果，在第 2 步自动填充 IMAGE_SOURCE 元数据。

自动执行：

1. 解析大纲，找出包含 Source: extract 的幻灯片

2. 创建图表目录：mkdir -p figures

3. 对每张需要提取的幻灯片，自动执行：

   • 从元数据读取 Figure 编号、Page 和 Caption
   • 运行图表提取脚本：

     npx -y bun ${SKILL_DIR}/scripts/extract-figure.ts \
       --pdf source-paper.pdf \
       --page <page-number> \
       --output figures/figure-<N>.png
     

     注意：extract-figure.ts 会将整页渲染为高分辨率 PNG——它不会自动检测或裁剪单个图表的边界框。在双栏页面上，你会得到两栏内容。若要分离某个图表，可以传入 --crop "x,y,width,height"（以渲染/缩放后页面上的像素为单位），也可以打开 PNG 确认图像内容，然后在应用模板之前手动裁剪。
   • 运行模板应用脚本：

     npx -y bun ${SKILL_DIR}/scripts/apply-template.ts \
       --figure figures/figure-<N>.png \
       --title "<slide-headline>" \
       --caption "Figure <N>: <caption-text>" \
       --output <NN>-slide-<slug>.png
     

   • 报告：“已提取：Figure N → 幻灯片 NN”

4. 对于包含 Source: generate 的幻灯片（或没有 IMAGE_SOURCE 的幻灯片）：

   • 继续执行第 6 步进行 AI 生成

注意：源 PDF 必须以 source-paper.pdf 为文件名保存在输出目录中。

故障排除：

• 如果图表检测漏掉了某个图表：手动在大纲中添加 // IMAGE_SOURCE 块
• 如果图表映射错误：编辑大纲中的 Figure: 和 Page: 值
• 如果提取失败：检查 PDF 页码（从 1 开始计数）

使用 PyMuPDF 作为页面提取的备用方案： 如果 extract-figure.ts 失败并报错“Image or Canvas expected”（复杂 PDF 中常见），请使用 PyMuPDF：

import fitz
doc = fitz.open("source-paper.pdf")
page = doc[page_num - 1]  # 0-indexed
mat = fitz.Matrix(3, 3)  # 3x scale for high resolution
pix = page.get_pixmap(matrix=mat)
pix.save(f"extracted/page-{page_num}.png")

然后使用 apply-template.ts 应用模板。

步骤 6：生成图像

1. 使用步骤 5 中选定的方法
2. 跳过步骤 5.5 中已处理的幻灯片（带有 Source: extract 的幻灯片）
3. 生成会话 ID：slides-{topic-slug}-{timestamp}
4. 使用相同的会话 ID 生成其余每张幻灯片
5. 报告进度：“已生成 X/N”
6. 失败时自动重试（API 路径：退避重试 3 次；参见步骤 5）

步骤 6.5：校对生成的图像（内容完整性）

文本转图像会将文本烘焙到像素中，导致拼写、数学符号和数字乱码——这是此技能最大的风险。不要在未经检查的情况下交付。 （这是此技能对代码库共享引用完整性核心的应用 [docs/citation-integrity-core.md]：数字和声明必须与来源一致，失败必须显示为可见标记，绝不能静默替换。）

对每张生成的幻灯片（尤其是含有公式、表格、关键数字或非拉丁文字的幻灯片），使用 Read 打开 PNG 并进行目视检查：

1. 拼写 / 用词 — 标题和正文与大纲一致，没有杜撰或乱码的词语。
2. 数学内容和符号 — 公式、下标、希腊字母和运算符正确（或不存在）。在确认之前，默认模型生成的内容有误。
3. 数字和单位 — 任何承载数据的数值都与来源完全一致。

如果发现乱码：

• 使用修正或简化后的提示词重新生成该幻灯片（将易出错的术语改为注音拼写、减少文本密度、将准确数字移至说明文字中）。最多重试 2 次。
• 如果重试 2 次后仍然失败，请在步骤 8 的摘要中将该幻灯片标记为 [CHECK]，并建议采取以下措施之一：
  • 使用来源 PDF 中提取的图表 / 表格替换（Source: extract），或
  • 简化幻灯片，移除容易出错的文本，或
  • 如果演示文稿确实需要忠实且可编辑的公式 / 数据，请改用 scholar-slides。

绝不要悄悄交付含有乱码数学内容或数据的幻灯片——务必明确指出。

步骤 7：合并为 PPTX 和 PDF

npx -y bun ${SKILL_DIR}/scripts/merge-to-pptx.ts <slide-deck-dir>
npx -y bun ${SKILL_DIR}/scripts/merge-to-pdf.ts <slide-deck-dir>

步骤 8：输出摘要

Slide Deck Complete!

Topic: [topic]
Style: [style name]
Location: [directory path]
Slides: N total

- 01-slide-cover.png ✓ Cover
- 02-slide-intro.png ✓ Content
- 04-slide-results.png ⚠ [CHECK] math/numbers — verify or use scholar-slides
- ...
- {NN}-slide-back-cover.png ✓ Back Cover

Outline: outline.md
PPTX: {topic-slug}.pptx
PDF: {topic-slug}.pdf

明确列出所有标记为 [CHECK] 的幻灯片（来自步骤 6.5），让用户知道哪些幻灯片可能含有乱码文本 / 数学内容 / 数据，以及如何补救。

修改幻灯片

参见 references/modification-guide.md，了解以下内容：

• 编辑单张幻灯片的工作流
• 添加新幻灯片（并重新编号）
• 删除幻灯片（并重新编号）
• 文件命名规范

图像生成依赖项

Gemini API（选项 1 — 推荐）

要求：

• GOOGLE_API_KEY 或 GEMINI_API_KEY 环境变量
• Python 3.8+ 和 pip
• google-genai 包（由脚本自动安装）

模型 ID：在步骤 5 中说明一次。

Gemini Web Skill（选项 2）

参见 references/gemini-web.md — 需要 baoyu-danger-gemini-web 技能、已登录 Google 账号的 Chrome，以及用户同意。

PDF 图表提取

要求（通过 cd ${SKILL_DIR}/scripts && npm install 安装）：

• 主要方式：pdfjs-dist npm 包（Node.js 请使用 legacy 构建）
• 用于 extract-figure.ts / apply-template.ts 的 canvas npm 包
• 备用方式：pymupdf Python 包（处理复杂 PDF 时更可靠）

参考资料

只阅读当前步骤所需的参考文件，切勿对 references/ 使用 glob。

文件	阅读时机
references/analysis-framework.md	步骤 1 — 深入分析内容；IMAGE_SOURCE 映射规则
references/style-selection.md	步骤 1/3 — 风格图库 + 自动选择（包括学术信号注意事项）
references/outline-template.md	步骤 2 — 大纲结构和 STYLE_INSTRUCTIONS 格式
references/layout-gallery.md	步骤 2 — 每张幻灯片的 Layout: 提示
references/base-prompt.md	步骤 4 — 图像生成的基础提示词
references/gemini-web.md	步骤 5 选项 2 — 同意、调用、代理
references/modification-guide.md	交付后编辑 — 添加/删除/重新编号幻灯片的工作流
references/content-rules.md	内容与风格指南
references/figure-container-template.md	步骤 5.5 — 提取图形容器的视觉规格
references/styles/<style>.md	所选风格的完整规范

注意事项

图像生成

• Gemini API：推荐使用。稳定、可靠，但需要 API 密钥
• Gemini Web：无需 API 密钥，但使用逆向工程的 API，存在账户风险
• 生成时间：每张幻灯片 10–30 秒
• 失败后会自动重试（API 路径：采用退避策略，最多重试 3 次）
• 通过会话 ID 保持风格一致性

内容指南

• 对敏感公众人物使用风格化替代形象
• 两种路径都使用 Gemini 图像模型，但 Web 路径的模型版本不受你控制——它会随 Google 的部署变化，并可能与 API 路径不同