Skill/skills/lyxy-reader-office/SKILL.md

---
name: lyxy-reader-office
description: 优先解析 docx、xlsx、pptx、pdf 四种办公文档的 skill，将文档转换为 Markdown 格式，支持全文提取、标题提取、章节提取、正则搜索、字数统计、行数统计，PDF 额外支持 OCR 高精度模式。使用时请阅读 scripts/README.md 获取详细用法。
compatibility: Requires Python 3.6+. DOCX/PPTX/XLSX 无需额外依赖（XML 原生解析）；PDF 至少需要 pypdf。推荐通过 lyxy-runner-python skill 使用 uv 自动管理依赖。
---

# 办公文档解析 Skill

将 Microsoft Office 文档（.docx、.pptx、.xlsx）和 PDF 文件解析为 Markdown 格式，支持多种查询模式。

## Purpose

**统一入口**：使用 `scripts/parser.py` 作为统一的命令行入口，自动识别文件类型并分派到对应的格式解析器。

**依赖选项**：此 skill 必须优先使用 lyxy-runner-python skill 执行，不可用时降级到直接 Python 执行。

### 必须使用 lyxy-runner-python

如果环境中存在 lyxy-runner-python skill，**必须**使用它来执行 parser.py 脚本：
- lyxy-runner-python 使用 uv 管理依赖，自动安装所需的第三方库
- 环境隔离，不污染系统 Python
- 跨平台兼容（Windows/macOS/Linux）

### 降级到直接执行

**仅当** lyxy-runner-python skill 不存在时，才降级到直接 Python 执行：
- 需要用户手动安装依赖
- DOCX/PPTX/XLSX 无需依赖也可通过 XML 原生解析工作
- PDF 至少需要安装 pypdf
- **禁止自动执行 pip install**，仅向用户提示安装建议

## When to Use

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

### 典型场景
- **文档内容提取**：将 Word/PPT/Excel/PDF 文档转换为可读的 Markdown 文本
- **文档元数据**：获取文档的字数、行数等信息
- **标题分析**：提取文档的标题结构
- **章节提取**：提取特定章节的内容
- **内容搜索**：在文档中搜索关键词或模式
- **PDF OCR**：对扫描版 PDF 启用 OCR 高精度解析

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

### 触发词

**中文触发词**
- "读取/解析/打开 docx/word 文档"
- "读取/解析/打开 xlsx/excel 文件"
- "读取/解析/打开 pptx/ppt 文件"
- "读取/解析/打开 pdf 文件"

**英文触发词**
- "read/parse/extract docx/word/xlsx/excel/pptx/powerpoint/pdf"

**文件扩展名**
- `.docx`、`.xlsx`、`.pptx`、`.pdf`

## Capabilities

### 1. 全文转换为 Markdown
将完整文档解析为 Markdown 格式，移除图片但保留文本格式（标题、列表、表格、粗体、斜体等）。

各格式的输出特点：
- **DOCX**：标准 Markdown 文档结构
- **PPTX**：每张幻灯片以 `## Slide N` 为标题，幻灯片之间以 `---` 分隔
- **XLSX**：以 `## SheetName` 区分工作表，数据以 Markdown 表格呈现
- **PDF**：纯文本流，使用 `--high-res` 可启用 OCR 版面分析识别标题

### 2. 获取文档元信息
- 字数统计（`-c` 参数）
- 行数统计（`-l` 参数）

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

### 4. 指定章节内容提取
根据标题名称提取特定章节的完整内容（`-tc` 参数），包含上级标题链和所有下级内容。

### 5. 正则表达式搜索
在文档中搜索关键词或模式（`-s` 参数），支持自定义上下文行数（`-n` 参数，默认 2 行）。

### 6. PDF OCR 高精度模式
对 PDF 文件启用 OCR 版面分析（`--high-res` 参数），适用于扫描版 PDF 或需要识别标题层级的场景。

## Execution

### 详细用法参考

**执行前请阅读 `scripts/README.md`**，其中包含：
- 完整的命令行参数说明
- 各格式的依赖安装指南（pip 和 uv 方式）
- 解析器优先级和对比
- 输出格式说明
- 错误处理和常见问题

### 基本语法

```bash
python parser.py <file_path> [options]
```

### 使用 lyxy-runner-python 执行（必须优先使用）

```bash
# DOCX - 推荐依赖
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx

# PPTX - 推荐依赖
uv run --with "markitdown[pptx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.pptx

# XLSX - 推荐依赖
uv run --with "markitdown[xlsx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.xlsx

# PDF - 推荐依赖
uv run --with "markitdown[pdf]" --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/file.pdf

# PDF OCR 高精度模式
uv run --with docling --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/file.pdf --high-res
```

> **注意**：以上为最小推荐依赖，更多解析器依赖和完整安装命令请查阅 `scripts/README.md` 的安装部分。

### 降级到直接 Python 执行

仅当 lyxy-runner-python skill 不存在时使用：

```bash
python3 skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
```

### 互斥参数

| 参数 | 说明 |
|------|------|
| （无参数） | 输出完整 Markdown 内容 |
| `-c` | 字数统计 |
| `-l` | 行数统计 |
| `-t` | 提取所有标题 |
| `-tc <name>` | 提取指定标题的章节内容（name 不含 # 号） |
| `-s <pattern>` | 正则表达式搜索 |
| `-n <num>` | 与 `-s` 配合，指定上下文行数（默认 2） |
| `--high-res` | PDF 专用，启用 OCR 版面分析 |

## Examples

### 提取完整文档内容
```bash
# DOCX
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/report.docx

# PPTX
uv run --with "markitdown[pptx]" skills/lyxy-reader-office/scripts/parser.py /path/to/slides.pptx

# XLSX
uv run --with "markitdown[xlsx]" skills/lyxy-reader-office/scripts/parser.py /path/to/data.xlsx

# PDF
uv run --with "markitdown[pdf]" --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/doc.pdf
```

### 获取文档字数
```bash
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -c /path/to/report.docx
```

### 提取所有标题
```bash
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -t /path/to/report.docx
```

### 提取指定章节
```bash
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -tc "第一章" /path/to/report.docx
```

### 搜索关键词
```bash
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -s "关键词" -n 3 /path/to/report.docx
```

### PDF OCR 高精度解析
```bash
uv run --with docling --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/scanned.pdf --high-res
```

## Notes

### 多策略解析降级

每种文件格式配备多个解析器，按优先级依次尝试，前一个失败自动回退到下一个。详细的解析器优先级和对比请查阅 `scripts/README.md`。

### 限制

- 不支持图片提取（仅纯文本）
- 不支持复杂的格式保留（字体、颜色、布局等）
- 不支持文档编辑或修改
- 仅支持 .docx、.xlsx、.pptx、.pdf 格式（不支持 .doc、.xls、.ppt 等旧格式）
- PDF 无内置 XML 原生解析，至少需要安装 pypdf

### 最佳实践

1. **必须优先使用 lyxy-runner-python**：如果环境中存在，必须使用 lyxy-runner-python 执行脚本
2. **查阅 README**：详细参数、依赖安装、解析器对比等信息请阅读 `scripts/README.md`
3. **大文件处理**：对于大文档，建议使用章节提取（`-tc`）或搜索（`-s`）来限制处理范围
4. **PDF 标题**：PDF 是版面描述格式，默认不含语义化标题；需要标题层级时使用 `--high-res`
5. **禁止自动安装**：降级到直接 Python 执行时，仅向用户提示安装依赖，不得自动执行 pip install