feat(scripts): 添加批量生成 YouTube Studio 内容管理器 URL 的脚本

2026-08-21 18:21:03 +08:00
commit c1b39e9466
29 changed files with 4020 additions and 0 deletions
--- a/scripts/build_studio_urls.py
+++ b/scripts/build_studio_urls.py
@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+根据需求清单（CSV/Excel）批量拼接 YouTube Studio 内容管理器 explore URL。
+
+用法:
+    python build_studio_urls.py -i 需求清单.csv  -o 输出.csv
+    python build_studio_urls.py -i 需求清单.xlsx -o 输出.csv
+
+输入列（支持中英文别名，未填可留空）:
+    所有者名称 : 所有者名称 / owner_name
+    所有者ID   : 所有者ID / owner_id / o
+    实体名称   : 实体名称 / 群组名称 / 频道名称 / 节目名称 / entity_name / group_name
+    实体ID     : 实体ID / 群组ID / group_id / entity_id / id
+    实体类型   : 实体类型 / 类型 / entity_type   (群组/所有者/频道/节目，或 GROUP/CONTENT_OWNER/CHANNEL/VIDEO)
+    数据周期   : 数据周期 / 周期 / period / time_period   (yyyy.mm.dd-yyyy.mm.dd 或 yyyy.m.d-yyyy.m.d)
+    国家       : 国家 / 国家/地区 / country / countries   (一个或多个，中文名或 ISO 两位代码)
+
+说明:
+    - 数据周期起止日期均包含在数据范围内，time_period 结束值取结束日后一天的日界线。
+    - 国家为多个时，ur_values 以 '%27' 包裹、'%7C' 连接（如 美国,日本 -> %27US%27%7C%27JP%27）。
+    - 中文国家名 -> ISO 代码的映射放在同目录 countries.json（可自行扩充）；已是两位代码的原样透传。
+    - 固定参数（metric/granularity/dimension/t_metrics 等）在本文件 CONFIG 中统一配置。
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from datetime import date
+
+import pandas as pd
+from urllib.parse import quote
+
+# ---------------------------------------------------------------------------
+# 固定参数（所有需求共用，按需修改）
+# ---------------------------------------------------------------------------
+CONFIG = {
+    "explore_type": "TABLE_AND_CHART",
+    "metric": "SUBSCRIBERS_NET_CHANGE",          # 主指标
+    "granularity": "DAY",                         # DAY / WEEK / MONTH / YEAR
+    "dimension": "USER",                          # 细分维度
+    "t_metrics": [                                # 表格列指标（可多个）
+        "SUBSCRIBERS_NET_CHANGE",
+        "VIDEO_COUNT_FIRST_PUBLISHED",
+        "ENGAGED_VIEWS",
+        "EXTERNAL_VIEWS",
+        "EXTERNAL_WATCH_TIME",
+        "AVERAGE_WATCH_TIME",
+        "TOTAL_ESTIMATED_EARNINGS",
+    ],
+    "o_column": "SUBSCRIBERS_NET_CHANGE",         # 排序字段
+    "o_direction": "ANALYTICS_ORDER_DIRECTION_DESC",  # DESC / ASC
+    "comparison_type": "NONE",
+}
+
+# 实体类型 中文/代码 -> URL 参数值（可扩充）
+ENTITY_TYPE_MAP = {
+    "群组": "GROUP", "GROUP": "GROUP",
+    "所有者": "CONTENT_OWNER", "账号": "CONTENT_OWNER", "CONTENT_OWNER": "CONTENT_OWNER",
+    "频道": "CHANNEL", "CHANNEL": "CHANNEL",
+    "节目": "VIDEO", "视频": "VIDEO", "VIDEO": "VIDEO",
+}
+DEFAULT_ENTITY_TYPE = "GROUP"
+
+# 日界线锚点 + 整日偏移（见 docs/adr/0001）
+ANCHOR_DATE = date(2026, 6, 15)
+ANCHOR_MS = 1781506800000
+MS_PER_DAY = 86400000
+
+# 数据周期正则：支持 2026.07.01-2026.08.01 / 2026.7.1-2026.8.1 / 2026-07-01~2026-08-01
+PERIOD_RE = re.compile(
+    r"(\d{4})[.\-/](\d{1,2})[.\-/](\d{1,2})\s*[-~～]\s*(\d{4})[.\-/](\d{1,2})[.\-/](\d{1,2})"
+)
+
+# 输入列名 -> 规范字段（键为去空白、转小写后的列名）
+COLUMN_ALIASES = {
+    # 所有者
+    "所有者名称": "owner_name", "ownername": "owner_name", "owner_name": "owner_name",
+    "所有者": "owner_name",
+    "所有者id": "owner_id", "ownerid": "owner_id", "owner_id": "owner_id", "o": "owner_id",
+    # 实体
+    "实体名称": "entity_name", "entity_name": "entity_name",
+    "群组名称": "entity_name", "group_name": "entity_name", "groupname": "entity_name",
+    "频道名称": "entity_name", "节目名称": "entity_name",
+    "实体id": "entity_id", "entity_id": "entity_id", "entityid": "entity_id",
+    "群组id": "entity_id", "group_id": "entity_id", "groupid": "entity_id",
+    "群组": "entity_id", "id": "entity_id",
+    "实体类型": "entity_type", "entity_type": "entity_type", "entitytype": "entity_type",
+    "类型": "entity_type", "type": "entity_type",
+    # 数据周期
+    "数据周期": "period", "周期": "period", "period": "period",
+    "time_period": "period", "timeperiod": "period", "日期范围": "period",
+    # 国家
+    "国家": "countries", "国家/地区": "countries", "国家地区": "countries",
+    "countries": "countries", "country": "countries", "筛选国家": "countries", "地区": "countries",
+}
+
+
+def ts(y, m, d):
+    """日期 -> 日界线 Unix 毫秒（锚点 + 整日偏移）。"""
+    return ANCHOR_MS + (date(y, m, d) - ANCHOR_DATE).days * MS_PER_DAY
+
+
+def normalize_columns(df):
+    """按别名把输入列映射到规范字段。返回 (field->column_index, 未识别列名列表)。"""
+    mapping = {}
+    unknown = []
+    for col in df.columns:
+        key = str(col).strip().lower()
+        field = COLUMN_ALIASES.get(key)
+        if field:
+            mapping[field] = col
+        else:
+            unknown.append(str(col))
+    return mapping, unknown
+
+
+def parse_period(text):
+    """解析数据周期，返回 (start_ms, end_ms)，起止日期均含。"""
+    text = str(text).strip()
+    m = PERIOD_RE.search(text)
+    if not m:
+        raise ValueError("无法解析数据周期: %r（应为 yyyy.mm.dd-yyyy.mm.dd）" % text)
+    y1, m1, d1, y2, m2, d2 = (int(g) for g in m.groups())
+    start_ms = ts(y1, m1, d1)
+    end_ms = ts(y2, m2, d2) + MS_PER_DAY  # 结束日包含
+    return start_ms, end_ms
+
+
+def load_country_map(path):
+    """加载 中文国家名 -> ISO 代码 映射。文件缺失则仅支持两位代码透传。"""
+    if not os.path.exists(path):
+        print("[提示] 未找到国家映射文件 %s，仅支持直接填写两位 ISO 代码" % path, file=sys.stderr)
+        return {}
+    with open(path, "r", encoding="utf-8-sig") as f:
+        data = json.load(f)
+    return {str(k).strip(): str(v).strip().upper() for k, v in data.items()}
+
+
+def parse_countries(text, country_map):
+    """解析国家列（一个或多个，中文名或 ISO 代码），返回 ISO 代码列表。"""
+    if text is None or (isinstance(text, float) and str(text) == "nan"):
+        return []
+    raw = str(text)
+    parts = re.split(r"[,，、;；\s|]+", raw)
+    codes = []
+    for part in parts:
+        p = part.strip().strip("'\"").strip()
+        if not p:
+            continue
+        upper = p.upper()
+        if re.fullmatch(r"[A-Z]{2}", upper):  # 已是两位 ISO 代码
+            codes.append(upper)
+        elif p in country_map:
+            codes.append(country_map[p])
+        else:
+            raise ValueError("未识别的国家: %r（不在映射文件中，也不是两位 ISO 代码）" % p)
+    return codes
+
+
+def resolve_entity_type(text):
+    """实体类型 -> URL 参数值。空则用默认群组。"""
+    if text is None or (isinstance(text, float) and str(text) == "nan") or str(text).strip() == "":
+        return DEFAULT_ENTITY_TYPE
+    key = str(text).strip()
+    if key in ENTITY_TYPE_MAP:
+        return ENTITY_TYPE_MAP[key]
+    raise ValueError("未识别的实体类型: %r（应为 群组/所有者/频道/节目 或 GROUP/CONTENT_OWNER/CHANNEL/VIDEO）" % key)
+
+
+def build_url(row, country_map):
+    """根据一行需求生成 URL。返回 (url, 状态, 错误信息)。"""
+    owner_id = row.get("owner_id", "").strip()
+    entity_type = resolve_entity_type(row.get("entity_type", ""))
+    entity_id = row.get("entity_id", "").strip()
+
+    if not owner_id:
+        return None, "error", "缺少所有者ID"
+    if not entity_id:
+        if entity_type == "CONTENT_OWNER":
+            entity_id = owner_id  # 账号整体场景回退
+        else:
+            return None, "error", "缺少实体ID"
+
+    period = row.get("period", "").strip()
+    if not period:
+        return None, "error", "缺少数据周期"
+    start_ms, end_ms = parse_period(period)
+
+    codes = parse_countries(row.get("countries", ""), country_map)
+
+    base = "https://studio.youtube.com/owner/%s/analytics/tab-overview/period-default/explore" % owner_id
+    params = []
+    params.append("o=%s" % owner_id)
+    params.append("entity_type=%s" % entity_type)
+    params.append("entity_id=%s" % entity_id)
+    if codes:
+        ur_values = quote("|".join("'%s'" % c for c in codes), safe="")  # 'US'|'JP' -> %27US%27%7C%27JP%27
+        params.append("ur_dimensions=COUNTRY")
+        params.append("ur_values=%s" % ur_values)
+        params.append("ur_inclusive_starts=")
+        params.append("ur_exclusive_ends=")
+    params.append("time_period=%d%%2C%d" % (start_ms, end_ms))
+    params.append("explore_type=%s" % CONFIG["explore_type"])
+    params.append("metric=%s" % CONFIG["metric"])
+    params.append("granularity=%s" % CONFIG["granularity"])
+    for m in CONFIG["t_metrics"]:
+        params.append("t_metrics=%s" % m)
+    params.append("dimension=%s" % CONFIG["dimension"])
+    params.append("o_column=%s" % CONFIG["o_column"])
+    params.append("o_direction=%s" % CONFIG["o_direction"])
+    params.append("comparison_type=%s" % CONFIG["comparison_type"])
+
+    url = base + "?" + "&".join(params)
+    return url, "ok", ""
+
+
+def main():
+    parser = argparse.ArgumentParser(description="批量拼接 YouTube Studio explore URL")
+    parser.add_argument("-i", "--input", required=True, help="需求清单文件（.csv / .xlsx / .xls）")
+    parser.add_argument("-o", "--output", default=None, help="输出 CSV 路径（默认：输入同目录 studio_urls_output.csv）")
+    parser.add_argument("--countries", default=None, help="国家映射 JSON 路径（默认：脚本同目录 countries.json）")
+    args = parser.parse_args()
+
+    if not os.path.exists(args.input):
+        print("错误：输入文件不存在: %s" % args.input, file=sys.stderr)
+        sys.exit(1)
+
+    ext = os.path.splitext(args.input)[1].lower()
+    if ext == ".csv":
+        try:
+            df = pd.read_csv(args.input, encoding="utf-8-sig")
+        except UnicodeDecodeError:
+            df = pd.read_csv(args.input, encoding="gbk")  # Excel 另存的 ANSI/GBK
+    elif ext in (".xlsx", ".xls"):
+        df = pd.read_excel(args.input)
+    else:
+        print("错误：不支持的输入格式: %s（支持 .csv/.xlsx/.xls）" % ext, file=sys.stderr)
+        sys.exit(1)
+
+    df = df.dropna(how="all")  # 去掉全空行
+
+    mapping, unknown = normalize_columns(df)
+    if unknown:
+        print("[提示] 未识别的列（忽略）: %s" % ", ".join(unknown), file=sys.stderr)
+    missing = [f for f in ("owner_id", "period") if f not in mapping]
+    if missing:
+        print("错误：输入缺少必要列: %s" % ", ".join(missing), file=sys.stderr)
+        sys.exit(1)
+
+    countries_file = args.countries or os.path.join(os.path.dirname(os.path.abspath(__file__)), "countries.json")
+    country_map = load_country_map(countries_file)
+
+    records = []
+    errors = []
+    for idx, raw in df.iterrows():
+        row = {f: ("" if pd.isna(raw[mapping[f]]) else str(raw[mapping[f]])) for f in mapping}
+        try:
+            url, status, msg = build_url(row, country_map)
+        except ValueError as e:
+            url, status, msg = None, "error", str(e)
+        if status == "ok":
+            start_ms, end_ms = parse_period(row.get("period", ""))
+            codes = parse_countries(row.get("countries", ""), country_map)
+            records.append({
+                "所有者名称": row.get("owner_name", ""),
+                "所有者ID": row.get("owner_id", ""),
+                "实体类型": row.get("entity_type", ""),
+                "实体名称": row.get("entity_name", ""),
+                "实体ID": row.get("entity_id", ""),
+                "数据周期": row.get("period", ""),
+                "国家": row.get("countries", ""),
+                "国家代码": ",".join(codes),
+                "开始时间戳": start_ms,
+                "结束时间戳": end_ms,
+                "URL": url,
+            })
+        else:
+            errors.append((idx + 2, row.get("owner_name", ""), row.get("entity_name", ""), msg))
+
+    out_path = args.output or os.path.join(
+        os.path.dirname(os.path.abspath(args.input)), "studio_urls_output.csv")
+    out_df = pd.DataFrame(records)
+    out_df.to_csv(out_path, index=False, encoding="utf-8-sig")
+    print("已生成 %d 条 URL -> %s" % (len(records), out_path))
+
+    if errors:
+        print("\n以下 %d 行生成失败：" % len(errors), file=sys.stderr)
+        for r in errors:
+            print("  第%d行 所有者=%s 实体=%s：%s" % r, file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()
--- a/scripts/countries.json
+++ b/scripts/countries.json
@@ -0,0 +1,24 @@
+{
+  "美国": "US", "日本": "JP", "英国": "GB", "德国": "DE", "法国": "FR",
+  "意大利": "IT", "西班牙": "ES", "加拿大": "CA", "澳大利亚": "AU", "韩国": "KR",
+  "巴西": "BR", "墨西哥": "MX", "印度": "IN", "俄罗斯": "RU", "荷兰": "NL",
+  "瑞典": "SE", "挪威": "NO", "芬兰": "FI", "丹麦": "DK", "比利时": "BE",
+  "瑞士": "CH", "奥地利": "AT", "波兰": "PL", "葡萄牙": "PT", "爱尔兰": "IE",
+  "新西兰": "NZ", "新加坡": "SG", "马来西亚": "MY", "泰国": "TH", "越南": "VN",
+  "印度尼西亚": "ID", "菲律宾": "PH", "土耳其": "TR", "沙特阿拉伯": "SA",
+  "阿联酋": "AE", "以色列": "IL", "南非": "ZA", "阿根廷": "AR", "智利": "CL",
+  "哥伦比亚": "CO", "秘鲁": "PE", "埃及": "EG", "尼日利亚": "NG", "中国": "CN",
+  "中国台湾": "TW", "台湾": "TW", "中国香港": "HK", "香港": "HK", "中国澳门": "MO", "澳门": "MO",
+  "乌克兰": "UA", "希腊": "GR", "捷克": "CZ", "匈牙利": "HU", "罗马尼亚": "RO",
+  "保加利亚": "BG", "克罗地亚": "HR", "斯洛伐克": "SK", "斯洛文尼亚": "SI",
+  "立陶宛": "LT", "拉脱维亚": "LV", "爱沙尼亚": "EE", "塞尔维亚": "RS", "冰岛": "IS",
+  "卢森堡": "LU", "马耳他": "MT", "塞浦路斯": "CY", "巴基斯坦": "PK",
+  "孟加拉国": "BD", "斯里兰卡": "LK", "哈萨克斯坦": "KZ", "卡塔尔": "QA",
+  "科威特": "KW", "巴林": "BH", "阿曼": "OM", "约旦": "JO", "黎巴嫩": "LB",
+  "摩洛哥": "MA", "阿尔及利亚": "DZ", "突尼斯": "TN", "肯尼亚": "KE",
+  "加纳": "GH", "坦桑尼亚": "TZ", "埃塞俄比亚": "ET", "玻利维亚": "BO",
+  "厄瓜多尔": "EC", "乌拉圭": "UY", "巴拉圭": "PY", "委内瑞拉": "VE",
+  "巴拿马": "PA", "哥斯达黎加": "CR", "古巴": "CU", "多米尼加": "DO",
+  "波多黎各": "PR", "危地马拉": "GT", "洪都拉斯": "HN", "萨尔瓦多": "SV",
+  "尼加拉瓜": "NI"
+}
--- a/scripts/install-skills.bat
+++ b/scripts/install-skills.bat
@@ -0,0 +1,12 @@
+@echo off
+rem Trae CN skill installer launcher - double click to run
+rem Actual logic lives in install-skills.ps1 (same folder)
+cd /d "%~dp0"
+if not exist "install-skills.ps1" (
+    echo [ERROR] install-skills.ps1 not found in %~dp0
+    pause
+    exit /b 1
+)
+powershell -NoProfile -ExecutionPolicy Bypass -File "install-skills.ps1"
+echo.
+pause
--- a/scripts/install-skills.ps1
+++ b/scripts/install-skills.ps1
@@ -0,0 +1,92 @@
+# =====================================================================
+# Trae CN 技能安装器（Windows）
+# 作用：把本项目 skills\ 下全部技能安装到用户级技能目录
+#       %USERPROFILE%\.trae-cn\skills\
+# 用法：双击同目录下的 install-skills.bat（推荐），或
+#       powershell -NoProfile -ExecutionPolicy Bypass -File install-skills.ps1
+# =====================================================================
+
+$ErrorActionPreference = "Stop"
+
+# --- 1. 定位源目录与目标目录 ---
+$ScriptDir    = $PSScriptRoot
+$ProjectRoot  = Split-Path -Parent $ScriptDir
+$SkillsSource = Join-Path $ProjectRoot "skills"
+$TraeSkills   = Join-Path $env:USERPROFILE ".trae-cn\skills"
+# 备份放在技能目录外，避免被 Trae 当成技能重复扫描
+$BackupRoot   = Join-Path $env:USERPROFILE ".trae-cn\skills-backup"
+
+Write-Host "=== Trae CN 技能安装器 ===" -ForegroundColor Cyan
+Write-Host "技能源目录: $SkillsSource"
+Write-Host "安装目标:   $TraeSkills"
+Write-Host ""
+
+# --- 2. 校验源目录并收集技能（含 SKILL.md 的子目录才算） ---
+if (-not (Test-Path $SkillsSource)) {
+    Write-Host "[错误] 找不到技能源目录: $SkillsSource" -ForegroundColor Red
+    exit 1
+}
+
+$skills = @(Get-ChildItem -Path $SkillsSource -Directory | Where-Object {
+    Test-Path (Join-Path $_.FullName "SKILL.md")
+})
+
+if ($skills.Count -eq 0) {
+    Write-Host "[错误] 源目录下没有可用技能（每个技能文件夹需包含 SKILL.md）。" -ForegroundColor Red
+    exit 1
+}
+
+Write-Host ("发现 {0} 个技能: {1}" -f $skills.Count, ($skills.Name -join ", "))
+Write-Host ""
+
+# --- 3. 逐个安装：旧版先备份，再复制新版 ---
+New-Item -ItemType Directory -Force -Path $TraeSkills | Out-Null
+
+$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
+$backupCount = 0
+
+foreach ($skill in $skills) {
+    $dest = Join-Path $TraeSkills $skill.Name
+
+    if (Test-Path $dest) {
+        New-Item -ItemType Directory -Force -Path $BackupRoot | Out-Null
+        $backupPath = Join-Path $BackupRoot ("{0}-{1}" -f $skill.Name, $timestamp)
+        Move-Item -Path $dest -Destination $backupPath
+        $backupCount++
+        Write-Host "[备份] $($skill.Name) 旧版 -> $backupPath" -ForegroundColor Yellow
+    }
+
+    Copy-Item -Path $skill.FullName -Destination $dest -Recurse -Force
+    Write-Host "[安装] $($skill.Name)" -ForegroundColor Green
+}
+
+# --- 4. 校验安装结果 ---
+Write-Host ""
+Write-Host "=== 校验结果 ==="
+$failed = @()
+foreach ($skill in $skills) {
+    if (Test-Path (Join-Path $TraeSkills "$($skill.Name)\SKILL.md")) {
+        Write-Host "  [OK]   $($skill.Name)" -ForegroundColor Green
+    } else {
+        Write-Host "  [FAIL] $($skill.Name)" -ForegroundColor Red
+        $failed += $skill.Name
+    }
+}
+
+# --- 5. 汇总与后续提示 ---
+Write-Host ""
+if ($failed.Count -gt 0) {
+    Write-Host ("安装失败: {0}" -f ($failed -join ", ")) -ForegroundColor Red
+    exit 2
+}
+
+Write-Host "全部安装成功。" -ForegroundColor Green
+if ($backupCount -gt 0) {
+    Write-Host "旧版本备份于: $BackupRoot（确认新版可用后可手动删除）" -ForegroundColor Yellow
+}
+
+Write-Host ""
+Write-Host "下一步: 重启 Trae CN 或新建会话后，在对话中提及技能名或相关意图即可触发:"
+foreach ($s in $skills) {
+    Write-Host "  - $($s.Name)"
+}
--- a/scripts/youtube_export_interceptor.py
+++ b/scripts/youtube_export_interceptor.py
@@ -0,0 +1,306 @@
+# -*- coding: utf-8 -*-
+r"""
+YouTube Studio 内容管理器「导出当前视图 → 逗号分隔值 (.csv)」下载流程 —— 拦截/解码/自动保存/重名去重 参考实现。
+
+## 已实证的下载生成机制（2026-08-21 抓包确认）
+
+1. 前端点击「导出当前视图 → 逗号分隔值 (.csv)」后，向后端发起：
+       POST https://studio.youtube.com/youtubei/v1/yta_web/csv_export?alt=json
+   请求体 `exportQuery` 内含 joinRequest 各节点（表格数据/图表数据/总计），以及
+   日期范围 `dateIdRange.inclusiveStart` / `dateIdRange.exclusiveEnd`（都是 YYYYMMDD）。
+
+2. 后端**不在服务器上生成一个可下载的 URL**，而是直接把打好的 zip 以
+   **base64 字符串**内联在响应里：
+       { "responseContext": {...}, "zippedData": "<base64>" }
+   实测 `zippedData` 以 `UEsDBBQ...` 开头（即 `PK\\x03\\x04`，ZIP 魔数），
+   base64 解码后得到 zip，内含 `表格数据.csv`、`图表数据.csv`、`总计.csv`。
+
+3. 前端把 `zippedData` base64 解码 → Blob → 触发浏览器下载。
+   由于没有出现指向下载文件的 GET/跳转，判定为「客户端 Blob 下载」而非服务端重定向。
+
+4. 浏览器自身已自动保存到本机默认下载目录（本机为 `D:\\Downloads`），无需"另存为"确认；
+   且 Chromium 对重名文件会自动追加 ` (1)`、` (2)` …后缀。
+
+## 结论：可以跨越下载流程
+- 在响应层拦截 `csv_export`，拿到 `zippedData`，自行 base64 解码并写盘，
+  即可完全掌控「保存目录 + 文件名 + 重名去重」，不依赖浏览器的下载管理器和弹窗。
+- 或者只用 Chromium 的下载偏好（auto-download + 内置去重）让它自动落盘。
+
+## 文件名约定（与实测 D:\\Downloads 中产物一致）
+    <维度标签> <inclusiveStart>_<exclusiveEnd> <账号名>.zip
+    例：内容 2026-07-23_2026-08-20 WL Media.zip
+    - 维度标签：VIDEO -> 内容；USER -> 频道（生产中建议从页面"维度"按钮文本读取）
+    - 日期格式 YYYY-MM-DD：inclusiveStart 与 exclusiveEnd 各取 YYYYMMDD 转 YYYY-MM-DD
+    - 账号名：右上角账号按钮文本
+
+自测（无需 Playwright）：    python youtube_export_interceptor.py --selftest
+
+实际运行（需 Playwright；必须复用已登录 YouTube Studio 的浏览器会话，否则跳登录页）：
+  方式 A（用已登录的用户数据目录启动，需先关闭 Chrome/Edge）：
+      python youtube_export_interceptor.py --url "<explore URL>" --channel chrome ^
+          --user-data-dir "%LOCALAPPDATA%\Google\Chrome\User Data"
+  方式 B（附加到已在调试端口运行的浏览器，无需关闭）：
+      python youtube_export_interceptor.py --url "<explore URL>" --connect http://localhost:9222
+      # 先启动：  chrome.exe --remote-debugging-port=9222  或  msedge.exe --remote-debugging-port=9222
+"""
+
+import argparse
+import base64
+import json
+import os
+import re
+import sys
+
+# 本机 Windows 下载目录。可改为 os.path.expanduser("~") / "Downloads"。
+DOWNLOAD_DIR = r"D:\Downloads"
+
+# 维度类型 -> 文件名前缀标签（生产环境请从页面「维度」按钮文本读取，这里兜底映射）。
+DIMENSION_LABEL = {
+    "VIDEO": "内容",
+    "USER": "频道",
+    "CONTENT_OWNER": "内容",
+}
+
+CSV_EXPORT_PATH = "/youtubei/v1/yta_web/csv_export"
+
+
+# --------------------------------------------------------------------------- #
+# 重名去重：需求文件.zip -> 需求文件 (1).zip -> 需求文件 (2).zip ...            #
+# --------------------------------------------------------------------------- #
+def dedup_path(directory, filename):
+    """返回不冲突的落盘路径。重名时按 `名称 (n).后缀` 递增，n 从 1 开始。
+
+    规则与用户要求一致：第二次同名保存 `xx (1).zip`，第三次 `xx (2).zip`，以此类推；
+    若 `xx (1).zip` 也已存在，则继续找 `xx (2).zip`（即取最小无冲突的 n）。
+    """
+    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` 反推导出文件名。
+
+    与实测产物命名一致：`<维度标签> <inclusiveStart>_<exclusiveEnd> <账号名>.zip`
+    """
+    def fmt_dateid(yyyymmdd):
+        s = str(yyyymmdd)
+        return f"{s[0:4]}-{s[4:6]}-{s[6:8]}"
+
+    # 从任意一个 joinRequest 节点取 dateIdRange
+    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)
+
+
+# --------------------------------------------------------------------------- #
+# Playwright 主流程（拦截响应 -> 解码 -> 去重 -> 落盘）                          #
+# --------------------------------------------------------------------------- #
+def intercept_and_save(page, account_name):
+    """给 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)
+
+            # 反推文件名：请求体在 response.request.post_data 里不总是可读，
+            # 这里从已捕获的 body 兜底；找不到就用时间戳命名，保证不误覆盖。
+            filename = None
+            try:
+                body = json.loads(response.request.post_data or "{}")
+                filename = build_export_filename(body.get("exportQuery", {}), account_name)
+            except Exception:
+                filename = f"export-{response.request.headers.get('date', '')}.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):
+    """启动/连接浏览器并触发导出。
+
+    关键：必须复用「已登录 YouTube Studio」的浏览器会话，否则会跳 Google 登录页。
+    - cdp_url：      附加到已在调试端口运行的浏览器（推荐，无需关闭浏览器）
+    - user_data_dir：用已登录的用户数据目录启动持久化上下文（需先关闭该浏览器）
+    - 两者都不传：   新建空白会话（大概率未登录，仅作占位/调试）
+    """
+    from playwright.sync_api import sync_playwright
+
+    with sync_playwright() as p:
+        browser = None
+        context = None
+
+        if cdp_url:
+            # 方式 B：附加到已打开、已登录的浏览器（先以调试端口启动浏览器）
+            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:
+            # 方式 A：用已登录的用户数据目录启动（cookies 复用；必须先关闭同名浏览器）
+            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 "studio.youtube.com" not in page.url and "accounts.google" in page.url:
+            print("[!] 当前会话未登录，已跳转到 Google 登录页。", file=sys.stderr)
+            print("    请用 --user-data-dir 复用已登录浏览器，或先手动登录后再试。",
+                  file=sys.stderr)
+
+        # 账号名：右上角账号按钮（示例选择器，按实际页面微调）
+        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)
+
+        # 触发导出：点「导出当前视图」→「逗号分隔值 (.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:
+        # 1) 用户示例：需求文件.zip 第二次 -> 需求文件 (1).zip，第三次 -> (2).zip
+        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")
+
+        # 2) 若 (1) 已存在，也应跳到 (2)
+        assert Path(dedup_path(td, "需求文件.zip")).name == "需求文件 (3).zip"
+
+        # 3) 无冲突时不加后缀
+        p3 = Path(dedup_path(td, "其他.zip"))
+        assert p3.name == "其他.zip", p3.name
+
+        # 4) 文件名反推（对应实测产物「内容 2026-07-23_2026-08-20 WL Media.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="浏览器品牌：chrome / msedge（复用登录态时必填其一）")
+    ap.add_argument("--connect", help="通过 CDP 附加到已打开的浏览器，如 http://localhost:9222")
+    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)
+    else:
+        selftest()
+        print("\n实际运行请先: pip install playwright\n"
+              "复用登录态（必选其一，详见脚本顶部 docstring）：\n"
+              "  方式 A: python youtube_export_interceptor.py --url \"<explore URL>\" "
+              "--channel chrome --user-data-dir \"%LOCALAPPDATA%\\Google\\Chrome\\User Data\"\n"
+              "  方式 B: python youtube_export_interceptor.py --url \"<explore URL>\" "
+              "--connect http://localhost:9222")