paper-report-ppt

Turn research PDFs into editable group-meeting PPTX following the paper's structure; embed figures verbatim. Invoke when converting a paper into a group meeting presentation.

mlj-1212@mlj-1212

Install

openclaw skills install @mlj-1212/paper-report-ppt

Paper Report PPT Skill

把研究生文献（PDF）按文章脉络生成用于组会汇报的可编辑 PPTX。文献配图原样嵌入不改，使用自由设计路径生成学术专业风格演示文稿。

本 skill 是自包含场景编排层，所有核心能力通过内置 Python 脚本实现，不依赖任何外部 skill。只需 pip install python-pptx PyMuPDF python-docx Pillow matplotlib 即可在任何 AI 环境中使用。

触发条件

当用户出现以下意图时调用本 skill：

"把这篇论文做成组会汇报 PPT"
"这篇文献帮我整理成汇报 slides"
"研究生组会汇报，按文章脉络来"
上传 PDF 并要求生成汇报演示文稿
"paper report" / "literature presentation" / "journal club slides"

输入契约

输入	必需	说明
文献 PDF	是	研究生文献（论文 / 预印本 / 学位论文），本地路径
汇报场景	否	组会 / 开题 / 中期 / 答辩；默认组会
目标页数	否	固定 17 页（含封面目录），不可更改
语言	否	默认跟随文献语言；中文文献默认中文汇报
侧重	否	IMRaD 均衡 / 问题驱动 / 创新点驱动 / 综述对比；默认均衡
演讲稿	否	是否同步生成完整演讲稿（独立 DOCX 文稿）；默认生成

工作流（S0–S5）

S0 — 意图确认与需求收集

输入：用户对话 + PDF 路径
输出：需求摘要（场景 / 页数 / 语言 / 侧重 + 矢量图处理决策）
脚本：scripts/install_check.py
门禁：⛔ ① 环境自检通过 ② 用户确认需求摘要后进入 S1

S0.1 环境自检（首要步骤）

进入 S0 后第一件事是运行环境自检：

bash

python ${PAPER_REPORT_PPT_DIR}/scripts/install_check.py --json

自检内容：

Python >= 3.8
4 个必需 pip 包：python-pptx、PyMuPDF、python-docx、Pillow（Pillow 用于 PDF 配图反色修复，缺失会导致黑底图问题）
1 个可选 pip 包：matplotlib（公式渲染）

退出码：0=就绪，2=需安装依赖。若退出码为 2，提示用户运行：

bash

pip install python-pptx PyMuPDF python-docx Pillow matplotlib

S0.2 需求收集

收集项：

PDF 路径
汇报场景与目标页数
汇报语言
脉络侧重（IMRaD 均衡 / 问题驱动 / 创新点驱动 / 综述对比）
PDF 中矢量图处理方式（默认不提取；如需保留接受栅格化）
是否同步生成演讲稿（DOCX 格式，默认生成）

矢量图决策：PDF 矢量图（图表 / 流程图）默认不提取。若用户要求保留：栅格化（parse_pdf.py --render-vector-figures，180 DPI）。在 S0 与用户确认。

S1 — 文献解析与素材提取

输入：PDF
输出：
- <work_dir>/<stem>.md（结构化 Markdown，含  标记）
- <work_dir>/<stem>_files/（原样提取的配图 PNG/JPG + image_manifest.json）
- <work_dir>/pages/page_XXXX.txt（逐页文本，长文献检索用）
- <work_dir>/formula_list.json（公式检测清单）
门禁：✅ <stem>.md 与 image_manifest.json 存在

PDF 解析（自包含，仅依赖 PyMuPDF）：

bash

python ${PAPER_REPORT_PPT_DIR}/scripts/parse_pdf.py <pdf_path> -o <work_dir>/<stem>.md

parse_pdf.py 是本 skill 自带的 PDF 解析器。功能包括：标题级别检测、加粗/斜体格式化、列表检测、页眉页脚过滤、图片原样提取（不重采样）、image_manifest.json 生成（字段：filename / sha256 / page_number / pixel_width / pixel_height / caption / figure_number）、基础表格检测、矢量图渲染（--render-vector-figures）。

公式检测：在 <stem>.md 中搜索 LaTeX 数学标记（ $...$ / $$...$$ / $...$ / \[...\]），生成 formula_list.json（每条记录：id / latex / source_page / complexity / render_as）。详细规则见 references/formula-rendering.md。

