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
parent b8bd749f43
commit 9020752eed
23 changed files with 885 additions and 294 deletions
--- a/skills/uv-env-setup/SKILL.md
+++ b/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)。
--- a/skills/uv-env-setup/references/troubleshooting.md
+++ b/skills/uv-env-setup/references/troubleshooting.md
@@ -1,9 +1,20 @@
 # 环境排查

-## uv 安装与 PATH
+## uv 不识别（按序排查）

- **`uv: command not found` / 无法识别**：装完未重开终端，PATH 未生效；重开终端或手动刷新 `$env:Path`。
- **winget 安装失败**：改用官方脚本 `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`，或 `pip install uv`。
+1. **刚装完、当前会话不认识**：会话内刷新 PATH——
+   - PowerShell：`$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")`
+   - Git Bash / zsh：`export PATH="$PATH:$HOME/.local/bin"`
+   - cmd：重开终端。
+2. **试试模块入口**：`python -m uv --version`。可用则后续所有 `uv <子命令>` 都换成 `python -m uv <子命令>`。
+3. **用 pip 兜底安装**：`pip install uv` 后回到第 2 条，立即生效（winget/官方脚本方式要等新终端）。
+4. **彻底没有 Python/uv**：先装 Python 3.10+（或让 `uv` 官方脚本一并装好托管 Python），再走第 3 条。
+
+## 无 pyproject.toml 的目录跑脚本
+
+- 脚本头部带 PEP 723 声明（`# /// script ... ///`），直接 `uv run <脚本>` 即可，uv 自动建缓存环境。
+- 报「无法解析依赖/找不到脚本」时：确认路径存在且为正斜杠写法；确认脚本头部声明未被删改。
+- 需要重建缓存环境：删除 `%LOCALAPPDATA%\uv\cache\environments-v2` 下对应目录（或整体清 `uv cache clean`）后重试。

 ## 网络与镜像（国内环境）

@@ -28,6 +39,14 @@ default = true
 - **lock 与 pyproject 不一致**：`uv.lock` 过期，`uv sync` 会自动更新；若报 lock 损坏，删除 `uv.lock` 后重新 `uv sync`。
 - **`requires-python` 不满足**：本机 Python 全部低于 3.10。让 uv 自动下载即可：`uv sync -p 3.12`（或省略，uv 自选）。

+## 已有 .venv 但缺 pyproject.toml
+
+历史环境是手动 `pip install` 搭的，不是 uv 管理：
+
+1. 在项目根新建 `pyproject.toml`，`dependencies` 写全实际用到的包（参考现有 .venv 里 `pip list`）。
+2. `requires-python` 与现有解释器大版本一致（如 `">=3.12"`），避免 uv 另下新 Python。
+3. `uv sync` 让 uv 接管该 `.venv` 并生成 `uv.lock`。
+
 ## .venv 损坏 / 重建

 症状：`uv run` 报奇怪的导入错误、DLL 加载失败，或 `.venv` 被移动过。
@@ -39,10 +58,20 @@ uv sync

 ## playwright 相关

- **`ModuleNotFoundError: playwright`**：环境未同步。项目根执行 `uv sync`，或直接用 `uv run python <脚本>`（隐式同步）。
+- **`ModuleNotFoundError: playwright`**：环境未同步。项目根执行 `uv sync`，或直接用 `uv run python <脚本>`；单脚本模式下直接 `uv run <脚本>`（PEP 723 自动装）。详见 SKILL.md 步骤 1 回退链。
 - **复用系统 Chrome/Edge 无需 `playwright install`**：只有用 uv 环境内置 Chromium 时才需要 `uv run playwright install chromium`。
 - **`playwright install` 下载浏览器慢**：`$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright"` 后重试。

+## 无 uv 的最终兜底
+
+uv 完全装不上时，用标准库 venv 手动搭（仅应急，失去 lock 可复现性）：
+
+```powershell
+python -m venv .venv
+.venv\Scripts\python.exe -m pip install pandas openpyxl playwright requests
+# 此后所有命令用 .venv\Scripts\python.exe 替代 uv run python
+```
+
 ## 与全局环境隔离

 - 本项目所有命令都经 `uv run`，不会污染全局 site-packages。
