lanyuanxiaoyao
688933c228
- 移除 cleaner.py 中 beautifulsoup4 的顶层导入，改为完全依赖函数内动态导入 - 新增 README 快速开始章节，提供验证环境和基础测试命令 - 完善测试前置依赖说明，明确仅需 chardet 即可运行基础测试 - 更新所有测试命令，移除不必要的 --with beautifulsoup4
253 lines
6.4 KiB
Markdown
253 lines
6.4 KiB
Markdown
# lyxy-document
|
||
|
||
统一文档解析工具 - 将 DOCX、XLSX、PPTX、PDF、HTML/URL 转换为 Markdown
|
||
|
||
## 项目概述
|
||
|
||
面向 AI Skill 的统一文档解析工具，支持多种文档格式解析为 Markdown，提供全文输出、字数统计、标题提取、内容搜索等功能。
|
||
|
||
## 开发环境
|
||
|
||
- 使用 uv 运行脚本和测试，禁用主机 Python
|
||
- 依赖管理：使用 `uv run --with` 按需加载依赖
|
||
- 快速获取建议：使用 `-a/--advice` 参数查看执行命令
|
||
|
||
## 项目架构
|
||
|
||
```
|
||
scripts/
|
||
├── lyxy_document_reader.py # CLI 入口
|
||
├── config.py # 配置（含 DEPENDENCIES 依赖配置）
|
||
├── core/ # 核心模块
|
||
│ ├── parser.py # 解析调度
|
||
│ ├── advice_generator.py # --advice 执行建议生成器
|
||
│ ├── markdown.py # Markdown 工具
|
||
│ └── exceptions.py # 异常定义
|
||
├── readers/ # 格式阅读器
|
||
│ ├── base.py # Reader 基类
|
||
│ ├── docx/ # DOCX 解析器
|
||
│ ├── xlsx/ # XLSX 解析器
|
||
│ ├── pptx/ # PPTX 解析器
|
||
│ ├── pdf/ # PDF 解析器
|
||
│ └── html/ # HTML/URL 解析器
|
||
└── utils/ # 工具函数
|
||
├── file_detection.py # 文件检测
|
||
└── encoding_detection.py # 编码检测
|
||
|
||
tests/ # 测试套件
|
||
openspec/ # OpenSpec 规范文档
|
||
README.md # 本文档（开发者文档）
|
||
SKILL.md # AI Skill 文档
|
||
```
|
||
|
||
## 核心概念
|
||
|
||
### Reader 机制
|
||
|
||
每种文档格式对应一个 Reader 包，包含多个解析实现。Reader 基类定义 `supports()` 和 `parse()` 方法，解析器按顺序尝试，第一个成功的结果返回。
|
||
|
||
### 依赖配置 (config.DEPENDENCIES)
|
||
|
||
按文件类型和平台组织依赖配置：
|
||
|
||
```python
|
||
DEPENDENCIES = {
|
||
"pdf": {
|
||
"default": {
|
||
"python": None,
|
||
"dependencies": ["docling", "unstructured[pdf]", ...]
|
||
},
|
||
"Darwin-x86_64": {
|
||
"python": "3.12",
|
||
"dependencies": ["docling==2.40.0", ...]
|
||
}
|
||
},
|
||
...
|
||
}
|
||
```
|
||
|
||
### --advice 生成机制
|
||
|
||
`--advice` 参数根据文件扩展名识别类型，检测当前平台，从 `config.DEPENDENCIES` 读取对应配置，生成 `uv run --with` 和 `pip install` 命令。
|
||
|
||
## 快速开始
|
||
|
||
### 验证环境
|
||
|
||
首先验证项目可以正常运行：
|
||
|
||
```bash
|
||
# 测试 --advice 功能（仅需 chardet）
|
||
uv run --with chardet python scripts/lyxy_document_reader.py test.pdf --advice
|
||
```
|
||
|
||
### 运行基础测试
|
||
|
||
```bash
|
||
# 运行 CLI 测试（验证项目基本功能）
|
||
uv run \
|
||
--with pytest \
|
||
--with chardet \
|
||
pytest tests/test_cli/test_main.py::TestCLIAdviceOption -v
|
||
```
|
||
|
||
## 开发指南
|
||
|
||
### 测试前置依赖说明
|
||
|
||
由于 `HtmlReader` 模块在导入时会加载 `cleaner.py`，但 `cleaner.py` 中的第三方库已改为动态导入，因此仅需基础依赖：
|
||
- **chardet**：编码检测
|
||
|
||
`beautifulsoup4` 仅在实际使用 HTML 清理功能时才需要，模块导入时不依赖。
|
||
|
||
### 如何添加新的 Reader
|
||
|
||
1. 在 `scripts/readers/` 下创建新目录
|
||
2. 继承 `BaseReader` 实现 `supports()` 和 `parse()`
|
||
3. 在 `scripts/readers/__init__.py` 中注册
|
||
4. 在 `config.DEPENDENCIES` 中添加依赖配置
|
||
|
||
### 如何测试
|
||
|
||
项目包含完整的测试套件，覆盖 CLI 和所有 Reader 实现。根据测试类型使用对应的 `uv run --with` 命令。
|
||
|
||
#### 运行所有测试
|
||
```bash
|
||
uv run \
|
||
--with pytest \
|
||
--with pytest-cov \
|
||
--with chardet \
|
||
pytest
|
||
```
|
||
|
||
#### 测试 DOCX reader
|
||
```bash
|
||
uv run \
|
||
--with pytest \
|
||
--with docling \
|
||
--with "unstructured[docx]" \
|
||
--with "markitdown[docx]" \
|
||
--with pypandoc-binary \
|
||
--with python-docx \
|
||
--with markdownify \
|
||
--with chardet \
|
||
pytest tests/test_readers/test_docx/
|
||
```
|
||
|
||
#### 测试 XLSX reader
|
||
```bash
|
||
uv run \
|
||
--with pytest \
|
||
--with docling \
|
||
--with "unstructured[xlsx]" \
|
||
--with "markitdown[xlsx]" \
|
||
--with pandas \
|
||
--with tabulate \
|
||
--with chardet \
|
||
pytest tests/test_readers/test_xlsx/
|
||
```
|
||
|
||
#### 测试 PPTX reader
|
||
```bash
|
||
uv run \
|
||
--with pytest \
|
||
--with docling \
|
||
--with "unstructured[pptx]" \
|
||
--with "markitdown[pptx]" \
|
||
--with python-pptx \
|
||
--with markdownify \
|
||
--with chardet \
|
||
pytest tests/test_readers/test_pptx/
|
||
```
|
||
|
||
#### 测试 PDF reader
|
||
```bash
|
||
# 默认命令（macOS ARM、Linux、Windows）
|
||
uv run \
|
||
--with pytest \
|
||
--with docling \
|
||
--with "unstructured[pdf]" \
|
||
--with "markitdown[pdf]" \
|
||
--with pypdf \
|
||
--with markdownify \
|
||
--with chardet \
|
||
--with reportlab \
|
||
pytest tests/test_readers/test_pdf/
|
||
|
||
# macOS x86_64 (Intel) 特殊命令
|
||
uv run \
|
||
--python 3.12 \
|
||
--with pytest \
|
||
--with "docling==2.40.0" \
|
||
--with "docling-parse==4.0.0" \
|
||
--with "numpy<2" \
|
||
--with "markitdown[pdf]" \
|
||
--with pypdf \
|
||
--with markdownify \
|
||
--with chardet \
|
||
--with reportlab \
|
||
pytest tests/test_readers/test_pdf/
|
||
```
|
||
|
||
#### 测试 HTML reader
|
||
```bash
|
||
uv run \
|
||
--with pytest \
|
||
--with trafilatura \
|
||
--with domscribe \
|
||
--with markitdown \
|
||
--with html2text \
|
||
--with beautifulsoup4 \
|
||
--with httpx \
|
||
--with chardet \
|
||
pytest tests/test_readers/test_html/
|
||
```
|
||
|
||
#### 运行特定测试文件或方法
|
||
```bash
|
||
# 运行特定测试文件（CLI 测试仅需 chardet）
|
||
uv run \
|
||
--with pytest \
|
||
--with chardet \
|
||
pytest tests/test_cli/test_main.py
|
||
|
||
# 仅运行 --advice 相关测试（不需要额外依赖）
|
||
uv run \
|
||
--with pytest \
|
||
--with chardet \
|
||
pytest tests/test_cli/test_main.py::TestCLIAdviceOption
|
||
|
||
# 运行特定测试类或方法
|
||
uv run \
|
||
--with pytest \
|
||
--with docling \
|
||
--with chardet \
|
||
pytest tests/test_cli/test_main.py::TestCLIDefaultOutput::test_default_output_docx
|
||
```
|
||
|
||
#### 查看测试覆盖率
|
||
```bash
|
||
uv run \
|
||
--with pytest \
|
||
--with pytest-cov \
|
||
--with chardet \
|
||
pytest --cov=scripts --cov-report=term-missing
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
- 语言：仅中文（交流、注释、文档、代码）
|
||
- 模块文件：150-300 行
|
||
- 错误处理：自定义异常 + 清晰信息 + 位置上下文
|
||
- Git 提交：`类型: 简短描述`（feat/fix/refactor/docs/style/test/chore）
|
||
|
||
## 文档说明
|
||
|
||
- **README.md**（本文档）：面向项目开发者
|
||
- **SKILL.md**：面向 AI 使用的 Skill 文档
|
||
- **openspec/**：OpenSpec 规范文档
|
||
|
||
## 许可证
|
||
|
||
MIT License
|