docs: 移除 pyproject.toml,改为 uv run --with 依赖管理方式

- 移除 pyproject.toml 和 uv.lock
- 更新 SKILL.md:使用 uv run --with 按需加载依赖
- 更新 README.md:添加多行格式的测试命令
- 更新项目规范文档
- 修复脚本:支持从任意位置执行
- 新增 uv-with-dependency-management 规范
This commit is contained in:
2026-03-09 14:14:33 +08:00
parent dfe6904f4c
commit c140bda66b
7 changed files with 267 additions and 292 deletions

117
SKILL.md
View File

@@ -5,7 +5,7 @@ license: MIT
metadata:
version: "1.0"
author: lyxy
compatibility: 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)。详见"多平台依赖安装指南"章节。
compatibility: Requires Python 3.11+. 使用 uv run --with 方式按需加载依赖,详见"依赖安装指南"章节。
---
# 统一文档解析 Skill
@@ -16,7 +16,7 @@ compatibility: Requires Python 3.11+. 优先使用 lyxy-runner-python skill 执
**统一入口**:使用 `scripts/lyxy_document_reader.py` 作为统一的命令行入口,自动识别文件类型并执行解析。
**双路径执行**此 skill 必须优先使用 **lyxy-runner-python skill** 执行脚本,该 skill 会自动管理 uv 隔离环境和依赖。当 lyxy-runner-python 不可用时,回退到主机 Python 环境执行
**依赖管理**使用 `uv run --with` 方式按需加载解析器依赖。每次执行时根据文档类型指定对应的依赖包
**支持的文档类型**
- **DOCX**Word 文档
@@ -78,17 +78,16 @@ compatibility: Requires Python 3.11+. 优先使用 lyxy-runner-python skill 执
### 基本语法
```bash
# 方式 1使用 lyxy-runner-python推荐
# lyxy-runner-python 会自动分析脚本依赖并使用 uv --with 安装
# AI 只需执行:
python scripts/lyxy_document_reader.py <文件路径或URL>
使用 `uv run --with` 按需加载依赖包:
# 方式 2回退到主机 Python需要预先手动安装依赖
# 根据文档类型安装对应依赖后执行:
python scripts/lyxy_document_reader.py <文件路径或URL>
```bash
# 根据文档类型选择对应依赖
uv run --with <依赖包1> --with <依赖包2> ... \
scripts/lyxy_document_reader.py <文件路径或URL>
```
具体的依赖包列表请参考下方的"依赖安装指南"。
### 使用示例
```bash
@@ -117,13 +116,13 @@ 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
使用 `uv run --with` 方式按需加载解析器依赖。以下命令适用于大多数平台macOS ARM、Linux、Windows
#### 平台检测
使用前,请先检测你的平台:
遇到问题时,可以检测你的平台:
```bash
# macOS / Linux
@@ -137,92 +136,52 @@ $env:OS # 或检查环境变量
python -c "import platform; print(f'{platform.system()}-{platform.machine()}')"
```
#### PDF 解析依赖
#### PDF 解析
根据你的平台选择对应的安装命令
**默认命令**(适用于 macOS ARM、Linux、Windows
**Windows x86_64**
```bash
uv run --with "lyxy-document[pdf-win]" scripts/lyxy_document_reader.py file.pdf
```
- 依赖docling, unstructured, PaddleOCR
- Python>=3.11
- 特殊说明:无
**macOS x86_64 (Intel)**
⚠️ **特殊平台**:需要特定版本配置
```bash
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-parse` 5.x 无 x86_64 wheel必须使用 4.0.0
- `easyocr`docling 的 OCR 后端)与 NumPy 2.x 不兼容
**macOS arm64 (Apple Silicon)**
```bash
uv run --with "lyxy-document[pdf-macos-arm]" scripts/lyxy_document_reader.py file.pdf
```
- 依赖docling, unstructured
- Python>=3.11
- 特殊说明:无
**Linux**
```bash
uv run --with "lyxy-document[pdf-linux]" scripts/lyxy_document_reader.py file.pdf
```
- 依赖docling, unstructured
- Python>=3.11
- 特殊说明:无
#### Office 文档依赖
**Windows x86_64**
```bash
uv run --with "lyxy-document[office-win]" scripts/lyxy_document_reader.py file.docx
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)**
**macOS x86_64 (Intel) 特殊说明**
此平台需要使用 Python 3.12 和特定版本的依赖:
```bash
uv run --python 3.12 --with "lyxy-document[office-macos-intel]" scripts/lyxy_document_reader.py file.docx
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
```
**macOS arm64 (Apple Silicon)**
原因:`docling-parse` 5.x 无 x86_64 wheel必须使用 4.0.0`easyocr`docling 的 OCR 后端)与 NumPy 2.x 不兼容。
#### DOCX 解析
```bash
uv run --with "lyxy-document[office-macos-arm]" scripts/lyxy_document_reader.py file.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
```
**Linux**
#### XLSX 解析
```bash
uv run --with "lyxy-document[office-linux]" scripts/lyxy_document_reader.py file.docx
uv run --with docling --with "unstructured[xlsx]" --with "markitdown[xlsx]" --with pandas --with tabulate --with chardet scripts/lyxy_document_reader.py file.xlsx
```
### 主机 Python 环境依赖安装
当 lyxy-runner-python 不可用时,需要根据文档类型手动安装依赖:
#### PPTX 解析
```bash
# DOCX 文档
pip install docling unstructured markitdown pypandoc-binary python-docx markdownify chardet
uv run --with docling --with "unstructured[pptx]" --with "markitdown[pptx]" --with python-pptx --with markdownify --with chardet scripts/lyxy_document_reader.py file.pptx
```
# XLSX 表格
pip install docling unstructured markitdown pandas tabulate chardet
#### HTML/URL 解析
# PPTX 演示文稿
pip install docling unstructured markitdown python-pptx markdownify chardet
```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
```
# PDF 文档
pip install docling unstructured unstructured-paddleocr markitdown pypdf markdownify chardet
**需要 JavaScript 渲染的网页**,额外添加:
# 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
```bash
--with pyppeteer --with selenium
```
## 错误处理