# 最简运行（XML 原生解析，无需安装依赖）
python parser.py report.docx

# 安装推荐依赖后运行
pip install "markitdown[docx]"
python parser.py report.docx

# 使用 uv 一键运行（自动安装依赖，无需手动 pip install）
uv run --with "markitdown[docx]" parser.py report.docx

命令行用法

基本语法

python parser.py <file_path> [options]

file_path 为 DOCX、PPTX、XLSX 或 PDF 文件路径（相对或绝对路径）。不带任何选项时输出完整 Markdown 内容。

参数说明

以下参数互斥，一次只能使用一个：

短选项	长选项	说明
`-c`	`--count`	输出解析后文档的总字符数（不含换行符）
`-l`	`--lines`	输出解析后文档的总行数
`-t`	`--titles`	输出所有标题行（1-6 级，含 `#` 前缀）
`-tc <name>`	`--title-content <name>`	提取指定标题及其下级内容（`name` 不包含 `#` 号）
`-s <pattern>`	`--search <pattern>`	使用正则表达式搜索文档，返回匹配结果

搜索辅助参数（与 -s 配合使用）：

短选项	长选项	说明
`-n <num>`	`--context <num>`	每个匹配结果包含的前后非空行数（默认：2）

PDF 专用参数：

长选项	说明
`--high-res`	启用 OCR 版面分析（需要额外依赖，处理较慢）

退出码

退出码	含义
`0`	解析成功
`1`	错误（文件不存在、格式无效、所有解析器失败、标题未找到、正则无效或无匹配）

使用示例

输出完整 Markdown：

python parser.py report.docx              # 输出到终端
python parser.py report.docx > output.md   # 重定向到文件

统计信息（-c / -l）：

输出单个数字，适合管道处理。

$ python parser.py report.docx -c
8500

$ python parser.py report.docx -l
215

提取标题（-t）：

每行一个标题，保留 # 前缀和层级。PDF 通常不包含语义化标题层级。

$ python parser.py report.docx -t
# 第一章 概述
## 1.1 背景
## 1.2 目标
# 第二章 实现

提取标题内容（-tc）：

输出指定标题及其下级内容。如果文档中有多个同名标题，用 --- 分隔。每段输出包含上级标题链。

$ python parser.py report.docx -tc "1.1 背景"
# 第一章 概述
## 1.1 背景
这是背景的详细内容...

搜索（-s）：

支持 Python 正则表达式语法。多个匹配结果用 --- 分隔。-n 控制上下文行数。

$ python parser.py report.docx -s "测试" -n 1
上一行内容
包含**测试**关键词的行
下一行内容
---
另一处上一行
另一处**测试**内容
另一处下一行

批量处理

# Linux/Mac
for file in *.docx; do
    python parser.py "$file" > "${file%.docx}.md"
done

# Windows PowerShell
Get-ChildItem *.docx | ForEach-Object {
    python parser.py $_.FullName > ($_.BaseName + ".md")
}

管道使用

# 过滤包含关键词的行
python parser.py report.docx | grep "重要" > important.md

# 统计含表格行数
python parser.py data.xlsx | grep -c "^|"

安装

脚本基于 Python 3.6+ 运行。每种文档类型有多个解析器按优先级依次尝试，建议安装对应类型的所有依赖以获得最佳兼容性。也可以只安装部分依赖，脚本会自动选择可用的解析器。

DOCX

优先级：Docling → unstructured → pypandoc-binary → MarkItDown → python-docx → XML 原生

# pip
pip install docling "unstructured[docx]" markdownify pypandoc-binary "markitdown[docx]" python-docx

# uv（一键运行，无需预安装）
uv run --with docling --with "unstructured[docx]" --with markdownify --with pypandoc-binary --with "markitdown[docx]" --with python-docx parser.py report.docx

PPTX

优先级：Docling → unstructured → MarkItDown → python-pptx → XML 原生

# pip
pip install docling "unstructured[pptx]" markdownify "markitdown[pptx]" python-pptx

# uv
uv run --with docling --with "unstructured[pptx]" --with markdownify --with "markitdown[pptx]" --with python-pptx parser.py presentation.pptx

XLSX

优先级：Docling → unstructured → MarkItDown → pandas → XML 原生

