lanyuanxiaoyao/lyxy-document
1
0
Fork 0
Code Releases Activity
Files
dfe6904f4c49aba93af3bda69afc464e88c45d2d
lyxy-document/openspec/specs/multi-platform-dependencies/spec.md
lanyuanxiaoyao dfe6904f4c feat: 添加多平台依赖支持 
为不同平台提供特定的依赖 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 规范文档
2026-03-09 10:49:53 +08:00

3.9 KiB
Raw Blame History

多平台依赖管理

Purpose

为不同平台提供特定的依赖配置，解决平台特定的依赖兼容性问题（如 macOS x86_64 的 docling-parse 版本限制）。通过强制用户选择平台特定的 extras，确保依赖在不同平台上都能正常安装和运行。

Requirements

Requirement: 平台特定的依赖配置

系统必须在 pyproject.toml 中为不同平台提供特定的依赖 extras。

Scenario: PDF 解析的平台特定 extras

  • WHEN 用户查看 pyproject.toml 中的 [project.optional-dependencies] 配置
  • THEN 系统必须提供以下 PDF 解析 extras：
    • pdf-win: Windows x86_64 平台的 PDF 解析依赖
    • pdf-macos-intel: macOS x86_64 (Intel) 平台的 PDF 解析依赖
    • pdf-macos-arm: macOS arm64 (Apple Silicon) 平台的 PDF 解析依赖
    • pdf-linux: Linux 平台的 PDF 解析依赖

Scenario: macOS x86_64 的特殊版本约束

  • WHEN 用户安装 pdf-macos-intel extra
  • THEN 系统必须使用以下硬编码版本：
    • docling==2.40.0
    • docling-parse==4.0.0

Scenario: Office 文档的平台特定 extras

  • WHEN 用户查看 pyproject.toml 中的 Office 文档 extras
  • THEN 系统必须提供以下组合 extras：
    • office-win: Windows x86_64 平台的完整 Office 文档依赖
    • office-macos-intel: macOS x86_64 (Intel) 平台的完整 Office 文档依赖
    • office-macos-arm: macOS arm64 (Apple Silicon) 平台的完整 Office 文档依赖
    • office-linux: Linux 平台的完整 Office 文档依赖

Requirement: 移除通用平台 extras

系统必须移除通用的平台无关 extras，强制用户明确选择平台。

Scenario: PDF extra 不存在

  • WHEN 用户尝试安装 lyxy-document[pdf] extra
  • THEN 系统必须报错或提示用户选择平台特定的 extra

Scenario: Office extra 不存在

  • WHEN 用户尝试安装 lyxy-document[office] extra
  • THEN 系统必须报错或提示用户选择平台特定的 extra

Requirement: 平台检测文档

系统必须在 SKILL.md 中提供平台检测方法和平台特定的安装指南。

Scenario: 平台检测命令

  • WHEN 用户阅读 SKILL.md 中的多平台依赖安装指南
  • THEN 系统必须提供以下平台的检测命令：
    • macOS / Linux: uname -m 和 uname -s
    • Windows: PowerShell 环境变量检测
    • Python 跨平台检测: import platform; print(f'{platform.system()}-{platform.machine()}')

Scenario: macOS x86_64 特殊说明

  • WHEN 用户在 macOS x86_64 平台阅读 PDF 解析依赖的安装说明
  • THEN 系统必须明确说明以下特殊要求：
    • 必须使用 Python 3.12
    • docling-parse 5.x 无 x86_64 wheel，必须使用 4.0.0

Scenario: 每个平台的安装命令

  • WHEN 用户阅读 SKILL.md
  • THEN 系统必须为每个平台（Windows/macOS Intel/macOS ARM/Linux）提供清晰的 uv run 命令示例

Requirement: Lock 文件管理

系统必须忽略 uv.lock 文件，不将其提交到版本控制。

Scenario: gitignore 配置

  • WHEN 用户查看项目的 .gitignore 文件
  • THEN 系统必须在文件中包含 uv.lock 条目

Scenario: 依赖安装灵活性

  • WHEN 用户使用 uv run --with 安装依赖
  • THEN 系统必须能够根据当前平台动态解析依赖，而不依赖预先锁定的 lock 文件

Requirement: 依赖重复但清晰

系统允许在多个平台 extras 中重复声明相同的依赖，以保持清晰和简单。

Scenario: 重复声明基础依赖

  • WHEN 用户查看不同的平台 extras
  • THEN 系统可以在每个 extra 中重复声明基础依赖（如 markitdown[pdf]、pypdf、markdownify）
  • AND 这些重复声明必须版本一致

Scenario: 维护简单性优先

  • WHEN 开发者需要修改依赖版本
  • THEN 系统优先选择简单清晰的重复声明，而不是复杂的依赖引用或约束文件
View Git Blame Copy Permalink