lanyuanxiaoyao/lyxy-document
1
0
Fork 0
Code Releases Activity
Files
master
lyxy-document/openspec/specs/uv-with-dependency-management/spec.md
lanyuanxiaoyao d3fd6de965 docs: 完成 Windows 平台依赖验证并同步规范 
- 添加 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/
2026-03-19 00:21:10 +08:00

4.5 KiB
Raw Permalink Blame History

UV --with 依赖管理

Purpose

基于文档的依赖管理方式，使用 uv run --with 按需加载依赖。移除 pyproject.toml 和 uv.lock，通过 SKILL.md 和 README.md 提供完整的依赖说明和命令示例。

Requirements

Requirement: 文档驱动的依赖声明

系统必须在 SKILL.md 和 README.md 中明确说明每种文档格式和平台所需的依赖包。README.md 面向开发者，提供开发和测试的命令示例；SKILL.md 面向 AI，强调 --advice 优先。

Scenario: SKILL.md 强调 --advice 而非完整命令

  • WHEN AI 或用户阅读 SKILL.md
  • THEN 文档引导使用 --advice 获取准确命令，不提供完整的 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

Requirement: 当前平台命令验证

系统必须验证当前平台的 uv run --with 命令可以正确执行。

Scenario: 验证 default 平台命令

  • WHEN 在当前平台执行 uv run --with 命令
  • THEN 必须可以成功安装所有依赖
  • AND 必须可以成功运行文档解析脚本

Scenario: 记录当前平台命令

  • WHEN 更新 SKILL.md 或 README.md
  • THEN 必须包含当前平台的命令示例
  • AND 命令中的依赖版本必须与 config.DEPENDENCIES 一致

Requirement: 版本一致性

SKILL.md 和 README.md 中的依赖版本必须与 config.DEPENDENCIES 中指定的版本一致。

Scenario: 文档中的版本与配置一致

  • WHEN 查看 SKILL.md 或 README.md 中的 uv run --with 命令示例
  • THEN 命令中指定的依赖版本必须与 config.DEPENDENCIES 中 default 配置的版本一致
  • AND 如果配置中指定了特定版本，文档中必须使用相同版本

Scenario: 更新依赖时同步更新文档

  • WHEN 更新 config.DEPENDENCIES 中的依赖版本
  • THEN 必须同步更新 SKILL.md 和 README.md 中的相关命令示例
  • AND 必须更新 docs/upgrade-deps-prompt.md 中的版本记录
View Git Blame Copy Permalink