CNWei
37479f48c7
- README：三栏工作台与弹窗说明、uv 路径默认值（python / uv-cache）、镜像只在装包时生效、API 与数据布局、测试现状注记 - RELEASE：补 uv-cache 与 uv 目录、配置入口改为弹窗、运行时注入说明 - 新增 ADR-0009：uv 与托管 Python 环境的决策与边界 - PLAN：补记已完成的后继迭代
2.6 KiB
2.6 KiB
ADR-0009：uv 与托管 Python 环境
- 状态：已接受
- 日期：2026-11-07
背景
Python 任务需要一个可复现的运行环境，但宿主机上的工具链状态不可控：PATH 上的 uv 版本随启动方式变化（终端 / 快捷方式 / 计划任务各不相同），也可能根本没装；pip、conda 与项目 .venv 的组合更是无法预设。之前的实现直接依赖 PATH 里的 uv，并要求用户先手动准备好虚拟环境，出了问题要到第一次运行时才暴露。
决策
- uv 是唯一的环境工具：建环境、装依赖、跑预装都走 uv，不依赖
pip.exe。 - uv 来源只认平台副本或指定路径：默认
程序目录\uv\uv.exe，或用户指定的uv.exe；不读系统 PATH。缺失时从科大镜像mirrors.ustc.edu.cn/github-release/astral-sh/uv/LatestRelease下载当前架构压缩包，校验 sha256 后安装到程序目录。 - 镜像只在装包时生效：建环境 / 预装依赖时注入
UV_DEFAULT_INDEX（以及兼容的UV_INDEX_URL）；任务运行时不再注入PIP_*或镜像变量。 - 路径默认值相对程序目录：
UV_PYTHON_INSTALL_DIR默认python、UV_CACHE_DIR默认uv-cache，注入前统一按可执行文件目录解析成绝对路径；用户可改成绝对路径。 - 用户环境优先，缺失才创建：解析顺序仍是显式
venv→ 解释器路径推断 → 工作目录向上查找；都没有时在保存任务时用 uv 创建.venv，运行期只校验、不再自动装依赖。 - 托管环境：
data/envs/<名称>预创建常用环境，Python 版本来自uv python install下载到平台的列表，可预装包、查看已装包。
原因
- PATH 上的 uv 版本与可用性不可控；平台副本随包分发，行为可预期。
- 相对默认值让整个发布目录可以整体搬迁；注入前解析成绝对路径，是因为 uv 的 cwd 在调用间会变化（项目目录 / 环境目录），相对路径会漂。
- 把装依赖限制在保存任务阶段，问题能当场暴露；运行期保持"只运行、不改环境"。
- 单机场景下，用户自己调试好的虚拟环境就是最可信的运行环境，应当优先复用而不是覆盖。
边界
- 托管环境不会自动升级依赖，也不跟随
pyproject.toml变更重建。 uv python install走 uv 自己的 Python 发行源，不受 PyPI 镜像影响；必要时用UV_PYTHON_INSTALL_MIRROR。- 删除托管环境是直接删除目录，不可恢复。
- 自定义 uv 若版本过旧，
uv python list/envs等子命令可能与平台预期的参数不一致。