feat(scripts): 添加批量生成 YouTube Studio 内容管理器 URL 的脚本
This commit is contained in:
61
skills/youtube-studio-csv-download/SKILL.md
Normal file
61
skills/youtube-studio-csv-download/SKILL.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
name: "youtube-studio-csv-download"
|
||||
description: "Download YouTube Studio analytics CSV export (zip) via a Playwright script that reuses a logged-in browser user-data dir or debug port, auto-saving to the Downloads folder with (n) dedup. Use when the user wants to download/save YT Studio CSV, or supplies a user-data path / remote-debugging-port."
|
||||
---
|
||||
|
||||
# 下载 YouTube Studio 分析 CSV（脚本版）
|
||||
|
||||
把 YouTube Studio 内容管理器「导出当前视图 → 逗号分隔值 (.csv)」的下载，改由 Playwright 拦截脚本完成：复用已登录的 Chrome/Edge 会话，自动保存 zip 到下载文件夹，重名自动追加 ` (n)` 后缀。
|
||||
|
||||
## 与 MCP 浏览器版技能的区别
|
||||
|
||||
- 本技能：用户**主动给了浏览器 user-data 目录或调试端口**、或明确要"跑脚本下载"时使用。
|
||||
- `youtube-studio-analytics-export`：走 MCP `integrated_browser`、界面点击兜底，适合交互式/按 URL 直连。
|
||||
两者产物相同（zip 内含 `表格数据.csv` / `图表数据.csv` / `总计.csv`），只选一条路径即可。
|
||||
|
||||
## 脚本与依赖
|
||||
|
||||
- 脚本：`scripts/youtube_export_download.py`（本技能目录下；若缺失，用 SearchCodebase 按 `youtube_export_download.py` 定位）
|
||||
- 依赖：playwright 已在根 `pyproject.toml` 统一声明，环境准备见 `uv-env-setup` 技能（复用系统 Chrome/Edge 时无需 `playwright install chromium`）
|
||||
- 登录态必须已存在：脚本不登录，只复用已登录会话。
|
||||
|
||||
## 步骤 1：确认登录态来源（二选一）
|
||||
|
||||
复用已登录 YouTube Studio 的浏览器会话，否则会跳到 Google 登录页。
|
||||
|
||||
- 方式 A（能关浏览器）：用已登录的**用户数据目录**。
|
||||
- 方式 B（浏览器不能关）：用**调试端口**附加。
|
||||
|
||||
**完成判据**：得到下面两者之一——
|
||||
- user-data 目录路径（Chrome：`<LOCALAPPDATA>\Google\Chrome\User Data`；Edge：`<LOCALAPPDATA>\Microsoft\Edge\User Data`），或
|
||||
- 调试端口号（如 `9222`）。
|
||||
|
||||
## 步骤 2：运行脚本
|
||||
|
||||
方式 A：
|
||||
|
||||
```powershell
|
||||
uv run python scripts\youtube_export_download.py --url "<explore URL>" --channel chrome --user-data-dir "$env:LOCALAPPDATA\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
|
||||
```
|
||||
|
||||
`--channel` 只允许 `chrome` / `msedge`，且必须与 `--user-data-dir` 指向的浏览器**同一品牌**。
|
||||
|
||||
**完成判据**：终端打印 `已保存: <完整路径> (<字节数>)`，退出码 0。
|
||||
|
||||
## 步骤 3：校验产物
|
||||
|
||||
```powershell
|
||||
Get-ChildItem -Path "D:\Downloads" -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)`。
|
||||
|
||||
## 遇到问题
|
||||
|
||||
查 `references/troubleshooting.md`（未登录跳转、目录被占用、CDP 连不上、channel 不匹配、未捕获响应、文件名回退等）。
|
||||
@@ -0,0 +1,25 @@
|
||||
# 故障排查
|
||||
|
||||
## 登录态相关问题
|
||||
|
||||
- **运行后跳到 Google 登录页**（URL 含 `accounts.google.com`）：未复用登录态。改用 `--user-data-dir`（方式 A）或 `--connect`（方式 B）。
|
||||
- **报错 "user data directory ... is already in use" / "ProcessSingleton"**：该浏览器还没关。完全退出 Chrome/Edge 后再用方式 A。
|
||||
- **`connect ECONNREFUSED 127.0.0.1:9222`**：调试端口没开。先 `chrome.exe --remote-debugging-port=9222`（Edge 同理）再 `--connect`。
|
||||
- **连上了但仍未登录**：`--channel` 与 `--user-data-dir` 品牌不匹配（例如 chrome 的目录配了 `--channel msedge`），或指向了没登录过的 profile。换正确的浏览器/目录。
|
||||
|
||||
## 环境与依赖
|
||||
|
||||
- **`playwright` / `sync_playwright` 找不到**：环境未同步。项目根执行 `uv sync`，或直接用 `uv run python <脚本>`；详见 `uv-env-setup` 技能。复用系统 Chrome/Edge 时无需 `playwright install chromium`。
|
||||
- **系统找不到浏览器**：确认本机装了 Chrome 或 Edge；用 `--channel` 显式指定 `chrome` 或 `msedge`。
|
||||
|
||||
## 运行过程
|
||||
|
||||
- **找不到「导出当前视图」按钮 / 点击超时**：URL 不是 explore 页，或页面尚未加载完。务必用用户提供的 explore URL，别用 overview URL。
|
||||
- **没打印「已保存」（未捕获 csv_export 响应）**：导出未被触发，或登录态已失效。重试步骤 2，必要时重新登录后重跑。
|
||||
- **文件名变成 `export.zip` 而非标准命名**：请求体解析失败触发兜底，内容仍完整；检查日期范围与账号名是否正常。
|
||||
- **中文/特殊字符文件名**：已把 Windows 非法字符 `\/:*?"<>|` 自动替换为 `_`，不会因文件名失败。
|
||||
|
||||
## 产物与去重
|
||||
|
||||
- **下载目录不存在导致写盘失败**：脚本不自动建目录。先建 `D:\Downloads`，或用 `--download-dir` 指定已存在目录。
|
||||
- **重名文件**：自动按 `名称 (1).zip`、`名称 (2).zip` 递增；这是脚本自己的 dedup_path 逻辑，不依赖浏览器。
|
||||
@@ -0,0 +1,252 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
r"""
|
||||
YouTube Studio 内容管理器「导出当前视图 → 逗号分隔值 (.csv)」下载脚本
|
||||
（拦截响应 + 解码 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 起。
|
||||
|
||||
登录态：脚本不负责登录，必须复用已登录 YouTube Studio 的浏览器会话，二选一：
|
||||
- --user-data-dir + --channel chrome|msedge ：用已登录的用户数据目录启动（需先关闭该浏览器）
|
||||
- --connect http://localhost:9222 ：附加到已在调试端口运行的浏览器
|
||||
|
||||
用法：
|
||||
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>" --connect http://localhost:9222
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import base64
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
|
||||
DOWNLOAD_DIR = r"D:\Downloads" # 默认下载目录，可用 --download-dir 覆盖
|
||||
|
||||
# 维度类型 -> 文件名前缀标签（生产环境建议从页面「维度」按钮文本读取，这里兜底映射）。
|
||||
DIMENSION_LABEL = {
|
||||
"VIDEO": "内容",
|
||||
"USER": "频道",
|
||||
"CONTENT_OWNER": "内容",
|
||||
}
|
||||
|
||||
CSV_EXPORT_PATH = "/youtubei/v1/yta_web/csv_export"
|
||||
|
||||
|
||||
def dedup_path(directory, filename):
|
||||
"""返回不冲突的落盘路径；重名按 `名称 (n).后缀` 递增，n 从 1 起。"""
|
||||
directory = os.path.abspath(directory)
|
||||
base, ext = os.path.splitext(filename)
|
||||
candidate = os.path.join(directory, filename)
|
||||
n = 1
|
||||
while os.path.exists(candidate):
|
||||
candidate = os.path.join(directory, f"{base} ({n}){ext}")
|
||||
n += 1
|
||||
return candidate
|
||||
|
||||
|
||||
def build_export_filename(export_query, account_name, dimension_label=None):
|
||||
"""从 csv_export 请求体 `exportQuery` 反推文件名。"""
|
||||
def fmt_dateid(yyyymmdd):
|
||||
s = str(yyyymmdd)
|
||||
return f"{s[0:4]}-{s[4:6]}-{s[6:8]}"
|
||||
|
||||
date_range = None
|
||||
dimension = None
|
||||
nodes = export_query.get("joinRequest", {}).get("nodes") or []
|
||||
for node in nodes:
|
||||
q = node.get("value", {}).get("query") or {}
|
||||
if not date_range:
|
||||
tr = q.get("timeRange", {}).get("dateIdRange")
|
||||
if tr and tr.get("inclusiveStart"):
|
||||
date_range = (tr["inclusiveStart"], tr.get("exclusiveEnd"))
|
||||
dims = q.get("dimensions") or []
|
||||
if dimension is None and dims:
|
||||
dimension = dims[0].get("type")
|
||||
|
||||
if not date_range:
|
||||
raise ValueError("无法从 exportQuery 解析日期范围")
|
||||
|
||||
if dimension_label is None:
|
||||
dimension_label = DIMENSION_LABEL.get(dimension or "", "")
|
||||
|
||||
start, end = date_range
|
||||
return f"{dimension_label} {fmt_dateid(start)}_{fmt_dateid(end)} {account_name}.zip"
|
||||
|
||||
|
||||
def decode_zipped_data(payload):
|
||||
"""把 csv_export 响应 payload 里的 zippedData 解码为 zip 字节流。"""
|
||||
zipped = payload.get("zippedData")
|
||||
if not zipped:
|
||||
raise ValueError("响应中缺少 zippedData 字段")
|
||||
return base64.b64decode(zipped)
|
||||
|
||||
|
||||
def intercept_and_save(page, account_name, download_dir):
|
||||
"""给 page 绑定 response 拦截器：命中 csv_export 就把 zip 保存到下载目录。"""
|
||||
import pathlib
|
||||
|
||||
saved = []
|
||||
|
||||
def on_response(response):
|
||||
if CSV_EXPORT_PATH not in response.url:
|
||||
return
|
||||
try:
|
||||
payload = response.json()
|
||||
data = decode_zipped_data(payload)
|
||||
|
||||
filename = None
|
||||
try:
|
||||
body = json.loads(response.request.post_data or "{}")
|
||||
filename = build_export_filename(body.get("exportQuery", {}), account_name)
|
||||
except Exception:
|
||||
filename = "export.zip" # 反推失败兜底，避免丢内容
|
||||
|
||||
filename = re.sub(r"[\\/:*?\"<>|]", "_", filename) # Windows 非法字符
|
||||
path = dedup_path(download_dir, filename)
|
||||
pathlib.Path(path).write_bytes(data)
|
||||
saved.append((filename, len(data), path))
|
||||
except Exception as e: # noqa: BLE001
|
||||
print(f"[interceptor] 处理 csv_export 响应失败: {e}", file=sys.stderr)
|
||||
|
||||
page.on("response", on_response)
|
||||
return saved
|
||||
|
||||
|
||||
def _default_user_data_dir(channel):
|
||||
"""返回指定浏览器的默认用户数据目录（Windows），用于复用已登录会话。"""
|
||||
_local = os.environ.get("LOCALAPPDATA") or os.path.expanduser(r"~\AppData\Local")
|
||||
if channel == "msedge":
|
||||
return os.path.join(_local, "Microsoft", "Edge", "User Data")
|
||||
return os.path.join(_local, "Google", "Chrome", "User Data")
|
||||
|
||||
|
||||
def run(url, user_data_dir=None, channel=None, cdp_url=None,
|
||||
download_dir=None, account_name=None):
|
||||
"""启动/连接浏览器并触发导出。必须复用已登录会话，否则跳 Google 登录页。"""
|
||||
from playwright.sync_api import sync_playwright
|
||||
|
||||
download_dir = download_dir or DOWNLOAD_DIR
|
||||
|
||||
with sync_playwright() as p:
|
||||
browser = None
|
||||
context = None
|
||||
|
||||
if cdp_url:
|
||||
browser = p.chromium.connect_over_cdp(cdp_url)
|
||||
context = browser.contexts[0] if browser.contexts else \
|
||||
browser.new_context(accept_downloads=True)
|
||||
page = context.new_page()
|
||||
page.goto(url, wait_until="domcontentloaded")
|
||||
elif user_data_dir:
|
||||
context = p.chromium.launch_persistent_context(
|
||||
user_data_dir=user_data_dir or _default_user_data_dir(channel),
|
||||
channel=channel,
|
||||
headless=False,
|
||||
accept_downloads=True,
|
||||
args=["--disable-blink-features=AutomationControlled"],
|
||||
)
|
||||
page = context.new_page()
|
||||
page.goto(url, wait_until="domcontentloaded")
|
||||
else:
|
||||
browser = p.chromium.launch(headless=False, channel=channel)
|
||||
context = browser.new_context(accept_downloads=True)
|
||||
page = context.new_page()
|
||||
page.goto(url, wait_until="domcontentloaded")
|
||||
|
||||
if "accounts.google" in page.url:
|
||||
print("[!] 当前会话未登录，已跳转到 Google 登录页。", file=sys.stderr)
|
||||
print(" 请用 --user-data-dir 或 --connect 复用已登录浏览器后重试。",
|
||||
file=sys.stderr)
|
||||
|
||||
if not account_name:
|
||||
account_name = "WL Media"
|
||||
try:
|
||||
account_name = page.locator(
|
||||
"ytcp-account-item button, .account-switcher button"
|
||||
).first.inner_text(timeout=5000).strip() or account_name
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
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)
|
||||
|
||||
if not saved:
|
||||
print("未捕获到 csv_export 响应，请确认已点击导出且登录态有效。")
|
||||
else:
|
||||
for name, size, path in saved:
|
||||
print(f"已保存: {path} ({size} bytes)")
|
||||
|
||||
if browser is not None:
|
||||
browser.close()
|
||||
elif context is not None:
|
||||
context.close()
|
||||
|
||||
|
||||
def selftest():
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
|
||||
with tempfile.TemporaryDirectory() as td:
|
||||
p0 = Path(dedup_path(td, "需求文件.zip"))
|
||||
assert p0.name == "需求文件.zip", p0.name
|
||||
p0.write_bytes(b"a")
|
||||
|
||||
p1 = Path(dedup_path(td, "需求文件.zip"))
|
||||
assert p1.name == "需求文件 (1).zip", p1.name
|
||||
p1.write_bytes(b"b")
|
||||
|
||||
p2 = Path(dedup_path(td, "需求文件.zip"))
|
||||
assert p2.name == "需求文件 (2).zip", p2.name
|
||||
p2.write_bytes(b"c")
|
||||
|
||||
assert Path(dedup_path(td, "需求文件.zip")).name == "需求文件 (3).zip"
|
||||
assert Path(dedup_path(td, "其他.zip")).name == "其他.zip"
|
||||
|
||||
export_query = {
|
||||
"joinRequest": {"nodes": [{"value": {"query": {
|
||||
"dimensions": [{"type": "VIDEO"}],
|
||||
"timeRange": {"dateIdRange": {
|
||||
"inclusiveStart": 20260723, "exclusiveEnd": 20260820}},
|
||||
}}}]},
|
||||
}
|
||||
name = build_export_filename(export_query, "WL Media")
|
||||
assert name == "内容 2026-07-23_2026-08-20 WL Media.zip", name
|
||||
|
||||
print("selftest OK：去重与文件名反推逻辑全部通过")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--selftest", action="store_true", help="仅跑去重/命名自测")
|
||||
ap.add_argument("--url", help="explore URL")
|
||||
ap.add_argument("--user-data-dir", help="浏览器用户数据目录（复用登录态，需先关闭该浏览器）")
|
||||
ap.add_argument("--channel", choices=["chrome", "msedge"],
|
||||
help="浏览器品牌，复用登录态时必填其一")
|
||||
ap.add_argument("--connect", help="通过 CDP 附加到已打开浏览器，如 http://localhost:9222")
|
||||
ap.add_argument("--download-dir", help=f"下载目录，默认 {DOWNLOAD_DIR}")
|
||||
ap.add_argument("--account-name", help="账号名（用于文件名），默认从页面读取")
|
||||
args = ap.parse_args()
|
||||
|
||||
if args.selftest:
|
||||
selftest()
|
||||
elif args.url:
|
||||
run(args.url, user_data_dir=args.user_data_dir, channel=args.channel,
|
||||
cdp_url=args.connect, download_dir=args.download_dir,
|
||||
account_name=args.account_name)
|
||||
else:
|
||||
selftest()
|
||||
print("\n实际运行需先 pip install playwright，再复用登录态（二选一）：\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>\" "
|
||||
"--connect http://localhost:9222")
|
||||
Reference in New Issue
Block a user