research-slide-deck-builder

研究演示文稿构建器

用途

将研究内容转化为清晰的演示文稿：故事线、幻灯片顺序、页面级布局、图表位置、演讲者备注，以及实际的演示文稿源文件。

对于进展汇报、导师交流、实验室会议和研究更新演示文稿，本技能应优先使用外部的 progress-slides 模板仓库作为实现脚手架：

https://github.com/a-green-hand-jack/progress-slides.git

不要在本技能中重复创建该模板。应将其视为外部幻灯片组件或项目模板，在用户的项目中克隆、检查、安装并编辑。

如果用户已有幻灯片，需要计时、口头过渡、排练或问答练习，请稍后使用 presentation-dry-run。

适用场景

• 用户需要为导师会议、实验室会议、组内更新、论文阅读报告、会议演讲、提案或答辩环节制作幻灯片。
• 用户询问演示文稿应该是什么样、要做多少页、标题页用什么，或每页应该如何组织。
• 用户要求使用 progress-slides 或可复用的幻灯片模板。
• project-init 项目的 slides/ 组件需要内容、设置或维护。
• 研究笔记、图表、实验报告或项目记忆需要整理成演示文稿。

模板使用策略

• 除非用户明确要求其他格式，否则研究进展、导师交流、实验室和项目更新演示文稿应优先使用 progress-slides。
• 保留上游模板代码。不要在本技能中重新实现其 CSS、组件、主题、包配置或构建流程。
• 编辑前，先检查克隆的模板中的 README.md、package.json 和现有幻灯片源文件，因为外部仓库是权威来源。
• 如果仓库是私有的或暂时无法访问，记录这一阻碍，并仍然生成演示文稿大纲或 Markdown 源文件，以便之后移入模板。
• 如果用户位于项目控制根目录布局中，请将模板放置或连接到 <ProjectName>/slides/，作为独立组件仓库。

安装或连接 progress-slides

对于新的幻灯片组件：

git clone https://github.com/a-green-hand-jack/progress-slides.git slides
cd slides

然后检查模板：

ls
cat README.md
cat package.json

使用模板锁文件或 README 指明的包管理器安装依赖。如果没有更具体的本地说明，请使用：

npm install

从 package.json 运行本地预览命令。常见的 Slidev 风格命令如下：

npm run dev
npx slidev

对于现有项目：

• 如果 slides/ 已存在且就是模板仓库，请直接在其中编辑。
• 如果 slides/ 已存在但不是模板，请询问用户是要迁移、将 progress-slides 添加为新的独立仓库，还是只编写兼容的大纲。
• 如果模板使用 Git，请保留其历史记录，并在 slides/ 中执行常规 Git 操作。

多套幻灯片的组件模型

研究项目通常会在整个生命周期中需要多套幻灯片。应将 slides/ 视为幻灯片工作区，而不是一份永久的 slides.md。

建议的结构：

slides/
├── slides.md                 # optional active/scratch deck or template index
├── decks/
│   ├── 2026-05-02-advisor-plan.md
│   ├── 2026-05-09-lab-update.md
│   ├── 2026-05-15-result-review.md
│   ├── neurips-rebuttal-risk-review.md
│   ├── assets/               # deck-local assets when Slidev root is decks/
│   ├── setup/
│   └── styles/
├── assets/
│   └── <shared-or-root-deck-assets>
├── templates/
├── snippets/
└── .agent/
    ├── slides-status.md      # component-level status
    ├── deck-index.md         # registry of decks
    └── decks/
        └── 2026-05-02-advisor-plan.md

采用以下策略：

• 对于正式会议，在 decks/<date>-<audience-or-purpose>-<slug>.md 下创建一套稳定的幻灯片。
• 根目录的 slides.md 仅用于当前默认幻灯片、临时工作副本，或模板的示例／索引幻灯片。
• 不要仅仅因为开始了新的导师／实验室进展更新，就覆盖旧的会议幻灯片。
• 在 snippets/ 中保存可复用的单页片段；在 decks/ 中保存完整的历史幻灯片。
• 将生成的输出保存在 dist/ 或被忽略的导出路径中，不要将其作为事实来源。
• 对于特定幻灯片的资源，优先使用当前 Slidev 根目录下的资源。如果入口是 decks/<deck-id>.md，请使用 decks/assets/<deck-id>/...，并在幻灯片中通过 ./assets/<deck-id>/... 引用。只有确认资源能够从当前入口解析时，才使用 assets/shared/...。
• 如果模板 CLI 只能写入 slides.md，请先在那里初始化，然后将最终源文件移动或复制到 decks/<deck-id>.md；或者在可用时使用其 --out decks/<deck-id>.md 选项。

