Skill/skills/lyxy-reader-docx/docx_parser.md

DOCX 解析器使用说明

简介

docx_parser.py 是一个功能强大的 DOCX 文件解析工具，支持将 Microsoft Word (.docx) 文档转换为 Markdown 格式。该脚本采用多策略解析机制，按优先级尝试以下解析方法：

1. MarkItDown（微软官方库）
2. python-docx（成熟的 Python 库）
3. XML 原生解析（备选方案）

环境要求

• Python 3.6+
• pip

安装依赖

根据你的需求安装相应的解析库：

# 安装 MarkItDown（推荐）
pip install markitdown

# 安装 python-docx（备选）
pip install python-docx

注意：建议至少安装一种解析库。如果未安装任何库，脚本会尝试使用 XML 原生解析，但功能可能受限。

命令行参数

基本语法

python3 docx_parser.py [options] <file_path>

位置参数

参数	说明
file_path	DOCX 文件的绝对路径

选项参数

参数	长参数	类型	默认值	说明
-n	--context	整数	2	与 -s 配合使用，指定每个检索结果包含的前后行数（不包含空行）

互斥参数

以下参数只能使用其中一个：

参数	长参数	说明
-c	--count	返回解析后的 markdown 文档的总字数
-l	--lines	返回解析后的 markdown 文档的总行数
-t	--titles	返回解析后的 markdown 文档的标题行（1-6级）
-tc	--title-content	指定标题名称，输出该标题及其下级内容（不包含#号）
-s	--search	使用正则表达式搜索文档，返回所有匹配结果（用---分隔）

使用示例

1. 输出完整 Markdown 内容

python3 docx_parser.py /path/to/document.docx

输出：完整的 Markdown 格式文档内容

2. 获取文档字数

python3 docx_parser.py -c /path/to/document.docx

输出：文档总字数（数字）

3. 获取文档行数

python3 docx_parser.py -l /path/to/document.docx

输出：文档总行数（数字）

4. 提取所有标题

python3 docx_parser.py -t /path/to/document.docx

输出示例：

# 主标题
## 第一章
### 1.1 简介
### 1.2 内容
## 第二章

5. 提取指定标题内容

python3 docx_parser.py -tc "第一章" /path/to/document.docx

输出：包含所有上级标题的指定章节内容

特点：

• 支持多个同名标题
• 自动包含完整的上级标题链
• 包含所有下级内容

示例输出：

# 主标题
## 第一章
这是第一章的内容
包含所有子章节...

### 1.1 简介
简介内容

### 1.2 内容
详细内容

6. 搜索关键词

6.1 基本搜索

python3 docx_parser.py -s "关键词" /path/to/document.docx

输出：所有匹配关键词的内容片段，默认前后各 2 行上下文，用 --- 分隔

6.2 自定义上下文行数

# 前后各 5 行
python3 docx_parser.py -s "关键词" -n 5 /path/to/document.docx

# 不包含上下文
python3 docx_parser.py -s "关键词" -n 0 /path/to/document.docx

6.3 正则表达式搜索

# 搜索包含数字的行
python3 docx_parser.py -s r"数字\d+" /path/to/document.docx

# 搜索邮箱地址
python3 docx_parser.py -s r"\b[\w.-]+@[\w.-]+\.\w+\b" /path/to/document.docx

# 搜索日期格式
python3 docx_parser.py -s r"\d{4}-\d{2}-\d{2}" /path/to/document.docx

输出示例：

这是前一行
包含匹配关键词
这是后一行
---
另一个匹配
---
第三个匹配

7. 将输出保存到文件

# 保存完整 Markdown
python3 docx_parser.py /path/to/document.docx > output.md

# 保存标题内容
python3 docx_parser.py -tc "第一章" /path/to/document.docx > chapter1.md

# 保存搜索结果
python3 docx_parser.py -s "关键词" /path/to/document.docx > search_results.md

功能特性

多策略解析

脚本自动尝试三种解析方法，确保最大的兼容性：

1. MarkItDown：微软官方库，解析效果最佳
2. python-docx：功能完善的第三方库
3. XML 原生解析：不依赖任何库的备选方案

智能匹配

标题提取

• 支持 1-6 级标题识别
• 自动处理不同样式的标题（Title、Heading 1-6）
• 保留原始标题层级关系

标题内容提取

• 支持同名标题提取
• 自动构建完整上级标题链
• 包含所有下级内容
• 保持文档结构完整

搜索功能

• 支持正则表达式
• 智能合并相近匹配
• 上下文行数控制（不包含空行）
• 结果用 --- 清晰分隔

文档处理

• 自动移除 Markdown 图片
• 规范化空白行（连续多个空行合并为一个）
• 支持表格、列表、粗体、斜体、下划线等格式

错误处理

• 文件存在性检查
• DOCX 格式验证
• 解析失败时自动尝试下一种方法
• 详细的错误提示信息

常见问题

Q: 如何处理大文档？

A: 对于非常大的文档，建议：

1. 使用 -tc 参数只提取需要的章节
2. 使用 -s 参数搜索特定内容
3. 将输出重定向到文件进行处理

Q: 搜索功能支持哪些正则表达式？

A: 支持所有 Python 标准正则表达式语法。需要注意特殊字符的转义：

# 错误：括号需要转义
python3 docx_parser.py -s "(关键词)" /path/to/document.docx

# 正确
python3 docx_parser.py -s "\(关键词\)" /path/to/document.docx

Q: 如何获取更多上下文？

A: 使用 -n 参数调整上下文行数：

# 默认 2 行（推荐）
python3 docx_parser.py -s "关键词" /path/to/document.docx

# 更多上下文（5 行）
python3 docx_parser.py -s "关键词" -n 5 /path/to/document.docx

# 不包含上下文
python3 docx_parser.py -s "关键词" -n 0 /path/to/document.docx

Q: 多个同名标题如何处理？

A: -tc 参数会返回所有同名标题，每个标题都包含其完整的上级标题链：

# 主标题

## 同名标题 1

内容1

# 主标题

## 同名标题 2

内容2

技术细节

标题识别规则

样式名称	Markdown 标题级别
Title	#
Heading 1	#
Heading 2	##
Heading 3	###
Heading 4	####
Heading 5	#####
Heading 6	######

列表识别规则

样式名称	Markdown 列表格式
List Bullet / Bullet	- (无序列表)
List Number / Number	1. (有序列表)

文本格式支持

格式	转换结果
粗体	**文本**
斜体	*文本*
下划线	<u>文本</u>
表格	Markdown 表格格式