362 lines
8.9 KiB
Markdown
362 lines
8.9 KiB
Markdown
# Document Parser 使用说明
|
||
|
||
一个整合的文档解析器，支持将 DOCX 和 PPTX 文件转换为 Markdown 格式。
|
||
|
||
## 概述
|
||
|
||
该脚本按优先级尝试多种解析方法，确保最大兼容性：
|
||
|
||
1. **MarkItDown** (微软官方库) - 推荐使用，格式最规范
|
||
2. **python-docx / python-pptx** (成熟的 Python 库) - 输出最详细
|
||
3. **XML 原生解析** (备选方案) - 无需依赖
|
||
|
||
### 特性
|
||
|
||
- 支持 DOCX 和 PPTX 格式
|
||
- 自动检测文件类型和有效性
|
||
- 保留文本格式（粗体、斜体、下划线）
|
||
- 提取表格并转换为 Markdown 格式
|
||
- 提取列表并保留层级结构
|
||
- 多种输出模式（字数、行数、标题、搜索等）
|
||
- 内容过滤和规范化
|
||
|
||
## 依赖要求
|
||
|
||
### 基础运行（XML 解析）
|
||
|
||
```bash
|
||
# Python 3.6+
|
||
python document_parser.py file.docx
|
||
```
|
||
|
||
### 使用 MarkItDown
|
||
|
||
```bash
|
||
# 使用 uv 自动安装
|
||
uv run --with markitdown[docx] document_parser.py file.docx
|
||
uv run --with markitdown[pptx] document_parser.py file.pptx
|
||
|
||
# 或手动安装
|
||
pip install markitdown[docx]
|
||
pip install markitdown[pptx]
|
||
```
|
||
|
||
### 使用 python-docx / python-pptx
|
||
|
||
```bash
|
||
# 使用 uv 自动安装
|
||
uv run --with python-docx document_parser.py file.docx
|
||
uv run --with python-pptx document_parser.py file.pptx
|
||
|
||
# 或手动安装
|
||
pip install python-docx
|
||
pip install python-pptx
|
||
```
|
||
|
||
### 所有依赖
|
||
|
||
```bash
|
||
# 安装所有解析库
|
||
uv run --with "markitdown[docx]" --with python-docx --with python-pptx document_parser.py file.docx
|
||
```
|
||
|
||
## 命令行用法
|
||
|
||
### 基本语法
|
||
|
||
```bash
|
||
python document_parser.py <file_path> [options]
|
||
```
|
||
|
||
### 必需参数
|
||
|
||
- `file_path`: DOCX 或 PPTX 文件的路径（相对或绝对路径）
|
||
|
||
### 可选参数（互斥组，一次只能使用一个）
|
||
|
||
| 参数 | 短选项 | 长选项 | 说明 |
|
||
|------|---------|---------|------|
|
||
| `-c` | `--count` | 返回解析后的 markdown 文档的总字数 |
|
||
| `-l` | `--lines` | 返回解析后的 markdown 文档的总行数 |
|
||
| `-t` | `--titles` | 返回解析后的 markdown 文档的标题行（1-6级） |
|
||
| `-tc <name>` | `--title-content <name>` | 提取指定标题及其下级内容（不包含#号） |
|
||
| `-s <pattern>` | `--search <pattern>` | 使用正则表达式搜索文档，返回所有匹配结果（用---分隔） |
|
||
|
||
### 搜索上下文参数
|
||
|
||
- `-n <num>` / `--context <num>`: 与 `-s` 配合使用，指定每个检索结果包含的前后行数（默认：2）
|
||
|
||
## 使用示例
|
||
|
||
### 1. 输出完整 Markdown 内容
|
||
|
||
```bash
|
||
# 使用最佳可用解析器
|
||
python document_parser.py report.docx
|
||
|
||
# 输出到文件
|
||
python document_parser.py report.docx > output.md
|
||
```
|
||
|
||
### 2. 统计文档信息
|
||
|
||
```bash
|
||
# 统计字数
|
||
python document_parser.py report.docx -c
|
||
|
||
# 统计行数
|
||
python document_parser.py report.docx -l
|
||
```
|
||
|
||
### 3. 提取标题
|
||
|
||
```bash
|
||
# 提取所有标题
|
||
python document_parser.py report.docx -t
|
||
|
||
# 输出示例：
|
||
# 第一章 概述
|
||
## 1.1 背景
|
||
## 1.2 目标
|
||
# 第二章 实现
|
||
```
|
||
|
||
### 4. 提取特定标题内容
|
||
|
||
```bash
|
||
# 提取特定章节
|
||
python document_parser.py report.docx -tc "第一章"
|
||
|
||
# 输出该标题及其所有子内容
|
||
```
|
||
|
||
### 5. 搜索文档内容
|
||
|
||
```bash
|
||
# 搜索关键词
|
||
python document_parser.py report.docx -s "测试"
|
||
|
||
# 使用正则表达式
|
||
python document_parser.py report.docx -s "章节\s+\d+"
|
||
|
||
# 带上下文搜索（前后各2行）
|
||
python document_parser.py report.docx -s "重要内容" -n 2
|
||
|
||
# 输出示例：
|
||
---
|
||
这是重要内容的前两行
|
||
**重要内容**
|
||
这是重要内容后两行
|
||
---
|
||
```
|
||
|
||
## 解析器对比
|
||
|
||
### DOCX 解析器
|
||
|
||
| 解析器 | 优点 | 缺点 | 适用场景 |
|
||
|---------|------|--------|---------|
|
||
| **MarkItDown** | • 格式规范<br>• 微软官方支持<br>• 兼容性好 | • 需要安装<br>• 输出较简洁 | • 需要标准格式输出<br>• 自动化文档处理 |
|
||
| **python-docx** | • 输出最详细<br>• 保留完整结构<br>• 支持复杂样式 | • 需要安装<br>• 可能包含多余空行 | • 需要精确控制输出<br>• 分析文档结构 |
|
||
| **XML 原生** | • 无需依赖<br>• 运行速度快<br>• 输出原始内容 | • 格式可能不统一<br>• 样式处理有限 | • 依赖不可用时<br>• 快速提取内容 |
|
||
|
||
### PPTX 解析器
|
||
|
||
| 解析器 | 优点 | 缺点 | 适用场景 |
|
||
|---------|------|--------|---------|
|
||
| **MarkItDown** | • 格式规范<br>• 自动添加 Slide 分隔<br>• 输出简洁 | • 需要安装<br>• 详细度较低 | • 快速预览幻灯片<br>• 提取主要内容 |
|
||
| **python-pptx** | • 输出最详细<br>• 保留完整结构<br>• 支持层级列表 | • 需要安装<br>• 依赖私有 API | • 需要完整内容<br>• 分析演示结构 |
|
||
| **XML 原生** | • 无需依赖<br>• 结构化输出<br>• 运行速度快 | • 格式可能不统一<br>• 幻灯片分组简单 | • 依赖不可用时<br>• 结构化提取 |
|
||
|
||
## 输出格式
|
||
|
||
### Markdown 输出结构
|
||
|
||
```markdown
|
||
# 标题 1 (一级)
|
||
|
||
正文段落
|
||
|
||
## 标题 2 (二级)
|
||
|
||
- 列表项 1
|
||
- 列表项 2
|
||
|
||
1. 有序列表项 1
|
||
2. 有序列表项 2
|
||
|
||
| 列1 | 列2 | 列3 |
|
||
|------|------|------|
|
||
| 数据1 | 数据2 | 数据3 |
|
||
|
||
**粗体文本** *斜体文本* <u>下划线文本</u>
|
||
```
|
||
|
||
### 标题格式
|
||
|
||
- 标题使用 Markdown 井号语法：`#` 到 `######`（1-6级）
|
||
- 标题名称不包含井号
|
||
- 段落通过空行分隔
|
||
|
||
### 表格格式
|
||
|
||
```markdown
|
||
| 列1 | 列2 | 列3 |
|
||
|------|------|------|
|
||
| 数据1 | 数据2 | 数据3 |
|
||
```
|
||
|
||
### 列表格式
|
||
|
||
- 无序列表：使用 `-` 前缀
|
||
- 有序列表：使用 `1.` 前缀
|
||
- 支持多层缩进（使用空格）
|
||
|
||
## 内容处理
|
||
|
||
### 自动处理
|
||
|
||
1. **图片移除**：自动删除 Markdown 图片语法
|
||
2. **空行规范化**：合并连续空行为单个空行
|
||
3. **样式标签过滤**：移除 HTML span 标签
|
||
4. **RGB 颜色过滤**：移除颜色代码行
|
||
|
||
### 过滤规则（filter_markdown_content）
|
||
|
||
- 保留：文本、表格、列表、基本格式
|
||
- 移除：
|
||
- HTML 注释 (`<!-- ... -->`)
|
||
- Markdown 图片 (``)
|
||
- HTML 图片标签 (`<img>`, `</img>`)
|
||
- 媒体链接 (`[text](file.ext)`)
|
||
- RGB 颜色代码 (`R:255 G:255 B:255`)
|
||
- 标准化：多余空格合并为单个空格
|
||
|
||
## 错误处理
|
||
|
||
### 文件验证
|
||
|
||
```bash
|
||
# 文件不存在
|
||
错误: 文件不存在: missing.docx
|
||
|
||
# 无效格式
|
||
错误: 文件不是有效的 DOCX 或 PPTX 格式: invalid.txt
|
||
```
|
||
|
||
### 解析器回退
|
||
|
||
脚本按优先级尝试解析器，如果失败则自动尝试下一个：
|
||
|
||
```
|
||
所有解析方法均失败:
|
||
- MarkItDown: 库未安装
|
||
- python-docx: 解析失败: ...
|
||
- XML 原生解析: document.xml 不存在或无法访问
|
||
```
|
||
|
||
### 搜索错误
|
||
|
||
```bash
|
||
# 无效正则
|
||
错误: 正则表达式无效或未找到匹配: '[invalid'
|
||
|
||
# 标题未找到
|
||
错误: 未找到标题 '不存在的标题'
|
||
```
|
||
|
||
## 高级用法
|
||
|
||
### 结合 uv 运行
|
||
|
||
```bash
|
||
# 自动安装依赖并运行
|
||
uv run --with "markitdown[docx]" --with python-docx document_parser.py report.docx
|
||
|
||
# 输出到文件
|
||
uv run --with python-docx document_parser.py report.docx > output.md
|
||
```
|
||
|
||
### 批量处理
|
||
|
||
```bash
|
||
# 使用 find 或 glob 批量处理
|
||
for file in *.docx; do
|
||
python document_parser.py "$file" > "${file%.docx}.md"
|
||
done
|
||
|
||
# Windows PowerShell
|
||
Get-ChildItem *.docx | ForEach-Object {
|
||
python document_parser.py $_.FullName > ($_.BaseName + ".md")
|
||
}
|
||
```
|
||
|
||
### 管道使用
|
||
|
||
```bash
|
||
# 进一步处理 Markdown 输出
|
||
python document_parser.py report.docx | grep "重要" > important.md
|
||
|
||
# 统计处理
|
||
python document_parser.py report.docx -l | awk '{print $1}'
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q: 为什么有些内容没有提取到？
|
||
|
||
A: 不同解析器的输出详细度不同：
|
||
|
||
- `python-docx` 输出最详细
|
||
- `MarkItDown` 输出较简洁
|
||
- `XML 原生` 输出原始内容
|
||
如需完整内容，尝试使用 `python-docx` 解析器。
|
||
|
||
### Q: 表格格式不正确？
|
||
|
||
A: 确保原始文档中的表格结构完整。XML 解析器可能无法处理复杂表格。
|
||
|
||
### Q: 中文显示乱码？
|
||
|
||
A: 脚本输出使用 UTF-8 编码。确保终端支持 UTF-8：
|
||
|
||
```bash
|
||
# Linux/Mac
|
||
export LANG=en_US.UTF-8
|
||
|
||
# Windows PowerShell
|
||
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
|
||
```
|
||
|
||
### Q: 如何只使用特定解析器？
|
||
|
||
A: 当前版本自动选择最佳可用解析器。可以通过注释代码中的解析器列表来限制，或安装/卸载特定依赖。
|
||
|
||
### Q: 大文件处理慢？
|
||
|
||
A: 大文件建议使用 XML 原生解析（最快），或在脚本外部处理。
|
||
|
||
## 性能参考
|
||
|
||
基于测试文件（约 10KB DOCX）的参考数据：
|
||
|
||
| 解析器 | 字符数 | 行数 | 相对速度 |
|
||
|---------|--------|------|---------|
|
||
| MarkItDown | ~6,000 | ~110 | 快 |
|
||
| python-docx | ~7,500 | ~120 | 中 |
|
||
| XML 原生 | ~8,600 | ~120 | 快 |
|
||
|
||
## 许可证
|
||
|
||
脚本遵循 PEP 8 规范，Python 3.6+ 兼容。
|
||
|
||
## 更新日志
|
||
|
||
### 最新更新
|
||
|
||
- 修复 XML 解析的 `.getroot()` 调用问题
|
||
- 优化样式匹配逻辑，使用精确匹配代替 `in` 操作
|
||
- 增强 `safe_open_zip` 安全检查
|
||
- 提取重复代码为通用函数
|
||
- 添加完整类型注解
|