Peytontalismanic424/paper-share-skills

Paper → Beamer Slides Pipeline

Given a paper (PDF or TeX source), produce a compiled SUSTech-themed Beamer presentation under 论文分享/<VENUE> - <SHORT_TITLE>/.

Theme variant: \usetheme{sustech} (lowercase, Variant A), from https://github.com/yhbcode000/sustech-slides-template.git. Do NOT use \usetheme{SUSTech} (Variant B, used in MT3) — it has different macros and no section-separator pages.

Default aspect ratio: aspectratio=1610 (16:10). Do NOT use 169 (16:9) — 1610 is preferred for laptop/projector compatibility and gives slightly more vertical space for dense content.

Bash runtime: All shell commands run under the session's bash tool, which on Windows is Git Bash. Unix-style rm -rf, cp -r, mkdir -p are available. Working directory is set per-block via cwd.

Requirements (COMPULSORY)

Every slide deck MUST satisfy these rules. No exceptions except where noted.

1. No slide overflow (strict) — all slides MUST compile without Overfull \hbox or Overfull \vbox warnings. Follow skill://sustech-beamer-overflow: single-column only, max 3 blocks + 1 callout, tables ≤5 columns with \footnotesize, no \resizebox. The ONLY exception is the index/TOC page (\twopane layout) — slight vertical overflow (Overfull \vbox) on the TOC frame is tolerated.

---

Phase 1 — Setup directory

1. Accept $ARGUMENTS — a PDF path, .tar.gz TeX archive, or .tex file (absolute or relative from session cwd), or an arXiv URL / bare arXiv ID.

2. If the input is an arXiv URL or bare ID (matches ^\d{4}\.\d{4,5}(v\d+)?$ or contains arxiv.org/(abs|pdf|e-print)/), download the TeX source first:

   uv run --no-project python \
     "<SKILLS_DIR>/paper-download-arxiv-paper-source/scripts/download_source.py" \
     "<arxiv-ref>"        # default output = session cwd
   

   • If stdout ends with TEX_SOURCES:: derive DIR_NAME — venue from \setsource{Venue}{Year} in the extracted paper_src/ TeX (fallback \markboth, then arXiv <year>); short title = first 1–3 significant words of \title{...} (fallback: ask the user, existing rule). Then mkdir -p "论文分享/<DIR_NAME>" and mv arXiv-<id>.tar.gz paper_src "论文分享/<DIR_NAME>/".
   • If stdout ends with PDF_ONLY: <path>: the paper has no TeX source on arXiv — copy that PDF to 论文分享/<DIR_NAME>/ per the .pdf branch below (MinerU path applies, Phase 2 DECISION GATE unchanged).
   • If the command exits nonzero: stop and report the stderr message to the user.

3. Derive a short directory name <VENUE> - <SHORT_TITLE> (arXiv-input runs already derived it in step 2):

   • Strip .pdf / .tar.gz / .tgz / .tex, replace spaces/hyphens/special chars.
   • Ask the user for the name if venue/title are not inferrable from the filename.
   • Convention: existing examples are SCIENCE ROBOTICS - HIL SERL, SCIENCE ROBOTICS - MT3.

4. Create 论文分享/<DIR_NAME>/ and extract/copy the source there (arXiv-input runs already moved the archive + paper_src/ in step 2):

   • .tar.gz / .tgz: extract with tar -xzf into paper_src/.
   • .pdf: copy directly to paper dir root.
   • .tex: copy source files into paper_src/.

---

Phase 2 — Content extraction

