# lyxy-document

统一文档解析工具 - 将 DOCX、XLSX、PPTX、PDF、HTML/URL 转换为 Markdown

## 开发环境

- 使用 uv 运行脚本和测试，禁用主机 Python
- 依赖管理：使用 `uv run --with` 按需加载依赖
- 快速获取建议：使用 `-a/--advice` 参数查看执行命令，无需手动查找依赖

## 项目结构

```
scripts/                    # 核心代码
├── core/                   # 核心模块
│   ├── advice_generator.py # 执行建议生成器（新增）
│   ├── parser.py           # 解析调度
│   ├── exceptions.py       # 异常定义
│   └── markdown.py         # Markdown 工具
├── readers/                # 格式阅读器
├── utils/                  # 工具函数
└── config.py               # 配置（含 DEPENDENCIES 依赖配置）
tests/                      # 测试
openspec/                   # 规范文档
skill/                      # SKILL 文档
```

## 开发工作流

使用 `uv run --with` 方式运行测试和开发工具：

```bash
# 运行测试（需要先安装 pytest）
uv run \
  --with pytest \
  --with pytest-cov \
  --with chardet \
  pytest

# 运行测试并查看覆盖率
uv run \
  --with pytest \
  --with pytest-cov \
  --with chardet \
  pytest --cov=scripts --cov-report=term-missing

# 运行特定测试文件
uv run \
  --with pytest \
  --with chardet \
  pytest tests/test_readers/test_docx/

# 运行特定测试类或方法
uv run \
  --with pytest \
  --with chardet \
  pytest tests/test_cli/test_main.py::TestCLIDefaultOutput::test_default_output_docx

# 代码格式化
uv run \
  --with black \
  --with isort \
  --with chardet \
  bash -c "black . && isort ."

# 类型检查
uv run \
  --with mypy \
  --with chardet \
  mypy .
```

**测试 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/
```

**测试 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 \
  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 \
  pytest tests/test_readers/test_pdf/
```

**测试其他格式**：

```bash
# XLSX reader
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
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/

# HTML reader
uv run \
  --with pytest \
  --with trafilatura \
  --with domscribe \
  --with markitdown \
  --with html2text \
  --with beautifulsoup4 \
  --with httpx \
  --with chardet \
  pytest tests/test_readers/test_html/
```

## 测试

项目包含完整的测试套件,覆盖 CLI 和所有 Reader 实现:

- **测试覆盖率**: 69%
- **测试数量**: 193 个测试
- **测试类型**:
  - CLI 功能测试（字数统计、行数统计、标题提取、搜索等）
  - Reader 解析测试（DOCX、PDF、HTML、PPTX、XLSX）
  - 多 Reader 实现测试（每种格式测试多个解析库）
  - 异常场景测试（文件不存在、空文件、损坏文件、特殊字符）
  - 编码测试（GBK、UTF-8 BOM 等）
  - 一致性测试（验证不同 Reader 解析结果的一致性）

运行测试前，请根据测试类型使用 `uv run --with` 安装对应的依赖包。详见上方的"开发工作流"章节。


## 代码规范

- 语言：仅中文（交流、注释、文档、代码）
- 模块文件：150-300 行
- 错误处理：自定义异常 + 清晰信息 + 位置上下文
- Git 提交：类型: 简短描述（feat/fix/refactor/docs/style/test/chore）

## Skill 文档规范

skill/SKILL.md 面向 AI 用户，必须遵循 Claude Skill 构建指南的最佳实践：

### YAML frontmatter

- **name**: kebab-case 格式
- **description**: 包含功能说明、触发词、文件类型、典型任务
- **license**: MIT
- **metadata**: 包含 version、author
- **compatibility**: 说明 Python 版本要求和依赖情况

### 文档章节结构

1. **Purpose**: 说明统一入口和双路径执行策略
2. **When to Use**: 典型场景和触发词列表（中英文、文件扩展名）
3. **Quick Reference**: 命令参数表格
4. **Workflow**: 4 步工作流程（检测环境、识别类型、执行解析、输出结果）
5. **使用示例**: 各文档类型的基本用法和高级用法
6. **错误处理**: 常见错误及解决方案
7. **References**: 指向项目文档的链接

### 依赖管理

- 使用 `uv run --with` 方式按需加载依赖
- 必须使用具体的 pip 包名
- 使用 `-a/--advice` 参数可快速获取针对具体文件的执行命令

## 解析器架构

### DOCX
docling、unstructured、pypandoc-binary、MarkItDown、python-docx、XML

### XLSX
docling、unstructured、MarkItDown、pandas、XML

### PPTX
docling、unstructured、MarkItDown、python-pptx、XML

### PDF（OCR 优先）
docling OCR、unstructured OCR、docling、unstructured、MarkItDown、pypdf

### HTML/URL
trafilatura、domscribe、MarkItDown、html2text

## 许可证

MIT License