记录幻灯片记忆：

• slides/.agent/slides-status.md：组件状态、当前幻灯片、近期幻灯片、过时证据、构建／导出策略
• slides/.agent/deck-index.md：每套幻灯片一行，记录 id、路径、受众、日期、用途、源证据、验证状态和后续事项
• slides/.agent/decks/<deck-id>.md：重要幻灯片的可选单独备注，包括幻灯片约定、源证据、视觉验证和未解决的风险

幻灯片设计原则

• 一页一事。每页都需要一句话层面的核心结论。
• 明确呈现受众的理解路径：背景 -> 问题 -> 证据 -> 决策。
• 对于导师进展更新，应优先呈现决策、阻碍和证据，而非精心润色的叙事。
• 对于研究报告，应优先呈现研究动机、问题界定、方法直觉和结果解读。
• 图表是证据，而非装饰。解释坐标轴、设置和核心结论。
• 幻灯片标题应具体。避免使用“结果”“方法”或“实验”等泛泛标题。
• 将密集的细节放入备用幻灯片，而不是缩小文字。
• 构建成功不等于视觉效果成功。Slidev 幻灯片可以成功编译，但浏览器视图仍可能存在溢出、frontmatter 错误、资源缺失、代码高亮难以阅读、布局头重脚轻，或页面内容过于密集而不便展示等问题。

幻灯片约定

编写幻灯片源文件之前，先确定一份简短的幻灯片约定：

• deck_scope：这套幻灯片允许涵盖的唯一叙事主线
• allowed_terms：应当出现的项目名称和演示术语，例如 FK-Doob-PhysGen
• banned_terms：不得出现在面向受众的文本中的实现名称、过时项目名称或流程术语
• one_sentence_claim：受众应当记住的那句话
• project_title：必须出现在标题页和幻灯片元数据中的确切项目名称

编写完成后，搜索幻灯片源文件，查找禁用术语或过时术语。如果实现过程中使用的内部代号有用，但会让受众困惑，请在标题和核心结论中将其替换为演示术语，仅在技术上确有必要时保留实现术语。

默认命名规则：标题页、浏览器／PDF 元数据以及第一个 H1 必须包含项目名称。除非用户明确要求，否则不要使用仅包含方法名称的标题。

工作流

1. 确定演示类型

确定以下内容：

• 幻灯片 id 和 decks/ 下的目标路径
• 受众：导师、实验室、委员会、会议、面试或课堂
• 时限
• 目标：征求反馈、进展报告、教学、说服或答辩
• 最重要的一条核心结论
• 可用材料：记忆、笔记、图表、报告、论文草稿、代码结果或现有幻灯片
• 幻灯片约定：范围、允许使用的术语、禁用术语、一句话核心主张和确切项目标题

2. 选择最接近的演示文稿类型

选择最接近的类型。

顾问进度汇报：

1. 标题 / 会议目标
2. 上次承诺的事项
3. 进度摘要
4. 关键结果或证据
5. 已解决的问题
6. 遇到的阻碍
7. 选项 / 需要作出的决定
8. 下周计划

实验室会议研究进展汇报：

1. 标题
2. 问题与研究动机
3. 当前研究问题
4. 方法或实验设置
5. 实验设置
6. 主要结果
7. 消融实验 / 分析
8. 局限性或失败案例
9. 后续步骤与问题

论文阅读报告：

1. 标题：论文及其重要性
2. 用一句话概括贡献
3. 问题设定
4. 方法概述
5. 关键技术思路
6. 主要实验
7. 优势
8. 缺点 / 假设
9. 与用户项目的相关性
10. 讨论问题

会议风格演讲：

1. 标题
2. 研究动机
3. 问题
4. 现有研究的空白
5. 方法直觉
6. 方法细节
7. 实验设置
8. 主要结果
9. 分析 / 消融实验
10. 局限性
11. 要点总结

3. 大幅编辑前先制定幻灯片计划

为每张幻灯片写明：

• 幻灯片编号
• 幻灯片类型
• 总结核心要点的标题
• 所需的视觉内容 / 证据
• 要点或图示内容
• 演讲者备注
• 风险：哪些内容可能让听众感到困惑

如果一张幻灯片没有核心要点，就将其合并、删去或移至备用部分。

编辑源内容前，先设定容量上限：

