用 lyhhyy5218-afk/paper-ppt-skill 做论文 PPT 时，最容易卡住的不是“怎么让它更好看”，而是把它当成一个黑盒命令：丢进去 PDF，等着直接吐出最终 PPT。这个 skill 的真实路线是五阶段流水线，前一阶段必须写出文件，后一阶段再读取这些文件继续处理；中间文件缺了，后面生成再顺也会空。

它适合组会汇报、文献综述、论文汇报这类任务，目标是从论文 PDF 中提取正文、表格、关键发现和论文配图，再用 python-pptx 生成蓝白学术风格的汇报 PPT。第一个边界也很明确：它依赖 PDF 可解析、论文图片能被正确提取、章节结构足够清楚；扫描质量差、图表裁剪困难或论文结构混乱时，检查 workdir 里的阶段文件，比反复重跑命令更有效。

content.md 是第一步结果

SKILL.md 把流程拆成 EXTRACT → IMAGES → STRUCTURE → GENERATE → REFINE。第一步用 PyMuPDF 提取全文，输出 paper_ppt_workdir/<论文文件名>/content.md；第二步提取论文配图，输出 figures/ 和 figures_manifest.json；第三步规划 PPT 结构，输出 outline.json；第四步生成 generate_ppt.py 并执行得到 .pptx；第五步检查溢出、重叠、空白页等问题。

所以第一次试跑后，先打开 content.md。如果标题、摘要、章节、表格和 Figure 位置已经不完整，后面的 outline.json 很难补回来。再看 figures_manifest.json：正式论文配图应该有文件名、页码、图号和裁剪坐标。论文里有矢量图时，skill 会用高分辨率渲染页面再按坐标裁剪，目标是避开页眉、页脚和页码，而不是拿整页截图凑数。

安装失败，多半是依赖或目录位置没对上

README 给出的安装方式是把仓库克隆到 Claude Code skills 目录：

git clone https://github.com/lyhhyy5218-afk/paper-ppt-skill.git ~/.claude/skills/paper-ppt

运行前要先准备 Python 依赖：

pip install python-pptx PyMuPDF Pillow

安装后在 Claude Code 里输入 /paper-ppt --help，能看到参数说明才算入口正常。常用命令可以从一个短 PDF 开始：

/paper-ppt ~/桌面/论文.pdf --uni 清华大学 --logo ~/logo.png --lang zh --theme blue --slides 25

这里的 --uni 控制封面和尾页学校名称，--logo 指向本地 logo，--lang 支持 zh 和 en，--theme 支持 blue、green、red，--slides 控制目标页数。默认学校名是上海海事大学，默认主题是蓝白学术配色；如果学校名称和 logo 不改，封面很容易看起来像别人的汇报模板。

用 outline.json 和验证报告判断结果

outline.json 是这套流程的中枢。它应该写清每页标题、内容类型、使用哪张论文配图、章节分隔页怎么安排、表格和公式放在哪里。README 的示例里，一篇 25 页论文可以被整理成 28 页学术汇报 PPT，包含封面、提纲、章节分隔页、内容页、图表页、结论页和感谢页。目标页数不是越少越好，关键是所有章节、表格数据和关键发现有没有被覆盖。

最终检查不能只确认 PPT 文件能不能打开。REFINE 阶段会读取生成的 PPT，检查每页形状数量、图片数量、文字框数量，确认图片有没有超出幻灯片边界、有没有覆盖文字。如果页面看起来内容很空，需要核对 outline.json 的页数分配；如果图表页不对，需要核对 figures/ 和 figures_manifest.json；如果文字被遮挡，再看生成脚本是否需要微调。

会话中断时可以用 /paper-ppt --resume 继续。它会检查 paper_ppt_workdir/ 下已有文件，跳过已经完成的阶段，从断点继续。这个功能的前提是 workdir 没被删除；如果把中间目录清掉，再 resume 也只能重新开始。

lyhhyy5218-afk/paper-ppt-skill 解决的是“论文 PDF 到学术汇报 PPT”的长链路问题。第一次使用时建议用短论文确认 content.md、figures/、outline.json 和最终 PPT 都能出现；这几处通了，再调学校 logo、主题色和目标页数，后面的论文汇报会稳很多。