--- a/skills/youtube-studio-csv-download/SKILL.md
+++ b/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 语义；每条失败可独立重跑。
--- a/skills/youtube-studio-csv-download/references/troubleshooting.md
+++ b/skills/youtube-studio-csv-download/references/troubleshooting.md
@@ -14,12 +14,16 @@

 ## 运行过程

- **找不到「导出当前视图」按钮 / 点击超时**：URL 不是 explore 页，或页面尚未加载完。务必用用户提供的 explore URL，别用 overview URL。
+- **找不到「导出当前视图」按钮 / 点击超时**：
+  - URL 不是 explore 页，或页面尚未加载完。务必用用户提供的 explore URL，别用 overview URL。
+  - 当前界面该入口是右上角**下载图标按钮**（只有 `aria-label`、无可见文本），脚本已按 label 定位并以文本定位兜底；若仍超时，确认页面语言为中文或改在英文界面重试（label 为 "Export current view"）。
+  - 脚本未捕获到有效响应时会自动重试一次触发；连续失败时手动确认页面能正常导出。
 - **没打印「已保存」（未捕获 csv_export 响应）**：导出未被触发，或登录态已失效。重试步骤 2，必要时重新登录后重跑。
+- **解出的 zip 报损坏 / `Incorrect padding`**：`zippedData` 是 URL-safe 无填充 base64，脚本已按此解码并做完整性校验后落盘；仍报错说明响应内容异常，检查是否被代理/网关改写。
 - **文件名变成 `export.zip` 而非标准命名**：请求体解析失败触发兜底，内容仍完整；检查日期范围与账号名是否正常。
 - **中文/特殊字符文件名**：已把 Windows 非法字符 `\/:*?"<>|` 自动替换为 `_`，不会因文件名失败。

 ## 产物与去重

- **下载目录不存在导致写盘失败**：脚本不自动建目录。先建 `D:\Downloads`，或用 `--download-dir` 指定已存在目录。
+- **下载目录不存在导致写盘失败**：脚本启动时会自动创建下载目录（`os.makedirs(..., exist_ok=True)`）。沙箱/受限环境看不到 `D:\Downloads` 时，用 `--download-dir` 指向工作区内目录即可。
 - **重名文件**：自动按 `名称 (1).zip`、`名称 (2).zip` 递增；这是脚本自己的 dedup_path 逻辑，不依赖浏览器。
--- a/skills/youtube-studio-csv-download/scripts/youtube_export_download.py
+++ b/skills/youtube-studio-csv-download/scripts/youtube_export_download.py
@@ -1,13 +1,22 @@
 # -*- coding: utf-8 -*-
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "playwright>=1.40",
+# ]
+# ///
 r"""
 YouTube Studio 内容管理器「导出当前视图 → 逗号分隔值 (.csv)」下载脚本
-（拦截响应 + 解码 zip + 自动保存到下载目录 + 重名去重）。
+（拦截响应 + 解码 zip + 完整性校验 + 自动保存到下载目录 + 重名去重）。

 机制（已实证）：前端点击导出后向后端
    POST https://studio.youtube.com/youtubei/v1/yta_web/csv_export?alt=json
 后端把打好的 zip 以 base64 内联在响应 `zippedData` 字段里（开头 `UEsDBBQ` 即 ZIP 文件头 `PK`）。
-本脚本拦截该响应，base64 解码后按 `<维度标签> <起始日>_<结束日> <账号名>.zip` 写盘，
-重名自动加 ` (n)` 后缀，n 从 1 起。
+注意两个字段细节（均为实证结论）：
+  - `zippedData` 是 **URL-safe base64**（-/_ 代替 +//，且省略 = 填充）；
+  - 当前界面导出入口是右上角**下载图标按钮**：只有 `aria-label="导出当前视图"`，没有可见文本。
+本脚本拦截该响应，base64 解码并校验 zip 完整性后按 `<维度标签> <起始日>_<结束日> <账号名>.zip`
+写盘，重名自动加 ` (n)` 后缀，n 从 1 起；未捕获到有效响应时自动重试一次触发导出。

 登录态：脚本不负责登录，必须复用已登录 YouTube Studio 的浏览器会话，二选一：
  - --user-data-dir + --channel chrome|msedge ：用已登录的用户数据目录启动（需先关闭该浏览器）
@@ -15,19 +24,25 @@ YouTube Studio 内容管理器「导出当前视图 → 逗号分隔值 (.csv)

 用法：
  python youtube_export_download.py --selftest
-  python youtube_export_download.py --url "<explore URL>" --channel chrome --user-data-dir "C:\Users\<you>\AppData\Local\Google\Chrome\User Data"
+  python youtube_export_download.py --url "<explore URL>" --channel chrome --user-data-dir "C:/Users/<you>/AppData/Local/Google/Chrome/User Data"
  python youtube_export_download.py --url "<explore URL>" --connect http://localhost:9222
 """

 import argparse
 import base64
