Files

lanyuanxiaoyao 7eab1dcef1 test: 添加全面的测试套件，覆盖所有 Reader 实现

- 测试数量从 83 个增加到 193 个 (+132%)
- 代码覆盖率从 48% 提升到 69% (+44%)
- 为每种文档格式的所有 Reader 实现创建独立测试
- 添加跨 Reader 的一致性验证测试
- 新增 4 个测试规范 (cli-testing, exception-testing, reader-testing, test-fixtures)
- 更新 README 测试统计信息

测试覆盖:
- DOCX: python-docx, markitdown, docling, native-xml, pypandoc, unstructured
- PDF: pypdf, markitdown, docling, docling-ocr, unstructured, unstructured-ocr
- HTML: html2text, markitdown, trafilatura, domscribe
- PPTX: python-pptx, markitdown, docling, native-xml, unstructured
- XLSX: pandas, markitdown, docling, native-xml, unstructured
- CLI: 所有命令行选项和错误处理

所有 193 个测试通过。

2026-03-08 22:20:21 +08:00

3.4 KiB

Raw Blame History

lyxy-document

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

开发环境

使用 uv 管理依赖，禁用主机 Python
依赖声明：pyproject.toml
安装：uv sync

项目结构

scripts/          # 核心代码
├── core/         # 核心模块（解析调度、异常、Markdown 工具）
├── readers/      # 格式阅读器
└── utils/        # 工具函数
tests/            # 测试
openspec/         # 规范文档
skill/            # SKILL 文档

开发工作流

# 运行测试
uv run pytest

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

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

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

# 代码格式化
uv run black .
uv run isort .

# 类型检查
uv run mypy .

测试

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

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

运行测试前确保已安装所有依赖：

uv sync

代码规范

语言：仅中文（交流、注释、文档、代码）
模块文件：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 版本要求和依赖情况

文档章节结构

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

双路径执行策略

优先: 使用 lyxy-runner-python skill（自动管理依赖）
回退: 主机 Python 环境（需手动安装依赖）

依赖说明

必须使用具体的 pip 包名
不能使用 lyxy-document[xxx] 形式（发布时没有 pyproject.toml）
按文档类型分组说明

解析器架构

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

3.4 KiB Raw Blame History Unescape Escape