Skill/skills/docx-reader/SKILL.md

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 可用）:

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

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

基本语法

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: 提取完整文档内容

# 提取完整文档
python3 docx_parser.py /path/to/document.docx

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

示例 2: 获取文档字数

# 获取字数
python3 docx_parser.py -c /path/to/document.docx

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

示例 3: 提取所有标题

# 提取标题
python3 docx_parser.py -t /path/to/document.docx

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

示例 4: 提取指定章节

# 提取 "第一章" 内容
python3 docx_parser.py -tc "第一章" /path/to/document.docx

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

示例 5: 搜索关键词

# 搜索关键词（默认 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 执行，需要手动安装至少一个解析库：

# 安装 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 或其他格式）