• 普通幻灯片最多应包含一个 H1、一个主要视觉区域和一个核心要点。
• 不要在同一张普通幻灯片上同时放置问题框、长篇要点、代码块和核心要点。
• 普通幻灯片中的代码块通常不应超过 3 行；更长的代码应放到备用部分。
• 表格应能放入 16:9 页面，且不必将文字缩小到难以阅读的程度。
• 三列布局中，每列的要点应控制在约 3 条，除非视觉设计明确支持更多内容。
• 备用幻灯片可以内容密集，但每张仍需有明确用途：参考链接、资源路径、实现细节或补充证据。

4. 编写与模板兼容的源文件

检查 progress-slides 后，按照模板现有的格式编写。对于 Slidev 风格的 Markdown，优先采用以下模式：

---
theme: default
title: Project Progress Update
---

# Specific Takeaway Title

- Evidence or status point
- Decision or implication



---

# Main Result Supports the Current Claim

<figure-or-table-placeholder>

- Setup:
- Metric:
- Interpretation:

如果模板支持演讲者备注，请将其放在靠近幻灯片源内容的位置。图片路径应相对于幻灯片演示文稿，以便演示文稿可以移动或共享。

Slidev 源文件注意事项：

• 仅在演示文稿顶部放置整套演示文稿的 frontmatter。
• 每张幻灯片的 frontmatter 本身必须是有效的 frontmatter 块：

---
layout: center
class: text-center
---

• 如果页面不需要单张幻灯片的 frontmatter，请省略。不要在普通 Markdown 正文中留下 layout: 或 class: 行。
• 修改后，如果源文件改动较大，请在 frontmatter 块之外搜索 ^layout: 和 ^class:。
• 标题元数据应包含项目名称，以便导出的 PDF 和浏览器标题易于识别。
• 如果演示文稿源文件位于 decks/ 下，请针对该文件运行 Slidev，例如 npx slidev decks/2026-05-02-advisor-plan.md，不要默认目标是 slides.md。

Slidev 根目录、资源和样式注意事项：

• 编写路径前，根据入口文件确定当前使用的 Slidev 根目录。对于 slides/decks/<deck-id>.md，根目录可能是 slides/decks/，而非 slides/。
• 将独立的会议资源放在当前根目录下的本地目录中，例如 slides/decks/assets/<deck-id>/figure.png，并在 slides/decks/<deck-id>.md 中通过 ./assets/<deck-id>/figure.png 引用。
• 会议演示文稿不要依赖实时的代码工作区路径。将稳定且适合演示的图片复制到演示文稿本地的资源目录中。
• 将整套演示文稿的 CSS 放在当前 Slidev 根目录下，例如 slides/decks/styles/index.css，并在 slides/decks/setup/main.ts 中通过 import '../styles/index.css' 加载。
• 不要依赖一个大型 Markdown <style> 块来统一设置整套演示文稿的样式；它可能无法在所有幻灯片上一致生效。
• 对于代码或流水线幻灯片，请检查 Shiki 高亮生成的嵌套 span。如果本地样式导致内容难以阅读，请覆盖特定幻灯片块中 pre、code 和 code span 的颜色。
• 对于结果图片，选择布局前请先检查实际图片尺寸：

sips -g pixelWidth -g pixelHeight <figure>.png

• 图片对幻灯片应单独设置尺寸，不要沿用普通图片网格的设置。两张科学图表通常比通用卡片图片需要更多垂直空间。

5. 正确使用项目证据

• 从 code/docs/results/、code/docs/reports/、论文图片或用户提供的资源中选取稳定的图片。
• 不要将原始日志、超大输出、检查点或 wandb/tensorboard 缓存复制到幻灯片仓库。
• 如果图片已经过时、含义不清或信息过于密集，请在最终确定演示文稿前使用 figure-results-review。
• 如果幻灯片中的论断与论文或项目状态不一致，请在 memory/ 或 slides/.agent/ 中更新风险信息。

6. 验证叙事和术语

在构建或导出之前：

• 确认首页标题、浏览器/PDF 标题元数据和主 H1 均包含项目名称
• 确认每张普通幻灯片都有一个主要结论
• 在面向观众的标题和结论中搜索 banned_terms、过时的项目名称和内部实现名称
• 检查最后一张幻灯片是否引入了缺乏动机的新方向，除非演示文稿的范围明确允许这样做
• 结论中优先使用演示术语，例如“等距条件模型”；仅在实现细节幻灯片中使用 model_D 等实现术语

7. 验证幻灯片

完成前：

