chore: migrate to uv pyproject.toml for dependency management
- Add pyproject.toml with project dependencies - Remove inline script metadata from yaml2pptx.py - Update openspec/config.yaml development guidelines - Update README.md and README_DEV.md documentation - Archive change: migrate-to-uv-package-management
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-03-02
|
||||
@@ -0,0 +1,102 @@
|
||||
## Context
|
||||
|
||||
当前项目使用 uv 作为 Python 运行环境，依赖声明采用 Inline script metadata 模式（PEP 723）。随着项目发展，模块化架构（core/, loaders/, renderers/, preview/, validators/）已经形成，依赖管理需要在项目层面统一。
|
||||
|
||||
**当前状态：**
|
||||
- yaml2pptx.py 包含 inline metadata 指定依赖
|
||||
- openspec/config.yaml 声明 "脚本使用Inline script metadata来指定脚本的依赖包"
|
||||
- 项目已采用模块化架构，涉及多个 Python 模块
|
||||
|
||||
**约束条件：**
|
||||
- 必须继续使用 uv 作为运行环境
|
||||
- 用户使用方式保持不变（`uv run yaml2pptx.py ...`）
|
||||
- 严禁污染主机环境配置
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 使用 pyproject.toml 统一管理项目依赖
|
||||
- 移除 yaml2pptx.py 中的 inline metadata
|
||||
- 更新开发规范文档以反映新方式
|
||||
- 保持用户 CLI 使用体验不变
|
||||
|
||||
**Non-Goals:**
|
||||
- 不改变 CLI 命令行接口
|
||||
- 不改变功能行为
|
||||
- 不引入新的运行时依赖
|
||||
|
||||
## Decisions
|
||||
|
||||
### 使用 pyproject.toml 而非 uv.lock
|
||||
|
||||
**选择：** 创建 pyproject.toml 作为依赖声明源
|
||||
|
||||
**理由：**
|
||||
- pyproject.toml 是 Python 生态的标准项目配置格式
|
||||
- uv 支持从 pyproject.toml 读取依赖并自动管理
|
||||
- 便于 IDE 集成和代码提示
|
||||
- 符合 Python 项目最佳实践
|
||||
|
||||
**备选方案考虑：**
|
||||
- 仅使用 uv.lock：uv.lock 是生成的锁定文件，不应手动编辑
|
||||
- 继续使用 inline metadata：无法满足项目级依赖管理需求
|
||||
|
||||
### pyproject.toml 内容结构
|
||||
|
||||
**选择：** 采用标准 [project] 配置段
|
||||
|
||||
**理由：**
|
||||
- 符合 PEP 621 标准
|
||||
- uv 原生支持
|
||||
- 便于未来扩展（如可选依赖、开发依赖）
|
||||
|
||||
**配置示例：**
|
||||
```toml
|
||||
[project]
|
||||
name = "yaml2pptx"
|
||||
version = "0.1.0"
|
||||
requires-python = ">=3.8"
|
||||
dependencies = [
|
||||
"python-pptx",
|
||||
"pyyaml",
|
||||
"flask",
|
||||
"watchdog",
|
||||
]
|
||||
```
|
||||
|
||||
### 移除 openspec/config.yaml 中的 inline metadata 描述
|
||||
|
||||
**选择：** 更新配置上下文，移除 "脚本使用Inline script metadata" 相关描述
|
||||
|
||||
**理由：**
|
||||
- 保持开发规范与实际实现一致
|
||||
- 避免误导 AI 和开发者
|
||||
- 强调 "始终使用 uv 运行" 的核心约束
|
||||
|
||||
**更新后内容：**
|
||||
```
|
||||
本项目编写的python脚本和任何python命令都始终使用uv运行，命令使用uv run python -c "xxx"执行命令；
|
||||
```
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
| 风险 | 缓解措施 |
|
||||
|------|----------|
|
||||
| 用户已有工作流可能依赖 inline metadata | 保持 CLI 使用方式不变，`uv run` 命令继续有效 |
|
||||
| pyproject.toml 配置错误可能导致依赖问题 | 严格遵循 PEP 621 标准和 uv 文档 |
|
||||
| 多个依赖管理源可能造成混淆 | 完全移除 inline metadata，单一依赖源 |
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. 创建 pyproject.toml 文件，声明项目依赖
|
||||
2. 移除 yaml2pptx.py 中的 inline metadata（第 2-10 行）
|
||||
3. 更新 openspec/config.yaml 中的开发规范
|
||||
4. 更新 README.md 中的依赖管理说明
|
||||
5. 验证 `uv run yaml2pptx.py` 命令仍可正常工作
|
||||
6. 如需要，更新 README_DEV.md
|
||||
|
||||
**回滚策略：** 保留 git 历史，可随时回滚到 inline metadata 模式
|
||||
|
||||
## Open Questions
|
||||
|
||||
无。本次变更技术路径明确，无需进一步决策。
|
||||
@@ -0,0 +1,27 @@
|
||||
## Why
|
||||
|
||||
当前项目使用 Inline script metadata 模式在 yaml2pptx.py 中指定依赖，这种方式在单文件脚本场景下有效，但随着项目模块化架构的发展，依赖管理需要在项目层面统一管理。迁移到 uv 的原生依赖管理模式（pyproject.toml）是更标准、更可维护的做法。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **BREAKING**: 移除 yaml2pptx.py 中的 Inline script metadata（第 2-10 行）
|
||||
- 新增 pyproject.toml 文件，使用 uv 的标准依赖管理格式
|
||||
- 更新 openspec/config.yaml 中的开发规范说明（移除 inline metadata 相关描述）
|
||||
- 更新 README.md 文档中的依赖管理说明
|
||||
- 用户命令使用方式保持不变（仍然使用 `uv run yaml2pptx.py ...`）
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
无新增功能能力。本次变更仅改变依赖管理的内部实现方式。
|
||||
|
||||
### Modified Capabilities
|
||||
无需修改现有 spec。用户视角的 CLI 行为、API 接口、功能特性均保持不变。
|
||||
|
||||
## Impact
|
||||
|
||||
- yaml2pptx.py: 移除第 2-10 行的 inline metadata
|
||||
- pyproject.toml: 新增项目依赖配置文件
|
||||
- openspec/config.yaml: 更新开发规范（移除 "脚本使用Inline script metadata" 描述）
|
||||
- README.md: 更新依赖管理说明
|
||||
- README_DEV.md: 可能需要同步更新开发规范说明
|
||||
@@ -0,0 +1,18 @@
|
||||
# Spec Changes: None
|
||||
|
||||
本次变更 `migrate-to-uv-package-management` 是纯基础设施变更，不涉及任何功能能力（capability）的变更。
|
||||
|
||||
## 变更范围
|
||||
|
||||
- 从 Inline script metadata 迁移到 pyproject.toml 依赖管理
|
||||
- 更新开发规范文档
|
||||
- 用户视角的 CLI 行为、API 接口、功能特性均保持不变
|
||||
|
||||
## 无需创建 spec 文件的原因
|
||||
|
||||
根据 proposal 的 Capabilities 部分：
|
||||
|
||||
- **New Capabilities**: 无
|
||||
- **Modified Capabilities**: 无
|
||||
|
||||
本次变更仅改变依赖管理的内部实现方式，不影响任何用户可见的行为或系统功能要求，因此无需创建或修改 spec 文件。
|
||||
@@ -0,0 +1,29 @@
|
||||
## 1. 创建 pyproject.toml
|
||||
|
||||
- [x] 1.1 在项目根目录创建 pyproject.toml 文件
|
||||
- [x] 1.2 配置 [project] 段，包含 name、version、requires-python
|
||||
- [x] 1.3 配置 dependencies 列表（python-pptx、pyyaml、flask、watchdog）
|
||||
|
||||
## 2. 移除 yaml2pptx.py 的 inline metadata
|
||||
|
||||
- [x] 2.1 移除 yaml2pptx.py 第 2-10 行的 inline metadata 注释块
|
||||
|
||||
## 3. 更新 openspec/config.yaml
|
||||
|
||||
- [x] 3.1 移除 context 中 "脚本使用Inline script metadata来指定脚本的依赖包和python运行版本" 描述
|
||||
- [x] 3.2 确保保留 "本项目编写的python脚本和任何python命令都始终使用uv运行" 核心约束
|
||||
|
||||
## 4. 更新 README.md
|
||||
|
||||
- [x] 4.1 更新 "安装" 部分，说明使用 pyproject.toml 管理依赖
|
||||
- [x] 4.2 更新 "依赖项" 部分，说明依赖由 pyproject.toml 声明，uv 自动管理
|
||||
|
||||
## 5. 验证
|
||||
|
||||
- [x] 5.1 运行 `uv run yaml2pptx.py check` 验证基本功能
|
||||
- [x] 5.2 运行 `uv run yaml2pptx.py convert` 验证转换功能
|
||||
- [x] 5.3 运行 `uv run yaml2pptx.py preview` 验证预览功能
|
||||
|
||||
## 6. 更新 README_DEV.md（可选）
|
||||
|
||||
- [x] 6.1 检查 README_DEV.md 中是否有 inline metadata 相关说明需要更新
|
||||
Reference in New Issue
Block a user