beamer-academic

name

beamer-academic

description

Generate high-quality academic Beamer slides from a thesis/paper (PDF, Word, or LaTeX source). Compatible with Claude Code and Codex. Supports thesis defense, proposal presentations, and conference talks. Built-in layout library with 13 professional page types, 5 color schemes, and interactive editing loop. Use when: (1) User asks to create thesis defense slides/PPT, (2) User wants to generate academic presentation from a paper, (3) User mentions beamer, 答辩PPT, 学术报告, 开题PPT, 论文幻灯片, or academic slides, (4) User has a PDF/docx/tex thesis and wants presentation output.

Beamer Academic

Generate publication-quality Beamer slides from an academic paper in one automated pipeline.

Pipeline Overview

论文 → 素材提取 → 大纲生成 → [用户确认] → 内容填充 → 编译 → [交互修改循环]

Phase 0: Environment Check & Input Clarification

0.1 Locate Thesis File

Search current directory for thesis in priority order:

1. .tex (LaTeX source — best quality, figures/equations directly reusable)
2. .docx (Word — good for text extraction, figures embedded)
3. .pdf (PDF — acceptable but figure extraction may lose quality)

If multiple candidates found, ask user which one. If none found, prompt: "请把论文文件放到当前目录（支持 .tex / .docx / .pdf）"

Recommend .tex or .docx over PDF: PDF figure extraction can produce low-quality raster images. If user only has PDF, warn:

注意：PDF 提取的图片可能有质量损失。如果你有论文的 Word 或 LaTeX 源文件，建议优先使用。

0.2 Check LaTeX Environment

which xelatex

If missing, recommend user to install (this is a one-time setup, not optional):

你的系统还没有安装 LaTeX 环境。beamer PPT 需要 xelatex 编译，我来帮你装一下：

Then provide the command for user's OS and offer to run it:

OS	Command
macOS	brew install --cask mactex-no-gui (推荐，约3.5GB，装一次永久可用)
Ubuntu/Debian	sudo apt install texlive-xetex texlive-lang-chinese texlive-fonts-recommended
Fedora/RHEL	sudo dnf install texlive-xetex texlive-xecjk
Windows (WSL)	sudo apt install texlive-xetex texlive-lang-chinese
Arch	sudo pacman -S texlive-xetex texlive-langchinese

Wait for installation to complete, verify with which xelatex, then proceed.

If user explicitly refuses to install (rare), fallback: deliver .tex + .sty + figures, suggest Overleaf.

0.3 Beamer Template (Ask User First)

Ask user about existing school beamer template:

你的学校/课题组有现成的 beamer 模板吗？（比如导师或师兄给过的 .sty 文件）

• 有：请放到当前目录，我直接使用
• 没有：我来帮你找或用内置通用模板

If user has a template: use it directly, skip the built-in theme.

If user has NO template:

1. Ask for school name
2. Search for existing public beamer templates for that school:
   • GitHub search: {school name} beamer template
   • Common sources: Overleaf Gallery, CTAN
3. If found: download and use (notify user which template)
4. If not found: use built-in assets/beamerthemeAcademic.sty with school logo
   • Ask: "你能提供学校 logo 图片吗？（放到当前目录即可）"
   • If no logo available: search online for the school's logo, or proceed without logo

0.4 Configuration

Check for config.yaml in current directory:

• Exists: read and use.
• Missing: ask user for basic info, then generate from template at assets/config.yaml.

Required user info (ask if not in config):

• Institution name and department
• Author name, supervisor, major
• Report type: defense | proposal | conference
• Color preference: blue | red | green | purple | teal
• Time limit (minutes): affects page count and content density
• Language: thesis language vs. PPT language (e.g., 英文论文 → 中文PPT)
• Chapnote preference: "每页要不要显示'对应论文 §X.X'的标注？"（some users find it helpful for committee, others find it cluttered）

0.5 Language Strategy

