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

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

skills/youtube-studio-csv-download/SKILL.md

@@ -15,8 +15,8 @@ description: "Download YouTube Studio analytics CSV export (zip) via a Playwrigh
 
 ## 脚本与依赖
 
-- 脚本：`scripts/youtube_export_download.py`（本技能目录下；若缺失，用 SearchCodebase 按 `youtube_export_download.py` 定位）
-- 依赖：playwright 已在根 `pyproject.toml` 统一声明，环境准备见 `uv-env-setup` 技能（复用系统 Chrome/Edge 时无需 `playwright install chromium`）
+- 脚本：`scripts/youtube_export_download.py`（本技能目录下；若缺失，用代码库全局搜索按 `youtube_export_download.py` 定位）
+- 依赖与环境：见 `uv-env-setup` 技能——项目环境走 `uv sync`；脱离项目时脚本头部带 PEP 723 声明，`uv run <脚本>` 自动备环境（复用系统 Chrome/Edge 时无需 `playwright install chromium`）。
 - 登录态必须已存在：脚本不登录，只复用已登录会话。
 
 ## 步骤 1：确认登录态来源（二选一）
@@ -32,30 +32,43 @@ description: "Download YouTube Studio analytics CSV export (zip) via a Playwrigh
 
 ## 步骤 2：运行脚本
 
+路径写法用正斜杠 + 引号，PowerShell / Git Bash / cmd 通用（`C:/Users/<you>/...` 即 `$env:LOCALAPPDATA` 指向的位置）。
+
 方式 A：
 
 ```powershell
-uv run python scripts\youtube_export_download.py --url "<explore URL>" --channel chrome --user-data-dir "$env:LOCALAPPDATA\Google\Chrome\User Data"
+uv run python scripts/youtube_export_download.py --url "<explore URL>" --channel chrome --user-data-dir "C:/Users/<you>/AppData/Local/Google/Chrome/User Data"
 ```
 
 方式 B（先 `chrome.exe --remote-debugging-port=9222` 或 `msedge.exe --remote-debugging-port=9222` 打开已登录浏览器）：
 
 ```powershell
-uv run python scripts\youtube_export_download.py --url "<explore URL>" --connect http://localhost:9222
+uv run python scripts/youtube_export_download.py --url "<explore URL>" --connect http://localhost:9222
 ```
 
-`--channel` 只允许 `chrome` / `msedge`，且必须与 `--user-data-dir` 指向的浏览器**同一品牌**。
+- 脱离项目环境时省略 `python <脚本>` 前缀，直接 `uv run "<技能目录>/scripts/youtube_export_download.py" ...`（单脚本模式）。
+- 默认下载到 `D:\Downloads`；运行在沙箱/受限环境的 agent（如部分 IDE 内置终端、云环境）看不到该盘符，**必须传 `--download-dir` 指向工作区内已存在的目录**。
+- 脚本会自动重试一次：未捕获到有效导出响应时再点一遍导出按钮。
+- `--channel` 只允许 `chrome` / `msedge`，且必须与 `--user-data-dir` 指向的浏览器**同一品牌**。
 
 **完成判据**：终端打印 `已保存: <完整路径> (<字节数>)`，退出码 0。
 
 ## 步骤 3：校验产物
 
+列出下载目录最新的 zip（按所用 shell 选一条）：
+
 ```powershell
-Get-ChildItem -Path "D:\Downloads" -Filter "*.zip" | Sort-Object LastWriteTime -Descending | Select-Object -First 3 Name, Length, LastWriteTime
+Get-ChildItem -Path "<download-dir>" -Filter "*.zip" | Sort-Object LastWriteTime -Descending | Select-Object -First 3 Name, Length, LastWriteTime
 ```
 
-**完成判据**：存在最新 `<维度标签> <起始日>_<结束日> <账号名>.zip`（如 `内容 2026-07-23_2026-08-20 WL Media.zip`）；同名重复时后缀为 ` (1)`、` (2)`。
+```bash
+ls -lt "<download-dir>"/*.zip | head -3
+```
+
+**完成判据**：存在最新 `<维度标签> <起始日>_<结束日> <账号名>.zip`（如 `内容 2026-07-23_2026-08-20 WL Media.zip`）；同名重复时后缀为 ` (1)`、` (2)`。脚本落盘前已做 zip 完整性校验，能写盘即可解压。
 
 ## 遇到问题
 
-查 `references/troubleshooting.md`（未登录跳转、目录被占用、CDP 连不上、channel 不匹配、未捕获响应、文件名回退等）。
+查 `references/troubleshooting.md`（未登录跳转、目录被占用、CDP 连不上、channel 不匹配、未捕获响应、文件名回退等）。
+
+> **批量场景**：多份 URL 循环下载时，由调用方外层逐条调用本脚本并复用同一登录态，脚本保持单 URL 语义；每条失败可独立重跑。