# pip
pip install docling "unstructured[xlsx]" markdownify "markitdown[xlsx]" pandas tabulate

# uv
uv run --with docling --with "unstructured[xlsx]" --with markdownify --with "markitdown[xlsx]" --with pandas --with tabulate parser.py data.xlsx

PDF

默认优先级：Docling → unstructured (fast) → MarkItDown → pypdf

--high-res 优先级：Docling OCR → unstructured OCR (hi_res) → Docling → unstructured (fast) → MarkItDown → pypdf

# pip - 基础文本提取（fast 策略，无需 OCR）
pip install docling "unstructured[pdf]" markdownify "markitdown[pdf]" pypdf

# pip - OCR 版面分析（--high-res 所需依赖）
pip install docling "unstructured[pdf]" unstructured-paddleocr "paddlepaddle==2.6.2" ml-dtypes markdownify "markitdown[pdf]" pypdf

# uv - 基础文本提取
uv run --with docling --with "unstructured[pdf]" --with markdownify --with "markitdown[pdf]" --with pypdf parser.py report.pdf

# uv - OCR 版面分析
uv run --with docling --with "unstructured[pdf]" --with unstructured-paddleocr --with "paddlepaddle==2.6.2" --with ml-dtypes --with markdownify --with "markitdown[pdf]" --with pypdf parser.py report.pdf --high-res

PDF 无内置 XML 原生解析，至少需要安装 pypdf。默认模式下 Docling 不启用 OCR，unstructured 使用 fast 策略。指定 --high-res 后，Docling 启用 OCR，unstructured 使用 hi_res 策略配合 PaddleOCR 进行版面分析。hi_res 策略需要额外安装 unstructured-paddleocr、paddlepaddle==2.6.2、ml-dtypes。PaddlePaddle 必须锁定 2.x 版本，3.x 在 Windows 上有 OneDNN 兼容问题。

安装所有依赖

# pip - 基础文本提取（不包含 PDF OCR）
pip install docling "unstructured[docx,pptx,xlsx,pdf]" markdownify pypandoc-binary "markitdown[docx,pptx,xlsx]" python-docx python-pptx pandas tabulate pypdf

# pip - 完整版（包含 PDF OCR）
pip install docling "unstructured[docx,pptx,xlsx,pdf]" markdownify unstructured-paddleocr "paddlepaddle==2.6.2" ml-dtypes pypandoc-binary "markitdown[docx,pptx,xlsx,pdf]" python-docx python-pptx pandas tabulate pypdf

# uv - 基础文本提取
uv run --with docling --with "unstructured[docx,pptx,xlsx,pdf]" --with markdownify --with pypandoc-binary --with "markitdown[docx,pptx,xlsx]" --with python-docx --with python-pptx --with pandas --with tabulate --with pypdf parser.py file.docx

# uv - 完整版（包含 PDF OCR）
uv run --with docling --with "unstructured[docx,pptx,xlsx,pdf]" --with markdownify --with unstructured-paddleocr --with "paddlepaddle==2.6.2" --with ml-dtypes --with pypandoc-binary --with "markitdown[docx,pptx,xlsx,pdf]" --with python-docx --with python-pptx --with pandas --with tabulate --with pypdf parser.py file.docx

依赖说明

MarkItDown：需要按文档类型安装可选依赖，直接 pip install markitdown 不包含任何格式支持。

pip install "markitdown[docx]"        # DOCX
pip install "markitdown[pptx]"        # PPTX
pip install "markitdown[xlsx]"        # XLSX
pip install "markitdown[pdf]"         # PDF
pip install "markitdown[docx,pptx,xlsx,pdf]"  # 全部

Docling：DOCX/PPTX/XLSX 使用 SimplePipeline 直接解析 XML 结构，不涉及 OCR。PDF 默认不启用 OCR（do_ocr=False），指定 --high-res 后启用 OCR（do_ocr=True）。首次运行 OCR 模式会自动下载模型到缓存目录，需保持网络连通。

unstructured：需同时安装 markdownify。支持按文档类型安装特定 extras 以减少依赖量：