If thesis language ≠ PPT language, establish rules upfront:

你的论文是英文，PPT 要做中文版吗？ 对于专业术语，我会：

1. 首次出现用"中文（English）"格式
2. 之后统一用中文
3. 公式/变量名保持英文不翻译

这样处理可以吗？

Build a terminology mapping table (stored in materials/terms.md):

| English | 中文 | 首次出现页 |
|---------|------|-----------|
| disparity | 形态多样性 | P4 |
| diversity | 分类丰富度 | P4 |
| Ornstein-Uhlenbeck | OU 过程 | P8 |

Ensure 术语一致性: same concept uses same translation across all pages.

Phase 1: Material Extraction

Create materials/ directory. Extraction strategy depends on input format:

From .tex source (best)

1. Figures: locate \includegraphics paths, copy originals → materials/figures/
2. Tables: extract tabular/table environments → materials/tables/
3. Equations: extract equation/align/$$ blocks → materials/equations.md
4. Structure: parse \chapter/\section hierarchy → materials/structure.md

From .docx

1. Figures: extract embedded images (python-docx or unzip) → materials/figures/
2. Tables: extract table contents → materials/tables/
3. Equations: extract OMML/LaTeX equations → materials/equations.md
4. Structure: parse heading hierarchy → materials/structure.md

From .pdf (fallback)

1. Figures: use pdfimages or read PDF for embedded images → materials/figures/
   • ⚠️ Quality may degrade. Prefer vector (PDF/SVG) extraction when possible.
2. Tables: read and reconstruct → materials/tables/
3. Equations: read and convert to LaTeX → materials/equations.md
4. Structure: parse chapter/section from text → materials/structure.md

1.2 Material Confirmation (In-Conversation)

After extraction, present a figure catalog to user in conversation:

🖼️ 素材库（共提取 12 张图）

#	文件名	来源	内容描述
1	fig_001.png	论文图1	地质年代柱状图
2	fig_002.png	论文图4	PCoA 碎石图
3	fig_003.png	论文图8	形态空间散点图
...

哪些图是你答辩必须展示的？ 可以说：

• "1, 3, 5, 8 必须用"
• "图7 不用了，跟图5 重复"
• "全部都可能用到"

This ensures:

• Key figures won't be missed in layout assignment
• User has a mental model of available materials before the outline phase
• Low-quality or duplicate figures can be flagged early

Phase 2: Brainstorm Outline (Interactive, In-Conversation)

This phase determines the entire presentation structure through conversation with the user. All confirmation happens IN THE CHAT — never ask user to open a file.

2.0 Chapter Structure Principle

Follow the thesis's own structure as the PRIMARY basis for PPT chapters.

• If thesis has explicit chapters (第一章...第四章): map directly to PPT chapters
• If thesis has no chapters (like a conference paper with sections): group related sections into 3-5 logical chapters for the PPT
• Do NOT invent arbitrary chapter divisions that don't match the thesis logic
• The PPT chapter structure should feel natural to someone who has read the thesis

2.1 First Pass: Structure Proposal

After reading the thesis, propose the high-level structure directly in conversation:

📐 PPT 结构提案

根据你的论文结构，我建议这样安排：

总页数：42 页（约 20 分钟答辩）

章	标题	页数	对应论文	说明
一	研究背景与科学问题	8页	第1章	背景+命题+假设+创新点
二	数据构建与描述性分析	7页	第2章	数据来源+特征工程+时序总览
三	演化模式与驱动机制	15页	第3章	H1+H2+H3 三个假设检验
四	结论与展望	5页	第4章	主要结论+局限+展望+成果

你觉得这个结构可以吗？ 可以告诉我：

• "第三章太长了，拆成两章"
• "加一章文献综述"
• "总页数控制在35页以内"

Wait for user to confirm or adjust. Loop until structure is approved.

2.2 Second Pass: Per-Section Detail

