---
name: lyxy-reader-docx
description: 优先解析 docx 文档的 skill，将 DOCX 文件转换为纯文本内容，不支持图片和格式提取。
compatibility: Requires Python 3.6+ and at least one of: markitdown or python-docx
---

# DOCX 文档解析 Skill

将 Microsoft Word (.docx) 文档解析为纯文本内容，支持多种解析模式和检索功能。

## Purpose

**依赖选项**: 此 skill 可以使用 lyxy-runner-python skill（推荐）或直接使用 Python 执行。

### 优先使用 lyxy-runner-python

如果环境中存在 lyxy-runner-python skill，应优先使用它来执行 docx_parser.py 脚本：
- lyxy-runner-python 使用 uv 管理依赖，自动安装 markitdown 或 python-docx
- 环境隔离，不污染系统 Python
- 跨平台兼容（Windows/macOS/Linux）

### 降级到直接执行

如果环境中不存在 lyxy-runner-python skill，则直接使用 Python 执行 docx_parser.py：
- 需要手动安装 markitdown 或 python-docx
- 脚本内部实现了多策略解析降级：MarkItDown → python-docx → XML 原生

## When to Use

任何需要读取或解析 .docx 文件内容的任务都应使用此 skill。

### 典型场景
- **文档内容提取**: 将 Word 文档转换为可读的文本内容
- **文档元数据**: 获取文档的字数、行数等信息
- **标题分析**: 提取文档的标题结构
- **章节提取**: 提取特定章节的内容
- **内容搜索**: 在文档中搜索关键词或模式

### 不适用场景
- ✗ 需要提取图片内容（仅支持纯文本）
- ✗ 需要保留复杂的格式信息（如字体、颜色、布局）
- ✗ 需要编辑或修改 .docx 文件
- ✗ 需要处理 .doc 或其他文档格式

## Capabilities

### 1. 全文转换为 Markdown
将完整的 DOCX 文档解析为 Markdown 格式文本，移除所有图片但保留文本格式。

**支持格式转换**:
- 标题（1-6级）
- 列表（有序和无序）
- 表格
- 粗体、斜体、下划线
- 连续空行规范化

### 2. 获取文档元信息
提供文档的基本统计信息：
- 字数统计（使用 `-c` 参数）
- 行数统计（使用 `-l` 参数）

### 3. 标题列表提取
提取文档中的所有标题（1-6级），按原始层级关系返回。

### 4. 指定章节内容提取
根据标题名称提取特定章节的完整内容，包括：
- 完整的上级标题链
- 该标题下的所有下级内容

支持同名标题提取，返回所有匹配章节。

### 5. 正则表达式搜索
在文档中搜索关键词或模式：
- 支持标准正则表达式
- 可自定义上下文行数（默认前后各 2 行）
- 多个匹配结果用 `---` 分隔
- 上下文行数不包含空行

## Triggers

### 中文触发词
- "读取 docx"
- "解析 docx"
- "打开 word 文档"
- "提取 word 文档内容"
- "解析 word 文件"

### 英文触发词
- "read docx"
- "parse docx"
- "extract from word document"
- "parse word file"
- "read word document"

### 文件扩展名
- `.docx` 文件

## Execution

### 优先使用 lyxy-runner-python

**推荐执行方式**（如果 lyxy-runner-python skill 可用）:

```bash
# 使用 lyxy-runner-python 执行（推荐）
uv run --with markitdown skills/lyxy-reader-docx/scripts/docx_parser.py /path/to/document.docx

# 或使用 python-docx
uv run --with python-docx skills/lyxy-reader-docx/scripts/docx_parser.py /path/to/document.docx
```

**大模型应优先检查 lyxy-runner-python skill 是否存在，如果存在则使用它执行。**

### 降级到直接执行

如果 lyxy-runner-python skill 不可用，则直接使用 Python：

```bash
# 直接使用 Python 执行
python3 skills/lyxy-reader-docx/scripts/docx_parser.py /path/to/document.docx
```

**提示用户**: 建议用户安装 markitdown 或 python-docx 以获得更好的解析效果：
```
建议：安装 markitdown 或 python-docx 以获得更好的解析效果

安装命令：
  pip install markitdown    # 推荐
  pip install python-docx   # 备选
```

