lanyuanxiaoyao/Skill
1
0
Fork 0
Code Activity
Files
4c9effac0b034a5924ab82f3bd2901110c53217f
Skill/temp/document_parser.md

8.9 KiB
Raw Blame History

Document Parser 使用说明

一个整合的文档解析器，支持将 DOCX 和 PPTX 文件转换为 Markdown 格式。

概述

该脚本按优先级尝试多种解析方法，确保最大兼容性：

  1. MarkItDown (微软官方库) - 推荐使用，格式最规范
  2. python-docx / python-pptx (成熟的 Python 库) - 输出最详细
  3. XML 原生解析 (备选方案) - 无需依赖

特性

  • 支持 DOCX 和 PPTX 格式
  • 自动检测文件类型和有效性
  • 保留文本格式（粗体、斜体、下划线）
  • 提取表格并转换为 Markdown 格式
  • 提取列表并保留层级结构
  • 多种输出模式（字数、行数、标题、搜索等）
  • 内容过滤和规范化

依赖要求

基础运行（XML 解析）

# Python 3.6+
python document_parser.py file.docx

使用 MarkItDown

# 使用 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

# 使用 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

所有依赖

# 安装所有解析库
uv run --with "markitdown[docx]" --with python-docx --with python-pptx document_parser.py file.docx

命令行用法

基本语法

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 内容

# 使用最佳可用解析器
python document_parser.py report.docx

# 输出到文件
python document_parser.py report.docx > output.md

2. 统计文档信息

# 统计字数
python document_parser.py report.docx -c

# 统计行数
python document_parser.py report.docx -l

3. 提取标题

# 提取所有标题
python document_parser.py report.docx -t

# 输出示例：
# 第一章 概述
## 1.1 背景
## 1.2 目标
# 第二章 实现

4. 提取特定标题内容

# 提取特定章节
python document_parser.py report.docx -tc "第一章"

# 输出该标题及其所有子内容

5. 搜索文档内容

# 搜索关键词
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 • 格式规范
• 微软官方支持
• 兼容性好		 • 需要安装
• 输出较简洁		 • 需要标准格式输出
• 自动化文档处理
python-docx • 输出最详细
• 保留完整结构
• 支持复杂样式		 • 需要安装
• 可能包含多余空行		 • 需要精确控制输出
• 分析文档结构
XML 原生 • 无需依赖
• 运行速度快
• 输出原始内容		 • 格式可能不统一
• 样式处理有限		 • 依赖不可用时
• 快速提取内容

PPTX 解析器

解析器 优点 缺点 适用场景
MarkItDown • 格式规范
• 自动添加 Slide 分隔
• 输出简洁		 • 需要安装
• 详细度较低		 • 快速预览幻灯片
• 提取主要内容
python-pptx • 输出最详细
• 保留完整结构
• 支持层级列表		 • 需要安装
• 依赖私有 API		 • 需要完整内容
• 分析演示结构
XML 原生 • 无需依赖
• 结构化输出
• 运行速度快		 • 格式可能不统一
• 幻灯片分组简单		 • 依赖不可用时
• 结构化提取

输出格式

Markdown 输出结构

# 标题 1 (一级)

正文段落

## 标题 2 (二级)

- 列表项 1
- 列表项 2

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

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

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

标题格式

  • 标题使用 Markdown 井号语法：# 到 ######（1-6级）
  • 标题名称不包含井号
  • 段落通过空行分隔

表格格式

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

列表格式

  • 无序列表：使用 - 前缀
  • 有序列表：使用 1. 前缀
  • 支持多层缩进（使用空格）

内容处理

自动处理

  1. 图片移除：自动删除 Markdown 图片语法
  2. 空行规范化：合并连续空行为单个空行
  3. 样式标签过滤：移除 HTML span 标签
  4. RGB 颜色过滤：移除颜色代码行

过滤规则（filter_markdown_content）

  • 保留：文本、表格、列表、基本格式
  • 移除：
    • HTML 注释 (<!-- ... -->)
    • Markdown 图片 (![alt](url))
    • HTML 图片标签 (<img>, </img>)
    • 媒体链接 ([text](file.ext))
    • RGB 颜色代码 (R:255 G:255 B:255)
  • 标准化：多余空格合并为单个空格

错误处理

文件验证

# 文件不存在
错误: 文件不存在: missing.docx

# 无效格式
错误: 文件不是有效的 DOCX 或 PPTX 格式: invalid.txt

解析器回退

脚本按优先级尝试解析器，如果失败则自动尝试下一个：

所有解析方法均失败:
- MarkItDown: 库未安装
- python-docx: 解析失败: ...
- XML 原生解析: document.xml 不存在或无法访问

搜索错误

# 无效正则
错误: 正则表达式无效或未找到匹配: '[invalid'

# 标题未找到
错误: 未找到标题 '不存在的标题'

高级用法

结合 uv 运行

# 自动安装依赖并运行
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

批量处理

# 使用 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")
}

管道使用

# 进一步处理 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：

# 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 安全检查
  • 提取重复代码为通用函数
  • 添加完整类型注解
View Git Blame Copy Permalink