Once chapter structure is approved, expand each chapter in conversation (not in a file):

📋 第一章 详细安排（8页）

页码	版式	标题	内容要点
P3	章节分隔	一、研究背景与科学问题	—
P4	左文右图	寒武纪辐射与软体动物的演化窗口	演化窗口介绍 + 地质年代图
P5	纯文段	经典命题：Disparity vs. Diversity	形态多样性与丰富度争论
P6	纯文段	驱动机制之一：外源突变	Sinsk 事件背景
P7	纯文段	驱动机制之二：系统发育约束	OU 过程假说
P8	列表	现有研究的四点不足	4个gap
P9	表格	研究目标与三个核心假设	H1/H2/H3 表格
P10	列表	论文的主要创新	5个创新点

这章的安排可以吗？ 可以说：

• "P5和P6合并成一页"
• "P9加一列'若成立则说明'"
• "ok，继续下一章"

Present one chapter at a time. Wait for approval before showing the next chapter.

2.3 Third Pass: Final Confirmation

After all chapters are individually approved, show a complete summary in conversation:

✅ 最终大纲确认

章	页码范围	页数	版式分布
封面+目录	P1–P2	2	cover, toc
一 研究背景	P3–P10	8	分隔×1, 左文右图×1, 纯文段×3, 列表×1, 表格×1, 列表×1
二 数据构建	P11–P17	7	分隔×1, ...
三 演化机制	P18–P32	15	分隔×1, ...
四 结论展望	P33–P37	5	分隔×1, ...
致谢	P38	1	thanks
合计		38页

确认后我将开始生成 beamer LaTeX 代码。确认吗？

HARD GATE: Do NOT proceed to Phase 3 until user explicitly confirms the final summary.

2.4 Save to outline.md

Only after final confirmation, save the approved structure to outline.md for Phase 3 reference. This file is for the AI's internal use — user has already approved everything in conversation.

Why In-Conversation Instead of File

• Users who don't know markdown can follow along naturally in chat
• Iterative refinement is faster (no "go check that file" round-trip)
• Each chapter gets individual attention

Layout Selection Rules (used in 2.2 per-page assignment)

1. Each chapter start → section-divider
2. Core formula/model definition → formula
3. Multi-row data comparison → table
4. High-information figure (multi-panel, heatmap) → full-image
5. Text-primary with supporting figure → text-left-image-right
6. Figure-primary with interpretation → image-left-text-right
7. Pure concept/background → text-only
8. Chapter-end with clear conclusion → conclusion-box
9. Between chapters → transition
10. Parallel bullet points → list

Rhythm Constraints

• No 3 consecutive pages with same layout
• Each chapter uses at least 3 different layouts
• Total: 35–50 pages (defense), 25–35 (proposal), 15–25 (conference)

Phase 3: Content Generation

1. Copy assets/beamerthemeAcademic.sty to current directory.
2. Generate defense.tex file header. Read references/tex-header.md for template.
3. For each page in outline.md:
   • Load layout skeleton from references/layouts.md (find section by layout id)
   • Fill slots with thesis content + extracted materials
4. Close with \end{document}.

Critical: Section Divider = 满版色 + 圆圈序号

每章开头用 \sectiondivider{1}{章标题}（圆圈里用阿拉伯数字，中文「一」在圆里像减号）。目录只在第 2 页出现一次。

Critical: TOC Page Format

The TOC page (P2) must use Chinese numbering with em-dash subtitles:

\begin{frame}
  \frametitle{汇报提纲}
  \vskip0.3cm
  {\footnotesize
  \begin{tabbing}
  \hspace{0.4cm}\=\hspace{0.6cm}\=\kill
  \textbf{\color{accentcolor}一}\>\textbf{研究动机}\,——\,为什么需要新的序列建模方案\\[8pt]
  \textbf{\color{accentcolor}二}\>\textbf{模型架构}\,——\,Transformer 的核心设计\\[8pt]
  \textbf{\color{accentcolor}三}\>\textbf{实验结果}\,——\,翻译质量与消融分析\\[8pt]
  \textbf{\color{accentcolor}四}\>\textbf{总结与展望}\,——\,贡献与未来方向\\
  \end{tabbing}
  }
