把现有
.pptx反编译为真正可编辑的 HTML、结构化 Artifact IR，以及一整套可复现的质量证据。
pptx-html-decompiler 不是截图导出器，也不是 AI PPT 生成器。它面向一个更底层的问题：
如何把 PPTX 中的文本、形状、图片、表格、图表和版式关系，转换成浏览器里仍然可选择、可编辑、可审计的对象？
核心链路：
PPTX / OOXML
↓
语义解析与继承解析
↓
Artifact IR
↓
可编辑 HTML / SVG / DOM
↓
视觉、结构、文字、可编辑性与便携性 QA
常见的 PPT/PDF → HTML 产品会把页面拆成背景图和绝对定位文字。它们可以“看起来很像”，但表格不再是表格，图表不再是图表，形状也无法可靠编辑。
本项目选择更难、但更有长期价值的路线：
- 保留对象边界，而不是整页截图；
- 保留文本段落、富文本、表格单元格和图表数据；
- 保留源 OOXML、关系 ID 和对象 ID 等 provenance；
- 同时输出视觉相似度和结构化 QA，不用一个平均分掩盖缺字、裁切或对象丢失；
- 遇到暂不支持的能力时明确报告，不静默降级。
一次转换会输出：
| 文件 | 用途 |
|---|---|
index.html |
可编辑、可检查的完整 HTML 版本 |
standalone.html |
内联本地资源、可独立移动的单文件版本 |
artifact.json |
面向程序、Agent 和编辑器的 Artifact IR |
conversion-report.json |
对象覆盖、兼容性、OCR、字体和降级诊断 |
quality-report.json/.md |
全部 QA 阶段的总报告 |
visual-qa/contact-sheet.png |
原始渲染、HTML 渲染和差异图的逐页对照 |
editable-dom-audit-report.json |
HTML 不是整页截图的结构证明 |
text-render-audit-report.json |
浏览器文字溢出、字体回退和行框证据 |
text-metric-audit-report.json |
参考文本行与 HTML 文本行的匹配证据 |
standalone-audit-report.json |
单文件 HTML 的资源解码与便携性证明 |
HTML 还支持单页清洁模式：
index.html?slide=3&clean=1
standalone.html?slide=3&clean=1
git clone https://github.com/Mijiang111/pptx-html-decompiler.git
cd pptx-html-decompiler
npm install完整 Visual QA 需要：
- LibreOffice：渲染 PPTX 兼容性参考；
- Poppler：PDF 渲染与文本框提取；
- Chromium：HTML 截图和 DOM 审计。
安装 Playwright Chromium：
npm run setup:visual如果暂时不需要图片 OCR，可以先运行：
npm run convert:qa -- ./input.pptx \
--out ./out/demo \
--skip-ocr转换指定页面：
npm run convert:qa -- ./input.pptx \
--out ./out/demo-first10 \
--slides 1-10 \
--skip-ocr只做转换、不运行完整 QA：
npm run convert -- ./input.pptx --out ./out/demoOCR 使用 PaddleOCR。需要时安装：
npm run setup:ocr
npm run convert:qa -- ./input.pptx --out ./out/demo- 段落、富文本 run、项目符号、编号、缩进和段落间距；
- 文本框内边距、垂直对齐、换行和 autofit 元数据；
- slide / layout / master 占位符与默认文本样式继承；
- CJK 与 East Asian 字体证据、字体回退和 Wingdings 符号归一化；
- 浏览器实际行框、溢出、裁切和参考文本行对比。
- 基础形状、组合、嵌套变换、旋转与翻转；
- 透明度、渐变、图案填充、虚线和箭头；
- 常用 DrawingML preset geometry；
- 自定义几何路径和 SVG 渲染；
- 可编辑的线条、连接符和 SmartArt 子对象。
- 行高、列宽、合并单元格、内边距和对齐；
- 单元格段落和富文本；
- 显式边框、填充和常见 tableStyle；
- 表格 DOM 结构、网格线和文字行级 QA。
- 解析系列、分类、数值、稀疏点、点颜色和标签；
- 常见柱状图、条形图、折线图、面积图、饼图和圆环图；
- 有界的柱线组合图与主/次坐标轴；
- 坐标轴范围、方向、交叉点、网格线、图例和 plot-area 布局；
- 图表主题覆盖、显式
noFill、部分 DrawingML 图案与线条语义； - 使用可编辑 SVG 重建，不把图表截图塞回页面。
- 图片裁剪、旋转、翻转、透明度和 duotone；
- SVG、SVGZ、EMF、WMF 的可追踪 rasterization；
- Office SVG/PNG 兼容预览的有证据回退；
- OCR 缓存、重复图片去重以及图片坐标到幻灯片坐标的映射。
Artifact IR 是 PPTX 与 HTML 之间的稳定语义层。它让浏览器编辑器、Agent、检索系统和 QA 工具不必直接理解全部 OOXML。
简化示例：
{
"$schema": "./schemas/artifact-ir-0.2.0.schema.json",
"artifactKind": "pptx-html-decompiler",
"schemaVersion": "0.2.0",
"source": {
"fileName": "input.pptx",
"selectedSlides": [1, 2, 3]
},
"slides": [
{
"index": 1,
"objects": [
{
"id": "slide_1_obj_1",
"kind": "text",
"frame": { "x": 80, "y": 64, "width": 680, "height": 90 },
"paragraphs": []
}
]
}
]
}正式 Schema 位于 schemas/artifact-ir-0.2.0.schema.json。
转换器不会只告诉你“任务完成”。convert:qa 会依次验证：
flowchart LR
A["PPTX 解析"] --> B["Artifact IR 校验"]
B --> C["HTML / SVG 渲染"]
C --> D["Visual QA"]
C --> E["Editable DOM Audit"]
C --> F["Text Render / Metric Audit"]
C --> G["Standalone / Viewer / Geometry Audit"]
D --> H["Quality Report"]
E --> H
F --> H
G --> H
评分被刻意拆开：
- Structure：几何、边界、填充、线条和层级；
- Text：完整性、换行、行数、位置和裁切；
- Editability：对象、文本和表格是否仍然存在于 DOM；
- Pixel similarity：保留为回归信号，但不作为唯一产品分数。
单个标题被裁切、语义对象丢失、整页截图替代或浏览器报错，都可以成为 hard failure，不能被高平均分冲掉。
| 命令 | 说明 |
|---|---|
npm run convert |
PPTX → HTML + Artifact IR |
npm run convert:qa |
转换并运行完整 QA 链路 |
npm run visual-qa |
单独运行视觉差异分析 |
npm run dom-audit |
验证对象、文本和表格 DOM 覆盖 |
npm run text-render-audit |
检查浏览器文字渲染与溢出 |
npm run text-metric-audit |
对比参考文本行和 HTML 文本行 |
npm run corpus:inventory |
扫描 PPTX 语料能力信号 |
npm run corpus:fixtures |
规划代表性 benchmark 切片 |
npm run corpus:convert-qa |
批量运行转换与 QA |
npm run benchmark:decision-audit |
审计 benchmark 与发布证据 |
npm test |
运行自包含回归测试 |
所有命令入口见 package.json。
bin/ CLI 入口
src/ OOXML 解析、Artifact IR、渲染与 QA
schemas/ Artifact IR JSON Schema
test/ 自包含回归测试
benchmarks/ benchmark 方法、注册表和根因诊断
scripts/ 辅助脚本
建议的代码阅读顺序：
项目还包含一个实验性能力：把授权的 PPTX 资源库批量转换成可检索的逐页 HTML/Artifact 数据库，再按主题、故事角色、版式和能力进行检索。
npm run corpus:inventory -- \
--root /path/to/pptx-corpus \
--out ./benchmarks/ai-ppt-database-inventory
npm run resources:convert -- \
--inventory ./benchmarks/ai-ppt-database-inventory/corpus-inventory.json \
--out ./out/ai-ppt-database-resources
npm run ai:catalog -- \
--inventory ./benchmarks/ai-ppt-database-inventory/corpus-inventory.json \
--conversion-root ./out/ai-ppt-database-resources \
--out ./out/ai-ppt-database-catalog这部分目前是检索与故事线规划实验，不代表项目已经变成通用 AI PPT 生成器。
当前版本适合：
- 常规商务 PPT 的可编辑 HTML 转换；
- 内部工具、Agent 和编辑器的 PPTX 语义底座；
- 需要 Artifact IR、对象 provenance 和逐页 QA 的工作流；
- 对复杂页面进行根因定位和能力回归。
仍需重点提高：
- 高度定制的原生图表布局和数据标签；
- 稀有字体、跨平台字体度量和复杂文本效果；
- 极端 SmartArt、自定义几何、遮罩和第三方生产器 OOXML；
- 更广泛、真正未见过的外部 OOS 验证。
LibreOffice 是默认兼容性参考，不等同于 Microsoft PowerPoint 的语义权威。涉及字体、图表、特效和特殊形状时，项目会优先记录 oracle 差异，而不是把所有差异都归因于转换器。
项目采用“先定位根因，再寻找或实现解法”的 benchmark 策略。完整规则见：
公开仓库不会包含没有再分发授权的第三方 PPTX、PowerPoint/PDF 参考输出、批量截图或本地资源库。公开单元测试是自包含的；完整内部 release gate 依赖 local-only 验证资产。
- 提升复杂原生图表的视觉上限；
- 扩大跨作者、跨行业、跨生产工具的外部 OOS 集；
- 继续提高文字换行、裁切和跨平台字体度量稳定性；
- 稳定 Artifact IR 供编辑器和 Agent 使用；
- 在 PPTX → HTML 足够成熟后，再扩大受控 HTML → PPTX 回写范围。
欢迎提交 Issue 和 Pull Request。开始前请阅读：
核心原则只有一句：
不要用截图掩盖问题；保留语义、可编辑性和可复现证据。
MIT © 2026 Mijiang111