lyxy-document/README.md

# lyxy-document

帮助 AI 工具读取转换文档到 Markdown 的统一工具。

## 功能特性

支持多种文档格式的解析，统一转换为 Markdown：

- **Office 文档**: DOCX、XLSX、PPTX
- **PDF 文档**: 支持 OCR 优先解析
- **HTML/URL**: 支持本地 HTML 文件和在线 URL 下载解析

## 安装

### 基础安装

```bash
uv add lyxy-document
```

### 可选依赖分组

按文件类型按需安装：

```bash
# 仅安装 DOCX 支持
uv add "lyxy-document[docx]"

# 仅安装 XLSX 支持
uv add "lyxy-document[xlsx]"

# 仅安装 PPTX 支持
uv add "lyxy-document[pptx]"

# 仅安装 PDF 支持
uv add "lyxy-document[pdf]"

# 仅安装 HTML 支持
uv add "lyxy-document[html]"

# 仅安装 HTTP/URL 下载支持
uv add "lyxy-document[http]"
```

组合分组：

```bash
# 安装所有 Office 格式支持
uv add "lyxy-document[office]"

# 安装 Web（HTML + HTTP）支持
uv add "lyxy-document[web]"

# 安装全部功能
uv add "lyxy-document[full]"

# 安装开发依赖
uv add --dev "lyxy-document[dev]"
```

## 使用方法

### 命令行使用

```bash
# 解析文档为 Markdown
uv run lyxy-document-reader document.docx

# 统计字数
uv run lyxy-document-reader document.docx -c

# 统计行数
uv run lyxy-document-reader document.docx -l

# 提取所有标题
uv run lyxy-document-reader document.docx -t

# 提取指定标题及其内容
uv run lyxy-document-reader document.docx -tc "标题名称"

# 搜索文档内容（支持正则表达式）
uv run lyxy-document-reader document.docx -s "搜索关键词" -n 2
```

### Python API 使用

```python
from core import parse_input, process_content
from readers import READERS

# 实例化 readers
readers = [ReaderCls() for ReaderCls in READERS]

# 解析文件
content, failures = parse_input("document.docx", readers)

if content:
    # 处理内容（移除图片、规范化空白）
    content = process_content(content)
    print(content)
else:
    print("解析失败:")
    for failure in failures:
        print(failure)
```

## 项目结构

```
lyxy-document/
├── lyxy_document_reader.py    # 统一 CLI 入口
├── core/                       # 核心模块
│   ├── exceptions.py           # 自定义异常体系
│   ├── markdown.py             # Markdown 工具函数
│   └── parser.py               # 统一解析调度器
├── readers/                    # 格式阅读器
│   ├── base.py                 # Reader 基类
│   ├── docx/                   # DOCX 阅读器
│   ├── xlsx/                   # XLSX 阅读器
│   ├── pptx/                   # PPTX 阅读器
│   ├── pdf/                    # PDF 阅读器
│   └── html/                   # HTML/URL 阅读器
├── utils/                      # 工具函数
│   └── file_detection.py       # 文件类型检测
└── tests/                      # 测试
```

## 解析器优先级

### DOCX
1. docling
2. unstructured
3. pypandoc-binary
4. MarkItDown
5. python-docx
6. XML 原生解析

### XLSX
1. docling
2. unstructured
3. MarkItDown
4. pandas
5. XML 原生解析

### PPTX
1. docling
2. unstructured
3. MarkItDown
4. python-pptx
5. XML 原生解析

### PDF（OCR 优先）
1. docling OCR
2. unstructured OCR
3. docling
4. unstructured
5. MarkItDown
6. pypdf

### HTML/URL
1. trafilatura
2. domscribe
3. MarkItDown
4. html2text

## 开发

### 安装开发依赖

```bash
uv sync --dev
```

### 运行测试

```bash
uv run pytest
```

### 代码格式化

```bash
uv run black .
uv run isort .
```

### 类型检查

```bash
uv run mypy .
```

## 许可证

MIT License