S2 — 组会汇报脉络大纲生成

输入：<stem>.md + image_manifest.json + formula_list.json
输出：<work_dir>/outline.md（组会脉络页序列）
脚本：scripts/filter_images.py（配图筛选）
门禁：⛔ 用户确认大纲后进入 S3

脉络模板预设

根据 S0 收集的"侧重"方向，从 references/outline-templates.md 选取对应模板。无论选哪个模板，最终 slides.json 的 page_type 序列必须遵循 R1 硬性规则（17页固定结构），区别仅在于 content 页的侧重方向不同：

侧重方向	模板	页数范围	适用场景
IMRaD 均衡	模板 1	17	常规组会汇报（默认）
问题驱动	模板 2	17	紧凑汇报，聚焦"问题→解决"
创新点驱动	模板 3	17	开题/中期/答辩，强调创新
综述对比	模板 4	17	文献综述，横向对比

配图智能筛选与排序

bash

python ${PAPER_REPORT_PPT_DIR}/scripts/filter_images.py <work_dir>/<stem>_files/image_manifest.json --max-per-page 2

输出 image_manifest_filtered.json，包含：

分类：按 caption 语义判断图片类型，自动过滤装饰性小图/logo/二维码
去重：按 sha256 去除重复图片
排序：按章节顺序排列（引言→方法→结果→讨论）
标记：标记图片所属章节

详细规则见 references/image-selection.md。

每页大纲需标注

该页对应文献的章节 / 页码区间
该页应嵌入的配图文件名（从 image_manifest_filtered.json 选取）
该页应嵌入的公式（从 formula_list.json 选取）
关键论点（≤3 条）

S3 — PPTX 生成（自由设计）

输入：S2 的 outline.md + image_manifest_filtered.json + 配图文件
输出：<work_dir>/output.pptx（可编辑 PPTX）
门禁：✅ PPTX 文件存在且可打开

Step 1 — 公式渲染（如有）

bash

python ${PAPER_REPORT_PPT_DIR}/scripts/render_formula.py <work_dir>/formula_list.json <work_dir>/<stem>_files/

公式渲染为 300 DPI PNG（透明背景，自动裁剪白边）。详细规则见 references/formula-rendering.md。

Step 2 — 生成 slides.json

AI 的工作：根据 outline.md，逐页生成结构化 JSON 数据，写入 <work_dir>/slides.json。

这是 AI 唯一需要做的创造性工作——把 outline 中每页的文字内容、配图分配、speaker notes 组织为 JSON 格式。不需要手写 SVG，不需要理解 DrawingML 规范。

参考示例：完整的 17 页 slides.json 示例见 references/example-slides.json，AI 生成时应严格模仿其结构和字段填写方式，确保跨环境一致。

slides.json 格式：

json

[
  {
    "page_num": 1,
    "page_type": "cover",
    "cn_title": "文献精读汇报：<中文论文标题>",
    "en_title": "<English Paper Title>",
    "subtitle": "作者 et al., 期刊, 年份",
    "presenter": "汇报人：研究生组会汇报",
    "date": "2026年7月29日",
    "notes": "今天汇报的文献是..."
  },
  {
    "page_num": 2,
    "page_type": "toc",
    "title": "汇报提纲",
    "sections": ["研究背景", "科学问题", "方法总览", "主要结果", "讨论与创新", "结论与展望"],
    "notes": "本次汇报分为六个部分..."
  },
  {
    "page_num": 3,
    "page_type": "content",
    "title": "研究背景",
    "bullets": ["要点1", "要点2", "要点3"],
    "highlights": [{"title": "知识缺口", "content": "..."}],
    "notes": "首先介绍研究背景..."
  },
  {
    "page_num": 7,
    "page_type": "figure",
    "title": "系统筛选结果",
    "image_path": "figure_1.png",
    "image_caption": "Figure 1: ...",
    "bullets": [],
    "notes": "请看这张图..."
  },
  {
    "page_num": 17,
    "page_type": "qa",
    "title": "感谢聆听",
    "key_message": "Q&A / 欢迎提问",
    "notes": "以上就是本次汇报的全部内容..."
  }
]

page_type 取值：