unstructured[docx] - DOCX 处理（仅需 python-docx）
unstructured[pptx] - PPTX 处理（仅需 python-pptx）
unstructured[xlsx] - XLSX 处理（需 openpyxl、xlrd、pandas 等）
unstructured - 基础包（用于 PDF fast 策略）
unstructured[all-docs] - 所有文档类型（包含大量不必要的 OCR/视觉依赖）

PaddleOCR：不能用 paddleocr 代替 unstructured-paddleocr，unstructured 查找的模块名是 unstructured_paddleocr。

输出格式

Markdown 文档结构

无选项时输出完整 Markdown，包含以下元素：

# 一级标题

正文段落

## 二级标题

- 无序列表项
- 无序列表项

1. 有序列表项
2. 有序列表项

| 列1 | 列2 | 列3 |
|------|------|------|
| 数据1 | 数据2 | 数据3 |

**粗体** *斜体* <u>下划线</u>

各格式特有结构

PPTX — 每张幻灯片以 ## Slide N 为标题，幻灯片之间以 --- 分隔：

## Slide 1

幻灯片 1 的内容

---

## Slide 2

幻灯片 2 的内容

---

XLSX — 以 ## SheetName 区分工作表，数据以 Markdown 表格呈现：

# Excel数据转换结果 (原生XML解析)

## Sheet1

| 列1 | 列2 | 列3 |
|------|------|------|
| 数据1 | 数据2 | 数据3 |

## Sheet2

| 列A | 列B |
|------|------|
| 值1 | 值2 |

PDF — 纯文本流，通常不包含语义化标题层级（PDF 是版面描述格式，标题只是视觉样式）。使用 Docling 或 unstructured hi_res 策略可通过版面分析识别部分标题，但准确度取决于排版质量。

内容自动处理

输出前会自动进行以下处理：

处理	说明
图片移除	删除 `![alt](url)` 语法
空行规范化	连续多个空行合并为一个
RGB 噪声过滤	移除 `R:255 G:128 B:0` 格式的颜色值行（仅 unstructured 解析器）
页码噪声过滤	移除 `— 3 —` 格式的页码行（仅 unstructured 解析器）
页眉/页脚过滤	自动跳过 Header/Footer 元素（仅 unstructured 解析器）

错误处理

错误消息

# 文件不存在
$ python parser.py missing.docx
错误: 文件不存在: missing.docx

# 格式无效
$ python parser.py readme.txt
错误: 不是有效的 DOCX、PPTX、XLSX 或 PDF 格式: readme.txt

# 所有解析器失败（DOCX 示例）
$ python parser.py report.docx
所有解析方法均失败:
- Docling: docling 库未安装
- unstructured: unstructured 库未安装
- pypandoc-binary: pypandoc-binary 库未安装
- MarkItDown: MarkItDown 库未安装
- python-docx: python-docx 库未安装
- XML 原生解析: document.xml 不存在或无法访问

# 标题未找到
$ python parser.py report.docx -tc "不存在的标题"
错误: 未找到标题 '不存在的标题'

# 无效正则或无匹配
$ python parser.py report.docx -s "[invalid"
错误: 正则表达式无效或未找到匹配: '[invalid'

解析器回退机制

脚本按优先级依次尝试各解析器。每个解析器失败后记录原因（库未安装 / 解析失败 / 文档为空），然后自动尝试下一个。全部失败时输出汇总信息并以退出码 1 退出。

解析器对比

DOCX

解析器	优点	缺点	适用场景
Docling	单一依赖覆盖全格式；自动 OCR；输出结构稳定	首次需下载模型；内存占用较高	一键解析；需要 OCR
unstructured	元素类型感知；自动过滤噪声；HTML 表格转 Markdown	需 `unstructured[docx]` / `[pptx]` / `[xlsx]` + `markdownify`	结构化输出；表格转换
pypandoc-binary	自带 Pandoc；输出整洁；错误信息清晰	仅 DOCX；包体积大	标准化 Markdown
MarkItDown	微软官方；格式规范	输出简洁	标准格式；自动化处理
python-docx	输出最详细；保留完整结构；支持复杂样式	可能含多余空行	精确控制输出
XML 原生	无需依赖；速度快	样式处理有限	依赖不可用时兜底

PPTX

