Files

Sidney Zhang 9020752eed

feat(scripts): 添加 PEP 723 脚本元数据并修复 HTTP/2 伪头过滤问题

- 为 build_studio_urls.py 和 lookup_groups.py 添加 PEP 723 依赖声明
- 修复 HTTP/2 伪头导致 requests 抛 InvalidHeader 的问题
- 添加 CDP 端口连通性预检查及启动指引

2026-08-27 13:33:34 +08:00

4.9 KiB

Raw Blame History

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 无法可靠刷新）
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。

4.9 KiB Raw Blame History Unescape Escape