DeepSeek Agent Harness 2026终极指南 - 第6章第26节 uv Python 3.12现代化工程地基一日通理论区收官了该动真格的了。但先别急着写 Agent Loop——地基打不好楼搭得越高塌得越快。这一节我们彻底告别 pipvenv 的原始时代用 uv 把 DeepPilot 的项目环境一次性搭好连带国内镜像源、pyproject.toml、Python 3.12 一并搞定。本文导航为什么不直接用 pipvenvuv 是什么来头第一步安装 uv 和 Python 3.12第二步国内镜像源——没有它寸步难行第三步pyproject.toml 一笔一画拆解第四步uv sync——依赖的闪电速度第五步uv run——永远不用 activateDeepPilot 初始化实录小结为什么不直接用 pipvenv说实话pipvenv 这套组合已经用了十几年了很多人习惯了也懒得换。但我踩过的坑让我不得不换第一个坑速度。在国内不用镜像源的情况下pip install 一个中型项目等上 10 分钟是常态。即使用了镜像源pip 的依赖解析器是逐包解析的遇到依赖冲突要回退重试来回折腾。第二个坑虚拟环境管理。python -m venv .venv创建完然后你要记得source .venv/bin/activateWindows 上还是.venv\Scripts\activate每开一个新终端都得来一遍。忘了 activate恭喜你直接把包装到全局环境里过两天发现莫名其妙各种冲突。第三个坑锁文件缺失。pip freeze requirements.txt 只能锁顶层依赖不锁传递依赖。同事的机器上 pip install -r requirements.txt 跑出来跟你的环境不一样太正常了因为中间某个包的子依赖在不同时间解析出来的版本不同。uv 把这三个问题一锅端了痛点pipvenvuv安装速度分钟级秒级Rust 写的解析器虚拟环境手动创建激活自动管理干活无需 activate确定性构建requirements.txt不可靠uv.lockCargo 级别靠谱不瞒你说我第一次用 uv sync 跑一个 30 依赖的项目2.3 秒搞定。同样的项目 pip 跑了 47 秒。这不是优化这是降维打击。uv 是什么来头uv 是 Astral 团队就是 Ruff 那个团队用 Rust 写的 Python 包管理器和项目管理工具。它的野心就是做 Python 生态的 Cargo——一个工具搞定虚拟环境、依赖安装、项目构建、脚本运行。核心能力uv pippip 的极速替代品命令兼容uv venv创建虚拟环境比 venv 快uv sync读 pyproject.toml uv.lock一键创建环境安装依赖uv run在项目环境中直接运行命令无需手动激活uv lock生成确定性锁文件pyproject.toml声明依赖uv lock生成 uv.lockuv sync创建 .venv 安装uv run script.py直接运行换人或换机器git clone uv sync环境完全一致对我们 DeepPilot 项目来说uv 就是工程地基。后续所有章节的uv run python -m deep_pilot.xxx都建立在今天搭好的环境之上。第一步安装 uv 和 Python 3.12Windows 安装# 方式一pip 安装如果你已经有 Pythonpip install uv# 方式二独立安装器推荐powershell-cirm https://astral.sh/uv/install.ps1 | iex# 验证uv--version# 输出uv 0.6.x (Windows)Linux / macOS 安装# 独立安装器curl-LsSfhttps://astral.sh/uv/install.sh|sh# 或者 pippipinstalluv# 验证uv--version用 uv 安装 Python 3.12uv 自带 Python 管理能力不需要你去 python.org 下载安装包# 安装 Python 3.12uv 自动下载管理uv pythoninstall3.12# 查看已安装的 Python 版本uv python list# 输出示例# cpython-3.12.9-platform uv 管理的路径# Windows PowerShell 下实际输出uv pythoninstall3.12# Downloading cpython-3.12.9-windows-x86_64-none (19.2 MiB)# Installed Python 3.12.9这一步做完你机器上就有了 Python 3.12。而且不是手动配PATH那种野路子——uv 帮你管好了版本和路径切版本也是半句命令的事。第二步国内镜像源——没有它寸步难行在国内开发不配镜像源就是自己找罪受。uv 的镜像源配置比 pip 灵活得多。方式一命令行传参临时加速# 单次使用装完即忘uv pipinstallrequests --index-url https://pypi.tuna.tsinghua.edu.cn/simple方式二pyproject.toml 声明推荐在项目的pyproject.toml里直接写死镜像源这样项目克隆到谁的机器上都自动走国内源[[tool.uv.index]] name tsinghua url https://pypi.tuna.tsinghua.edu.cn/simple default true方式三全局环境变量最省事# Linux/macOS 加到 ~/.bashrc 或 ~/.zshrcexportUV_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simple# Windows PowerShell 加到 $PROFILE$env:UV_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simple主流国内镜像源速查表镜像源URL推荐度清华 TUNAhttps://pypi.tuna.tsinghua.edu.cn/simple⭐⭐⭐⭐⭐阿里云https://mirrors.aliyun.com/pypi/simple⭐⭐⭐⭐中科大https://pypi.mirrors.ustc.edu.cn/simple⭐⭐⭐⭐腾讯云https://mirrors.cloud.tencent.com/pypi/simple⭐⭐⭐华为云https://repo.huaweicloud.com/repository/pypi/simple⭐⭐⭐我个人首选清华 TUNA这么多年了没掉过链子。但我们 DeepPilot 项目的 pyproject.toml 里会用default true指清华同时加阿里云作为 fallback[[tool.uv.index]] name tsinghua url https://pypi.tuna.tsinghua.edu.cn/simple default true [[tool.uv.index]] name aliyun url https://mirrors.aliyun.com/pypi/simple这样万一清华抽风uv 会自动切到阿里云。生产级项目留后手不丢人。第三步pyproject.toml 一笔一画拆解pyproject.toml 是 Python 项目的身份证。它不在代码里但在根目录下定义了项目元信息、依赖、构建配置、工具链设置——一把全搞定。来看看 DeepPilot 的 pyproject.toml 长什么样[project] name deep-pilot version 0.1.0 description DeepPilot - 手写 DeepSeek Agent Harness 教学项目 requires-python 3.12 readme README.md license { text MIT } dependencies [ openai1.50.0, pydantic2.9.0, pydantic-settings2.5.0, python-dotenv1.0.0, ] [project.optional-dependencies] dev [ pytest8.0, pytest-asyncio0.24.0, ] [build-system] requires [hatchling] build-backend hatchling.build [tool.uv] dev-dependencies [ pytest8.0, pytest-asyncio0.24.0, ] [[tool.uv.index]] name tsinghua url https://pypi.tuna.tsinghua.edu.cn/simple default true [[tool.uv.index]] name aliyun url https://mirrors.aliyun.com/pypi/simple逐段拆解[project]项目身份信息。namePyPI 上的包名。DeepPilot 用deep-pilot连字符风格。version当前版本号。我们跟课程进度走v0.1 是最初版第六、七章后续逐步升级到 v1.0。requires-python3.12锁死 Python 3.12。正如五条铁律第一条强调的我们用 Python 3.12 来享受更好的类型提示语法PEP 695 type statement。licenseMIT 最宽松随便用。dependencies运行时必须的依赖。openai1.50.0调用 DeepSeek API它兼容 OpenAI 协议。表示至少 1.50不锁死小版本允许安全升级。pydantic2.9.0数据校验和序列化。项目核心所有 JSON 都走 pydantic。pydantic-settings2.5.0pydantic 的环境变量管理扩展下一节讲配置中枢就用它。python-dotenv1.0.0读取.env文件。[project.optional-dependencies]可选依赖组。dev开发时用的包——pytest 系列生产环境不需要装。安装时用uv sync --group dev或uv sync --extra dev。[build-system]构建工具。hatchlingHatch 的构建后端轻量比 setuptools 现代得多。[tool.uv]uv 专属配置区。dev-dependenciesuv 原生支持的开发依赖声明方式比optional-dependencies更自然uv sync --dev一把装上。[[tool.uv.index]]镜像源声明。双层中括号表示 TOML 的数组表。我们声明两个镜像源清华为主default true阿里云备用。不要被这个文件吓到——你大部分时间只需要在dependencies和dev-dependencies里增减包名其他部分写好之后几乎不动。第四步uv sync——依赖的闪电速度有了 pyproject.toml一切就绪。现在来跑 uv sync见证 Rust 的速度# 进入项目目录mkdirdeep-pilotcddeep-pilot# 把上面的 pyproject.toml 创建好或者用 uv init 再改# 执行同步uvsync实际控制台输出Windows清华源$ uv sync Using CPython 3.12.9 Creating virtual environment at: .venv Resolved 32 packages in 235ms Building deep-pilot file:///D:/projects/deep-pilot Built deep-pilot file:///D:/projects/deep-pilot Prepared 15 packages in 1.2s Installed 32 packages in 298ms annotated-types0.7.0 anyio4.9.0 certifi2026.7.22 colorama0.4.6 deep-pilot0.1.0 (from file:///D:/projects/deep-pilot) distro1.9.0 h110.16.0 httpcore1.0.9 httpx0.28.1 idna3.10 jiter0.10.0 openai2.4.0 pydantic2.11.3 pydantic-core2.33.1 pydantic-settings2.9.1 python-dotenv1.1.1 sniffio1.3.1 tqdm4.67.1 typing-extensions4.14.1 typing-inspection0.4.1从执行到安装完成总共不到2 秒。而且生成了uv.lock文件——它记录了每个包的精确版本和哈希值。以后团队成员git clone之后跑uv sync环境跟你一模一样一个字节都不差。.venv/清华镜像源uv开发者.venv/清华镜像源uv开发者uv sync读取 pyproject.toml解析依赖树 (Rust)下载 .whl 包返回包 (极速)安装到虚拟环境写入 uv.lock (确定性快照)✅ 完成 (2秒内)这就是为什么我们整个 DeepPilot 课程只用 uv。简单、快、可靠——三个字概括了一切。第五步uv run——永远不用 activate传统 venv 的 daily 体验是什么开终端 →source .venv/bin/activate→ 干活 → 关终端。忘了 activate 就装到系统环境里一坨浆糊。uv run 直接消灭了这个动作# 传统方式4步source.venv/bin/activate# 1. 激活pip list# 2. 确认python main.py# 3. 运行deactivate# 4. 退出# uv 方式1步uv run python main.py原理很简单uv run自动检测项目根目录下的.venv或 pyproject.toml 声明的环境在启动命令前把 Python 解释器和PATH指向项目环境。你对环境无感但命令执行的上下文永远是项目的。# 跑个脚本uv run python-cimport pydantic; print(pydantic.VERSION)# 输出2.11.3# 跑模块将来就是我们的 deep_pilotuv run python-mdeep_pilot.main# 跑 pytestuv run pytest# 甚至直接跑 pip代替全局 pipuv pip list还有一个杀手功能uv run 可以应对未安装的依赖# 只有 pyproject.toml 里有 httpx但你还没 uv sync# uv run 自动先 sync 再执行uv run--withhttpx python-cimport httpx; print(ok)这个即用即装的能力在快速原型验证时特别好用——你不需要先配环境再写代码可以边写边让 uv 帮你补依赖。DeepPilot 初始化实录现在把前面五步串起来过一次 DeepPilot 项目的完整初始化。这是你在自己机器上操作的真实实录——直接跟着敲就行。完整操作序列# Step 1: 确保 uv 可用 uv--version# uv 0.6.x# Step 2: 创建项目目录 mkdirdeep-pilotcddeep-pilot# Step 3: 用 uv init 初始化项目骨架 uv init--namedeep-pilot--python3.12# Initialized project deep-pilot at D:\projects\deep-pilot# 看看 uv init 给我们生成了什么ls# Mode LastWriteTime Length Name# ---- ------------- ------ ----# d----- 2026/09/11 10:00 src# -a---- 2026/09/11 10:00 112 .gitignore# -a---- 2026/09/11 10:00 185 .python-version# -a---- 2026/09/11 10:00 312 pyproject.toml# -a---- 2026/09/11 10:00 0 README.mduv init默认生成的是一个 Python 库包结构src/目录下放代码。但我们 DeepPilot 走的是扁平应用结构不用src/布局直接根目录下放deep_pilot/包。改成 DeepPilot 项目结构# 删掉 uv init 生成的 src 骨架rm-rsrc# 创建 DeepPilot 的包目录mkdirdeep_pilotmkdirlogsmkdirtests# deep_pilot 下创建模块文件从 v0.1 ~ v1.0 逐步填内容# New-Item -ItemType File deep_pilot/__init__.py # Windows PowerShell# touch deep_pilot/__init__.py # Linux/macOSechodeep_pilot/__init__.pyechodeep_pilot/config.pyechodeep_pilot/client.pyechodeep_pilot/logger.pyechodeep_pilot/main.pyechotests/__init__.py最终项目骨架deep-pilot/ ├── pyproject.toml # 项目身份证依赖、镜像源、构建配置 ├── uv.lock # 确定性锁文件自动生成git 提交 ├── .python-version # Python 版本声明uv 读取 ├── .gitignore ├── README.md ├── .env.example # 配置模板敏感信息不提交 ├── .env # 真实配置gitignore ├── deep_pilot/ # 主包目录 │ ├── __init__.py │ ├── config.py # 配置中枢 ← 第27节写 │ ├── client.py # DeepSeek 客户端封装 ← 第28节写 │ ├── logger.py # 日志系统 ← 第30节写 │ └── main.py # 入口 ├── logs/ # 日志输出目录 │ └── .gitkeep └── tests/ # 测试目录 └── __init__.py这个结构就是 DeepPilot 在整门课程中一步步填满的骨架。从第 27 节的 config.py 到第 12 章的子 Agent 编排所有模块都在这个目录下生长。修改 pyproject.toml把 uv init 生成的默认 pyproject.toml 替换为上文 DeepPilot 专用版本。这里只说一下关键修改点# 对比 init 生成的默认版 vs DeepPilot 定制版 # 默认版 [project] name deep-pilot version 0.1.0 requires-python 3.12 dependencies [] # DeepPilot 定制版加了4个生产依赖 开发依赖 镜像源 [project] name deep-pilot version 0.1.0 description DeepPilot - 手写 DeepSeek Agent Harness 教学项目 requires-python 3.12 dependencies [ openai1.50.0, pydantic2.9.0, pydantic-settings2.5.0, python-dotenv1.0.0, ] [project.optional-dependencies] dev [pytest8.0, pytest-asyncio0.24.0] [[tool.uv.index]] name tsinghua url https://pypi.tuna.tsinghua.edu.cn/simple default true [[tool.uv.index]] name aliyun url https://mirrors.aliyun.com/pypi/simple最终的 uv sync# 切到项目根目录cddeep-pilot# 执行同步uvsync# 完整输出清华源首次安装 32 个包# Using CPython 3.12.9# Creating virtual environment at: .venv# Resolved 32 packages in 215ms# Prepared 15 packages in 1.05s# Installed 32 packages in 287ms# openai2.4.0# pydantic2.11.3# pydantic-settings2.9.1# python-dotenv1.1.1# ... (30 个传递依赖)检查一切正常# 验证 Python 版本uv run python--version# Python 3.12.9# 验证核心依赖导入uv run python-cimport openai, pydantic; print(all good)# all good# 验证 uv.lock 已生成lsuv.lock# -a---- 2026/09/11 10:02 58213 uv.lock到这一步DeepPilot v0.1 的工程地基就算搭完了。2 秒同步、1 秒验证从零到可运行环境不超过 3 秒。用 pipvenv 的话光创建虚拟环境 下载包就不止这个时间。小结告别 pipvenvuv 是 Python 生态的 CargoRust 提速 10-100 倍依赖解析和安装不再痛苦。pyproject.toml 是项目的心脏依赖声明、镜像源配置、构建工具一把抓一个文件管所有。uv.lock 保证环境一致性团队成员之间、本地与 CI 之间环境分毫不差。uv sync替代 pip install2 秒搞定 30 个包的完整环境。uv run替代 activate永远不用手动激活虚拟环境命令跑在正确的上下文中。国内镜像源三件套pyproject.toml 声明项目级 环境变量全局 命令行参数临时按需选用。DeepPilot v0.1 地基搭建完成deep_pilot/包目录、pyproject.toml、uv.lock 全部就位。下节预告地基搭好了config.py 还是空的。下一节我们写pydantic 配置中枢——用 pydantic-settings 管理 base_url、api_key、model 等所有配置从.env文件读取、启动时自动校验、配错了立刻友好报错。这是五条铁律里 pydantic 强类型的第一个落地模块。如果觉得本文对你有帮助欢迎点赞、收藏、关注三连本系列持续更新中关注不迷路~