page_type	用途	必需字段	可选字段
`cover`	封面页	`cn_title`或`title`, `subtitle`	`en_title`, `presenter`, `date`, `notes`
`toc`	目录页	`title`, `sections`(数组)	`notes`
`section`	章节分隔页	`title`	`notes`
`content`	内容页	`title`, `bullets`(数组)	`highlights`, `notes`
`figure`	配图页	`title`, `image_path`	`image_caption`, `bullets`, `notes`
`model`	工作模型页	`title`, `image_path`	`image_caption`, `notes`
`conclusion`	结论页	`title`, `key_message`	`bullets`, `notes`
`qa`	致谢页	`title`	`key_message`, `notes`

Step 2.5 — 验证 slides.json（跨环境一致性检查）

生成 slides.json 后，必须运行验证脚本，确保符合 R1-R7 硬性规则：

bash

python ${PAPER_REPORT_PPT_DIR}/scripts/validate_slides_json.py <work_dir>/slides.json \
  --manifest <work_dir>/image_manifest_filtered.json

退出码 0=通过，1=有错误。有错误时必须修改 slides.json 后重新验证，直到全部通过。 --json 模式可获取机器可读报告，方便 AI 自动解析并修复。

Step 3 — 执行 gen_pptx.py 生成 PPTX

bash

python ${PAPER_REPORT_PPT_DIR}/scripts/gen_pptx.py \
  --input <work_dir>/slides.json \
  --images-dir <work_dir>/<stem>_files/ \
  --output <work_dir>/output.pptx \
  --theme ref

参数说明：

--input：slides.json 路径
--images-dir：配图文件所在目录
--output：输出 PPTX 路径
--theme：默认 ref（深蓝导航栏 + 白色直角卡片 + 海军蓝标题 + 中英文对照封面，对齐参考模板风格）。可选 academic / minimal / trae 通用风格，向后兼容；跨环境一致性建议统一用 ref。

PDF 配图黑底自动修复：部分 PDF 使用 /ImageMask 模板蒙版（1-bit 线稿/工作模型图），被 PyMuPDF 提取后会出现"黑底白线"。parse_pdf.py 已内置反色检测（fix_inverted_image），基于颜色空间元数据（colorspace=0 且 bpc=1 判定为蒙版）自动反色为白底，真实暗背景图（如荧光显微图，RGB 模式）不会被误伤。如需关闭该行为，将 PIL_AVAILABLE 强制为 False 即可。

脚本行为：

读取 slides.json，逐页生成 python-pptx 原生 DrawingML 对象
每页包含：顶部装饰条 + 标题栏 + 内容区 + 底部页码
配图以 preserveAspectRatio 方式完整嵌入，不裁剪
speaker notes 写入每页备注栏
总输出约 300-500 个原生可编辑对象

S4 — 演讲稿生成

输入：slides.json + outline.md + <stem>.md
输出：<work_dir>/output_speech.docx（完整口头演讲文字稿）
脚本：scripts/gen_speech_docx.py
门禁：✅ DOCX 文件存在且包含开场白 + 全部页面讲解 + 结束语

演讲稿与 speaker notes 的区别：

维度	Speaker Notes	演讲稿
定位	PPT 备注栏提示	独立完整文稿
粒度	每页几句要点	连贯叙事，含开场白/过渡语/结尾
长度	每页 50-100 字	全文 3000-6000 字（20 分钟演讲）
用途	演讲时瞄一眼	逐字练习/留存参考

Step 1 — AI 生成 speech_data.json

AI 基于 slides.json 的 notes + outline.md + 文献解析 MD，生成结构化演讲稿内容：

json

{
  "title": "文献汇报演讲稿：<论文标题>",
  "meta": {
    "literature": "作者, 年份, 期刊",
    "scenario": "研究生组会",
    "duration_minutes": 20,
    "date": "2026-07-29"
  },
  "opening": "各位老师同学好，今天汇报的文献是...",
  "sections": [
    {
      "part_title": "第一部分：研究背景",
      "pages": [
        {
          "page_num": "P03",
          "page_title": "研究背景",
          "duration_minutes": 1.5,
          "content": "该页的完整口头讲解文字，200-400字..."
        }
      ]
    }
  ],
  "closing": "以上就是本次汇报的全部内容，感谢大家的聆听...",
  "duration_table": [
    {"part": "开场白", "pages": "-", "duration": "1分钟"},
    {"part": "第一部分", "pages": "P03-P04", "duration": "3分钟"}
  ],
  "tips": ["时长分配建议", "重点强调提示", "可能被提问的预判"]
}

