feat(scripts): 添加 PEP 723 脚本元数据并修复 HTTP/2 伪头过滤问题
- 为 build_studio_urls.py 和 lookup_groups.py 添加 PEP 723 依赖声明 - 修复 HTTP/2 伪头导致 requests 抛 InvalidHeader 的问题 - 添加 CDP 端口连通性预检查及启动指引
This commit is contained in:
@@ -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 语义；每条失败可独立重跑。
|
||||
@@ -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 逻辑，不依赖浏览器。
|
||||
@@ -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>\" "
|
||||
|
||||
Reference in New Issue
Block a user