创建或迁移 Python 项目时，用 uv+ruff+ty…

适用于新建 Python 项目/包、编写带依赖的独立脚本，或从 pip/Poetry/mypy/black 迁移到现代工具链。

适用场景

解决思路

1. 按场景选择实现方式：单文件且有外部依赖的脚本使用 PEP 723 内联元数据（见 references/pep723-scripts.md）；新建不打算分发的多文件项目使用最小 uv 设置；新建可复用包/库使用完整项目设置；迁移现有项目按迁移指南执行。
2. 用 uv 替代 pip、virtualenv、pip-tools、pipx、pyenv 做包/依赖管理；用 ruff 替代 flake8、black、isort、pyupgrade、pydocstyle 做 lint 和格式化；用 ty 替代 mypy、pyright 做类型检查；用 pytest 做带覆盖率的测试；用 prek 替代 pre-commit 做 pre-commit hooks。
3. 安全工具配置：用 shellcheck 做 shell 脚本 lint，用 detect-secrets 做 secret 检测，用 actionlint 做 workflow 语法校验，用 zizmor 做 workflow 安全审计，用 pip-audit 做依赖漏洞扫描，用 Dependabot 做自动依赖更新；配置和使用见 references/security-setup.md。
4. 始终用 uv add 和 uv remove 管理依赖，不要手动编辑 pyproject.toml 添加依赖；不要用 uv pip install，改用 uv add 和 uv sync。
5. 不要手动激活或管理虚拟环境（如 source .venv/bin/activate），所有命令都用 uv run <cmd> 执行。
6. 开发/测试/文档依赖使用 [dependency-groups]（PEP 735），不要用 [project.optional-dependencies]。
7. 避免使用 hatchling build backend，使用 uv_build；避免 Poetry，使用 uv；避免 requirements.txt，脚本用 PEP 723、项目用 pyproject.toml。
8. 避免在 [tool.ty] 下配置 python-version，应在 [tool.ty.environment] 下配置 python-version。
9. 最小项目 Quick Start：运行 uv init myproject；cd myproject；用 uv add requests rich 添加依赖；用 uv add --group dev pytest ruff ty 添加开发依赖；用 uv run python src/myproject/main.py 运行代码；用 uv run pytest 运行测试；用 uv run ruff check . 运行 lint。
10. 完整项目可从零开始：先询问用户是否偏好使用 Trail of Bits cookiecutter 模板引导完整项目：uvx cookiecutter gh:trailofbits/cookiecutter-python。
11. 完整项目步骤 1：运行 uv init --package myproject；cd myproject，创建包含 pyproject.toml、README.md、src/myproject/__init__.py、.python-version 的结构。
12. 完整项目步骤 2：按 references/pyproject.md 配置 pyproject.toml，关键内容为 [project] 中 name、version、requires-python = ">=3.11"、dependencies；[dependency-groups] 中 dev = [{include-group = "lint"}, {include-group = "test"}, {include-group = "audit"}]、lint = ["ruff", "ty"]、test = ["pytest", "pytest-cov"]、audit = ["pip-audit"]；[tool.ruff] 中 line-length = 100、target-version = "py311"；[tool.ruff.lint] 中 select = ["ALL"]、ignore = ["D", "COM812", "ISC001"]；[tool.pytest] 中 addopts = ["--cov=myproject", "--cov-fail-under=80"]；[tool.ty.terminal] 中 error-on-warning = true；[tool.ty.environment] 中 python-version = "3.11"；[tool.ty.rules] 中 possibly-unresolved-reference = "error"、unused-ignore-comment = "warn"。
13. 完整项目步骤 3：用 uv sync --all-groups 安装所有依赖组，或用 uv sync --group dev 安装指定组。
14. 完整项目步骤 4：添加 Makefile，包含 dev: uv sync --all-groups；lint: uv run ruff format --check && uv run ruff check && uv run ty check src/；format: uv run ruff format .；test: uv run pytest；build: uv build。
15. 从 requirements.txt + pip 迁移：先判断代码性质；独立脚本转换为 PEP 723 内联元数据（见 references/pep723-scripts.md）；项目则运行 uv init --bare，用 uv add 逐个添加依赖（不要手动编辑 pyproject.toml），也可用 grep -v '^#' requirements.txt | grep -v '^-' | grep -v '^\s*$' | while read -r pkg; do uv add "$pkg" || echo "Failed to add: $pkg"; done 导入，然后 uv sync；之后删除 requirements.txt、requirements-dev.txt，删除虚拟环境（venv/、.venv/），将 uv.lock 加入版本控制。
16. 从 setup.py / setup.cfg 迁移：运行 uv init --bare 创建 pyproject.toml；用 uv add 添加 install_requires 中每个依赖；用 uv add --group dev 添加开发依赖；将非依赖元数据（name、version、description 等）复制到 [project]；删除 setup.py、setup.cfg、MANIFEST.in。
17. 从 flake8 + black + isort 迁移：用 uv remove 移除 flake8、black、isort；删除 .flake8、pyproject.toml 中的 [tool.black] 和 [tool.isort] 配置；用 uv add --group dev ruff 添加 ruff；添加 ruff 配置（见 references/ruff-config.md）；运行 uv run ruff check --fix . 应用修复；运行 uv run ruff format . 格式化。
18. 从 mypy / pyright 迁移：用 uv remove 移除 mypy/pyright；删除 mypy.ini、pyrightconfig.json 或 [tool.mypy]/[tool.pyright] 段；用 uv add --group dev ty 添加 ty；运行 uv run ty check src/。
19. uv 命令速查：uv init 创建项目；uv init --package 创建可分发包；uv add <pkg> 添加依赖；uv add --group dev <pkg> 添加到依赖组；uv remove <pkg> 移除依赖；uv sync 安装依赖；uv sync --all-groups 安装所有依赖组；uv run <cmd> 在虚拟环境中运行命令；uv run --with <pkg> <cmd> 用临时依赖运行；uv build 构建包；uv publish 发布到 PyPI。
20. 临时依赖使用 uv run --with：例如 uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"；uv run --with rich python -m rich.progress；uv run --with requests --with rich python script.py；uv run --with httpx pytest。判断标准：uv add 用于项目依赖（写入 pyproject.toml/uv.lock）；--with 用于一次性使用、测试或非项目上下文脚本。
21. 依赖组配置示例：[dependency-groups] 中 dev = ["ruff", "ty"]；test = ["pytest", "pytest-cov", "hypothesis"]；docs = ["sphinx", "myst-parser"]；安装用 uv sync --group dev --group test。
22. 最佳实践清单：包使用 src/ layout；设置 requires-python = ">=3.11"；配置 ruff 使用 select = ["ALL"] 并显式 ignores；使用 ty 做类型检查；强制测试覆盖率最低 80%+；开发工具使用 dependency groups 而不是 extras；将 uv.lock 加入版本控制；独立脚本使用 PEP 723。
23. 进一步阅读参考：migration-checklist.md、pyproject.md、uv-commands.md、ruff-config.md、testing.md、pep723-scripts.md、prek.md、security-setup.md、dependabot.md。

适用边界 · 注意事项

• 用户明确希望保留旧工具链或现有工作流时。
• 必须支持 Python < 3.11 时。
• 非 Python 项目，或 Python 不是主要语言的混合代码库。