\end{frame}

Critical: Figure Extraction from PDF

NEVER use full-page PDF screenshots as figures. When source is PDF:

1. Use pdfimages -all paper.pdf materials/figures/ to extract embedded vector/raster images
2. If pdfimages not available, use mutool extract or Python PyMuPDF
3. If only pdftoppm is available, crop the figure region ONLY:
   • First identify figure bounding box coordinates
   • Use Python PIL to crop the figure out of the page image
   • Remove surrounding text, page numbers, captions
4. Quality check: if extracted figure contains visible paper text around it, it's WRONG — re-crop
5. For well-known papers (Transformer, ResNet, etc.), consider re-drawing key diagrams with tikz

Critical: Anti-AI Writing Style (NO Bullet List Abuse)

The #1 sign of AI-generated slides is overuse of \begin{itemize} and uniform page structure.

Core rules:

1. Each page COMBINES multiple elements (段落+keybox, 段落+公式+段落, 段落+表格+结论)
2. Adjacent pages MUST use different composition patterns
3. \begin{itemize} is BANNED. Only \enumerate with intro paragraph allowed
4. 80% of pages use paragraph-style writing, not bullet points
5. Use inline patterns: $\bullet$ \textbf{term}, \alert{keyword}, \textbf{title}\,——\,explanation

Read references/writing-style.md for 6 concrete composition patterns with LaTeX code examples.

Content Quality Rules

Constraint	Value
Text per page (text-only)	150–200 chars
Text per page (with figure)	100–150 chars
Equations per page	max 2
Table rows	3–8
\alert{} keywords per page	1–2
Page structure	COMBINE multiple elements (see writing-style.md)
\itemize	BANNED

Section Divider (Enforced)

Every chapter boundary MUST use \sectiondivider{1}{章标题}（圆圈用 1/2/3）。

Anti-AI Title & Content Check

Before finalizing, check all titles and content. Read references/writing-style.md for the full red-flag list.

Quick check: "这个标题/段落像答辩学生写的还是 AI 写的？" 如果像 AI，改到像人。

Figure & Table Numbering

All figures and tables in the presentation MUST be numbered sequentially:

• Figures: 图 1, 图 2, 图 3... (using \figcap{图 1\;描述文字})
• Tables: in frame title or above table, mark as 表 1, 表 2...

Example:

\figcap{图 1\;Transformer 编码器--解码器架构}
\figcap{图 2\;多头注意力并行投影机制}

Table title pattern:

\frametitle{机器翻译 BLEU 对比（表 2）}
% or inside the frame:
{\small\textbf{表 1}\;不同层类型的复杂度对比}

Numbering must be consistent throughout — do not skip or repeat numbers.

Phase 4: Compilation & Layout Verification

4.1 Compile

xelatex -interaction=nonstopmode defense.tex && xelatex -interaction=nonstopmode defense.tex

On failure: read defense.log, fix common issues (missing image, font, overfull hbox), retry up to 3 times.

If user has no LaTeX environment, skip compilation and deliver .tex + .sty + materials/figures/.

4.2 Layout Bug Detection

After compilation, check defense.log for these common layout issues:

Symptom	Cause	Fix
Overfull \vbox on frame	Content exceeds page height	Reduce text, split into 2 pages, or shrink font
Overfull \hbox with image	Image too wide for column	Add keepaspectratio, reduce width
Image overlaps text in columns	\column width sum > \textwidth	Ensure left + right column ≤ 1.0
tikz overlay covers text	[remember picture, overlay] node position wrong	Adjust yshift/xshift values
Text runs below frame	Too many paragraphs	Cut to 150-200 chars or split page

