lanyuanxiaoyao
dfe6904f4c
为不同平台提供特定的依赖 extras，解决 macOS x86_64 的依赖兼容性问题。 - 添加平台特定的 PDF 解析 extras：pdf-win, pdf-macos-intel, pdf-macos-arm, pdf-linux - 添加平台特定的 Office 文档 extras：office-win, office-macos-intel, office-macos-arm, office-linux - macOS x86_64 使用硬编码版本：docling==2.40.0, docling-parse==4.0.0 - 移除通用的 pdf 和 office extras，强制用户选择平台 - 更新 SKILL.md 添加详细的多平台依赖安装指南 - 更新 README.md 添加平台特定安装说明 - 在 .gitignore 中添加 uv.lock - 删除现有的 uv.lock 文件 - 创建 multi-platform-dependencies 规范文档
lyxy-document
统一文档解析工具 - 将 DOCX、XLSX、PPTX、PDF、HTML/URL 转换为 Markdown
开发环境
- 使用 uv 管理依赖，禁用主机 Python
- 依赖声明：pyproject.toml
- 安装：根据平台选择对应的 extras（详见 SKILL.md）
- macOS x86_64 (Intel):
uv pip install -e ".[pdf-macos-intel]" - macOS arm64 (Apple Silicon):
uv pip install -e ".[pdf-macos-arm]" - Windows:
uv pip install -e ".[pdf-win]" - Linux:
uv pip install -e ".[pdf-linux]"
- macOS x86_64 (Intel):
项目结构
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 解析结果的一致性）
运行测试前确保已安装所有依赖（根据你的平台选择对应的 extras）：
# macOS x86_64 (Intel) 示例
uv pip install -e ".[office-macos-intel]"
# 其他平台请参考 SKILL.md 的"多平台依赖安装指南"
代码规范
- 语言：仅中文（交流、注释、文档、代码）
- 模块文件：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