---
name: lyxy-document-reader
description: 统一文档解析工具 - 将 DOCX、XLSX、PPTX、PDF、HTML/URL 转换为 Markdown。支持全文输出、字数统计、行数统计、标题提取、章节提取、正则搜索。当用户要求"读取/解析/打开文档"、上传 .docx/.xlsx/.pptx/.pdf/.html 文件、或提供 URL 时使用。
license: MIT
metadata:
  version: "1.0"
  author: lyxy
compatibility: Requires Python 3.11+. 使用 uv run --with 方式按需加载依赖。
---

# 统一文档解析 Skill

将 DOCX、XLSX、PPTX、PDF、HTML 文件或 URL 网页内容解析为 Markdown 格式，支持多种查询模式。

## Purpose

**统一入口**：使用 `scripts/lyxy_document_reader.py` 作为统一的命令行入口，自动识别文件类型并执行解析。

**快速获取建议（必须优先使用）**：使用 `-a/--advice` 参数获取准确的执行建议，包含 `uv run --with ...` 命令和 `python` 命令，无需阅读此文档的后续内容。

**支持的文档类型**：
- **DOCX**：Word 文档
- **XLSX**：Excel 表格
- **PPTX**：PowerPoint 演示文稿
- **PDF**：PDF 文档（支持 OCR）
- **HTML/URL**：HTML 文件或网页地址

## When to Use

任何需要读取或解析 Office 文档、PDF、HTML 文件、URL 网页内容的任务都应使用此 skill。

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

### 触发词
- **中文**："读取/解析/打开 文档/Word/Excel/PPT/PDF/网页"
- **英文**："read/parse/extract document/docx/xlsx/pptx/pdf/html"
- **文件扩展名**：`.docx`、`.xlsx`、`.pptx`、`.pdf`、`.html`、`.htm`
- **URL 模式**：`http://`、`https://`

## Quick Reference

| 参数 | 说明 |
|------|------|
| `-a` / `--advice` | 仅显示执行建议，不实际解析文件（必须优先使用） |
| （无参数） | 输出完整 Markdown 内容 |
| `-c` / `--count` | 字数统计 |
| `-l` / `--lines` | 行数统计 |
| `-t` / `--titles` | 提取所有标题（1-6级） |
| `-tc <name>` | 提取指定标题的章节内容 |
| `-s <pattern>` | 正则表达式搜索 |
| `-n <num>` / `--context <num>` | 与 `-s` 配合，指定上下文行数（默认2） |

## Workflow

0. **获取执行建议（必须优先执行）**：
   ```bash
   python scripts/lyxy_document_reader.py --advice <文件路径或URL>
   ```
   - 根据建议中的命令执行即可，无需继续阅读后续内容

1. **检测执行环境**：
   - 优先检测 **lyxy-runner-python skill** 是否可用
   - 可用 → 使用 lyxy-runner-python skill 执行
   - 不可用 → 回退到主机 Python 环境

2. **识别文件类型**：
   - 根据文件扩展名自动选择对应的解析器
   - URL 自动识别为 HTML/网页类型

3. **输出结果**：
   - 返回 Markdown 格式内容或统计信息

### 使用示例

```bash
# 获取执行建议（必须优先执行此命令）
python scripts/lyxy_document_reader.py --advice document.docx

# 读取 Word 文档
python scripts/lyxy_document_reader.py document.docx

# 解析网页内容
python scripts/lyxy_document_reader.py https://example.com

# 统计字数
python scripts/lyxy_document_reader.py document.docx -c

# 提取所有标题
python scripts/lyxy_document_reader.py document.docx -t

# 提取指定章节
python scripts/lyxy_document_reader.py document.docx -tc "第三章"

# 搜索内容
python scripts/lyxy_document_reader.py document.docx -s "关键词"

# 正则搜索
python scripts/lyxy_document_reader.py document.docx -s "\d{4}-\d{2}-\d{2}"

# 指定上下文行数
python scripts/lyxy_document_reader.py document.docx -s "关键词" -n 5
```

## 错误处理

| 错误信息 | 原因 | 解决 |
|---------|------|------|
| 错误: input_path 不能为空 | 未提供输入 | 提供 file_path 或 URL |
| 错误: 不支持的文件类型 | 无对应 reader | 检查文件扩展名 |
| 所有解析方法均失败 | 所有解析器失败 | 检查文件是否损坏 |
| 错误: 无效的正则表达式 | 正则语法错误 | 检查正则语法 |
| 错误: 未找到匹配 | 搜索无结果 | 检查搜索词或正则 |
| ModuleNotFoundError: No module named 'xxx' | 缺少依赖 | 使用 lyxy-runner-python 或 pip 安装对应依赖 |