lanyuanxiaoyao
d3fd6de965
- 添加 Windows 平台依赖验证结果到 docs/upgrade-deps-prompt.md - 更新 openspec 配置，移除 pyproject.toml 相关说明 - 同步 upgrade-deps 变更的 delta specs 到主规范 - multi-platform-dependencies: 新增平台验证和版本文档化要求 - uv-with-dependency-management: 新增命令验证和版本一致性要求 - 归档 upgrade-deps 变更至 openspec/changes/archive/2026-03-19-upgrade-deps/
110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
# 多平台依赖管理
|
||
|
||
## Purpose
|
||
|
||
为不同平台提供特定的依赖配置，解决平台特定的依赖兼容性问题（如 macOS x86_64 的 docling-parse 版本限制）。通过 `uv run --with` 方式按需加载依赖，在文档中提供平台特定的命令示例。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 平台检测文档
|
||
系统必须在 SKILL.md 中提供平台检测方法和平台特定的 `uv run --with` 命令示例。
|
||
|
||
#### 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
|
||
- 提供完整的 `uv run --python 3.12 --with "docling==2.40.0" --with "docling-parse==4.0.0" --with "numpy<2" ...` 命令示例
|
||
- unstructured 在 Darwin-x86_64 平台不可用，已从配置中移除
|
||
|
||
#### Scenario: 每个平台的运行命令
|
||
- **WHEN** 用户阅读 SKILL.md
|
||
- **THEN** 系统必须为每个平台（Windows/macOS Intel/macOS ARM/Linux）和每种文档格式提供清晰的 `uv run --with` 命令示例
|
||
- **AND** 命令必须包含所有必需的依赖包
|
||
|
||
### Requirement: 依赖配置结构
|
||
config.py 中的 DEPENDENCIES 配置使用字典结构，保持简单直接以便于在不同平台进行细致调整。
|
||
|
||
#### Scenario: 配置数据格式不变
|
||
- **WHEN** 代码访问 config.DEPENDENCIES["pdf"]["default"]
|
||
- **THEN** 返回的数据结构保持不变
|
||
- **AND** 包含 "python" 和 "dependencies" 字段
|
||
|
||
#### Scenario: 所有文件类型都有 Darwin-x86_64 配置
|
||
- **WHEN** 查看 config.DEPENDENCIES
|
||
- **THEN** pdf/docx/xlsx/pptx/xls/ppt 都有 "Darwin-x86_64" 平台配置
|
||
- **AND** Darwin-x86_64 配置中不包含 unstructured 相关依赖
|
||
|
||
### Requirement: 依赖版本管理
|
||
所有依赖必须指定版本号；default 平台使用最新版本作为标杆；default 配置在当前平台测试失败时，在特定平台配置中探索可运行的最新版本；default 配置的 python 版本必须为 None（使用默认 python 版本），仅在特定平台配置中可指定 python 版本；当前版本截止时间为 2026-03-18。
|
||
|
||
#### Scenario: default 平台使用最新版本且 python 为 None
|
||
- **WHEN** 查看 config.DEPENDENCIES 中 default 配置
|
||
- **THEN** python 版本为 None
|
||
- **AND** 所有依赖都有明确的版本号
|
||
- **AND** 使用截止 2026-03-18 的最新版本
|
||
|
||
#### Scenario: 特定平台在 default 失败时探索可运行版本
|
||
- **WHEN** default 配置在当前平台测试失败
|
||
- **THEN** 在特定平台配置中探索可运行的最新版本
|
||
|
||
### 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` 文件，每次 `uv run` 都是全新的依赖解析。
|
||
|
||
#### Scenario: 移除 uv.lock 文件
|
||
- **WHEN** 用户查看项目根目录
|
||
- **THEN** 系统必须不包含 uv.lock 文件
|
||
- **AND** 依赖版本由文档中的版本约束说明
|
||
|
||
#### Scenario: gitignore 配置（可选）
|
||
- **WHEN** 用户查看项目的 `.gitignore` 文件
|
||
- **THEN** 系统可以包含 `uv.lock` 条目以确保不会误提交（如果用户重新创建了 lock 文件）
|
||
|
||
### Requirement: 当前平台依赖验证
|
||
系统必须在当前平台上验证 `config.DEPENDENCIES` 的 default 配置是否可以正常工作。
|
||
|
||
#### Scenario: 验证 default 配置可用性
|
||
- **WHEN** 在当前平台运行测试
|
||
- **THEN** 必须验证 default 配置的所有依赖都可以正确安装
|
||
- **AND** 必须验证所有文档类型的解析功能正常工作
|
||
|
||
#### Scenario: 记录验证结果
|
||
- **WHEN** 完成当前平台的依赖验证
|
||
- **THEN** 必须在 `docs/upgrade-deps-prompt.md` 中记录验证结果
|
||
- **AND** 必须记录当前平台信息和测试通过日期
|
||
|
||
### Requirement: 依赖版本文档化
|
||
系统必须在 `docs/upgrade-deps-prompt.md` 中记录当前所有依赖的版本号和更新时间戳。
|
||
|
||
#### Scenario: 版本记录包含所有依赖
|
||
- **WHEN** 查看 `docs/upgrade-deps-prompt.md`
|
||
- **THEN** 文档必须包含所有文件类型（pdf/docx/xlsx/pptx/html/xls/ppt/doc）的所有依赖版本号
|
||
- **AND** 必须标注版本更新时间戳
|