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

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

skills/uv-env-setup/SKILL.md

@@ -1,61 +1,95 @@
 ---
 name: "uv-env-setup"
-description: "用 uv 准备并维护本项目 Python 运行环境（pyproject.toml → uv sync → uv run）。当用户提到环境准备/环境初始化/装依赖/重建 venv，脚本报 ModuleNotFoundError（pandas/openpyxl/playwright），.venv 缺失或损坏，或首次运行 scripts/、skills/*/scripts/ 下的 Python 脚本时使用。"
+description: "用 uv 准备并维护本项目与各技能脚本的 Python 运行环境（项目环境 uv sync / 单脚本 PEP 723 模式）。当用户提到环境准备/装依赖/重建 venv、脚本报 ModuleNotFoundError（pandas/openpyxl/playwright），或 uv/.venv 不可用时使用。"
 ---
 
 # uv 运行环境准备
 
-本项目所有 Python 脚本共用一套 uv 管理的环境：根目录 `pyproject.toml` 是依赖的**唯一事实来源**，`uv sync` 落地 `.venv\`，`uv run` 执行脚本（自动使用该环境，免激活、免手装依赖）。
+三种运行形态共用一个入口 `uv run`：
 
-## 步骤 1：确认 uv 可用
+- **项目环境**：在含 `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
 ```
 
-未安装时任选其一（Windows）：
+失败时**按顺序**尝试，命中即停：
 
-- `winget install astral-sh.uv`
-- `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
-- `pip install uv`
+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 可用）。
 
-装完重开终端使 PATH 生效。
+**完成判据**：`uv --version` 或 `python -m uv --version` 打印出版本号；若走了第 2 条，记下后续命令都要带 `-m uv`。
 
-**完成判据**：`uv --version` 打印出版本号。
+## 步骤 2A：项目环境同步
 
-## 步骤 2：同步依赖
-
-项目根目录（`pyproject.toml` 所在处）执行：
+项目根（`pyproject.toml` 所在处）执行：
 
 ```powershell
 uv sync
 ```
 
-- 首次运行自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright）。
+- 首次自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright、requests）。
 - 本机无兼容 Python 时，uv 自动下载托管 Python（`requires-python = ">=3.10"`）。
-- `uv run` 本身也会隐式同步；显式 `uv sync` 是为了在跑脚本前把依赖错误一次性暴露出来。
+- `uv run` 会隐式同步；显式 `uv sync` 是为了把依赖错误一次性暴露。
 
-**完成判据**：命令退出码 0，且项目根出现 `.venv\` 目录。
+**完成判据**：退出码 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; 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
+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`、脚本的用法帮助。
+**完成判据**：打印 `env OK` 与两条 `selftest OK`。
 
 ## 其他技能如何使用本环境
 
-- 统一在项目根目录用 `uv run python <脚本> [参数]` 执行，uv 自动向上定位 `pyproject.toml` 并复用其环境。
-- 不用裸 `python`（依赖 PATH 碰运气），不手动激活 venv，不 `pip install` 到全局。
+- 四个业务技能（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`。禁止 `pip install` / `uv pip install` 直装——绕过 lock，环境不可复现。
+- 项目环境：改根 `pyproject.toml` 的 `dependencies`（唯一入口）后 `uv sync` 更新 `uv.lock`。
+- 单脚本模式：改脚本头部 PEP 723 的 `dependencies`，下次 `uv run` 自动生效。
+- 两个来源不要混着加同一依赖，防止版本漂移；禁止绕过声明直装。
 
 ## 排查
 
-网络慢/超时、uv 安装失败、`.venv` 损坏重建、多版本 Python 冲突等，查 [references/troubleshooting.md](references/troubleshooting.md)。
+网络慢/超时、镜像配置、`.venv` 损坏重建、uv 安装方式差异、无 uv 手动兜底等，查 [references/troubleshooting.md](references/troubleshooting.md)。