代码编写规范参见 python-coding skill。
项目初始化
创建新项目：
uv init myproject --package # 创建库/包项目
uv init myapp # 创建应用项目
标准项目结构：
myproject/
├── pyproject.toml # 依赖声明的唯一真相源
├── uv.lock # 锁定文件（必须提交到 git）
├── .python-version # 固定 Python 版本（可选）
├── src/myproject/ # 源代码
├── tests/ # 测试代码
└── README.md
依赖管理
添加依赖：
uv add requests # 添加生产依赖
uv add --dev pytest ruff # 添加开发依赖
uv add "fastapi>=0.100" # 指定版本约束
同步与锁定：
uv lock # 更新 uv.lock
uv sync # 同步环境（安装所有依赖）
uv sync --frozen # CI 中使用：使用现有锁定，不更新
移除依赖：
uv remove requests
Python 版本管理
uv python install 3.12 # 安装 Python 3.12
uv python pin 3.12 # 固定项目使用 3.12
虚拟环境
uv venv # 创建 .venv
uv sync # 自动创建并同步环境
不要手动激活 - 使用 uv run 代替。
运行代码
uv run python script.py # 自动同步后运行
uv run pytest # 运行测试
uv run --no-sync python app.py # 跳过同步
在 pyproject.toml 中定义脚本：
[project.scripts]
myapp = "myproject.main:cli"
[tool.uv.scripts]
dev = "uvicorn myapp:app --reload"
test = "pytest tests/"
lint = "ruff check ."
使用方式：uv run dev、uv run test、uv run lint
标准工作流
开发流程：
# 1. 克隆项目
git clone <repo> && cd myproject
# 2. 同步环境
uv sync
# 3. 开发
uv run python -m myproject
# 4. 添加依赖
uv add newpackage
git add pyproject.toml uv.lock
git commit -m "Add newpackage"
CI/CD 模板：
# .github/workflows/test.yml
- uses: astral-sh/setup-uv@v1
- run: uv sync --frozen
- run: uv run pytest
核心规则
- 单一真相源:
pyproject.toml是唯一的依赖声明处 - 始终提交锁定文件:
uv.lock确保可重现性 - 使用 uv run: 通过
uv run执行所有命令以自动管理环境 - 固定 Python 版本: 使用
.python-version或requires-python - 分离开发依赖: 使用
--dev标志或tool.uv.dev-dependencies
常见操作
更新依赖：
uv lock --upgrade-package requests # 更新单个包
uv lock --upgrade # 更新所有包
导出兼容格式：
uv pip compile pyproject.toml -o requirements.txt
安装可选依赖组：
uv sync --extra dev
禁止操作
- ❌ 禁止手动编辑
uv.lock - ❌ 禁止在 uv 项目中使用
pip install - ❌ 禁止提交
.venv/目录 - ❌ 禁止在
pyproject.toml外声明依赖 - ❌ 禁止使用
requirements.txt作为主要依赖源
决策框架
当被要求：
- 创建项目 → 使用
uv init - 添加依赖 → 使用
uv add - 运行代码 → 使用
uv run - 更新依赖 → 使用
uv lock --upgrade - 配置 CI → 使用
uv sync --frozen
始终优先使用 uv 命令而非传统的 pip/virtualenv 工作流。