Skill/temp/scripts/README.md

Document Parser 使用说明

模块化文档解析器，将 DOCX、PPTX、XLSX、PDF 文件转换为 Markdown 格式。

每种文档类型配备多个解析器，按优先级依次尝试，前一个失败自动回退到下一个。不安装任何第三方库时，DOCX/PPTX/XLSX 仍可通过内置 XML 原生解析工作（PDF 至少需要 pypdf）。

快速开始

# 最简运行（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 策略可通过版面分析识别部分标题，但准确度取决于排版质量。

内容自动处理

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

处理	说明
图片移除	删除  语法
空行规范化	连续多个空行合并为一个
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         # 本文档