生成规则：

口语化：用"大家看""请注意""这里关键的一点是"等口语引导词
连贯性：每页讲解之间用过渡语衔接
数据口头化：把 PPT 上的数字转化为口头表述
配图引导：配图页必须包含"请大家看这张图"类引导语
时长标注：每部分标注预计时长，总时长与汇报场景匹配
文献对应：关键论点后标注文献位置
问题预判：预判 2-3 个可能被提问的问题

Step 2 — 执行 gen_speech_docx.py 生成 DOCX

bash

python ${PAPER_REPORT_PPT_DIR}/scripts/gen_speech_docx.py \
  --input <work_dir>/speech_data.json \
  --output <work_dir>/output_speech.docx \
  --verbose

DOCX 排版规范：

CJK 字体：Microsoft YaHei（通过 XML eastAsia 属性设置）
标题层级：H1（文档标题）、H2（部分标题）、H3（页面标题）
正文段落：12pt，1.5 倍行距
时长分配表：三列表格（部分 / 页面 / 预计时长），表头浅绿底色 #EDF5E8
页脚：居中页码（第 N 页）
页面尺寸：A4，1 英寸边距

S5 — 交付与质检

输入：PPTX + image_manifest.json + outline.md
输出：交付清单 + 质检报告
脚本：scripts/validate_pptx.py
门禁：✅ 三项质检通过

bash

python ${PAPER_REPORT_PPT_DIR}/scripts/validate_pptx.py <work_dir>/output.pptx \
  --manifest <work_dir>/<stem>_files/image_manifest.json \
  --outline <work_dir>/outline.md

三项质检：

可编辑性核验：用 python-pptx 检查每页 shape 类型分布（textbox / autoshape / picture 计数），确认非整页图片
图片原样核验：提取 ppt/media/ 文件计算 sha256，与 image_manifest.json 的 sha256 比对
脉络一致性核验：提取每页标题文本，与 outline.md 页面标题序列比对

输出 JSON 报告，退出码 0=全部通过，1=有未通过项。

关键约束

1. 文献配图原样不改（三层保证）

层	保证机制	实现位置
提取层	`parse_pdf.py` 直接写 image bytes，不重采样	`scripts/parse_pdf.py`
嵌入层	`gen_pptx.py` 用 `preserveAspectRatio` 完整显示，不裁剪	`scripts/gen_pptx.py`
验证层	`validate_pptx.py` 比对 sha256 确保图片未被修改	`scripts/validate_pptx.py`

2. 可编辑 PPTX 保证

gen_pptx.py 用 python-pptx 直接构建 DrawingML 原生对象：文本→text frame、形状→autoshape、图片→picture，非整页图片插入。每页 15-35 个原生形状，总计 300-500 个。所有文本框可改文字、形状可改属性、图片可替换。

3. 文献配图选取规则

优先选取带 Figure N caption 的配图
每页最多 1–2 张配图，避免信息过载
装饰性小图 / logo 不纳入
详细规则见 references/image-selection.md

4. 跨环境一致性保证（硬性规则）

为确保同一份文献在不同 AI 环境（TRAE / WorkBuddy / Cursor / Qwen 等）中生成结构一致的 PPT，AI 在 S2/S3 生成 slides.json 时必须遵守以下规则。违反任一规则将导致不同环境输出不一致。

R1 — 固定页面结构（17页制）

所有文献统一生成 17 页，page_type 序列固定为：

text

cover(1) → toc(2) → section(3) → content(4) → content(5) →
section(6) → figure(7~13) → section(14) → content(15) →
conclusion(16) → qa(17)

结果图不足 7 张时：figure 页数 = 实际配图数（7~13 页区间弹性），后续页码顺延
结果图超过 7 张时：合并次要图，最多 7 个 figure 页
不允许省略 section 分隔页；不允许在 section 前插入 content 页

R2 — 封面页固定格式

封面页必须同时包含 cn_title 和 en_title，禁止仅使用 title：

json

{
  "page_type": "cover",
  "cn_title": "文献中文标题（完整翻译，不缩写）",
  "en_title": "文献英文原标题（照抄原文）",
  "subtitle": "第一作者 et al., 期刊名, 年份"
}

