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
2026-03-02 22:03:23 +08:00
parent 0a804eacc8
commit 027a832c9a
11 changed files with 1280 additions and 27 deletions
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@

 ### 安装

-本工具使用 [uv](https://github.com/astral-sh/uv) 管理依赖，运行时会自动安装所需的 Python 包。
+本工具使用 [uv](https://github.com/astral-sh/uv) 管理依赖。项目依赖在 pyproject.toml 中声明，运行时会自动安装所需的 Python 包。

 ### 基本用法

@@ -352,7 +352,7 @@ yaml2pptx 采用模块化架构，易于扩展：
 - `flask` - 预览服务器
 - `watchdog` - 文件监听

-所有依赖由 uv 自动管理，无需手动安装。
+依赖在 pyproject.toml 中声明，由 uv 自动管理，无需手动安装。

 ## 🤝 贡献

--- a/README_DEV.md
+++ b/README_DEV.md
@@ -186,7 +186,7 @@ python yaml2pptx.py input.yaml output.pptx
 ```

 **依赖管理**：
- 所有依赖在 `yaml2pptx.py` 的 `/// script` 头部声明
+- 所有依赖在 `pyproject.toml` 的 `[project.dependencies]` 中声明
 - uv 会自动安装依赖，无需手动 `pip install`

 ### 2. 命令行接口
@@ -519,22 +519,20 @@ uv run yaml2pptx.py preview temp/test.yaml --no-browser

 ### Q: 为什么不能直接使用 python 运行脚本？

-A: 项目使用 uv 的 Inline script metadata 来管理依赖。直接使用 python 会导致依赖缺失。必须使用 `uv run yaml2pptx.py`。
+A: 项目使用 uv 和 pyproject.toml 来管理依赖。直接使用 python 会导致依赖缺失。必须使用 `uv run yaml2pptx.py`。

 ### Q: 如何添加新的依赖？

-A: 在 `yaml2pptx.py` 的 `/// script` 头部添加：
-```python
-# /// script
-# requires-python = ">=3.8"
-# dependencies = [
-#     "python-pptx",
-#     "pyyaml",
-#     "flask",
-#     "watchdog",
-#     "new-dependency",  # 添加新依赖
-# ]
-# ///
+A: 在 `pyproject.toml` 的 `[project.dependencies]` 中添加：
+```toml
+[project]
+dependencies = [
+    "python-pptx",
+    "pyyaml",
+    "flask",
+    "watchdog",
+    "new-dependency",  # 添加新依赖
+]
 ```

 ### Q: 为什么元素使用 dataclass 而不是普通字典？
--- a/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/.openspec.yaml
+++ b/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-02
--- a/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/design.md
+++ b/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/design.md
@@ -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
+
+无。本次变更技术路径明确，无需进一步决策。
--- a/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/proposal.md
+++ b/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/proposal.md
@@ -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: 可能需要同步更新开发规范说明
--- a/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/specs/no-spec-changes.md
+++ b/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/specs/no-spec-changes.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 文件。
--- a/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/tasks.md
+++ b/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/tasks.md
@@ -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 相关说明需要更新
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -2,7 +2,7 @@ schema: spec-driven

 context: |
  本项目始终面向中文开发者，使用中文进行注释、交流等内容的处理，不考虑多语言；
-  本项目编写的python脚本和任何python命令都始终使用uv运行，脚本使用Inline script metadata来指定脚本的依赖包和python运行版本，命令使用uv run python -c "xxx"执行命令；
+  本项目编写的python脚本和任何python命令都始终使用uv运行，需要执行临时命令使用uv run python -c "xxx"执行命令；
  严禁直接使用主机环境的python直接执行脚本或命令，严禁在主机环境直接安装python依赖包；
  本项目编写的测试文件、临时文件必须放在temp目录下；
  严禁污染主机环境的任何配置，如有需要，必须请求用户审核操作；
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -0,0 +1,10 @@
+[project]
+name = "yaml2pptx"
+version = "0.1.0"
+requires-python = ">=3.8"
+dependencies = [
+    "python-pptx",
+    "pyyaml",
+    "flask",
+    "watchdog",
+]
--- a/uv.lock
+++ b/uv.lock
--- a/yaml2pptx.py
+++ b/yaml2pptx.py
@@ -1,14 +1,4 @@
 #!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.8"
-# dependencies = [
-#     "python-pptx",
-#     "pyyaml",
-#     "flask",
-#     "watchdog",
-# ]
-# ///
-
 """
 YAML to PPTX Converter
 将 YAML 格式的演示文稿源文件转换为 PPTX 文件