docs: 移除 pyproject.toml,改为 uv run --with 依赖管理方式
- 移除 pyproject.toml 和 uv.lock - 更新 SKILL.md:使用 uv run --with 按需加载依赖 - 更新 README.md:添加多行格式的测试命令 - 更新项目规范文档 - 修复脚本:支持从任意位置执行 - 新增 uv-with-dependency-management 规范
This commit is contained in:
@@ -2,45 +2,31 @@
|
||||
|
||||
## Purpose
|
||||
|
||||
为不同平台提供特定的依赖配置,解决平台特定的依赖兼容性问题(如 macOS x86_64 的 docling-parse 版本限制)。通过强制用户选择平台特定的 extras,确保依赖在不同平台上都能正常安装和运行。
|
||||
为不同平台提供特定的依赖配置,解决平台特定的依赖兼容性问题(如 macOS x86_64 的 docling-parse 版本限制)。通过 `uv run --with` 方式按需加载依赖,在文档中提供平台特定的命令示例。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 平台特定的依赖配置
|
||||
系统必须在 `pyproject.toml` 中为不同平台提供特定的依赖 extras。
|
||||
### Requirement: 平台检测文档
|
||||
系统必须在 SKILL.md 中提供平台检测方法和平台特定的 `uv run --with` 命令示例。
|
||||
|
||||
#### 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: 平台检测命令
|
||||
- **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** 用户安装 `pdf-macos-intel` extra
|
||||
- **THEN** 系统必须使用以下硬编码版本:
|
||||
- `docling==2.40.0`
|
||||
- `docling-parse==4.0.0`
|
||||
#### Scenario: macOS x86_64 特殊说明
|
||||
- **WHEN** 用户在 macOS x86_64 平台阅读 PDF 解析依赖的安装说明
|
||||
- **THEN** 系统必须明确说明以下特殊要求:
|
||||
- 必须使用 Python 3.12
|
||||
- `docling-parse` 5.x 无 x86_64 wheel,必须使用 4.0.0
|
||||
- 提供完整的 `uv run --python 3.12 --with "docling==2.40.0" --with "docling-parse==4.0.0" --with "numpy<2" ...` 命令示例
|
||||
|
||||
#### 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
|
||||
#### Scenario: 每个平台的运行命令
|
||||
- **WHEN** 用户阅读 SKILL.md
|
||||
- **THEN** 系统必须为每个平台(Windows/macOS Intel/macOS ARM/Linux)和每种文档格式提供清晰的 `uv run --with` 命令示例
|
||||
- **AND** 命令必须包含所有必需的依赖包
|
||||
|
||||
### Requirement: 平台检测文档
|
||||
系统必须在 `SKILL.md` 中提供平台检测方法和平台特定的安装指南。
|
||||
@@ -63,24 +49,13 @@
|
||||
- **THEN** 系统必须为每个平台(Windows/macOS Intel/macOS ARM/Linux)提供清晰的 `uv run` 命令示例
|
||||
|
||||
### Requirement: Lock 文件管理
|
||||
系统必须忽略 `uv.lock` 文件,不将其提交到版本控制。
|
||||
系统必须移除 `uv.lock` 文件,每次 `uv run` 都是全新的依赖解析。
|
||||
|
||||
#### Scenario: gitignore 配置
|
||||
#### Scenario: 移除 uv.lock 文件
|
||||
- **WHEN** 用户查看项目根目录
|
||||
- **THEN** 系统必须不包含 uv.lock 文件
|
||||
- **AND** 依赖版本由文档中的版本约束说明
|
||||
|
||||
#### 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** 系统优先选择简单清晰的重复声明,而不是复杂的依赖引用或约束文件
|
||||
- **THEN** 系统可以包含 `uv.lock` 条目以确保不会误提交(如果用户重新创建了 lock 文件)
|
||||
|
||||
Reference in New Issue
Block a user