解析器	优点	缺点	适用场景
Docling	文本/表格/图片 OCR；统一 Markdown	需下载模型	一次性转换；含图片的 PPTX
unstructured	元素感知；过滤 RGB 噪声；表格转换	需 `unstructured[pptx]` + `markdownify`	结构化输出
MarkItDown	自动 Slide 分隔；简洁	详细度低	快速预览
python-pptx	输出最详细；支持层级列表	依赖私有 API	完整内容提取
XML 原生	无需依赖；速度快	分组简单	依赖不可用时兜底

XLSX

解析器	优点	缺点	适用场景
Docling	全表导出；处理合并单元格/图像 OCR	大表可能慢	快速全表转换
unstructured	元素感知；过滤噪声；表格转换	需 `unstructured[xlsx]` + `markdownify`	结构化输出
MarkItDown	支持多工作表；简洁	详细度低	快速预览
pandas	功能强大；支持复杂表格	需 `pandas` + `tabulate`	数据分析
XML 原生	无需依赖；支持所有单元格类型	无数据处理能力	依赖不可用时兜底

PDF

解析器	模式	优点	缺点	适用场景
Docling	默认	结构化 Markdown；表格/图片占位	首次需下载模型	有文本层的 PDF
Docling OCR	`--high-res`	内置 OCR；结构化 Markdown	模型体积大；OCR 耗时长	扫描版 PDF；多语言
unstructured	默认	fast 策略；速度快	不做版面分析；标题不可靠	快速文本提取
unstructured OCR	`--high-res`	hi_res 版面分析 + PaddleOCR；标题识别	需额外 PaddleOCR 依赖	版面分析；OCR
MarkItDown	通用	微软官方；格式规范	输出简洁	标准格式
pypdf	通用	轻量；速度快；安装简单	功能简单	快速文本提取

常见问题

为什么有些内容没有提取到？

不同解析器输出详细度不同。优先级高的解析器不一定输出最详细——Docling 和 unstructured 侧重结构化，python-docx/python-pptx 输出最详细但不做噪声过滤。建议安装对应类型的所有依赖，脚本会自动选择优先级最高的可用解析器。

PDF 文件没有标题层级？

PDF 是版面描述格式，不包含语义化标题结构。使用 --high-res 参数可启用 Docling OCR 或 unstructured hi_res 策略，通过版面分析识别部分标题，准确度取决于排版质量。默认模式下建议用 -s 搜索定位内容，或用 -c / -l 了解文档规模。

表格格式不正确？

XML 原生解析器对复杂表格（合并单元格、嵌套表格）支持有限。安装 Docling、unstructured 或对应的专用库可获得更好的表格处理效果。

中文显示乱码？

脚本输出 UTF-8 编码，确保终端支持：

# Linux/Mac
export LANG=en_US.UTF-8

# Windows PowerShell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

如何只使用特定解析器？

当前版本不支持指定解析器，总是按优先级自动选择。可以通过只安装目标解析器的依赖来间接控制——未安装的解析器会被跳过。

大文件处理慢？

Docling 和 unstructured 对大文件较慢（尤其是 OCR）。如果只需要快速提取文本，可以只安装轻量依赖（如 pypdf、python-docx），让脚本回退到这些解析器。DOCX/PPTX/XLSX 不安装任何依赖时使用 XML 原生解析，速度最快。

文件结构

scripts/
├── common.py         # 公共函数和常量
├── docx_parser.py    # DOCX 文件解析
├── pptx_parser.py    # PPTX 文件解析
├── xlsx_parser.py    # XLSX 文件解析
├── pdf_parser.py     # PDF 文件解析
├── parser.py         # 命令行入口
└── README.md         # 本文档

README.md Unescape Escape

Document Parser 使用说明

快速开始

命令行用法

基本语法

参数说明

退出码

使用示例

批量处理

管道使用

安装

DOCX

PPTX

XLSX

PDF

安装所有依赖

依赖说明

输出格式

Markdown 文档结构

各格式特有结构

内容自动处理

错误处理

错误消息

解析器回退机制

解析器对比

DOCX

PPTX

XLSX

PDF

常见问题

为什么有些内容没有提取到？

PDF 文件没有标题层级？

表格格式不正确？

中文显示乱码？

如何只使用特定解析器？

大文件处理慢？

文件结构

README.md