作者：吴振谦 · wuzhenqian@nbu.edu.cn · QQ：38328063
开发原因：高校教师在课程建设与教材建设中，长期面临「课件里的大量图片、公式、文本散落各处，难以整理为规范、可复用、图文并茂的教学资源」的痛点——手工整理一份课程的图文知识库往往要耗费数周。本工具把 PPT 自动转化为图文并茂的多模态教学知识库，让教师从机械整理中解放出来。
版本：当前 3.1.2（历经理念重构：v1.5 六步管线 → v2.0 十六规则落地 → v2.3 整篇分章分节 → v2.6 预览图判定/公式双通道 → v3.0 全链路提速+实时打印 → v3.1 WPS 渲染+按需视觉兜底）。
输入一份教学 PPT（.pptx），自动完成 8 环节流水线：
DEEPSEEK_API_KEY（语义解读/教材文案）、DASHSCOPE_API_KEY（qwen VLM 兜底）pip install pptx-wzqhttps://github.com/wuzhenqian6611/pptx-wzqpython -c "from pptx_wzq import docs; print(docs.__path__)"# 一条命令跑完 8 环节（推荐） pptx-paser "C:\课件\战略管理.pptx" -o "C:\输出\战略管理知识库" # 只跑图块+文本+公式+解读（跳过相关性与文案，省 Token） pptx-paser "C:\课件\战略管理.pptx" -o out --skip related,author # 断点续传（中断后重跑同命令即可自动接续） pptx-paser "C:\课件\战略管理.pptx" -o out # 单步命令（叶子工具） pptx-blocks out --pptx "战略管理.pptx" --texts out\战略管理_texts.md --no-vlm pptx-author --texts out\战略管理_texts.md --formulas out\战略管理_formulas.md --captions out\战略管理_captions.md -o out\战略管理_textbook.md
| 命令 | 功能 |
|---|---|
pptx-paser | 总编排器：8 环节一条命令跑完，断点续传/成功清理 |
pptx-blocks | 图块提取+解构+渲染；--caption-sources 模式按 sources/ 顺序解读 |
pptx-text | 文本提取（in_group/表格 Markdown） |
pptx-formula | 公式提取 → LaTeX |
pptx-caption | 图片/图块解读（模型路由） |
pptx-related | 块相关性过滤 + 审计 |
pptx-author | 整篇分章分节教材文案（500 字为限） |
pptx-bind | 图文绑定 JSON |
pptx-html / pptx-deck | 教材 HTML / 教学 Deck 导出 |
| 对象 | 预处理操作 | 解析器行为 |
|---|---|---|
| 逻辑图/示意图 | Ctrl+G 把底图+文字+箭头合成一个组合 | 整体 = 1 个 group 块，XML 段导出 sources/，渲染图存 images/ |
| 嵌套组合 | 有意为之才用；想分开就移出外层 | 并入外层 children，不单独成块 |
| Visio/vsdx | 不要组合进其他形状；保持独立 OLE | 独立 visio 块：可剥离 .vsdx / 不可剥离 XML 段 |
| 公式 | 行内公式保持独立；想并入图块就移进组合 | 组合内随块转 LaTeX；非组合进 formulas.md |
| 首页/尾页 | 无需操作（默认跳过图块） | 封面/致谢不产块（文本/公式仍提取） |
| 小像素图 | <20% 页面默认舍弃；想保留 → 组合进相邻图形 | 组合内豁免；非组合丢弃入审计 |
| 表格 | 无需操作 | Markdown 表格输出（texts.md） |
| srcRect 裁剪图 | 无需操作（自动一致） | 元数据/资源/渲染/描述全程按裁剪 |
| 问题 | 说明 |
|---|---|
| 没有 Office 会怎样？ | 渲染降级：无块渲染图（images/ 为空）；XML/JSON/文案等其余产物正常。 |
| 没有 API Key？ | 跳过对应解读/文案步骤；PPTX_PASER_NO_VLM=1 可跳过 VLM 全流程 0 Token。 |
| 中途中断？ | 重跑同命令自动接续（state.json + doc_md5 换源检测）。 |
| DeepSeek 对某 XML 段空响应？ | 自动降级 qwen 读渲染图 → 规则模板兜底，保证每块有解读。 |
| 如何查安装版本与文档？ | pptx-paser --version；from pptx_wzq import docs。 |
把任意 PPT 课件解构为「多模态教学知识库」：文本/公式/图块三路抽取 + AI 解读 + 教材级文案，输出 JSON/Markdown/渲染图三件套。
OOXML 原生解析 + DeepSeek-V4-Flash（语义/文案）+ qwen3.7-plus（VLM 兜底）+ PowerPoint/WPS COM 渲染（ProgID 自动探测）。
sources/ + images/ + visual_blocks.json + binding + textbook.md + captions.md。
| 模块 | 职责 | Token |
|---|---|---|
extract_pptx_images.py | OOXML 原子对象提取（图片/形状/grpSp/表格/公式/图表）；XML 段原生提取；srcRect 裁剪；OLE 预览图判定（preview_of）；PowerPoint/WPS COM 渲染（ProgID 探测 + DispatchEx） | 0 |
extract_texts.py | 页面文本（in_group 标记）、表格 Markdown | 0 |
visual_blocks.py | 单阶段确定性拆块、块渲染、语义增强、跨模态关系 | DeepSeek |
cli_blocks.py | XML 段导出、rldimg 复制、caption 路由、binding、captions.md | DeepSeek+qwen |
cli_author.py | 整篇分章分节文案、500 字为限、自动分批 | DeepSeek |
cli_related.py | 相关性过滤 + 审计 | DeepSeek |
cli_paser.py | 总编排、断点续传、归位、成功清理 | — |
pptx-paser / pptx-blocks / pptx-text / pptx-formula / pptx-caption pptx-related / pptx-author / pptx-bind / pptx-html / pptx-deck
| # | 规则 | 实现 |
|---|---|---|
| 1 | 一个 grpSp 组合即是一个图块，组合内一切内容读取为该图块内容 | kind="group"，children 递归收编 |
| 2 | 嵌套组合不单独提取 | 嵌套仅作外层 children |
| 3 | OLE Visio/vsdx 独立成块（除非在组合内） | kind="visio" 分支 |
| 4 | 非组合像素图单独成块；重叠文本并入 | raster 独立块 + 重叠文本并入 |
| 5 | 组合内公式作块内容；非组合公式独立提取 | formula 排除 in_group |
| 6 | 首页/尾页图块舍弃 | skip_cover_pages 整页跳过 |
| 7 | 非组合像素图 < 整页 20% 舍弃 | raster_min_area_ratio=0.20 |
| 8 | 表格仍读取为表格（Markdown） | 表格移交 text 步骤 |
| 9 | grpSp 内 srcRect 须全程一致 | children 携带 src_rect + 裁剪落盘 |
| # | 规则 | 实现 |
|---|---|---|
| 10 | grpSp 保留整段 XML，页标记，每组合一个独立 .xml 存 sources/ | sources/slide_{页}_{块id}_grp.xml |
| 11 | grpSp 块 caption 用 DeepSeek 读 XML；公式转 LaTeX | _ds_read_xml + 超长压缩 + 重试 |
| 12 | grpSp 块 PowerPoint 渲染 PNG 存 images/；PNG 不送 qwen | COM ExportAsFixedFormat + PyMuPDF |
| 13 | Visio 可剥离 → .vsdx 存 sources/ + PNG 存 images/ | 原生剥离 + 渲染 |
| 14 | Visio 不可剥离 → XML 段，同 grpSp | sources/slide_{页}_{块id}_ole.xml |
| 15 | SVG/WMF 同 Visio：尽量 XML 段，不行才 PNG | sources/slide_{页}_{块id}_vec.xml |
| 16 | 仅无法 DeepSeek 解读的块才送 qwen | 模型路由 + 空响应降级链 |
{
"block_id": "blk_01", "page": 7, "block_type": "战略管理概念框架",
"bbox": {"x": 142.3, "y": 226.4, "w": 1026.2, "h": 400.2},
"assets": {"xml_source": "./sources/slide_07_blk_01_grp.xml",
"raster_png": null,
"rldimg": ["./sources/rldimg/slide_07_blk_01_image4.png", "…"]},
"internal_structure": {"nodes": ["…"], "edges": ["…"]},
"semantic_description": {
"block_type": "战略管理概念框架",
"expression_goal": "展示战略管理概念框架的核心逻辑",
"expression_role": "将抽象概念通过战略哲学/商道/天道/人道具象化…",
"expression_features": ["概念框架", "层次结构", "关系图"],
"vlm_caption": "该图块以“战略哲学”为中心…",
"teaching_use": "教学辅助图示",
"formula_latex": "", "caption_source": "deepseek_xml"
},
"member_obj_ids": ["…"], "vector_resources": []
}
| 版本 | 里程碑 |
|---|---|
| 1.5.0 | 六步管线重构、三件套交付物、版本统一 |
| 2.0.0 | 16 条规则落地、组合即块、XML 段导出、DeepSeek caption 路由、PowerPoint 渲染 |
| 2.1.0 | captions 绑定 sources/ + 通道标注；每页扩写 500 字 |
| 2.2.0 | textbook 500 字为限（不足扩写、超出直出整理） |
| 2.3.0 | Author 整篇自主分章分节，每页标注章节 |
| 2.4.0 | 技术分析报告（html/pdf/md）随安装包分发 |
| 2.5.0 | 使用手册+技术分析合并文档、README 全量更新 |
| 2.5.1 | 渲染静默降级修复（dependencies 补 pymupdf）；渲染失败明确警告 |
| 2.5.2 | images/ 不再被 caption/blocks_json 清空（--skip-render）；DispatchEx 独立实例 |
| 2.6.0 | OLE 预览图判定（preview_of，vector 块 63→0）+ 组合内公式进 formulas.md |
| 3.0.0 | 语义增强提速（去 thinking + 并发，10 倍）+ 模型调用实时打印（[DeepSeek]/[qwen]） |
| 3.0.1 | related 并发提速（162 倍）+ 正文为空保守保留（防误删） |
| 3.0.2 | 渲染 Open 失败根因：pptx 强制 resolve 绝对路径 + 错误完整显示 |
| 3.1.0 | WPS 渲染支持（ProgID 自动探测 PowerPoint/Kwpp + 简化参数回退） |
| 3.1.1 | qwen 视觉兜底按需触发（仅 caption 未解读块）+ 图路径接通 images/ |
| 3.1.2 | 文档体系更新：README/使用手册/技术分析同步 3.0.x~3.1.x 全部变更 |