280 lines
9.1 KiB
Markdown
280 lines
9.1 KiB
Markdown
---
|
||
name: docx-reader
|
||
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 可以使用 python-runner skill（推荐）或直接使用 Python 执行。
|
||
|
||
### 优先使用 python-runner
|
||
|
||
如果环境中存在 python-runner skill，应优先使用它来执行 docx_parser.py 脚本：
|
||
- python-runner 使用 uv 管理依赖，自动安装 markitdown 或 python-docx
|
||
- 环境隔离，不污染系统 Python
|
||
- 跨平台兼容（Windows/macOS/Linux）
|
||
|
||
### 降级到直接执行
|
||
|
||
如果环境中不存在 python-runner 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
|
||
|
||
### 优先使用 python-runner
|
||
|
||
**推荐执行方式**（如果 python-runner skill 可用）:
|
||
|
||
```bash
|
||
# 使用 python-runner 执行（推荐）
|
||
uv run --with markitdown skills/docx-reader/scripts/docx_parser.py /path/to/document.docx
|
||
|
||
# 或使用 python-docx
|
||
uv run --with python-docx skills/docx-reader/scripts/docx_parser.py /path/to/document.docx
|
||
```
|
||
|
||
**大模型应优先检查 python-runner skill 是否存在，如果存在则使用它执行。**
|
||
|
||
### 降级到直接执行
|
||
|
||
如果 python-runner skill 不可用，则直接使用 Python：
|
||
|
||
```bash
|
||
# 直接使用 Python 执行
|
||
python3 skills/docx-reader/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
|
||
```
|
||
|
||
输出：所有匹配结果及其上下文，用 `---` 分隔
|
||
|
||
## 依赖安装
|
||
|
||
### 推荐方式：使用 python-runner
|
||
|
||
如果使用 python-runner 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
|
||
|
||
### 为什么选择 python-runner？
|
||
|
||
| 特性 | 优势 |
|
||
| ------ | ------ |
|
||
| 环境隔离 | 不污染系统 Python |
|
||
| 自动依赖 | 自动安装 markitdown 或 python-docx |
|
||
| 快速启动 | 比 venv 快 10-100 倍 |
|
||
| 跨平台 | 自动适配 Windows/macOS/Linux |
|
||
| 零配置 | 开箱即用，无需预安装依赖 |
|
||
|
||
### 最佳实践
|
||
|
||
1. **优先使用 python-runner**: 如果环境中存在，应优先使用 python-runner 执行脚本
|
||
2. **大文件处理**: 对于大文档，建议使用章节提取或关键词搜索来限制处理范围
|
||
3. **依赖管理**: 使用 python-runner 可以自动管理依赖，避免环境配置问题
|
||
4. **错误处理**: 脚本会自动尝试多种解析方法，确保最大兼容性
|
||
5. **禁止自动安装**: 在降级到直接 Python 执行时，仅向用户提示安装依赖，不得自动执行 pip install
|
||
|
||
### 限制
|
||
|
||
- ✗ 不支持图片提取（仅纯文本）
|
||
- ✗ 不支持复杂的格式保留（字体、颜色、布局等）
|
||
- ✗ 不支持文档编辑或修改
|
||
- ✗ 仅支持 .docx 格式（不支持 .doc 或其他格式）
|