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:
77
openspec/specs/uv-with-dependency-management/spec.md
Normal file
77
openspec/specs/uv-with-dependency-management/spec.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# UV --with 依赖管理
|
||||
|
||||
## Purpose
|
||||
|
||||
基于文档的依赖管理方式,使用 `uv run --with` 按需加载依赖。移除 pyproject.toml 和 uv.lock,通过 SKILL.md 和 README.md 提供完整的依赖说明和命令示例。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 文档驱动的依赖声明
|
||||
系统必须在 SKILL.md 和 README.md 中明确说明每种文档格式和平台所需的依赖包。
|
||||
|
||||
#### Scenario: SKILL.md 包含完整的依赖命令
|
||||
- **WHEN** AI 或用户阅读 SKILL.md
|
||||
- **THEN** 文档必须为每种文档格式(DOCX/XLSX/PPTX/PDF/HTML)和平台提供完整的 `uv run --with` 命令示例
|
||||
- **AND** 命令必须包含所有必需的依赖包
|
||||
|
||||
#### Scenario: README.md 包含开发依赖速查表
|
||||
- **WHEN** 开发者阅读 README.md
|
||||
- **THEN** 文档必须提供测试每种格式的 `uv run --with` 命令示例
|
||||
- **AND** 必须包含特殊平台的版本约束说明(如 macOS Intel)
|
||||
|
||||
### Requirement: 按需加载依赖
|
||||
系统必须使用 `uv run --with` 方式按需加载依赖,无需预先安装 extras 组合。
|
||||
|
||||
#### Scenario: 运行 PDF 解析
|
||||
- **WHEN** 用户执行 `uv run --with docling --with pypdf --with chardet scripts/lyxy_document_reader.py file.pdf`
|
||||
- **THEN** 系统必须自动安装这些依赖(如果尚未安装)
|
||||
- **AND** 必须成功执行脚本
|
||||
|
||||
#### Scenario: 测试 DOCX reader
|
||||
- **WHEN** 开发者执行 `uv run --with docling --with python-docx ... pytest tests/test_readers/test_docx/`
|
||||
- **THEN** 系统必须只安装指定的依赖
|
||||
- **AND** 必须成功运行测试
|
||||
|
||||
### Requirement: 平台特定版本约束
|
||||
系统必须在文档和命令中明确说明特殊平台的版本约束。
|
||||
|
||||
#### Scenario: macOS Intel 的 PDF 解析
|
||||
- **WHEN** 用户在 macOS x86_64 平台阅读 PDF 解析说明
|
||||
- **THEN** 文档必须明确说明需要 Python 3.12
|
||||
- **AND** 命令必须包含版本约束:`--with "docling==2.40.0" --with "docling-parse==4.0.0" --with "numpy<2"`
|
||||
- **AND** 必须说明原因:docling-parse 5.x 无 x86_64 wheel
|
||||
|
||||
#### Scenario: 其他平台使用最新版本
|
||||
- **WHEN** 用户在 macOS ARM 或 Linux 平台
|
||||
- **THEN** 命令可以省略版本号,使用最新兼容版本
|
||||
- **AND** 文档必须说明这是可行的
|
||||
|
||||
### Requirement: 移除 pyproject.toml
|
||||
系统必须移除 pyproject.toml 文件,不再使用 extras 声明依赖。
|
||||
|
||||
#### Scenario: 项目根目录不包含 pyproject.toml
|
||||
- **WHEN** 用户查看项目根目录
|
||||
- **THEN** 系统必须不包含 pyproject.toml 文件
|
||||
|
||||
#### Scenario: 依赖说明不在 pyproject.toml
|
||||
- **WHEN** 用户尝试查找依赖声明
|
||||
- **THEN** 系统必须引导用户查阅 SKILL.md 或 README.md
|
||||
|
||||
### Requirement: 移除 uv.lock
|
||||
系统必须移除 uv.lock 文件,每次 `uv run` 都是全新的依赖解析。
|
||||
|
||||
#### Scenario: 项目不包含 uv.lock
|
||||
- **WHEN** 用户查看项目根目录
|
||||
- **THEN** 系统必须不包含 uv.lock 文件
|
||||
|
||||
#### Scenario: 依赖版本由文档说明
|
||||
- **WHEN** 用户需要了解依赖版本约束
|
||||
- **THEN** 系统必须在 SKILL.md 或 README.md 中说明
|
||||
- **AND** 不依赖 uv.lock 锁定版本
|
||||
|
||||
### Requirement: 核心 chardet 依赖
|
||||
系统必须在所有 `uv run --with` 命令中包含 chardet 依赖。
|
||||
|
||||
#### Scenario: 所有格式都包含 chardet
|
||||
- **WHEN** 用户查阅任何格式的依赖命令
|
||||
- **THEN** 命令必须包含 `--with chardet`
|
||||
Reference in New Issue
Block a user