bifangknt Uv
Overview
以可复现、可审计的方式使用 uv。优先给出最小可执行命令，先读状态后做写入，明确是否会修改 uv.lock、.venv、.python-version。
Workflow
- 确认上下文：当前目录是否为
pyproject.toml项目、是否允许改动锁文件和环境。 - 先选操作面：运行命令（
run）、同步环境（sync）、更新锁（lock）、Python 版本（python）、工具（tool）。 - 先执行只读探测：版本、help、检查状态（如
uv --version、uv lock --check、uv sync --check）。 - 再执行变更命令：明确写入范围（
uv.lock、.venv、.python-version、工具目录）。 - 输出关键结果与下一步。
Operation Decision
- 只执行一次命令且不想持久安装工具：用
uv tool run（或uvx）。 - 在项目环境中执行代码/命令：用
uv run。 - 需要补齐或重建项目环境：用
uv sync。 - 需要检查或更新锁文件：用
uv lock（只检查用uv lock --check）。 - 需要固定解释器版本：用
uv python install+uv python pin。
Command Rules
uv选项必须放在被执行命令之前；必要时用--分隔（例如uv run --python 3.12 -- python）。- 需要临时依赖时用
uv run --with <pkg>或uv tool run --with <pkg>。 - 不希望自动发现项目时用
--no-project。 uv run/uv sync默认会处理 lock/sync；需要禁止写锁文件时优先--locked，需要跳过锁文件更新检查时用--frozen。- 执行 Python 脚本工具（如校验脚本）缺依赖时，优先
uv run --with pyyaml <script>。 - 在 Windows 下出现 Python 默认编码导致的
UnicodeDecodeError时，可先设置$env:PYTHONUTF8='1'后再运行uv run ...。
Failure Handling
- 命令不存在或子命令写错：先运行对应
--help，再重试最小命令。 No module named ...：改为uv run --with <missing-package> ...。--locked失败（锁文件过期）：先uv lock或uv sync更新，再重试。- 目录不是项目却执行了项目命令：改用
--no-project或切换到正确项目目录。 - PowerShell 环境变量导致参数展开异常：优先使用单引号和显式变量赋值。
Safety Checklist
执行会写入的命令前，先确认：
- 当前仓库/目录是否正确。
- 是否允许修改
uv.lock与.venv。 - 是否允许写入
.python-version。 - 是否为一次性命令（应使用
uv tool run）还是持久安装（uv tool install）。
Output Format
统一按以下结构输出：
Plan: 本次要完成的 uv 任务。Commands: 实际执行命令（先只读，后变更）。Result: 关键结果（是否改动锁文件/环境、关键版本、状态检查结果）。Next: 失败时的最短可执行下一步。
Reference
按需读取参考文档：
- 命令索引：
references/commands.md - 运行与临时依赖：
references/run.md - 锁与同步：
references/sync-lock.md - Python 版本管理：
references/python.md - 工具命令：
references/tool.md - 常见故障：
references/troubleshooting.md