AI 工作流经常从一个 Python 脚本开始：整理文本、读取结果，再把数据交给下一步。脚本能在作者电脑上运行，还不等于同事能够复现。先把 Python 与依赖管理清楚，后续再接入模型调用，会更容易定位问题。
本文依据 Astral 官方文档及官方仓库文档源码整理，资料核对日期为 2026 年 10 月 19 日。示例只处理内存中的合成文本，不调用模型 API，也不需要 API Key。
项目模式和单文件模式如何选择
uv 支持通过项目的 pyproject.toml 声明依赖，也支持在单个 Python 文件中声明脚本依赖，并管理相应运行环境。[1][2]
本文建议按交付形式选择：
情况 | 建议方式 | 需要保留的内容 |
|---|---|---|
多个模块、测试和长期维护 | 项目模式 | 源码、项目元数据和锁文件 |
一次性演示或独立小工具 | 单文件模式 | 脚本、内联元数据及脚本锁文件 |
一段文本统计脚本适合先作为小例子。等到它出现多个输入源、配置和测试，再按项目结构组织。
第一步：确认 uv，再创建独立目录
先用 uv --version 确认工具已安装。未安装时，按 Astral 官方安装页选择适合系统的方法；本文不要求修改全局 Python 环境。[4]
在父目录执行：
1uv init ai-script-demo2cd ai-script-demo3uv add rich
uv init 用于初始化项目，uv add 管理项目依赖。项目使用 pyproject.toml 保存元数据，并用 uv.lock 记录解析后的依赖。[2]
初始化生成的入口布局可能随工具版本与选项变化。下面另建一个明确命名的脚本，不依赖默认入口文件的路径。
第二步：写一个可检查的最小脚本
在项目根目录保存 summarize.py：
1from rich import print23samples = [4 "整理文章标题",5 "核对文档来源",6 "生成发布草稿",7]89result = {10 "items": len(samples),11 "characters": sum(len(item) for item in samples),12}1314print(result)
然后运行：
1uv run --locked summarize.py
预期结果中，items 为 3，characters 为 18；显示样式可能因终端而异。这是按示例代码计算的预期值，本文未在读者环境执行。
官方文档说明，uv run 通常会在运行前处理项目锁定与环境同步；加上 --locked 后，如果锁文件与项目元数据不一致，会报错而非自动更新锁文件。[3]
这一步的价值是把“程序逻辑是否正确”与“环境是否一致”分开检查。后续增加模型调用时，先保留这个不需要凭据的小检查，再单独验证外部服务。
第三步：把环境说明交付完整
本文建议交付时保留：
- 实际脚本与
pyproject.toml； uv.lock和项目使用的 Python 版本信息；- 记录
uv --version的环境说明； - 一条运行命令和可以核对的预期输出。
依赖变更后，应明确更新锁文件并审阅差异。验证交付结果时，可以先运行：
1uv lock --check2uv run --locked summarize.py
官方文档将 uv lock --check 用于检查锁文件是否与项目元数据一致。[3] 检查失败时先找出差异，不要为了消除报错而直接删除锁文件。
单文件试验：让依赖跟着脚本走
如果只是分享一个独立脚本，可把上面的代码另存为 quick_summary.py，然后执行：
1uv add --script quick_summary.py rich2uv lock --script quick_summary.py3uv run --script quick_summary.py
uv add --script 会在脚本顶部写入内联依赖元数据；uv lock --script 为脚本生成相邻的锁文件，例如 quick_summary.py.lock。[1]
要留意：使用内联脚本元数据时，uv 使用脚本声明的依赖环境，不应假定它自动继承所在项目的依赖。[1] 脚本需要什么，就在对应声明中写清楚。
锁文件解决的是环境的一部分
本文建议把复现分成几项分别记录：依赖版本、Python 与工具版本、输入数据、运行参数，以及输出是否依赖外部服务。仅有依赖锁文件，还不足以承诺一段模型生成结果逐字相同。
让 Agent 协助时，可以使用：
先检查项目现有的 Python 与依赖管理方式。若已有 uv 项目，复用其配置；在独立目录完成合成数据示例，说明依赖变化、实际执行结果和未验证范围。不要为了这个示例读取凭据或调用模型 API。
先完成一个边界清楚、结果可核对的小程序，再增加复杂能力，后面的调试依据会更充分。
参考来源
本文为原创整理。示例代码、选型表和交付建议为作者设计，命令已对照官方文档，未在读者环境实测。官方文档站读取受限时，同时核对了 Astral 官方仓库中的对应文档源码。