lanyuanxiaoyao
dfe6904f4c
为不同平台提供特定的依赖 extras，解决 macOS x86_64 的依赖兼容性问题。 - 添加平台特定的 PDF 解析 extras：pdf-win, pdf-macos-intel, pdf-macos-arm, pdf-linux - 添加平台特定的 Office 文档 extras：office-win, office-macos-intel, office-macos-arm, office-linux - macOS x86_64 使用硬编码版本：docling==2.40.0, docling-parse==4.0.0 - 移除通用的 pdf 和 office extras，强制用户选择平台 - 更新 SKILL.md 添加详细的多平台依赖安装指南 - 更新 README.md 添加平台特定安装说明 - 在 .gitignore 中添加 uv.lock - 删除现有的 uv.lock 文件 - 创建 multi-platform-dependencies 规范文档
8.1 KiB
8.1 KiB
name, description, license, metadata, compatibility
| name | description | license | metadata | compatibility | ||||
|---|---|---|---|---|---|---|---|---|
| lyxy-document-reader | 统一文档解析工具 - 将 DOCX、XLSX、PPTX、PDF、HTML/URL 转换为 Markdown。支持全文输出、字数统计、行数统计、标题提取、章节提取、正则搜索。当用户要求"读取/解析/打开文档"、上传 .docx/.xlsx/.pptx/.pdf/.html 文件、或提供 URL 时使用。 | MIT |
|
Requires Python 3.11+. 优先使用 lyxy-runner-python skill 执行（自动管理依赖）。回退到主机 Python 时需根据平台手动安装依赖：Windows(pdf-win/office-win) / macOS Intel(pdf-macos-intel/office-macos-intel,需Python 3.12) / macOS ARM(pdf-macos-arm/office-macos-arm) / Linux(pdf-linux/office-linux)。详见"多平台依赖安装指南"章节。 |
统一文档解析 Skill
将 DOCX、XLSX、PPTX、PDF、HTML 文件或 URL 网页内容解析为 Markdown 格式，支持多种查询模式。
Purpose
统一入口：使用 scripts/lyxy_document_reader.py 作为统一的命令行入口，自动识别文件类型并执行解析。
双路径执行：此 skill 必须优先使用 lyxy-runner-python skill 执行脚本，该 skill 会自动管理 uv 隔离环境和依赖。当 lyxy-runner-python 不可用时，回退到主机 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
| 参数 | 说明 |
|---|---|
| （无参数） | 输出完整 Markdown 内容 |
-c / --count |
字数统计 |
-l / --lines |
行数统计 |
-t / --titles |
提取所有标题（1-6级） |
-tc <name> |
提取指定标题的章节内容 |
-s <pattern> |
正则表达式搜索 |
-n <num> / --context <num> |
与 -s 配合，指定上下文行数（默认2） |
Workflow
-
检测执行环境：
- 优先检测 lyxy-runner-python skill 是否可用
- 可用 → 使用 uv 隔离环境执行
- 不可用 → 回退到主机 Python 环境
-
识别文件类型：
- 根据文件扩展名自动选择对应的解析器
- URL 自动识别为 HTML/网页类型
-
执行解析：
- 按优先级尝试多个解析器，直到成功
- 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
-
输出结果：
- 返回 Markdown 格式内容或统计信息
基本语法
# 方式 1：使用 lyxy-runner-python（推荐）
# lyxy-runner-python 会自动分析脚本依赖并使用 uv --with 安装
# AI 只需执行：
python scripts/lyxy_document_reader.py <文件路径或URL>
# 方式 2：回退到主机 Python（需要预先手动安装依赖）
# 根据文档类型安装对应依赖后执行：
python scripts/lyxy_document_reader.py <文件路径或URL>
使用示例
# 读取 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
多平台依赖安装指南
重要说明：本项目为不同平台提供特定的依赖配置，请根据你的平台选择对应的 extra。
平台检测
在使用前，请先检测你的平台：
# 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 解析依赖
根据你的平台选择对应的安装命令：
Windows x86_64
uv run --with "lyxy-document[pdf-win]" scripts/lyxy_document_reader.py file.pdf
- 依赖：docling, unstructured, PaddleOCR
- Python：>=3.11
- 特殊说明：无
macOS x86_64 (Intel) ⚠️ 特殊平台：需要特定版本配置
uv run --python 3.12 --with "lyxy-document[pdf-macos-intel]" scripts/lyxy_document_reader.py file.pdf
- 依赖：docling==2.40.0, docling-parse==4.0.0, numpy<2
- Python：必须 3.12
- 特殊说明：
docling-parse5.x 无 x86_64 wheel，必须使用 4.0.0easyocr（docling 的 OCR 后端）与 NumPy 2.x 不兼容
macOS arm64 (Apple Silicon)
uv run --with "lyxy-document[pdf-macos-arm]" scripts/lyxy_document_reader.py file.pdf
- 依赖：docling, unstructured
- Python：>=3.11
- 特殊说明：无
Linux
uv run --with "lyxy-document[pdf-linux]" scripts/lyxy_document_reader.py file.pdf
- 依赖：docling, unstructured
- Python：>=3.11
- 特殊说明：无
Office 文档依赖
Windows x86_64
uv run --with "lyxy-document[office-win]" scripts/lyxy_document_reader.py file.docx
macOS x86_64 (Intel)
uv run --python 3.12 --with "lyxy-document[office-macos-intel]" scripts/lyxy_document_reader.py file.docx
macOS arm64 (Apple Silicon)
uv run --with "lyxy-document[office-macos-arm]" scripts/lyxy_document_reader.py file.docx
Linux
uv run --with "lyxy-document[office-linux]" scripts/lyxy_document_reader.py file.docx
主机 Python 环境依赖安装
当 lyxy-runner-python 不可用时，需要根据文档类型手动安装依赖：
# DOCX 文档
pip install docling unstructured markitdown pypandoc-binary python-docx markdownify chardet
# XLSX 表格
pip install docling unstructured markitdown pandas tabulate chardet
# PPTX 演示文稿
pip install docling unstructured markitdown python-pptx markdownify chardet
# PDF 文档
pip install docling unstructured unstructured-paddleocr markitdown pypdf markdownify chardet
# HTML/URL 网页
pip install trafilatura domscribe markitdown html2text beautifulsoup4 httpx chardet
# 网页（需要 JS 渲染时，额外添加）
pip install pyppeteer selenium
# 安装所有文档类型支持
pip install docling unstructured unstructured-paddleocr markitdown pypandoc-binary python-docx python-pptx pandas tabulate pypdf markdownify trafilatura domscribe html2text beautifulsoup4 httpx pyppeteer selenium chardet
错误处理
| 错误信息 | 原因 | 解决 |
|---|---|---|
| 错误: input_path 不能为空 | 未提供输入 | 提供 file_path 或 URL |
| 错误: 不支持的文件类型 | 无对应 reader | 检查文件扩展名 |
| 所有解析方法均失败 | 所有解析器失败 | 检查文件是否损坏 |
| 错误: 无效的正则表达式 | 正则语法错误 | 检查正则语法 |
| 错误: 未找到匹配 | 搜索无结果 | 检查搜索词或正则 |
| ModuleNotFoundError: No module named 'xxx' | 缺少依赖 | 使用 lyxy-runner-python 或 pip 安装对应依赖 |