# DOCX 解析器使用说明

## 简介

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

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

## 环境要求

- Python 3.6+
- pip

## 安装依赖

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

```bash
# 安装 MarkItDown（推荐）
pip install markitdown

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

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

## 命令行参数

### 基本语法

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

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

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

### 2. 获取文档字数

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

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

### 3. 获取文档行数

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

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

### 4. 提取所有标题

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

输出示例：
```
# 主标题
## 第一章
### 1.1 简介
### 1.2 内容
## 第二章
```

### 5. 提取指定标题内容

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

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

**特点：**
- 支持多个同名标题
- 自动包含完整的上级标题链
- 包含所有下级内容

示例输出：
```
# 主标题
## 第一章
这是第一章的内容
包含所有子章节...

### 1.1 简介
简介内容

### 1.2 内容
详细内容
```

### 6. 搜索关键词

#### 6.1 基本搜索

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

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

#### 6.2 自定义上下文行数

```bash
# 前后各 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 正则表达式搜索

```bash
# 搜索包含数字的行
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. 将输出保存到文件

```bash
# 保存完整 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: 建议优先安装 `markitdown`，它是微软官方库，解析效果最好。如果需要更多控制或兼容性，可以同时安装 `python-docx`。

### Q: 为什么某些文档解析不完整？

A: 可能原因：
1. 文档使用特殊格式或样式
2. 文档已损坏
3. 未安装合适的解析库

尝试安装多个解析库，或检查文档是否损坏。

### Q: 如何处理大文档？

A: 对于非常大的文档，建议：
1. 使用 `-tc` 参数只提取需要的章节
2. 使用 `-s` 参数搜索特定内容
3. 将输出重定向到文件进行处理

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

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

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

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

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

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

```bash
# 默认 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` 参数会返回所有同名标题，每个标题都包含其完整的上级标题链：

```markdown
# 主标题
## 同名标题 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 表格格式 |

## 许可证

本脚本遵循相关开源许可证。

## 贡献

欢迎提交问题和改进建议。