+import io
 import json
 import os
 import re
 import sys
+import time
+import zipfile

 DOWNLOAD_DIR = r"D:\Downloads"  # 默认下载目录，可用 --download-dir 覆盖

+EXPORT_RESPONSE_TIMEOUT = 30  # 每次触发导出后等待 csv_export 响应的秒数
+MAX_EXPORT_ATTEMPTS = 2       # 未捕获到有效响应时的最大触发次数（1 次重试）
+
 # 维度类型 -> 文件名前缀标签（生产环境建议从页面「维度」按钮文本读取，这里兜底映射）。
 DIMENSION_LABEL = {
    "VIDEO": "内容",
@@ -80,11 +95,43 @@ def build_export_filename(export_query, account_name, dimension_label=None):


 def decode_zipped_data(payload):
-    """把 csv_export 响应 payload 里的 zippedData 解码为 zip 字节流。"""
+    """把 csv_export 响应 payload 里的 zippedData 解码为 zip 字节流。
+
+    该字段是 URL-safe base64（-/_ 代替 +//，且省略 = 填充）：标准 b64decode 遇
+    -/_ 或非 4 对齐长度会抛 Incorrect padding，或静默解出损坏字节流。先补齐填充，
+    再用 altchars 兼容 URL-safe 与标准两种字符表；解码后校验 PK 文件头。
+    """
    zipped = payload.get("zippedData")
    if not zipped:
        raise ValueError("响应中缺少 zippedData 字段")
-    return base64.b64decode(zipped)
+    z = str(zipped).strip()
+    data = base64.b64decode(z + "=" * (-len(z) % 4), altchars=b"-_")
+    if not data.startswith(b"PK"):
+        raise ValueError(
+            "zippedData 解码结果不是 zip 字节流（缺 PK 文件头），"
+            "响应可能被网关改写或导出接口已变动")
+    return data
+
+
+def verify_zip(data):
+    """校验内存 zip 完整性：结构可读、成员 CRC 全过；否则抛 ValueError。"""
+    try:
+        with zipfile.ZipFile(io.BytesIO(data)) as zf:
+            bad = zf.testzip()
+    except zipfile.BadZipFile as e:
+        raise ValueError(f"zip 结构损坏: {e}") from e
+    if bad is not None:
+        raise ValueError(f"zip 成员 CRC 校验失败: {bad}")
+
+
+def trigger_export(page):
+    """点「导出当前视图」→「逗号分隔值 (.csv)」。
+
+    导出入口是右上角的下载图标按钮：只有 aria-label、无可见文本，
+    优先按 label 定位（get_by_text 兜底旧版有可见文本的界面）。
+    """
+    page.get_by_label("导出当前视图").or_(page.get_by_text("导出当前视图")).first.click()
+    page.get_by_text("逗号分隔值 (.csv)").click()


 def intercept_and_save(page, account_name, download_dir):
@@ -99,6 +146,7 @@ def intercept_and_save(page, account_name, download_dir):
        try:
            payload = response.json()
            data = decode_zipped_data(payload)
+            verify_zip(data)

            filename = None
            try:
@@ -132,6 +180,7 @@ def run(url, user_data_dir=None, channel=None, cdp_url=None,
    from playwright.sync_api import sync_playwright

    download_dir = download_dir or DOWNLOAD_DIR
+    os.makedirs(download_dir, exist_ok=True)

    with sync_playwright() as p:
        browser = None
@@ -175,10 +224,17 @@ def run(url, user_data_dir=None, channel=None, cdp_url=None,

        saved = intercept_and_save(page, account_name, download_dir)

-        # 触发导出：点「导出当前视图」→「逗号分隔值 (.csv)」
-        page.get_by_text("导出当前视图").click()
-        page.get_by_text("逗号分隔值 (.csv)").click()
-        page.wait_for_timeout(3000)
+        # 触发导出并等待响应；未捕获到有效 zip（未触发/响应无效）自动重试一次
+        for attempt in range(1, MAX_EXPORT_ATTEMPTS + 1):
+            trigger_export(page)
+            deadline = time.time() + EXPORT_RESPONSE_TIMEOUT
+            while not saved and time.time() < deadline:
+                page.wait_for_timeout(500)
+            if saved:
+                break
+            if attempt < MAX_EXPORT_ATTEMPTS:
+                print(f"[重试] 第 {attempt} 次未捕获到有效导出响应，自动重试……",
+                      file=sys.stderr)

        if not saved:
            print("未捕获到 csv_export 响应，请确认已点击导出且登录态有效。")
@@ -222,7 +278,25 @@ def selftest():
        name = build_export_filename(export_query, "WL Media")
        assert name == "内容 2026-07-23_2026-08-20 WL Media.zip", name

-    print("selftest OK：去重与文件名反推逻辑全部通过")
+        # zip 解码：标准 base64 与 URL-safe 无填充变体都要解出同一字节流
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+            zf.writestr("a.csv", "x,y\n1,2")
+        raw = buf.getvalue()
+        std = base64.b64encode(raw).decode("ascii")
+        urlsafe_nopad = std.replace("+", "-").replace("/", "_").rstrip("=")
+        assert decode_zipped_data({"zippedData": std}) == raw
+        assert decode_zipped_data({"zippedData": urlsafe_nopad}) == raw
+        verify_zip(raw)
+
+        # 非 zip 字节流要报 PK 文件头错误，而不是静默落盘损坏文件
+        try:
+            decode_zipped_data({"zippedData": base64.b64encode(b"not a zip").decode()})
+            raise AssertionError("非 zip 数据应抛 ValueError")
+        except ValueError as e:
+            assert "PK" in str(e), e
+
+    print("selftest OK：去重、文件名反推、zip 解码与完整性校验全部通过")


 if __name__ == "__main__":
@@ -245,7 +319,8 @@ if __name__ == "__main__":
            account_name=args.account_name)
    else:
        selftest()
-        print("\n实际运行需先 pip install playwright，再复用登录态（二选一）：\n"
+        print("\n实际运行需先准备依赖环境（uv sync 或直接 uv run，见 uv-env-setup 技能），"
+              "再复用登录态（二选一）：\n"
              "  方式 A: python youtube_export_download.py --url \"<explore URL>\" "
              "--channel chrome --user-data-dir <你的 Chrome User Data 目录>\n"
              "  方式 B: python youtube_export_download.py --url \"<explore URL>\" "
--- a/skills/yt-studio-groupid-lookup/SKILL.md
+++ b/skills/yt-studio-groupid-lookup/SKILL.md
@@ -14,6 +14,8 @@ description: "把一批群组名批量解析为 entity_id（即 groupId），并
 - **建 URL 前置**：要生成 explore 报告 URL，但清单里只有群组名、没有 entity_id。
 - **排查失败**：回放遇到 401 / 查不到 / 大小写差异，需要定位修复。

+> **流程位置**：本技能是 `yt-studio-url-builder` 的前置——url-builder 只认 `entity_id`（groupId）；清单里只有群组名时必须先跑本技能把 ID 填进清单，再交给 url-builder。
+
 ## 领域词汇

 - **套件（Bundle）**：从页面捕获的一次 `search_groups` 请求 = 完整请求头（`Authorization: SAPISIDHASH...`、`Cookie`、`X-YouTube-Delegation-Context` 等）+ 请求体模板（含 `context.user.delegationContext`）。一个内容所有者一份。手写必 401，唯一可靠来源。
@@ -24,8 +26,8 @@ description: "把一批群组名批量解析为 entity_id（即 groupId），并

 ## 脚本与依赖

- 脚本：`scripts/lookup_groups.py`（本技能目录下；若缺失，用 SearchCodebase 按 `lookup_groups.py` 定位）。
- 依赖：playwright、requests、openpyxl 已统一在根 `pyproject.toml` 声明（`uv sync` 自动装），环境准备见 `uv-env-setup` 技能。
+- 脚本：`scripts/lookup_groups.py`（本技能目录下；若缺失，用代码库全局搜索按 `lookup_groups.py` 定位）。
+- 依赖与环境：见 `uv-env-setup` 技能——项目环境走 `uv sync`；脱离项目时脚本头部带 PEP 723 声明，`uv run <脚本>` 自动备环境。
 - 登录态必须已存在：脚本不登录，只复用已登录 YouTube Studio 会话，否则跳 Google 登录页。

 ## 选择运行分支
@@ -44,7 +46,7 @@ description: "把一批群组名批量解析为 entity_id（即 groupId），并
 ### 步骤 0：环境与自测（分支 D）

 ```bash
-uv run python scripts\lookup_groups.py --selftest
+uv run python scripts/lookup_groups.py --selftest
 ```

 **完成判据**：打印 `selftest OK`，退出码 0（无需浏览器/网络）。
@@ -54,7 +56,8 @@ uv run python scripts\lookup_groups.py --selftest
 复用已登录 YouTube Studio 的浏览器会话，否则跳 Google 登录页。与 `youtube-studio-csv-download` 同一套约定：

 - 方式 A（能关浏览器）：`--user-data-dir <目录> --channel chrome|msedge`，二者必须同品牌。
- 方式 B（浏览器不能关）：先 `chrome.exe --remote-debugging-port=9222` 或 `msedge.exe --remote-debugging-port=9222`，再加 `--connect http://localhost:9222`。
+- 方式 B（浏览器不能关）：先 `chrome.exe --remote-debugging-port=9222` 或 `msedge.exe --remote-debugging-port=9222`，再加 `--connect http://localhost:9222`。脚本附加前会先探测端口；报 `CDP 端口不可达` 时按提示排查——最常见是**旧 Chrome/Edge 残留进程吞掉了调试端口参数**，需彻底退出后重启或改用独立 user-data-dir 启动。
+- 注意：cookie 存在不等于会话有效。profile 目录里看得到 SAPISID/SID 等 cookie 也可能仍跳登录页，此时由用户在浏览器手动登录一次再重跑。

 **完成判据**：得到任意一种可复用的登录态（用户数据目录路径，或调试端口号）。

@@ -67,19 +70,19 @@ uv run python scripts\lookup_groups.py --selftest

 ### 步骤 3：运行脚本

-分支 A（在线捕获 + 回放）：
+分支 A（在线捕获 + 回放；路径写法统一正斜杠 + 引号，PowerShell / Git Bash / cmd 通用）：

 ```powershell
 # 单所有者
-uv run python scripts\lookup_groups.py --url "<owner URL>" --names 名单.xlsx --channel chrome --user-data-dir "$env:LOCALAPPDATA\Google\Chrome\User Data"
+uv run python scripts/lookup_groups.py --url "<owner URL>" --names 名单.xlsx --channel chrome --user-data-dir "C:/Users/<you>/AppData/Local/Google/Chrome/User Data"
 # 多所有者：--url 重复；浏览器不能关就改用 --connect
-uv run python scripts\lookup_groups.py --url "<owner1 URL>" --url "<owner2 URL>" --names 名单.csv --connect http://localhost:9222 --save-bundles bundles.json
+uv run python scripts/lookup_groups.py --url "<owner1 URL>" --url "<owner2 URL>" --names 名单.csv --connect http://localhost:9222 --save-bundles bundles.json
 ```

 分支 B（离线回放，套件已存盘，无需浏览器）：

 ```powershell
-uv run python scripts\lookup_groups.py --bundles bundles.json --names 名单.json --out result.xlsx
+uv run python scripts/lookup_groups.py --bundles bundles.json --names 名单.json --out result.xlsx
 ```

 分支 C（仅捕获/校验套件，暂不查询）：
@@ -90,8 +93,9 @@ uv run python scripts\lookup_groups.py --url "<owner URL>" --save-bundles bundle

 **关键行为**：
 - 打开页面后先**自动触发一次群组搜索**（猜搜索框）；猜不中会提示「在浏览器顶部搜索框输入任意词并回车」，只需触发一次 `search_groups` 请求即可。
- 捕到请求后，脚本校验 `delegationContext.externalOwnerId` 与 URL ownerId 是否一致、鉴权头是否齐全（缺 Authorization/Cookie/delegation 是 401 根因，会在捕获时直接打警告）。
+- 捕到请求后，脚本校验 `delegationContext.externalOwnerId` 与 URL ownerId 是否一致、鉴权头是否齐全（缺 Authorization/Cookie/delegation 是 401 根因，会在捕获时直接打警告），并**自动过滤 HTTP/2 伪头**（`:authority` 等，流入 requests 会报 InvalidHeader）。
 - 回放用线程本地 Session，并发（默认 8 线程）逐个名字 × 逐个所有者，**首个精确命中即停**。
+- 套件是一次性凭据：鉴权头逐请求计算，回放前如间隔较久或全量 401，直接重新在线捕获更新 `bundles.json`。

 **完成判据**：终端打印 `[输出] 精确命中 N/M -> <路径>`，退出码 0，且生成结果文件。

--- a/skills/yt-studio-groupid-lookup/references/troubleshooting.md
+++ b/skills/yt-studio-groupid-lookup/references/troubleshooting.md
@@ -14,6 +14,12 @@
 - 原因：方式 A 时浏览器未关闭（用户数据目录被占用）；方式 B 时调试端口没起。
 - 解决：方式 A 关闭 Chrome/Edge 后重试；方式 B 先 `chrome.exe --remote-debugging-port=9222`（或 msedge）再运行。

+### CDP 端口不可达（脚本前置探测）
+- 现象：`[!] CDP 端口不可达: http://localhost:9222`（Playwright 连接之前就报出）。
+- 原因一：浏览器根本没带 `--remote-debugging-port=9222` 启动。按提示命令重启。
+- 原因二：**带参数启动了但仍不通**——有 Chrome/Edge 残留进程占着默认 profile，新实例的调试端口参数被已运行实例吞掉（Chrome 单实例复用机制）。彻底退出所有该浏览器进程（任务管理器确认）后重启；或改用独立目录启动：`chrome.exe --remote-debugging-port=9222 --user-data-dir="C:/yts-cdp"`。
+- 脚本已在附加前先探测端口并区分这两种情况，遇到即按输出指引处理，无需先跑 Playwright 再排错。
+
 ### channel 不匹配
 - 现象：启动后用 --user-data-dir 报告浏览器品牌不符。
 - 原因：`--channel` 与用户数据目录指向的浏览器不是同一品牌（chrome / msedge）。
@@ -43,6 +49,16 @@

 ## 回放查询

+### 回放报 InvalidHeader（Invalid leading whitespace / 伪头）
+- 现象：`requests` 抛 `InvalidHeader: Invalid leading whitespace, expected field value...`。
+- 原因：套件 headers 里残留 HTTP/2 伪头（`:authority`、`:method`、`:path`、`:scheme`），不能当普通头发送。
+- 解决：脚本已双保险——捕获时自动过滤（输出 `已过滤 HTTP/2 伪头 N 个`），回放时再滤一次兜住旧 bundles.json；新版本无需人工处理。
+
+### 跳转到 Google 登录页但 profile 里看得到 cookie
+- 现象：Cookies 文件里有 SAPISID/SID/__Secure-3PSID 等，页面仍停在 accounts.google。
+- 原因：cookie 存在不等于会话有效，Google 已在服务端让该会话过期。
+- 解决：由用户在该浏览器手动重新登录一次，之后继续复用该会话；不要试图靠改 cookie 文件修复。
+
 ### 回放全量 401
 - 现象：结果备注大量 `HTTP401（鉴权失败：套件缺 Authorization/Cookie 或已过期，请重新捕获）`。
 - 原因：套件过期（鉴权头是逐请求计算的），或头不全。
@@ -93,4 +109,4 @@

 ### 缺依赖报 ModuleNotFoundError
 - 现象：`ModuleNotFoundError: No module named 'requests'` 或 `'playwright'` 或 `'openpyxl'`。
- 解决：项目根 `uv sync` 后统一用 `uv run` 前缀执行；或单独 `pip install requests playwright openpyxl`。
+- 解决：项目根 `uv sync` 后统一用 `uv run` 前缀执行；脱离项目时直接 `uv run <脚本>`（脚本头部 PEP 723 声明会自动装依赖，见 `uv-env-setup` 技能）；或单独 `pip install requests playwright openpyxl`。
--- a/skills/yt-studio-groupid-lookup/scripts/lookup_groups.py
+++ b/skills/yt-studio-groupid-lookup/scripts/lookup_groups.py
@@ -1,4 +1,13 @@
 # -*- coding: utf-8 -*-
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "playwright>=1.40",
+#     "requests>=2.31",
+#     "openpyxl>=3.1",
+#     "pandas>=2.0",
+# ]
+# ///
 r"""
 YouTube Studio 内容管理器「群组名 -> entity_id（groupId）」批量解析脚本
 （Playwright 自动捕获鉴权套件 + requests 回放查询 + Excel/CSV 输出）。
@@ -88,6 +97,10 @@ HTTP_HINTS = {
    429: "（限流：调低 --max-workers 或稍后重试）",
 }

+# HTTP/2 伪头（:authority/:method/:path/:scheme）：requests 作为普通头发送会抛
+# InvalidHeader。捕获时即过滤，不让伪头流入 bundles.json。
+PSEUDO_HEADER_RE = re.compile(r"^:")
+
 REQUEST_TIMEOUT = 30
 MANUAL_WAIT_SECONDS = 180

@@ -256,8 +269,10 @@ def search(bundle: dict, name: str, session=None) -> dict:

    session 可注入测试替身（.post(url, json=..., headers=..., timeout=...)）。
    """
+    # 双保险：捕获时已滤伪头，这里再滤一次兜住手工维护的旧 bundles.json
    headers = {k: v for k, v in (bundle.get("headers") or {}).items()
-               if str(k).lower() not in STRIP_HEADERS}
+               if str(k).lower() not in STRIP_HEADERS
+               and not PSEUDO_HEADER_RE.match(str(k))}
    body = build_body(bundle.get("bodyTemplate") or {}, name)
    url = bundle.get("url") or ENDPOINT
    try:
@@ -386,6 +401,26 @@ OWNER_DISPLAY_SELECTORS = (
 )


+def _assert_cdp_reachable(cdp_url):
+    """CDP 附加前先探测调试端口，失败时给出可执行的启动指引（区别于端口通但被吞）。"""
+    base = (cdp_url or "").rstrip("/")
+    try:
+        import urllib.request
+
+        with urllib.request.urlopen(f"{base}/json/version", timeout=3):
+            return
+    except Exception:
+        pass
+    raise SystemExit(
+        f"[!] CDP 端口不可达: {base}\n"
+        "    先确认浏览器已带调试端口参数启动：\n"
+        '      chrome.exe --remote-debugging-port=9222  '
+        '(msedge.exe 同理，或 chrome.exe --remote-debugging-port=9222 --user-data-dir="C:/yts-cdp")\n'
+        "    若已带参数仍连不上：有 Chrome/Edge 残留进程占用了默认 profile，"
+        "新实例的调试端口参数会被吞掉。请先在任务管理器彻底退出所有 Chrome/Edge 进程，"
+        '再重启；或改用独立 user-data-dir 启动（如 --user-data-dir="C:/yts-cdp"）。')
+
+
 def _launch_page(p, user_data_dir, channel, cdp_url):
    """按 interceptor 同款三种方式拿到 (browser, context, page)。"""
    if cdp_url:
@@ -496,6 +531,12 @@ def _capture_bundle(page, url, wait_seconds, owner_display=""):
        headers = dict(req.all_headers())
    except Exception:  # noqa: BLE001
        headers = dict(req.headers)
+    # 过滤 HTTP/2 伪头，防止回放时 requests 抛 InvalidHeader
+    pseudo = sorted(k for k in headers if PSEUDO_HEADER_RE.match(k))
+    if pseudo:
+        print(f"[捕获] 已过滤 HTTP/2 伪头 {len(pseudo)} 个: {', '.join(pseudo)}",
+              file=sys.stderr)
+        headers = {k: v for k, v in headers.items() if not PSEUDO_HEADER_RE.match(k)}
    try:
        body = json.loads(req.post_data or "{}")
    except Exception:  # noqa: BLE001
@@ -535,6 +576,8 @@ def capture_bundles(urls, user_data_dir=None, channel=None, cdp_url=None,

    mode = "CDP 附加" if cdp_url else ("用户数据目录" if user_data_dir else "全新会话（大概率未登录）")
    print(f"[捕获] 浏览器会话：{mode}")
+    if cdp_url:
+        _assert_cdp_reachable(cdp_url)

    bundles = []
    with sync_playwright() as p:
@@ -545,7 +588,8 @@ def capture_bundles(urls, user_data_dir=None, channel=None, cdp_url=None,
        except Exception as e:  # noqa: BLE001
            raise SystemExit(
                f"[!] 启动/连接浏览器失败: {e}\n"
-                "    方式 A 需先关闭对应浏览器；方式 B 先以调试端口启动：\n"
+                "    方式 A 需先关闭对应浏览器（有残留进程会报目录被占用）；"
+                "方式 B 先以调试端口启动：\n"
                "    chrome.exe --remote-debugging-port=9222")
        try:
            for i, url in enumerate(urls, 1):
--- a/skills/yt-studio-url-builder/SKILL.md
+++ b/skills/yt-studio-url-builder/SKILL.md
@@ -13,6 +13,8 @@ description: "根据需求清单（CSV/Excel）批量生成 YouTube Studio 内
 - **制作输入清单**：用户有零散需求（所有者ID、实体、日期范围、国家），需先整理成脚本可读的输入文件。
 - **排查问题**：运行后出现失败行、空输出、解析错误，需要定位并修复。

+> **前置依赖**：URL 的 `entity_id` 必须是现成 ID。清单里只有**群组名**时，先走 `yt-studio-groupid-lookup` 技能解析出 groupId 并回填清单，再执行本技能——群组名无法直接拼 URL，这是流程顺序要求而非脚本缺陷。
+
 ## 领域词汇

 - **所有者（Content Owner）**：拥有内容管理器的账号实体，URL 中由 `o` 参数 + `/owner/<id>/` 路径标识。
@@ -29,8 +31,8 @@ description: "根据需求清单（CSV/Excel）批量生成 YouTube Studio 内

 ### 1. 定位脚本与依赖

- 脚本默认位于 `scripts/build_studio_urls.py`；若缺失，用 SearchCodebase 按 `build_studio_urls.py` 定位。
- 运行环境由 `uv-env-setup` 技能统一管理：依赖（pandas、openpyxl）在根 `pyproject.toml` 声明，`uv run` 自动同步。首次运行前先按该技能准备环境。
+- 脚本默认位于 `scripts/build_studio_urls.py`；若缺失，用代码库全局搜索按 `build_studio_urls.py` 定位。
+- 运行环境由 `uv-env-setup` 技能统一管理：项目环境走 `uv sync` + `uv run`；脱离项目时脚本头部带 PEP 723 声明，`uv run <脚本>` 自动备环境。首次运行前先按该技能选好分支。
 - 中文国家名 → ISO 代码的映射在 `scripts/countries.json`，可自行扩充。

 完成标准：脚本路径已确定，且第 4 步的运行命令可直接执行。
@@ -60,8 +62,8 @@ description: "根据需求清单（CSV/Excel）批量生成 YouTube Studio 内
 ### 4. 运行脚本

 ```bash
-# 项目根目录下
-uv run python scripts\build_studio_urls.py -i <输入文件> [-o <输出csv>]
+# 项目根目录下；路径写法用正斜杠，PowerShell / Git Bash / cmd 通用
+uv run python scripts/build_studio_urls.py -i <输入文件> [-o <输出csv>]
 ```

 - 输入支持 `.csv`（UTF-8 或 GBK，自动尝试）与 `.xlsx` / `.xls`。
--- a/skills/yt-studio-url-builder/scripts/build_studio_urls.py
+++ b/skills/yt-studio-url-builder/scripts/build_studio_urls.py
@@ -1,5 +1,12 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "pandas>=2.0",
+#     "openpyxl>=3.1",
+# ]
+# ///
 """
 根据需求清单（CSV/Excel）批量拼接 YouTube Studio 内容管理器 explore URL。