Proactive overlap prevention (apply during Phase 3 content generation):

• For text-left-image-right: left text ≤ 150 chars, image height ≤ 3.4cm per image
• For image-left-text-right: right text ≤ 120 chars, image height ≤ 0.60\textheight
• For full-image: use only tikz overlay positioning, no surrounding text except \figcap
• For formula: max 2 equations, with \vskip0.1cm spacing between
• Never put more than 3 \vskip commands in one frame (sign of overstuffing)

If overlap detected in compiled PDF (user reports "P7图文重叠了"):

1. Identify the frame in .tex
2. Check: is text too long? Is image too tall? Are column widths correct?
3. Apply fix: reduce text / shrink image / split into 2 pages
4. Recompile and verify

Phase 5: Interactive Editing (Guided Choices)

Present result:

✅ PDF 已生成：./defense.pdf（共 XX 页，预计答辩时长 XX 分钟） 说修改意见，或说"满意"结束。

5.1 Guided Modification (Never Let User Struggle to Express)

When user gives vague feedback, offer concrete choices instead of asking them to describe:

User says	Respond with choices
"这页不好看"	"你觉得是：A. 文字太密想拆成两页？B. 图太小想换成满版图？C. 想换个版式？"
"这里有点奇怪"	"我看到可能的问题：A. 图文重叠了 B. 文字太学术想简化 C. 想加个过渡说明？"
"第三章不太行"	"第三章目前15页。你想：A. 整体缩减（砍到10页）？B. 某几页太密拆开？C. 补一页总结？"
"改好看点"	"我可以：A. 加几页满版图让节奏更松 B. 关键结论用高亮框突出 C. 换个配色？"

Principle: Always give 2–3 concrete options with preview of effect. User picks, not describes.

5.2 Modification Execution

Type	Action
Single page content edit	Edit corresponding \begin{frame}...\end{frame}
Add/remove page	Update outline.md, regenerate affected section
Global style change	Modify .sty or header
Layout switch	Replace frame with different layout skeleton

After each edit, recompile and present again. Loop until user says done.

Phase 6: Speaker Notes & Rehearsal Support (Optional)

After user confirms the slides are satisfactory, offer:

需要我帮你生成讲稿和配速建议吗？可以帮助你控制答辩节奏。

If user accepts, generate notes.md:

6.1 Per-Page Speaker Notes

## P4 — 寒武纪辐射与软体动物的演化窗口
⏱️ 建议时长: 45秒

### 要点提词
- 演化窗口: 5.41亿年前，持续4000万年
- 软体动物门: 现代海洋第二大门类
- 272个属: 本文研究对象

### 讲稿参考
"首先介绍一下研究背景。寒武纪是海洋生态系统大规模重组的关键时期……"

6.2 Time Pacing Table

Present pacing summary in conversation:

⏱️ 时间配速建议（总计 20 分钟）

章	页数	建议时长	每页均速
一 研究背景	8页	4分钟	30秒/页
二 数据构建	7页	3.5分钟	30秒/页
三 演化机制	15页	9分钟	36秒/页（重点章节，可以慢一些）
四 结论展望	5页	2.5分钟	30秒/页
致谢+缓冲	1页	1分钟	—

⚠️ 第三章是重点，建议对关键结果页多花时间讲解。

6.3 Beamer Notes Integration (Optional)

If user wants notes embedded in PDF (for dual-screen presentation mode):

\setbeameroption{show notes on second screen=right}

Add \note{} blocks to each frame in .tex with the speaker notes content.

Reference Files

• references/layouts.md — All 13 layout skeletons with slot definitions and LaTeX code
• references/tex-header.md — Standard .tex file preamble template
• references/layout-registry.yaml — Layout selection rules in structured format

Assets

• assets/beamerthemeAcademic.sty — Beamer theme file (copied to user project)
• assets/config.yaml — Configuration template (copied to user project)