lanyuanxiaoyao
027a832c9a
- 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
103 lines
3.1 KiB
Markdown
103 lines
3.1 KiB
Markdown
## 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
|
||
|
||
无。本次变更技术路径明确，无需进一步决策。
|