**禁止自动安装**: 不得自动执行 pip install 命令安装依赖。仅向用户提示安装建议即可。

**降级策略说明**: 脚本内部实现了多策略解析降级（MarkItDown → python-docx → XML 原生），即使未安装第三方库也能通过 XML 原生解析工作，只是功能可能受限。

## Command Usage

### 基本语法
```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        | 使用正则表达式搜索文档，返回所有匹配结果（用---分隔） |

## Examples

### 示例 1: 提取完整文档内容
```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 -t /path/to/document.docx
```

输出：所有 1-6 级标题列表

### 示例 4: 提取指定章节
```bash
# 提取 "第一章" 内容
python3 docx_parser.py -tc "第一章" /path/to/document.docx
```

输出：该章节的完整内容（包含上级标题链和所有下级内容）

### 示例 5: 搜索关键词
```bash
# 搜索关键词（默认 2 行上下文）
python3 docx_parser.py -s "关键词" /path/to/document.docx

# 自定义 5 行上下文
python3 docx_parser.py -s "关键词" -n 5 /path/to/document.docx
```

输出：所有匹配结果及其上下文，用 `---` 分隔

## 依赖安装

### 推荐方式：使用 lyxy-runner-python

如果使用 lyxy-runner-python skill，依赖会自动管理，无需手动安装。

### 手动安装（降级模式）

如果直接使用 Python 执行，需要手动安装至少一个解析库：

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

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

**重要限制**:
- ✗ **禁止自动安装**: 不得自动执行 pip install 命令安装依赖
- ✗ **仅提示即可**: 向用户展示安装建议，但由用户决定是否安装
- ✗ **不阻塞执行**: 即使未安装依赖，脚本也能通过 XML 原生解析运行

### 多策略解析

脚本自动尝试以下解析方法，确保最大兼容性：
1. **MarkItDown**（微软官方库，效果最佳）
2. **python-docx**（成熟的 Python 库）
3. **XML 原生解析**（备选方案，无需任何依赖）

即使未安装任何依赖库，脚本也会尝试使用 XML 原生解析，但功能可能受限。

## Error Handling

### 常见错误

| 错误类型 | 说明 | 解决方案 |
| --------- | ---- | -------- |
| 文件不存在 | 提供的文件路径无效 | 检查文件路径是否正确 |
| 无效的 DOCX | 文件不是有效的 DOCX 格式或已损坏 | 确认文件格式正确 |
| 未找到标题 | 指定的标题名称不存在 | 使用 `-t` 参数查看所有标题 |
| 正则表达式无效 | 提供的正则表达式格式错误 | 检查正则表达式语法 |
| 解析库未安装 | 未安装 markitdown 或 python-docx | 提示用户安装以获得更好的解析效果，但禁止自动安装。脚本会自动降级到 XML 原生解析。 |

## Notes

### 为什么选择 lyxy-runner-python？

| 特性 | 优势 |
| ------ | ------ |
| 环境隔离 | 不污染系统 Python |
| 自动依赖 | 自动安装 markitdown 或 python-docx |
| 快速启动 | 比 venv 快 10-100 倍 |
| 跨平台 | 自动适配 Windows/macOS/Linux |
| 零配置 | 开箱即用，无需预安装依赖 |

### 最佳实践

1. **优先使用 lyxy-runner-python**: 如果环境中存在，应优先使用 lyxy-runner-python 执行脚本
2. **大文件处理**: 对于大文档，建议使用章节提取或关键词搜索来限制处理范围
3. **依赖管理**: 使用 lyxy-runner-python 可以自动管理依赖，避免环境配置问题
4. **错误处理**: 脚本会自动尝试多种解析方法，确保最大兼容性
5. **禁止自动安装**: 在降级到直接 Python 执行时，仅向用户提示安装依赖，不得自动执行 pip install

### 限制

- ✗ 不支持图片提取（仅纯文本）
- ✗ 不支持复杂的格式保留（字体、颜色、布局等）
- ✗ 不支持文档编辑或修改
- ✗ 仅支持 .docx 格式（不支持 .doc 或其他格式）