pdf-to-pptx-omml
从 PDF 教材/讲义提取章节内容生成专业 PPTX(正文 20pt/行距 1.4/Times New Roman,公式转 OMML 在 PowerPoint 中完全可编辑,图表按 caption 自动定位裁剪 300dpi 原图)。适用 AoPS/IB/Cambridge/国内理工教材等 → 课件转换。触发词:教材提取 PPT、OMML 公式、章节转课件、PDF to PPTX、课件制作。先跑 probe 免费诊断,再按推荐管线执行。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 19 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/GongfaChen/pdf-to-pptx-omml with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/GongfaChen/pdf-to-pptx-omml'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/gongfachen--pdf-to-pptx-omml)HTML
<a href="/listings/gongfachen--pdf-to-pptx-omml"><img src="/api/listings/gongfachen--pdf-to-pptx-omml/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 127 lines
- ---
- name: pdf-to-pptx-omml
- description: 从 PDF 教材/讲义提取章节内容生成专业 PPTX(正文 20pt/行距 1.4/Times New Roman,公式转 OMML 在 PowerPoint 中完全可编辑,图表按 caption 自动定位裁剪 300dpi 原图)。适用 AoPS/IB/Cambridge/国内理工教材等 → 课件转换。触发词:教材提取 PPT、OMML 公式、章节转课件、PDF to PPTX、课件制作。先跑 probe 免费诊断,再按推荐管线执行。
- ---
- # PDF 教材 → PPT(OMML 可编辑公式)工作流
- 环境:Windows + Python(pymupdf / python-pptx / lxml / pillow / pdfplumber / pywin32)+ 本机 PowerPoint 或 WPS。
- 所有脚本在 `scripts/`,实战坑总表在 `references/pitfalls.md`(执行前必读对应类别)。
- ## 流程总览
- ```
- 前置 A(环境闸)→ probe(诊断)→ 定位章节 → 裁图 → 构建 PPTX → 静态校验 → COM 导出 PDF → 版式审计 → 交付
- ```
- ## 前置 A · 环境闸(scripts/check_env.py)
- 开工先跑只读环境闸,确认依赖矩阵与 COM 闸能不能跑(不打开 PowerPoint、不导出、不修改任何文件):
- ```bash
- python scripts/check_env.py
- ```
- 输出:7 项依赖(fitz/pptx/lxml/PIL/pdfplumber/win32com/pythoncom)的 OK/MISSING 矩阵与缺失项安装命令、
- PowerPoint/WPS COM ProgID 是否注册,以及闸 2(公式原生渲染核验)的结论。命名「前置 A」是为了不与下面的「第 0 步 · probe 诊断」撞号。
- - **有 COM**(pywin32 + PowerPoint/WPS 均可用):闸 2 可执行,交付前必须 `pres.SaveAs(pdf, 32)` 并核验 CambriaMath 字形 / 无 `[formula]` 占位。
- - **无 COM**:闸 2 不可执行 → **公式渲染未验收**,不得据此宣布通过或交付;LibreOffice 等只认 `mc:Fallback` 的渲染器导出的 PDF 禁止作为交付物(与下方「诚实边界」一致)。
- ## 第 0 步 · probe 诊断(只读,先判管线)
- ```bash
- python scripts/probe_pdf.py <教材.pdf> --report 诊断.md
- ```
- 报告给出:每页有无文本层(文字层/扫描版/OCR 可疑)、嵌入位图数、caption 命中数、
- 数学符号密度、单/双栏、装订线页。据此选管线:
- | 诊断结果 | 管线 |
- |---|---|
- | 全书文字层 | 原生管线:caption 文本块定位 + clip 渲染裁图 |
- | 大量扫描页 | 扫描管线:按页码渲染逐页视觉确认,公式目视转录 |
- | OCR 可疑页多 | 混合管线:正文用文本层,**公式一律以渲染页目视为准**(坑 40) |
- ## 第 1 步 · 定位章节页码
- - `pymupdf` 搜索各节标题 + 下一章标题确定页码范围,dump 全文通读。
- - **注意 `p.number` 是 0-based**(坑 9);核对用页面文本匹配,不靠记忆页码。
- - 扫描版无文本层:按用户给的页码渲染页面(1-based)视觉确认。
- ## 第 2 步 · 裁剪图表
- 直接调用 `scripts/crop_figures.py`(把坑 16/28/41/42 的裁图规则固化成 CLI,只读 PDF,产出 `assets/` + `preview/` + `crop_report.md`):
- ```bash
- python scripts/crop_figures.py <教材.pdf> --out <目录> [--dpi 300] [--cols 4]
- ```
- 规则链(脚本内已实现,无需手写):
- - **xref 位图优先**:`get_image_info(xrefs=True)` 拿 bbox,按 xref 原分辨率提取(坑 16);同 bbox 另渲染一张 300dpi clip 作对照。
- - **caption clip**:矢量/文字页用带标点的严格 caption 匹配(坑 41)定位,clip 渲染 300dpi PNG。
- - **prose 三判据**(坑 28):`prose_ratio ≥ 0.86` + `longest_word ≥ 4` + `y1 ≥ 58`,命中即判为正文并跳过该裁剪(「混入正文的重裁」);区域无矢量绘图/位图也跳过。
- - **双栏**:按中缝分左右栏定裁剪框(坑 28)。
- - **装订线**:像素级扫描边缘饱和色竖线,裁剪 x0 移到线右侧(坑 42);PIL 差分白边 trim 兜底。
- 拼图用 `scripts/contact_sheet.py`(也可单独跑,或由 `crop_figures.py` 在裁图末尾自动调用),输出 `preview/contact_sheet.png` 逐张视觉校验:
- ```bash
- python scripts/contact_sheet.py <assets目录|图片...> --out preview/contact_sheet.png [--cols 4]
- ```
- ## 第 3 步 · 构建 PPTX(omml_helpers)
- 用 `scripts/omml_helpers.py` 构造公式,**不要手写 OMML XML**——库已把坑 1/3/6/10/11/12/35 在 API 层堵死
- (裸 str 自动包 T()、空基底抛错、a14 命名空间自动声明、无 m:acc/supHide)。用法见 `references/omml-cookbook.md`。
- - **大运算符 / 方程组**:`SUM(sub, sup, body)`、`PROD(sub, sup, body)`(m:nary,∑/∏ 上下限必须同时给,坑 12)、`EQARR(*rows)`(左对齐方程组 m:eqArr,不套 `m:d`;列向量仍用 `CV`,坑 34)。示例见 cookbook。
- - **每份 deck 前调 `reset_run_style()`**:`set_run_style()` 写的是模块级全局,size/color/font 传 `None` 只表示「不修改」而非「清空」,连续构建多份 deck 会串味;重置回出厂默认后再设本 deck 样式。
- - **helper 片段拼接一律用 `M(...)`,不要用 `+`**(坑 45):`_Frag` 是 str 子类,`T('a') + T('b')` 曾退化成普通 str 被下游当裸文本包 `T()` 转义,公式显示成 XML 字面文本;库已重载 `__add__/__radd__` 修好,但 `+` 跨版本不稳且 `validate_omml.py lint` 会报,统一用 `M(...)`。
- 规格:16:9(13.333×7.5in);正文 Times New Roman 20pt / line_spacing=1.4;
- display 公式**独占段落且行距 1.0**(坑 13/15);浅色 shape 里公式必须显式设深色(坑 18)。
- 行高预算(坑 24):正文 ≈33.9pt/行;无分数 display ≈1.0 行,含分数 ≈1.7 行;
- 每行字符数 ≈ 宽度(in)×72/8.7。溢出修法优先级:合并公式行 > 精简文案 > 拆页;**禁止全局缩字号**。
- - **带上下限 / 多行的「大结构」必须 `display=True` 独占段落**(坑 13/24/34):`SUM`/`PROD`(m:nary 上下限)、`EQARR`/`CV`/`MX`(多行结构)不要内联 `display=False` 塞进正文行——smoke demo 实测 EQARR 内联导出后被挤压、贴住相邻文字,`collisions=0` 但稿件难看。
- 行高预算把这一行按 **1 行** 算(无分数 display ≈1.0 行,坑 24),而大结构实际要 ≈1.3–1.7 行(两行向量 ≈1.3 行、三行 ≈1.7 行,坑 34;含分数 ≈1.7 行,坑 24)→ 垂直溢出/挤压。若确实要行内表达,退化为单个符号(如 `∑` 或 `a_i`),而不是整段 nary/eqArr。
- ## 第 4 步 · 校验闭环(三道闸,缺一不可)
- ```bash
- # 闸 1:静态校验(不打开 PowerPoint,先扫低级错误)
- python scripts/validate_omml.py check <成品>.pptx
- python scripts/validate_omml.py lint build_ppt.py # 构建脚本源码自伤扫描
- # 闸 2:COM 导出 PDF + 字形级审计
- # PowerPoint: pres.SaveAs(pdf, 32)(公式原生渲染,一个 PDF 同时核验版式+公式)
- # 失败备选:WPS COM DispatchEx('KWPP.Application') Slides(i).Export(...)(导出路径纯 ASCII)
- python scripts/audit_layout.py <导出的.pdf> --footer "<页脚文案>" --skip-pages 1 --report 审计.md
- # 闸 3:contact sheet 目视(审美问题:对齐/留白/图位置)
- ```
- 审计目标:collisions=0 / overflow=0 / footer=1(跳过页除外),迭代到全零。
- ## 交付物
- ```
- <项目目录>/
- 诊断.md # probe 报告
- ch<N>_text.txt # 章节全文
- crop_figures.py # 裁图脚本
- build_ppt.py # PPT 构建脚本(omml_helpers)
- assets/fig*.png # 300dpi 裁剪图
- preview/ # contact sheet
- <名称>.pptx # 最终交付
- ```
- ## 诚实边界
- - 扫描版页的公式为目视转录,需人工核对;OCR 文本层的公式串一律不信(坑 40)。
- - 表格结构不自动还原,仅保证阅读顺序;加密 PDF 不处理。
- - mc:Fallback 在只认 Fallback 的渲染器(如 LibreOffice)里会替换整段内容——交付前必须走完闸 2 的 PowerPoint 原生渲染核验。
- - 环境依赖本机 PowerPoint(或 WPS)COM;Linux/macOS 无 COM 时闸 2 无法执行,**公式渲染未验收**,不得据此宣布通过或交付。LibreOffice 等只认 mc:Fallback 的渲染器仅可用于版式粗看,其导出的 PDF 禁止作为交付物。
README.md · README · 157 lines
- # pdf-to-pptx-omml
- [](https://github.com/GongfaChen/pdf-to-pptx-omml/releases)
- [](https://github.com/GongfaChen/pdf-to-pptx-omml/actions/workflows/ci.yml)
- [](LICENSE)
- [](https://www.python.org/)
- [](README.md)
- **把 PDF 教材章节变成公式完全可编辑的 PPT**——公式转 OMML(PowerPoint 原生数学对象,双击就能改),
- 不是截图、不是图片。图表按 caption 自动定位、300dpi 原图裁剪,版式经字形级审计闭环保证不压字、不溢出。
- > 适用:AoPS / IB / Cambridge / 国内理工科教材与讲义 → 课件。
- > 目标用户:高校教师、教研团队、课件制作者、辅导机构。
- ## 效果演示:真实教材 before / after
- **Before** —— AoPS Precalculus 第 6.2 节教材原页(p.200,Problem 6.11–6.12,公式与图形混排):
- 
- **After** —— 同一节内容提取成的课件。所有公式(根号、上标、绝对值、下标)
- 均为 **原生 OMML**:双击即可编辑,可改字体、可复制进 Word/LaTeX,不是截图、不是图片。
- 
- 
- > 注:教材页面截图仅作效果展示,版权归 AoPS 所有;工具只处理用户自有的文件。
- ## 为什么不是"又一个 PDF 转 PPT 工具"
- 市面上工具把公式变成图片或乱码。本项目积累了一条 **45 条实战坑**打磨出的流水线
- (`references/pitfalls.md`),并把它封装成三层护栏:
- | 层 | 工具 | 拦截什么 |
- |---|---|---|
- | API 层 | `scripts/omml_helpers.py` | 裸文本塞公式、空基底、命名空间错位、禁用结构(m:acc / supHide)——写错当场抛异常 |
- | 静态层 | `scripts/validate_omml.py` | 解包 pptx 逐 slide 扫描转义 XML / 空元素 / 裸文本 / oMathPara 混排 + 构建脚本 lint |
- | 渲染层 | `scripts/audit_layout.py` | 对 PowerPoint 导出的 PDF 做字形级碰撞(阈值 0.40)、内容溢出、页脚计数三件套审计 |
- 公式示例(构建出来的全部是可编辑 OMML):分数、上下标、根号、limLow 定积分、
- 列向量/矩阵(m:eqArr / m:m)、范数 ‖v‖、定界符。
- ## 快速开始
- ```bash
- # 依赖(Python 3.12+;渲染核验需 Windows + 本机 PowerPoint)
- pip install -r requirements.txt
- # 1. 环境自检:构建一个含全套公式类型的 PPTX,验证 PowerPoint 能打开
- python demo/smoke_test.py
- # 2. 诊断你的教材(只读,免费)
- python scripts/probe_pdf.py <教材.pdf> --report 诊断.md
- # 3. 按 SKILL.md 工作流执行(probe → 裁图 → 构建 → 三道闸校验)
- ```
- ## 仓库结构
- ```
- SKILL.md # Agent 技能主文件(工作流 + 管线判定)
- SECURITY.md # 安全策略与漏洞报告渠道(私密 Advisory)
- requirements.txt # 依赖(含 pywin32 的 Windows 平台标记)
- scripts/
- probe_pdf.py # PDF 可提取性诊断(只读):文本层/扫描页/OCR 可疑/图数/公式密度/栏式
- omml_helpers.py # OMML 构造库:T/F/S/Q/SQ/RAD/LIM/PAR/ABS/CV/MX/NORM/M + SUM/PROD/EQARR
- validate_omml.py # 静态校验器:pptx 体检 + 源码 lint
- audit_layout.py # 版式审计:字形碰撞 / 溢出 / 页脚三件套
- check_env.py # 前置环境闸(只读):依赖矩阵 + COM ProgID + 闸 2 可执行性判定
- crop_figures.py # 裁图 CLI:xref 位图优先 / caption clip / prose 三判据 / 双栏 / 装订线
- contact_sheet.py # 拼图:带标签 contact sheet(crop_figures.py 末尾自动调用)
- license_check.py # 许可证钩子(Ed25519 验签,当前免费全通过,见下文)
- references/
- pitfalls.md # 45 条实战坑(按类别索引)——本仓库的核心资产
- omml-cookbook.md # helper 用法手册与反模式清单
- demo/
- smoke_test.py # 一键环境自检
- assets/ # README 效果演示截图(before / after)
- .github/
- workflows/ci.yml # CI:self-check + lint + 构建 + 静态校验 + probe(Linux,无 COM)
- ISSUE_TEMPLATE/ # bug / feature 表单(含环境信息与自检要求)
- ```
- ## 工作流总览
- ```
- probe 诊断 ──→ 定位章节 ──→ 裁图(xref 位图优先 / caption+clip 矢量)
- │
- ▼
- build_ppt(omml_helpers 构建公式)
- │
- ┌─────────────────┼─────────────────┐
- ▼ ▼ ▼
- validate check COM 导出 PDF contact sheet
- (静态扫低级错误) audit 三件套审计 (目视审美兜底)
- └────── 全零后才交付 ──────┘
- ```
- ## 诚实边界
- - 扫描版页的公式为**目视转录**,交付后需人工核对;OCR 文本层里的公式串一律不可信。
- - 表格结构不自动还原(保证阅读顺序);加密 PDF 不处理。
- - 渲染核验依赖本机 PowerPoint(或 WPS)COM;Linux/macOS 可构建,但缺少自动审计闭环——**无 COM 即公式渲染未验收**,不得据此宣布通过或交付。LibreOffice 等只认 mc:Fallback 的渲染器仅可用于版式粗看,其导出的 PDF 禁止作为交付物。
- - probe 报告只做只读诊断,不猜、不脑补提不出来的内容。
- ## 路线图
- - [x] v0.1 开源核心:probe + OMML helper 库 + 双校验器 + 审计脚本
- - [x] v0.2 护栏补强:坑 45(`_Frag` 拼接退化)、结构感知 fallback、SUM/PROD/EQARR、环境闸 `check_env`、裁图 CLI、公式渲染断言
- - [x] v0.3 许可证钩子:纯 Python Ed25519(RFC 8032)、keygen / issue / verify CLI、`.gitignore` 挡私钥
- - [x] v0.3.1 许可安全加固:环境公钥仅 dev 模式、小阶公钥拒绝、`PAID_FEATURES` 分层、RFC 8032 签名向量、闸门移到 argparse 之后
- - [x] CI:GitHub Actions(Linux × Python 3.12/3.13,10 步静态校验 + 构建 + probe)
- - [ ] 批量章节模式(一次跑整本书,断点续跑)
- - [ ] 多模板(学术蓝 / 极简黑白 / 学校 VI)
- - [ ] 英文教材双语注释页自动生成
- - [ ] 商业化:免费 probe + 按章付费解锁生产级流水线(支付宝 AI 付 A2M/402,评估中)
- > 版本对应:v0.1→`3de474f`,v0.2→`7d6ff38`,v0.3→`efdbcdf`,v0.3.1→`2d6f4eb`(tag 早于 CI/`requirements.txt`,
- > 直接从 `main` 克隆可获得完整工程化文件)。
- ## License / 授权
- 代码以 MIT 开源。`scripts/license_check.py` 是为未来付费层预埋的**许可证钩子**,
- 当前对用户完全透明。分层用两个集合表达,切换时只改集合,不改逻辑:
- | 层 | 集合 | 现在的内容 | 无 license 时的行为 |
- |---|---|---|---|
- | 永久免费 | `FREE_FEATURES` | `probe` | 放行 |
- | 免费(开源层) | 其余非付费 feature | `core`(构建/校验/审计/裁图) | 放行 |
- | 付费(预留) | `PAID_FEATURES` | **空** | 退出码 1 并提示获取 license |
- - **现在**:`PAID_FEATURES` 为空,所以不放 license 也一切可用;各 CLI 入口在
- `parse_args()` 之后调用 `require_license(feature)`,无 license 时静默放行。
- - **将来**:把付费 feature(如 `pipeline`)加入 `PAID_FEATURES` 即可生效;存在
- license 且公钥已配置时走严格 Ed25519 验签(签名 → 产品 → 有效期 → 功能范围)。
- - **换钥**:`--generate-keys` 生成密钥对(私钥**不进仓库**)→ 替换模块内
- `PUBLIC_KEY_HEX` 后重新发布。环境变量 `PDF2PPTX_OMML_PUBKEY` **只在开发模式**
- (`PDF2PPTX_OMML_DEV=1`)生效并打印警告;发布构建会忽略它——否则任何人都能
- 换成自己的公钥自签 license,付费闸形同虚设。
- - **实现与性能**:纯 Python RFC 8032(零第三方依赖),实测校验 **152–163 ms/次**(约 0.16 s);
- 故意不做结果缓存——缓存文件用户可写,等于给付费闸开后门。
- 全链路自检:`python scripts/license_check.py --self-test`
- (含 RFC 8032 公钥/签名向量、篡改/过期/越权、免费模式、小阶公钥拒绝)。
- `license_check.py --verify` 退出码:
- | 码 | 含义 |
- |---|---|
- | 0 | 通过(免费模式或有效 license;用 `status: FREE` / `status: OK` 区分) |
- | 1 | 未找到 license 文件(免费模式,非错误)/ 付费功能被拒 |
- | 2 / 3 / 4 / 5 / 6 / 7 | 签名无效 / 已过期 / 产品或功能不符 / 格式损坏 / 机器绑定不符 / 内部错误 |
- > 素材说明:`assets/` 下的教材页截图版权归 AoPS 所有,仅作效果展示,**不在 MIT 授权范围内**;
- > 工具本身只处理用户自有或已获授权的文件。详见 `assets/README.md`。
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.