lanyuanxiaoyao/PPTX
1
0
Fork 0
Code Activity
Files
124ef0e5ce2206a25b4b0cecaa8fdfae3d949fbf
PPTX/openspec/changes/archive/2026-03-02-migrate-to-uv-package-management/design.md
lanyuanxiaoyao 027a832c9a 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

3.1 KiB
Raw Blame History

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 原生支持
  • 便于未来扩展（如可选依赖、开发依赖）

配置示例：

[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

无。本次变更技术路径明确，无需进一步决策。

View Git Blame Copy Permalink