lanyuanxiaoyao
c140bda66b
- 移除 pyproject.toml 和 uv.lock - 更新 SKILL.md：使用 uv run --with 按需加载依赖 - 更新 README.md：添加多行格式的测试命令 - 更新项目规范文档 - 修复脚本：支持从任意位置执行 - 新增 uv-with-dependency-management 规范
197 lines
6.8 KiB
Markdown
197 lines
6.8 KiB
Markdown
---
|
||
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` 作为统一的命令行入口，自动识别文件类型并执行解析。
|
||
|
||
**依赖管理**：使用 `uv run --with` 方式按需加载解析器依赖。每次执行时根据文档类型指定对应的依赖包。
|
||
|
||
**支持的文档类型**：
|
||
- **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
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| （无参数） | 输出完整 Markdown 内容 |
|
||
| `-c` / `--count` | 字数统计 |
|
||
| `-l` / `--lines` | 行数统计 |
|
||
| `-t` / `--titles` | 提取所有标题（1-6级） |
|
||
| `-tc <name>` | 提取指定标题的章节内容 |
|
||
| `-s <pattern>` | 正则表达式搜索 |
|
||
| `-n <num>` / `--context <num>` | 与 `-s` 配合，指定上下文行数（默认2） |
|
||
|
||
## Workflow
|
||
|
||
1. **检测执行环境**：
|
||
- 优先检测 **lyxy-runner-python skill** 是否可用
|
||
- 可用 → 使用 uv 隔离环境执行
|
||
- 不可用 → 回退到主机 Python 环境
|
||
|
||
2. **识别文件类型**：
|
||
- 根据文件扩展名自动选择对应的解析器
|
||
- URL 自动识别为 HTML/网页类型
|
||
|
||
3. **执行解析**：
|
||
- 按优先级尝试多个解析器，直到成功
|
||
- DOCX：docling → unstructured → pypandoc → MarkItDown → python-docx → XML
|
||
- XLSX：docling → unstructured → MarkItDown → pandas → XML
|
||
- PPTX：docling → unstructured → MarkItDown → python-pptx → XML
|
||
- PDF：docling OCR → unstructured OCR → docling → unstructured → MarkItDown → pypdf
|
||
- HTML：trafilatura → domscribe → MarkItDown → html2text
|
||
|
||
4. **输出结果**：
|
||
- 返回 Markdown 格式内容或统计信息
|
||
|
||
### 基本语法
|
||
|
||
使用 `uv run --with` 按需加载依赖包：
|
||
|
||
```bash
|
||
# 根据文档类型选择对应的依赖包
|
||
uv run --with <依赖包1> --with <依赖包2> ... \
|
||
scripts/lyxy_document_reader.py <文件路径或URL>
|
||
```
|
||
|
||
具体的依赖包列表请参考下方的"依赖安装指南"。
|
||
|
||
### 使用示例
|
||
|
||
```bash
|
||
# 读取 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
|
||
```
|
||
|
||
### 依赖安装指南
|
||
|
||
使用 `uv run --with` 方式按需加载解析器依赖。以下命令适用于大多数平台（macOS ARM、Linux、Windows）。
|
||
|
||
#### 平台检测
|
||
|
||
在遇到问题时，可以检测你的平台：
|
||
|
||
```bash
|
||
# macOS / Linux
|
||
uname -m # 显示架构: x86_64 或 arm64
|
||
uname -s # 显示系统: Darwin 或 Linux
|
||
|
||
# Windows PowerShell
|
||
$env:OS # 或检查环境变量
|
||
|
||
# Python 跨平台检测
|
||
python -c "import platform; print(f'{platform.system()}-{platform.machine()}')"
|
||
```
|
||
|
||
#### PDF 解析
|
||
|
||
**默认命令**（适用于 macOS ARM、Linux、Windows）：
|
||
|
||
```bash
|
||
uv run --with docling --with "unstructured[pdf]" --with "markitdown[pdf]" --with pypdf --with markdownify --with chardet scripts/lyxy_document_reader.py file.pdf
|
||
```
|
||
|
||
**macOS x86_64 (Intel) 特殊说明**：
|
||
|
||
此平台需要使用 Python 3.12 和特定版本的依赖：
|
||
|
||
```bash
|
||
uv run --python 3.12 --with "docling==2.40.0" --with "docling-parse==4.0.0" --with "numpy<2" --with "markitdown[pdf]" --with pypdf --with markdownify --with chardet scripts/lyxy_document_reader.py file.pdf
|
||
```
|
||
|
||
原因：`docling-parse` 5.x 无 x86_64 wheel，必须使用 4.0.0；`easyocr`（docling 的 OCR 后端）与 NumPy 2.x 不兼容。
|
||
|
||
#### DOCX 解析
|
||
|
||
```bash
|
||
uv run --with docling --with "unstructured[docx]" --with "markitdown[docx]" --with pypandoc-binary --with python-docx --with markdownify --with chardet scripts/lyxy_document_reader.py file.docx
|
||
```
|
||
|
||
#### XLSX 解析
|
||
|
||
```bash
|
||
uv run --with docling --with "unstructured[xlsx]" --with "markitdown[xlsx]" --with pandas --with tabulate --with chardet scripts/lyxy_document_reader.py file.xlsx
|
||
```
|
||
|
||
#### PPTX 解析
|
||
|
||
```bash
|
||
uv run --with docling --with "unstructured[pptx]" --with "markitdown[pptx]" --with python-pptx --with markdownify --with chardet scripts/lyxy_document_reader.py file.pptx
|
||
```
|
||
|
||
#### HTML/URL 解析
|
||
|
||
```bash
|
||
uv run --with trafilatura --with domscribe --with markitdown --with html2text --with beautifulsoup4 --with httpx --with chardet scripts/lyxy_document_reader.py https://example.com
|
||
```
|
||
|
||
**需要 JavaScript 渲染的网页**，额外添加：
|
||
|
||
```bash
|
||
--with pyppeteer --with selenium
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
| 错误信息 | 原因 | 解决 |
|
||
|---------|------|------|
|
||
| 错误: input_path 不能为空 | 未提供输入 | 提供 file_path 或 URL |
|
||
| 错误: 不支持的文件类型 | 无对应 reader | 检查文件扩展名 |
|
||
| 所有解析方法均失败 | 所有解析器失败 | 检查文件是否损坏 |
|
||
| 错误: 无效的正则表达式 | 正则语法错误 | 检查正则语法 |
|
||
| 错误: 未找到匹配 | 搜索无结果 | 检查搜索词或正则 |
|
||
| ModuleNotFoundError: No module named 'xxx' | 缺少依赖 | 使用 lyxy-runner-python 或 pip 安装对应依赖 |
|