lanyuanxiaoyao/lyxy-document
1
0
Fork 0
Code Releases Activity
Files
6e75c99d5be462d500c4e50d0567ec99598e87a8
lyxy-document/SKILL.md
lanyuanxiaoyao c140bda66b docs: 移除 pyproject.toml，改为 uv run --with 依赖管理方式 
- 移除 pyproject.toml 和 uv.lock
- 更新 SKILL.md：使用 uv run --with 按需加载依赖
- 更新 README.md：添加多行格式的测试命令
- 更新项目规范文档
- 修复脚本：支持从任意位置执行
- 新增 uv-with-dependency-management 规范
2026-03-09 14:14:33 +08:00

6.8 KiB
Raw Blame History

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
version author
1.0 lyxy
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 按需加载依赖包：

# 根据文档类型选择对应的依赖包
uv run --with <依赖包1> --with <依赖包2> ... \
     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

依赖安装指南

使用 uv run --with 方式按需加载解析器依赖。以下命令适用于大多数平台（macOS ARM、Linux、Windows）。

平台检测

在遇到问题时，可以检测你的平台：

# 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）：

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 和特定版本的依赖：

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 解析

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 解析

uv run --with docling --with "unstructured[xlsx]" --with "markitdown[xlsx]" --with pandas --with tabulate --with chardet scripts/lyxy_document_reader.py file.xlsx

PPTX 解析

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 解析

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 渲染的网页，额外添加：

--with pyppeteer --with selenium

错误处理

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