name: uv description: 如果项目使用uv，请使用此技能。使用此技能通过uv创建/管理Python项目和环境，添加/移除依赖，从uv.lock同步项目，并在项目环境中运行命令。 triggers:

uv
uv.lock

uv (Python)

当仓库有uv.lock、在其文档/Makefile中提及uv，或已使用uv创建的.venv时，使用uv作为默认的Python依赖和环境管理工具。

快速决策规则

如果仓库有uv.lock和pyproject.toml：将其视为uv管理的项目。
如果仓库只有requirements.txt：仍然可以使用uv pip进行快速安装。
除非仓库明确使用uv pip，否则首选项目命令（uv add/remove/sync/run/lock）而不是原始pip。

安装（如果需要）

首选可用的打包安装方法。如果使用官方安装程序，请先审查（避免盲目管道到shell），并遵循官方文档的最新说明。

# macOS/Linux（官方安装程序）
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows（PowerShell，官方安装程序）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

常见操作

初始化新项目

uv init
# 或
uv init my-project

创建/使用虚拟环境

uv venv  # 创建 .venv

# 如果需要特定版本，匹配项目声明的需求
# （例如，pyproject.toml / CI 配置），而不是任意最新版本。
uv venv --python 3.x

# 可选激活（对于uv命令不是必需的）
source .venv/bin/activate  # macOS/Linux
# .venv\\Scripts\\activate   # Windows

添加/移除依赖（更新pyproject.toml和uv.lock）

uv add requests
uv add 'requests==2.31.0'
uv add -r requirements.txt

uv remove requests

锁定 + 同步（可重现安装）

uv lock   # （重新）生成 uv.lock
uv sync   # 创建/更新 .venv 以匹配 uv.lock

如果拉取新更改且uv.lock发生变化，运行uv sync。

在项目环境中运行命令

uv run python -m pytest -q
uv run python main.py
uv run ruff check .

使用uv作为快速pip替代（需求工作流）

uv venv
uv pip install -r requirements.txt
uv pip freeze
uv pip list

注意事项/陷阱

uv通常会自动检测并使用项目根目录中的.venv。
在CI/容器中，您可能会看到uv pip install --system，但本地开发首选虚拟环境。
如果命令修改依赖，首选uv add/remove/lock/sync，以便uv.lock保持正确。