DECISION GATE: If TeX source is available (.tar.gz archive containing .tex, or direct .tex file), skip MinerU entirely. Read all content (title, authors, abstract, sections, tables, references directly from the TeX source using read — it's more accurate than MinerU output and preserves table structures exactly.

Only run MinerU when the input is a PDF with no TeX source available:

"$MINERU_PYTHON" \
  "<SKILLS_DIR>/pdf-to-markdown/convert.py" \
  "论文分享/<DIR_NAME>/<pdf_filename>.pdf" \
  "论文分享/<DIR_NAME>/md_output" \
  --lang en

• English papers: --lang en. Chinese/mixed: --lang ch.
• The wrapper prints DONE -> ...md on success.
• Output lands at md_output/<name>/auto/<name>.md.

If MinerU env is missing, stop and tell the user to install it per the pdf-to-markdown skill preflight.

---

Phase 3 — Install the packaged template

The promoted paper-to-beamer package is the primary, offline template source:

uv run --project "<SKILLS_DIR>/paper-to-beamer" python \
  "<SKILLS_DIR>/paper-to-beamer/scripts/copy_template.py" \
  --output "论文分享/<DIR_NAME>/slides-template"

This copies the verified main_template.tex, latexmkrc, and sustech-theme/ bundle. A network clone is never a fallback. Only when the user explicitly requests a template refresh may the upstream repository be cloned into a separate temporary directory for review before package release.

---

Phase 4 — Create working dir and copy essentials

# cwd: $PP_ROOT
mkdir -p "论文分享/<DIR_NAME>/slides-beamer"
cp -r "论文分享/<DIR_NAME>/slides-template/sustech-theme" \
  "论文分享/<DIR_NAME>/slides-beamer/"
cp "论文分享/<DIR_NAME>/slides-template/latexmkrc" \
  "论文分享/<DIR_NAME>/slides-beamer/"
cp "论文分享/<DIR_NAME>/slides-template/main_template.tex" \
  "论文分享/<DIR_NAME>/slides-beamer/main.tex"
mkdir -p "论文分享/<DIR_NAME>/slides-beamer/figures"

All subsequent edits target slides-beamer/ only. slides-template/ is kept pristine as a reference.

---

Phase 5 — Read and extract content

When TeX source available (preferred — .tar.gz archive or .tex file): read the main .tex from paper_src/ directly using read. All content (title, authors, abstract, sections, tables, references) is extracted from the structured LaTeX source. Tables can be recreated directly from tabular environments — no MinerU needed.

When only Markdown available (PDF-only input): read md_output/<name>/auto/<name>.md. Extract these data points:

Phase 6 — Fill slides-beamer/main.tex

This is the core creative phase. Read main.tex (copied from template), then edit it section by section to replace every \ph{…} placeholder and \phfig with real content from the Markdown.

Use the HIL SERL example as a filled-in style reference: 论文分享/SCIENCE ROBOTICS - HIL SERL/slides-beamer/main.tex.

6.0 Preamble metadata

• \title[ACRONYM 论文分享]{Chinese descriptive title} — Chinese title as main; short title MUST include "论文分享" suffix. Follow HIL SERL: \title[HIL-SERL 论文分享]{...}.
• \subtitle{English original paper title} — English original as subtitle.
• \author[short]{…} — full author list from paper.
• \institute[short]{…} — primary institutions.
• \setsource{Venue}{Year} — paper venue.
• \setdomains{\domaintag{...}\domaintag{...}\domaintag{...}} — 3-4 research domain tags displayed on the title page as colored pills. Tags MUST be in Chinese (e.g. 多智能体RL, LLM Agent, RL后训练). English terms like Multi-Agent RL, RL Post-Training are NEVER allowed — they look inconsistent next to Chinese text and break the SUSTech theme's bilingual presentation style.
• \setpresenter{$PRESENTER} (default) or ask the user.
• \setvenue{<venue location>} (default: ask the user).
• Title page source footnote \creditline (default shows: 哔哩哔哩 · 白拾的物理AI组会 · github.com/yhbcode000/sustech-slides-template). For public sharing/publishing videos it is recommended to keep; for reports/thesis defenses requiring a clean layout, add \hidecredits in the preamble to disable, or \setcreditline{} to empty, or \setcreditline{...} for custom text.

Delete the placeholder-helper macros \ph and \phfig — they're no longer needed.

6.1 Title page

The \titlepage frame stays as-is. Preamble metadata drives it.

6.2 📑 Enhanced TOC

The template now uses a two-pane \twopane layout (from the theme). The left pane contains a compact TOC via {\tocdense\small\tableofcontents[hideallsubsections]}. The right pane contains three blocks:

1. \block{核心观察} — 3-5 key metrics/insights from the paper
2. \block{附录讨论} — 3-5 appendix highlights (Oral signal, comparisons, method explainers)
3. \callout[一句话概括] — one-sentence paper summary

The separate 论文信息 frame is DELETED. Title/venue/authors are already in the preamble. The one-sentence summary lives in the TOC callout. No separate info frame needed.

TOC spacing: Use {\tocdense\small\tableofcontents[hideallsubsections]} — \tocdense (from theme) compacts the beamer TOC spacing. Prefix with \vspace{-0.6em} to pull content up closer to the title.

Left margin: The theme's \tocdense adds \hskip2em left margin for balanced TOC layout.

6.3 👤 Author introduction — CROSS-VALIDATE ONLINE BEFORE WRITING

CRITICAL: You MUST search online for author bios BEFORE writing this frame. Paper PDFs only provide names and affiliations — they lack Chinese names, current positions, prior notable work, lab names, and recent recognitions. Generic entries like "Tsinghua University, first author" are UNACCEPTABLE.

Search procedure (execute BEFORE writing the frame):

1. Write to xd://web_search with {"query": "<first author> <institution> <paper domain>", "limit": 5} — get Chinese name, current role, prior work, lab.
2. Write to xd://web_search with {"query": "<corr author 1> <institution>", "limit": 5} — same for each corresponding author.
3. Cross-reference at least 2 sources per author. Prefer personal homepages or Google Scholar.
4. Also search via xd://web_search with {"query": "<institution> <lab/prof> <domain>", "limit": 5} for lab context.

What to extract from search results:

• Chinese name (paper PDFs often lack Chinese characters)
• Current position (assistant prof? PhD student? industry? paper affiliation may be stale)
• Notable prior work (what is this person known for? e.g. MAPPO, RLinf, GRPO)
• Lab / group name (e.g. EDI Lab, NICS-EFC, RAIL)
• Recent recognitions (papers at top venues, awards, leadership roles)

Fill the frame with telegraphic, sourced bios:

\begin{frame}{作者介绍}
  \begin{block}{核心作者}
    \begin{itemize}
      \item \shl{<first author>}（<Chinese>）：<dept>, <role>。以 \keyword{<prior work>} 著称。在本文中<role>。
      \item 合作者来自 <institutions>，构成<description>团队。
    \end{itemize}
  \end{block}
  \tightgap
  \begin{block}{通讯作者}
    \begin{itemize}
      \item \shl{<corr 1>}（<Chinese>）：<position> @ <inst>，<lab> PI。研究方向为 \keyword{<f1>}、\keyword{<f2>}。<notable work>。本文<role>。
      \item \shl{<corr 2>}（<Chinese>）：<position> @ <inst>，<lab>。<notable>。本文<role>。
    \end{itemize}
  \end{block}
  \tightgap
  \begin{callout}[研究脉络]
    <team trajectory leading to this paper>。
  \end{callout}
\end{frame}

6.4 📋 Background and Motivation

Map to the 研究背景与动机 section in the template:

• Set \renewcommand{\secblurb}{…} (one-sentence summary) before \section.
• Fill bullet placeholders with telegraphic motivation from abstract/intro.
• Move the figure to a dedicated [plain,c] slide after this content slide: \fitfigure{fig1_overview.jpg} + \figcap{1}{caption}. Remove the \begin{columns} wrapper — this slide stays text-only.
• Fill \metric{…}{…} with up to 3 key numbers from the paper.

6.5 Related Work

Map to the 相关工作 section:

• Fill research areas from the paper's Related Work section.
• List actual baseline methods and their relationships.
• State the key differentiator in the callout.

If the paper has a clear "Related Work" section, use it. Otherwise condense from scattered references in the introduction.

6.6 🔧 Method

Map to the 方法 section (2 frames: overview + core design).

Frame 1 (Overview) :

• List system components from the paper's method section.
• Move the figure to a dedicated [plain,c] slide after this content slide: \fitfigure{fig2_system.jpg} + \figcap{2}{caption}. Remove the \begin{columns} wrapper.

Frame 2 (Core design) :

• List up to 4 key design elements.
• Add one-line takeaway in the callout.

6.7 🧪 Experimental Design

Map to the 实验设计 section:

• List task categories/datasets.
• State evaluation protocol and baselines.
• Move the figure to a dedicated [plain,c] slide after this content slide: \fitfigure{fig3_tasks.jpg} + \figcap{3}{caption}. Remove the \begin{columns} wrapper.

6.8 📈 Results and Analysis

Map to the 实验结果 section (2 frames: main table + analysis).

Frame 1 (Main table) :

• Recreate the table with real data from the paper.
• Keep ≤5 columns, ≤6 rows.
• Highlight best results with \shl{…}.
• Use \theadrow, \altrow, \thc{…} with booktabs.
• One-line conclusion in the callout.

Frame 2 (Analysis) :

• Bullet-point analysis (3–4 observations).
• Analysis figure on a dedicated [plain,c] slide after the analysis bullets.

6.9 💡 Key Takeaways

Map to the 要点总结 section (corresponds to "核心贡献"):

• 3 enumerated key takeaways.
• One-sentence summary in the callout.

6.10 ⚠️ Limitations and Discussion

Map to the 局限性 section:

• 3–4 limitations.
• Author-identified future directions in the callout.

6.11 📚 References

Map to the 参考文献 frame:

• Fill bibitem entries with actual references from the paper.
• First bibitem should be the paper itself (marked （本文）).
• Include 3–5 key baselines.

6.12 💬 Q&A

Replace placeholder text in the Q&A frame with:

• Presenter name, institution, contact info.
• Keep the Q&A styling (\fontsize{40}{44} etc.).

6.13 Figures handling

For every placeholder that needs a figure:

1. TeX source available (preferred): copy figures from paper_src/figures/ to slides-beamer/figures/ with semantic names: fig1_overview.pdf, fig2_system.pdf, etc. TeX sources use vector .pdf figures — superior quality.
2. Markdown available: list images from md_output/<name>/auto/images/. Each is a hash-named .jpg. Pick the relevant figure by inspecting with inspect_image or from the markdown's ![](images/...) references.
3. Place the figure on its own dedicated slide — NEVER inside a \begin{columns} block:

   \begin{frame}[plain,c]
     \centering
     \includegraphics[height=0.92\textheight,width=\textwidth,keepaspectratio]{filename}
     \figcap{N}{caption text}
   \end{frame}
   

If a figure is missing or uncapturable, insert a placeholder callout instead (the \phfig helper was deleted in 6.0, so do NOT reference it.

---

Phase 7 — Compile the slides

Compile with latexmk (4 passes for stability):

cd "论文分享/<DIR_NAME>/slides-beamer"
latexmk -xelatex -interaction=nonstopmode main.tex 2>&1 | tail -20

• Check for Overfull \hbox / Overfull \vbox warnings. Fix any overflow by simplifying blocks or moving content to the next slide.
• If compilation fails, inspect the log, fix main.tex, and recompile.
• Once clean, the compiled PDF is at main.pdf.

---

Phase 8 — Final output

Output the path to main.pdf:

echo "Complete! PDF: 论文分享/<DIR_NAME>/slides-beamer/main.pdf"