StudioLift/skills/uv-env-setup/SKILL.md

name, description

name	description
uv-env-setup	用 uv 准备并维护本项目 Python 运行环境（pyproject.toml → uv sync → uv run）。当用户提到环境准备/环境初始化/装依赖/重建 venv，脚本报 ModuleNotFoundError（pandas/openpyxl/playwright），.venv 缺失或损坏，或首次运行 scripts/、skills/*/scripts/ 下的 Python 脚本时使用。

uv 运行环境准备

本项目所有 Python 脚本共用一套 uv 管理的环境：根目录 pyproject.toml 是依赖的唯一事实来源，uv sync 落地 .venv\，uv run 执行脚本（自动使用该环境，免激活、免手装依赖）。

步骤 1：确认 uv 可用

uv --version

未安装时任选其一（Windows）：

• winget install astral-sh.uv
• powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
• pip install uv

装完重开终端使 PATH 生效。

完成判据：uv --version 打印出版本号。

步骤 2：同步依赖

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

uv sync

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

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

步骤 3：验证

uv run python -c "import pandas, openpyxl, playwright; print('env OK')"
uv run python skills\youtube-studio-csv-download\scripts\youtube_export_download.py --selftest
uv run python skills\yt-studio-url-builder\scripts\build_studio_urls.py --help

完成判据：三条命令均成功——打印 env OK、selftest OK、脚本的用法帮助。

其他技能如何使用本环境

• 统一在项目根目录用 uv run python <脚本> [参数] 执行，uv 自动向上定位 pyproject.toml 并复用其环境。
• 不用裸 python（依赖 PATH 碰运气），不手动激活 venv，不 pip install 到全局。

新增依赖

改 pyproject.toml 的 dependencies（唯一入口），再 uv sync 更新 uv.lock。禁止 pip install / uv pip install 直装——绕过 lock，环境不可复现。

排查

网络慢/超时、uv 安装失败、.venv 损坏重建、多版本 Python 冲突等，查 references/troubleshooting.md。