• 在依赖项可用时，运行模板的预览或构建命令
• 确认幻灯片能在本地打开；不要仅凭 npm run build 就认定幻灯片在视觉上可用
• 确认所有图片路径在浏览器预览中均有效，而不只是 Markdown 源文件中有效
• 确认全局 CSS 已从当前使用的 Slidev 根目录加载
• 检查文字在 16:9 演示视图中是否清晰可读
• 检查每张结果页是否说明了设置、指标和解读
• 目视检查第一页、第二页和最后三页，因为标题、框架和收尾方面的错误影响很大
• 以 16:9 截取具有代表性的幻灯片：一张文字密集的背景页、一张表格或指标页、一张包含两幅图的页面、一张代码或流水线页面，以及一张备份页（如果备份页使用了不同布局）
• 尽可能通过模板的导出命令、Slidev 浏览器导出界面或 slidev export --format png 导出 PNG/PDF；Slidev CLI 导出需要 Playwright/playwright-chromium
• 如果缺少 Playwright 或 Chromium 导致无法导出 PNG/PDF，请记录缺少的依赖项，并改用浏览器预览截图或手动检查浏览器
• 检查表格、代码块、三列布局、问题框和要点框是否溢出
• 即使没有内容溢出，顶部留白过多也应视为布局问题；使用针对幻灯片的类重新分配内容，不要把所有元素都堆在顶部附近
• 确认科学图表足够大，便于目视检查，尤其是并排图表
• 使用项目控制根目录布局时，更新 slides/.agent/slides-status.md 和 slides/.agent/deck-index.md，记录幻灯片路径、用途、受众、源证据、构建状态、视觉验证状态、过时证据风险、已知未检查风险和后续操作
• 对于重要或可复用的幻灯片，还应编写 slides/.agent/decks/<deck-id>.md

最终检查清单：

- [ ] Deck source lives in `decks/<deck-id>.md` unless this is a temporary/default `slides.md` deck.
- [ ] `slides.md` was not used to overwrite a previous real meeting deck.
- [ ] Title includes project name.
- [ ] Deck has one explicit narrative scope.
- [ ] Banned or stale terms checked with search.
- [ ] No normal slide has H1 + question box + code block + takeaway together.
- [ ] Code blocks are <= 3 lines unless in backup.
- [ ] Tables fit within 16:9 width.
- [ ] No literal `layout:` or `class:` frontmatter is rendered as body text.
- [ ] Deck-local assets resolve from the active Slidev root.
- [ ] Global CSS is imported from the active Slidev root, not only embedded in Markdown.
- [ ] Result figure dimensions were inspected before final sizing.
- [ ] Internal code names are replaced in audience-facing text where appropriate.
- [ ] Preview/build passes, or missing dependency is recorded.
- [ ] Representative 16:9 screenshots, PNG/PDF export, or browser visual inspection completed.
- [ ] Code blocks remain readable after syntax highlighting.
- [ ] Figure slides are readable and not undersized.
- [ ] `slides/.agent/slides-status.md` and `slides/.agent/deck-index.md` updated when project memory is present.

输出格式

对于仅要求规划的请求，请输出：

# Research Slide Deck Plan - [Deck Name]

## Context
- Audience:
- Time limit:
- Goal:
- One takeaway:
- Template: progress-slides
- Deck id:
- Deck path:
- Deck scope:
- Allowed terms:
- Banned terms:

## Slide Plan
| # | Type | Takeaway title | Visual/evidence | Speaker note | Risk |
|---:|---|---|---|---|---|

## Required Assets
- [ ] [figure/table/diagram]

## Decision Points
1. [Decision/question]

## Backup Slides
- [Backup topic]

对于实现请求，请编辑克隆的 progress-slides 仓库中实际的 slides/ 源文件，并报告已更改的路径以及使用的预览或构建命令。

在现有的幻灯片组件中创建新幻灯片时，默认使用：

slides/decks/<YYYY-MM-DD>-<audience-or-purpose>-<slug>.md
slides/decks/assets/<deck-id>/...
slides/.agent/deck-index.md
slides/.agent/decks/<deck-id>.md

仅当用户明确要求使用当前默认幻灯片，或模板工具要求临时暂存文件时，才使用 slides/slides.md。

禁止事项

• 不要在技能中另建一套幻灯片模板。
• 除非用户要求修改外部模板本身，否则不要重新设计该模板。
• 不要制作缺少证据或决策依据的状态要点幻灯片。
• 不要把面向会议演讲的叙事强加给顾问进展汇报。
• 不要因为用户担心遗漏内容，就在幻灯片中塞入过多信息。
• 如果用户期待的是可打开并用于演示的幻灯片，不要在 Markdown 正确或构建成功后就停止。
• 不要留下缺乏说明、只是堆放素材的备份页。
• 不要把 slides/slides.md 当成项目整个生命周期中唯一的幻灯片文件。
• 不要在每次会议中重复使用同一个文件，以免丢失旧幻灯片。