R3 — 图片路径必须使用 manifest 文件名

image_path 必须直接使用 image_manifest_filtered.json 中该图片的 filename 字段值（不含目录前缀）。

text

正确: "image_path": "JPGR_p6_0.jpeg"
错误: "image_path": "figure_1.png"
错误: "image_path": "/abs/path/to/JPGR_p6_0.jpeg"

禁止自行重命名、使用索引偏移、或编造文件名。

R4 — 一图一页

每个 figure 页只放一张配图。禁止将 Figure 2 和 Figure 3 合并到同一页。如果文献有 9 张图，则生成 7 个 figure 页（合并最次要的 2 张），而非 5 个 figure 页（每页放 2 张）。

R5 — 目录固定四段式

toc 页的 sections 固定为四段，不得自行增减：

json

"sections": ["研究背景与科学问题", "材料与方法", "主要结果", "讨论与结论"]

R6 — bullets 数量与长度

页面类型	bullets 数量	每条最大长度
content	3-4 条	40 个中文字符
figure	2-3 条	40 个中文字符
conclusion	3-5 条	35 个中文字符

R7 — content/figure 页必填字段

content 页必须包含 sub_title 和 conclusion 字段；figure 页必须包含 image_caption 和 sub_title 字段。这些字段直接影响 PPT 美观度，缺失会导致版面空洞。

输出契约

产物	路径	说明
可编辑 PPTX	`<work_dir>/output.pptx`	主交付物
演讲稿	`<work_dir>/output_speech.docx`	完整口头演讲文字稿（DOCX）
质检报告	终端输出 / `--json` 可导出	三项核验结果
组会大纲	`<work_dir>/outline.md`	脉络文档
文献解析	`<work_dir>/<stem>.md` + `<stem>_files/`	素材留档

脚本清单

脚本	功能	依赖
`install_check.py`	环境自检	无
`parse_pdf.py`	PDF → 结构化 MD + 配图提取	PyMuPDF
`filter_images.py`	配图筛选/去重/排序	无
`render_formula.py`	LaTeX 公式 → PNG	matplotlib
`gen_pptx.py`	slides.json → 可编辑 PPTX	python-pptx
`gen_speech_docx.py`	speech_data.json → 演讲稿 DOCX	python-docx
`validate_slides_json.py`	slides.json 跨环境一致性验证	无
`validate_pptx.py`	PPTX 三项质检	python-pptx

跨环境兼容性

本 skill v4.0 为自包含架构，在所有有文件系统的 AI 环境中均可使用：

环境	兼容性	说明
TRAE (SOLO CN / Cloud)	✅ 完全兼容	所有脚本均可在 TRAE 中运行
Claude Code	✅ 完全兼容	仅需 pip install 5 个包
Cursor	✅ 完全兼容	同上
WorkBuddy	✅ 完全兼容	同上
Qwen	✅ 完全兼容	同上
纯对话 Chatbot	❌ 不支持	需要文件系统

安装命令：

bash

pip install python-pptx PyMuPDF python-docx matplotlib Pillow

无 ppt-master 依赖、无 Node.js 依赖、无任何外部 skill 依赖。

paper-report-ppt

Install

Paper Report PPT Skill

触发条件

输入契约

工作流（S0–S5）

S0 — 意图确认与需求收集

S0.1 环境自检（首要步骤）

S0.2 需求收集

S1 — 文献解析与素材提取

S2 — 组会汇报脉络大纲生成

脉络模板预设

配图智能筛选与排序

每页大纲需标注

S3 — PPTX 生成（自由设计）

Step 1 — 公式渲染（如有）

Step 2 — 生成 slides.json

Step 2.5 — 验证 slides.json（跨环境一致性检查）

Step 3 — 执行 gen_pptx.py 生成 PPTX

S4 — 演讲稿生成

S5 — 交付与质检

关键约束

1. 文献配图原样不改（三层保证）

2. 可编辑 PPTX 保证

3. 文献配图选取规则

4. 跨环境一致性保证（硬性规则）

R1 — 固定页面结构（17页制）

R2 — 封面页固定格式

R3 — 图片路径必须使用 manifest 文件名

R4 — 一图一页

R5 — 目录固定四段式

R6 — bullets 数量与长度

R7 — content/figure 页必填字段

输出契约

脚本清单

跨环境兼容性

Related skills