Sidney Zhang
9020752eed
- 为 build_studio_urls.py 和 lookup_groups.py 添加 PEP 723 依赖声明 - 修复 HTTP/2 伪头导致 requests 抛 InvalidHeader 的问题 - 添加 CDP 端口连通性预检查及启动指引
4.9 KiB
4.9 KiB
name, description
| name | description |
|---|---|
| uv-env-setup | 用 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 可用（含回退链）
uv --version
失败时按顺序尝试，命中即停：
- 会话内刷新 PATH 再试（刚装完 uv、不想重开终端）：
- PowerShell：
$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User") - Git Bash / zsh：
export PATH="$PATH:$HOME/.local/bin" - cmd：重开终端（cmd 无法可靠刷新）
- PowerShell：
python -m uv --version：只要 uv 以模块存在就可用。此后把本文所有uv <子命令>都替换为python -m uv <子命令>，其余不变。pip install uv装上后回到第 2 条（winget/官方脚本安装的 uv 对新会话才生效，pip 装的立即随当前 Python 可用）。
完成判据：uv --version 或 python -m uv --version 打印出版本号；若走了第 2 条，记下后续命令都要带 -m uv。
步骤 2A：项目环境同步
项目根（pyproject.toml 所在处）执行：
uv sync
- 首次自动创建
.venv\并安装全部依赖（pandas、openpyxl、playwright、requests）。 - 本机无兼容 Python 时，uv 自动下载托管 Python（
requires-python = ">=3.10"）。 uv run会隐式同步；显式uv sync是为了把依赖错误一次性暴露。
完成判据：退出码 0，且项目根出现 .venv\ 目录。
步骤 2B：单脚本模式（无项目文件）
对任意一个技能脚本直接：
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：验证
项目环境下三条自检：
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。