---
title: "用 uv 管理 AI 脚本环境：从单文件试验到可复现项目"
slug: "uv-ai-scripts-reproducible-environments"
kind: "runbook"
version: "1.0"
status: "reviewed"
compatibility: "已安装 uv 的 macOS、Linux 或 Windows 环境；命令需按已安装版本核对。示例使用 rich，无模型 API 调用。"
risk_level: "medium"
requires_approval: true
updated_at: "2026-10-19T00:22:48.655Z"
verified_at: ""
source: "https://blog.atlankj.com/posts/uv-ai-scripts-reproducible-environments"
---

# 目标

在独立目录用 uv 建立合成数据脚本，保存依赖与验证记录。

# 前置条件

- 用户已允许创建演示目录及下载所需 Python 或 Python 包。
- uv 已安装；记录 uv --version。
- 目标目录不存在，或已确认适合放置本次演示。
- 已检查上级目录与项目适用指令。
- 本文示例未在读者环境实测，需逐步验证。

# 输入

演示目录、项目模式或单文件模式、Python 版本约束、允许使用的软件包源。

# 约束

- 只在本次演示目录内创建脚本和项目文件。
- 不覆盖已有项目配置、锁文件或用户文件。
- 不读取模型凭据，不调用模型 API，不处理真实用户数据。
- 使用已批准的软件包源；不改全局 Python 环境。
- 下载或安装未在本次授权范围内时，暂停该步骤并说明需要什么。
- 不把锁文件等同于模型输出确定性。

# 操作步骤

1. 记录 uv 版本，确认演示目录和包源。
2. 项目模式：在父目录运行 uv init ai-script-demo，进入该目录后运行 uv add rich。
3. 将 A 文示例保存为 summarize.py；内容使用三个固定中文字符串和 rich.print。
4. 运行 uv lock --check，再运行 uv run --locked summarize.py。
5. 对照 items=3、characters=18，记录实际输出与执行结果。
6. 可选的单文件模式：在另一个演示目录保存 quick_summary.py，再运行 uv add --script quick_summary.py rich、uv lock --script quick_summary.py、uv run --script quick_summary.py。
7. 核对相邻脚本锁文件是否生成，记录两种模式各自的依赖声明。
8. 提供运行命令、版本信息及未验证范围。

# 输出结果

项目或脚本文件、对应依赖声明和锁文件、实际验证记录；不产生外部发布。

# 验证方法

- 项目模式下 uv lock --check 成功。
- 程序成功退出，items 为 3、characters 为 18。
- 单文件模式下脚本包含内联元数据并存在对应锁文件。
- 不生成 API 调用，不接触凭据。
- 无法执行的步骤明确标记为未验证。

# 异常处理

- uv 不存在：报告安装前置条件，不擅自执行安装脚本。
- 下载失败：检查已批准的网络与包源，不关闭证书验证。
- 锁文件不一致：展示元数据差异，取得依赖变更授权后再更新。
- Python 版本不满足：说明约束，按已有授权决定是否下载兼容解释器。
- 目录存在：停止初始化该目录，选择新的演示目录。

# 回滚方式

保留生成文件清单。需要回滚时仅清理明确属于本次演示且用户已授权删除的文件；不清理共享缓存、不重置现有仓库、不改全局解释器。

# 参考来源

- https://github.com/astral-sh/uv/blob/main/docs/guides/scripts.md
- https://github.com/astral-sh/uv/blob/main/docs/guides/projects.md
- https://github.com/astral-sh/uv/blob/main/docs/concepts/projects/sync.md

资料核对：2026-10-19。