增加lyxy-reader-office skill
This commit is contained in:
212
skills/lyxy-reader-office/SKILL.md
Normal file
212
skills/lyxy-reader-office/SKILL.md
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user