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"

---

输入契约

---

工作流（S0–S5）

S0 — 意图确认与需求收集

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

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

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

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，提示用户运行：

pip install python-pptx PyMuPDF python-docx Pillow matplotlib

S0.2 需求收集

收集项：

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

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

---

S1 — 文献解析与素材提取

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

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

python ${PAPER_REPORT_PPT_DIR}/scripts/parse_pdf.py  -o /.md

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

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

---

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

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

脉络模板预设

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

配图智能筛选与排序

python ${PAPER_REPORT_PPT_DIR}/scripts/filter_images.py /_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 + 配图文件
• 输出：/output.pptx（可编辑 PPTX）
• 门禁：✅ PPTX 文件存在且可打开

Step 1 — 公式渲染（如有）

python ${PAPER_REPORT_PPT_DIR}/scripts/render_formula.py /formula_list.json /_files/

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

Step 2 — 生成 slides.json

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

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

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

slides.json 格式：

[
  {
    "page_num": 1,
    "page_type": "cover",
    "cn_title": "文献精读汇报：<中文论文标题>",
    "en_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 取值：

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

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

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

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

Step 3 — 执行 gen_pptx.py 生成 PPTX

python ${PAPER_REPORT_PPT_DIR}/scripts/gen_pptx.py \
  --input /slides.json \
  --images-dir /_files/ \
  --output /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 + .md
• 输出：/output_speech.docx（完整口头演讲文字稿）
• 脚本：scripts/gen_speech_docx.py
• 门禁：✅ DOCX 文件存在且包含开场白 + 全部页面讲解 + 结束语

演讲稿与 speaker notes 的区别：

Step 1 — AI 生成 speech_data.json

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

{
  "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": ["时长分配建议", "重点强调提示", "可能被提问的预判"]
}

生成规则：

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

Step 2 — 执行 gen_speech_docx.py 生成 DOCX

python ${PAPER_REPORT_PPT_DIR}/scripts/gen_speech_docx.py \
  --input /speech_data.json \
  --output /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
• 门禁：✅ 三项质检通过

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

三项质检：

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

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

---

关键约束

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

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 序列固定为：

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：

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

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

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

正确: "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 固定为四段，不得自行增减：

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

R6 — bullets 数量与长度

R7 — content/figure 页必填字段

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

---

输出契约

---

脚本清单

---

跨环境兼容性

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

安装命令：

pip install python-pptx PyMuPDF python-docx matplotlib Pillow

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