---
name: "uv-env-setup"
description: "用 uv 准备并维护本项目与各技能脚本的 Python 运行环境（项目环境 uv sync / 单脚本 PEP 723 模式）。当用户提到环境准备/装依赖/重建 venv、脚本报 ModuleNotFoundError（pandas/openpyxl/playwright），或 uv/.venv 不可用时使用。"
---

# uv 运行环境准备

三种运行形态共用一个入口 `uv run`：

- **项目环境**：在含 `pyproject.toml` 的项目根运行 `scripts/` 或整套技能。根 `pyproject.toml` 是依赖唯一事实来源，`uv sync` 落地 `.venv\`，`uv run` 免激活执行。
- **单脚本模式**：脱离项目仓库单独运行某个技能脚本（如技能安装到用户级目录后跨项目使用）。三个脚本头部都带 PEP 723 内联依赖声明（`# /// script ... ///`），`uv run <脚本路径>` 会自动建缓存环境并装依赖，无需任何项目文件。
- **无 uv 回退链**：uv 完全不可用时按固定顺序降级，见步骤 1。

先按下表选分支，再执行对应步骤。

| 你的情况 | 分支 |
|---|---|
| 在本项目目录内跑任何脚本 | A：项目环境 |
| 技能已安装到用户级目录（如 `~\.trae-cn\skills\`、`~\.zcode\skills\`），当前目录没有 pyproject.toml | B：单脚本模式 |
| `uv` 命令无法识别 | 先走步骤 1 的回退链，再回到 A/B |

**完成判据（全局）**：最终用于跑业务脚本的那条命令成功打印结果，且不是靠裸 `python` 碰运气。

## 步骤 1：确认 uv 可用（含回退链）

```powershell
uv --version
```

失败时**按顺序**尝试，命中即停：

1. **会话内刷新 PATH 再试**（刚装完 uv、不想重开终端）：
   - PowerShell：`$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")`
   - Git Bash / zsh：`export PATH="$PATH:$HOME/.local/bin"`
   - cmd：重开终端（cmd 无法可靠刷新）
2. **`python -m uv --version`**：只要 uv 以模块存在就可用。此后把本文所有 `uv <子命令>` 都替换为 `python -m uv <子命令>`，其余不变。
3. **`pip install uv` 装上后回到第 2 条**（winget/官方脚本安装的 uv 对新会话才生效，pip 装的立即随当前 Python 可用）。

**完成判据**：`uv --version` 或 `python -m uv --version` 打印出版本号；若走了第 2 条，记下后续命令都要带 `-m uv`。

## 步骤 2A：项目环境同步

项目根（`pyproject.toml` 所在处）执行：

```powershell
uv sync
```

- 首次自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright、requests）。
- 本机无兼容 Python 时，uv 自动下载托管 Python（`requires-python = ">=3.10"`）。
- `uv run` 会隐式同步；显式 `uv sync` 是为了把依赖错误一次性暴露。

**完成判据**：退出码 0，且项目根出现 `.venv\` 目录。

## 步骤 2B：单脚本模式（无项目文件）

对任意一个技能脚本直接：

```powershell
uv run "C:/Users/<you>/.trae-cn/skills/yt-studio-url-builder/scripts/build_studio_urls.py" --help
```

- uv 读脚本头部的 PEP 723 声明，自动缓存专用环境（默认仅 pandas/openpyxl，或含 playwright）。
- 环境、路径写法用正斜杠 `/`，在 PowerShell、Git Bash、cmd 中都合法。
- 首次运行某脚本会下载其依赖，耗时略长属正常现象。

**完成判据**：脚本按预期输出（`--help` 打印用法 / `--selftest` 打印 selftest OK），无需 `.venv` 或 pyproject.toml。

## 步骤 3：验证

项目环境下三条自检：

```powershell
uv run python -c "import pandas, openpyxl, playwright, requests; print('env OK')"
uv run python skills/youtube-studio-csv-download/scripts/youtube_export_download.py --selftest
uv run python skills/yt-studio-groupid-lookup/scripts/lookup_groups.py --selftest
```

**完成判据**：打印 `env OK` 与两条 `selftest OK`。

## 其他技能如何使用本环境

- 四个业务技能（url-builder、groupid-lookup、csv-download）的 SKILL.md 默认**本技能已跑通**；它们给出的 `uv run python <脚本>` 命令按所选分支执行即可。
- 统一不裸调 `python`、不手动激活 venv、不向全局 `pip install` 依赖。
- 各 agent（trae-cn / zcode 等）的终端方言不同：示例中的调用统一写成对两者都安全的形态——正斜杠路径 + 引号包裹；确需 shell 特有能力时区分 PowerShell 与 bash 写法，不要混用。

## 新增依赖

- 项目环境：改根 `pyproject.toml` 的 `dependencies`（唯一入口）后 `uv sync` 更新 `uv.lock`。
- 单脚本模式：改脚本头部 PEP 723 的 `dependencies`，下次 `uv run` 自动生效。
- 两个来源不要混着加同一依赖，防止版本漂移；禁止绕过声明直装。

## 排查

网络慢/超时、镜像配置、`.venv` 损坏重建、uv 安装方式差异、无 uv 手动兜底等，查 [references/troubleshooting.md](references/troubleshooting.md)。