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

skills/uv-env-setup/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: "uv-env-setup"
+description: "用 uv 准备并维护本项目 Python 运行环境（pyproject.toml → uv sync → uv run）。当用户提到环境准备/环境初始化/装依赖/重建 venv，脚本报 ModuleNotFoundError（pandas/openpyxl/playwright），.venv 缺失或损坏，或首次运行 scripts/、skills/*/scripts/ 下的 Python 脚本时使用。"
+---
+
+# uv 运行环境准备
+
+本项目所有 Python 脚本共用一套 uv 管理的环境：根目录 `pyproject.toml` 是依赖的**唯一事实来源**，`uv sync` 落地 `.venv\`，`uv run` 执行脚本（自动使用该环境，免激活、免手装依赖）。
+
+## 步骤 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`
+
+装完重开终端使 PATH 生效。
+
+**完成判据**：`uv --version` 打印出版本号。
+
+## 步骤 2：同步依赖
+
+项目根目录（`pyproject.toml` 所在处）执行：
+
+```powershell
+uv sync
+```
+
+- 首次运行自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright）。
+- 本机无兼容 Python 时，uv 自动下载托管 Python（`requires-python = ">=3.10"`）。
+- `uv run` 本身也会隐式同步；显式 `uv sync` 是为了在跑脚本前把依赖错误一次性暴露出来。
+
+**完成判据**：命令退出码 0，且项目根出现 `.venv\` 目录。
+
+## 步骤 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
+```
+
+**完成判据**：三条命令均成功——打印 `env OK`、`selftest OK`、脚本的用法帮助。
+
+## 其他技能如何使用本环境
+
+- 统一在项目根目录用 `uv run python <脚本> [参数]` 执行，uv 自动向上定位 `pyproject.toml` 并复用其环境。
+- 不用裸 `python`（依赖 PATH 碰运气），不手动激活 venv，不 `pip install` 到全局。
+
+## 新增依赖
+
+改 `pyproject.toml` 的 `dependencies`（唯一入口），再 `uv sync` 更新 `uv.lock`。禁止 `pip install` / `uv pip install` 直装——绕过 lock，环境不可复现。
+
+## 排查
+
+网络慢/超时、uv 安装失败、`.venv` 损坏重建、多版本 Python 冲突等，查 [references/troubleshooting.md](references/troubleshooting.md)。

skills/uv-env-setup/references/troubleshooting.md

@@ -0,0 +1,49 @@
+# 环境排查
+
+## uv 安装与 PATH
+
+- **`uv: command not found` / 无法识别**：装完未重开终端，PATH 未生效；重开终端或手动刷新 `$env:Path`。
+- **winget 安装失败**：改用官方脚本 `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`，或 `pip install uv`。
+
+## 网络与镜像（国内环境）
+
+`uv sync` / `uv run` 拉包慢或超时时，临时切换清华镜像：
+
+```powershell
+$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
+uv sync
+```
+
+要持久化则写入 `pyproject.toml`：
+
+```toml
+[[tool.uv.index]]
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+default = true
+```
+
+## sync 相关
+
+- **`No solution found` / 依赖解析冲突**：`dependencies` 里的版本约束互相矛盾。放宽或修正 `pyproject.toml` 后重试。
+- **lock 与 pyproject 不一致**：`uv.lock` 过期，`uv sync` 会自动更新；若报 lock 损坏，删除 `uv.lock` 后重新 `uv sync`。
+- **`requires-python` 不满足**：本机 Python 全部低于 3.10。让 uv 自动下载即可：`uv sync -p 3.12`（或省略，uv 自选）。
+
+## .venv 损坏 / 重建
+
+症状：`uv run` 报奇怪的导入错误、DLL 加载失败，或 `.venv` 被移动过。
+
+```powershell
+Remove-Item -Recurse -Force .venv
+uv sync
+```
+
+## playwright 相关
+
+- **`ModuleNotFoundError: playwright`**：环境未同步。项目根执行 `uv sync`，或直接用 `uv run python <脚本>`（隐式同步）。
+- **复用系统 Chrome/Edge 无需 `playwright install`**：只有用 uv 环境内置 Chromium 时才需要 `uv run playwright install chromium`。
+- **`playwright install` 下载浏览器慢**：`$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright"` 后重试。
+
+## 与全局环境隔离
+
+- 本项目所有命令都经 `uv run`，不会污染全局 site-packages。
+- 若此前 `pip install` 过 playwright/pandas 到全局，与本 `.venv` 无冲突，但项目内一律走 `uv run`。

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

@@ -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 不匹配、未捕获响应、文件名回退等）。

skills/youtube-studio-csv-download/references/troubleshooting.md

@@ -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 逻辑，不依赖浏览器。

skills/youtube-studio-csv-download/scripts/youtube_export_download.py

@@ -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")

skills/yt-studio-url-builder/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: "yt-studio-url-builder"
+description: "根据需求清单（CSV/Excel）批量生成 YouTube Studio 内容管理器 explore URL。当用户要求拼接/生成 YouTube Studio URL、批量产出报告链接、制作或校验需求输入清单、排查 URL 生成失败问题时使用。"
+---
+
+# YouTube Studio URL 拼接器
+
+基于需求清单（CSV/Excel）批量生成 YouTube Studio 内容管理器（Content Manager）高级模式 explore 报告 URL。底层执行脚本 `scripts/build_studio_urls.py`，需求行只提供差异化条件，固定参数由脚本顶部 `CONFIG` 统一维护。
+
+## 何时使用
+
+- **生成 URL**：用户给出所有者/群组/频道/节目清单，要求批量产出 explore URL。
+- **制作输入清单**：用户有零散需求（所有者ID、实体、日期范围、国家），需先整理成脚本可读的输入文件。
+- **排查问题**：运行后出现失败行、空输出、解析错误，需要定位并修复。
+
+## 领域词汇
+
+- **所有者（Content Owner）**：拥有内容管理器的账号实体，URL 中由 `o` 参数 + `/owner/<id>/` 路径标识。
+- **实体（Entity）**：报告统计的对象，由 `entity_type` + `entity_id` 标识（CONTENT_OWNER / GROUP / CHANNEL / VIDEO）。
+- **群组（Group）**：所有者名下用于组织一批频道/资产的实体，`entity_id` 为其 groupId（如 `NCy9C2QPQ1E`）。
+- **需求（Requirement）**：输入清单中的一行，描述一条待生成 URL 的完整条件（所有者、实体、数据周期、国家筛选）。
+- **数据周期（Period）**：`yyyy.mm.dd-yyyy.mm.dd` 或 `yyyy.m.d-yyyy.m.d` 的日期区间，起始日与结束日均包含。
+- **日界线（Day Boundary）**：周期中日期对应的 Unix 毫秒，采用「锚点 2026-06-15 = 1781506800000 + 整日偏移」计算，不做时区换算。
+- **国家筛选（Country Filter）**：`ur_dimensions=COUNTRY` + `ur_values`；多国以 `'`（`%27`）包裹、`|`（`%7C`）连接；国家用 ISO 3166-1 alpha-2 代码。
+
+## 工作流
+
+### 1. 定位脚本与依赖
+
+- 脚本默认位于 `scripts/build_studio_urls.py`；若缺失，用 SearchCodebase 按 `build_studio_urls.py` 定位。
+- 运行环境由 `uv-env-setup` 技能统一管理：依赖（pandas、openpyxl）在根 `pyproject.toml` 声明，`uv run` 自动同步。首次运行前先按该技能准备环境。
+- 中文国家名 → ISO 代码的映射在 `scripts/countries.json`，可自行扩充。
+
+完成标准：脚本路径已确定，且第 4 步的运行命令可直接执行。
+
+### 2. 收集每条需求
+
+对每条待生成 URL 的需求，明确以下要素（留空表示走默认）：
+
+| 要素 | 必填 | 说明 |
+|---|---|---|
+| 所有者ID | 是 | URL 中的 `o` 参数与 `/owner/<id>/` 路径 |
+| 实体类型 | 可默认 | 群组/所有者/频道/节目；缺省按群组 |
+| 实体ID | 视类型 | 群组/频道/节目必填；所有者场景可留空（回退用所有者ID） |
+| 数据周期 | 是 | 见领域词汇「数据周期」 |
+| 国家 | 可空 | 一个或多个，中文名或两位 ISO 代码 |
+
+完成标准：对每一条需求，上表要素已确定，或明确「留空走默认」。
+
+### 3. 制作输入文件
+
+按 [references/input-guide.md](references/input-guide.md) 生成 CSV/Excel 需求清单（文件格式、列名别名、日期/国家/实体类型写法、完整示例、核对清单）。
+
+完成标准：输入文件包含必要列（所有者ID、数据周期），且列名能被脚本识别（无「缺必要列」错误）。
+
+### 4. 运行脚本
+
+```bash
+# 项目根目录下
+uv run python scripts\build_studio_urls.py -i <输入文件> [-o <输出csv>]
+```
+
+- 输入支持 `.csv`（UTF-8 或 GBK，自动尝试）与 `.xlsx` / `.xls`。
+- 未指定 `-o` 时，输出到输入文件同目录的 `studio_urls_output.csv`。
+- 可用 `--countries <json>` 覆盖国家映射文件路径（默认脚本同目录 `countries.json`）。
+
+完成标准：脚本退出码为 0，且输出 CSV 行数与成功需求数一致。
+
+### 5. 校验输出并处理失败行
+
+- 检查输出列：所有者名称、所有者ID、实体类型、实体名称、实体ID、数据周期、国家、国家代码、开始时间戳、结束时间戳、URL。
+- 抽查 URL 是否包含正确的 `entity_type` / `entity_id` / `time_period` / `ur_values`（国家筛选）。
+- 有失败行时脚本以退出码 2 结束，并在 stderr 逐行打印「第N行 …：原因」；逐条按 [references/troubleshooting.md](references/troubleshooting.md) 修复后重跑。
+
+完成标准：所有需求行均生成 URL，或失败行已定位原因并修复。
+
+## 固定参数（CONFIG）
+
+metric / granularity / dimension / t_metrics / o_column / o_direction / explore_type / comparison_type 等固定参数集中在脚本顶部 `CONFIG` 一处维护。**修改固定参数只需改 `CONFIG`（单点维护）**，不要逐行携带到需求清单中。
+
+## 参考
+
+- [需求输入制作指南](references/input-guide.md)：列名别名、日期/国家/实体类型写法、完整示例、制作核对清单。
+- [常见问题排查](references/troubleshooting.md)：按 现象 → 原因 → 解决 逐条排查。

skills/yt-studio-url-builder/references/input-guide.md

@@ -0,0 +1,83 @@
+# 需求输入清单制作指南
+
+输入文件是脚本的唯一数据来源。本指南回答：怎么组织列、怎么写日期和国家、用什么实体类型、以及怎么核对。
+
+## 1. 文件格式
+
+- **CSV**：UTF-8（带/不带 BOM）或 GBK/ANSI（Excel 另存）均可，脚本自动尝试编码。
+- **Excel**：`.xlsx` / `.xls`，读首个工作表。
+- 全空行会被忽略。
+
+## 2. 列与别名
+
+脚本按「去空白、转小写」后的列名匹配，**中英文别名均可**。未识别列会被忽略（stderr 有提示），但不中断生成。
+
+| 规范字段 | 必填 | 可用列名（别名） | 示例 |
+|---|---|---|---|
+| owner_name 所有者名称 | 否 | 所有者名称 / owner_name / 所有者 | 示例内容所有者 |
+| owner_id 所有者ID | **是** | 所有者ID / owner_id / o | bqSUnNpU67xJ51TxH4PKpQ |
+| entity_name 实体名称 | 否 | 实体名称 / 群组名称 / 频道名称 / 节目名称 / entity_name | 示例群组-1 |
+| entity_id 实体ID | 视类型 | 实体ID / 群组ID / group_id / entity_id / id / 群组 | NCy9C2QPQ1E |
+| entity_type 实体类型 | 否 | 实体类型 / 类型 / entity_type / type | 群组 |
+| period 数据周期 | **是** | 数据周期 / 周期 / period / time_period / 日期范围 | 2026.08.01-2026.08.31 |
+| countries 国家 | 否 | 国家 / 国家/地区 / countries / country / 筛选国家 / 地区 | 美国,日本 |
+
+> 注意：
+> - 「所有者名称 / 实体名称」只进输出回显，不参与 URL 拼装，缺列不影响生成。
+> - **必要列只有两列：所有者ID、数据周期**。
+
+## 3. 数据周期格式
+
+- 形式：`yyyy.mm.dd-yyyy.mm.dd` 或 `yyyy.m.d-yyyy.m.d`（前导零可省）。
+- 起止日期之间可用 `-`、`~`、`～`；日期内部用 `.`、`/`、`-`。
+- **起止日期均包含在数据范围内**（结束日取次日的日界线）。
+- 例子：`2026.08.01-2026.08.31`、`2026.8.1-2026.8.31`、`2026-07-01~2026-08-01` 均可。
+- 时间换算为日界线毫秒：`ts(X) = 1781506800000 + (X − 2026-06-15) × 86400000`。
+
+## 4. 国家格式
+
+- 中文国家名：须在 `scripts/countries.json` 映射内（可自行扩充）。
+- 两位 ISO 代码（如 `US`、`JP`）：原样透传，大小写不敏感。
+- 多个国家：用 `,`、`、`、`;`、空格或 `|` 分隔均可。
+- 留空 = 不筛选国家（URL 中不带 `ur_dimensions` / `ur_values`）。
+- 输出中的「国家代码」列展示解析后的 ISO 代码，便于核对。
+
+## 5. 实体类型
+
+| 输入（中文/代码） | URL 参数值 |
+|---|---|
+| 群组 / GROUP | GROUP |
+| 所有者 / 账号 / CONTENT_OWNER | CONTENT_OWNER |
+| 频道 / CHANNEL | CHANNEL |
+| 节目 / 视频 / VIDEO | VIDEO |
+
+- 缺省按「群组」处理。
+- 实体类型为**所有者**且实体ID留空时，自动回退用所有者ID作为 entity_id。
+
+## 6. 完整示例（对应 assets/需求输入示例.xlsx）
+
+| 所有者名称 | 所有者ID | 实体类型 | 实体名称 | 实体ID | 数据周期 | 国家 |
+|---|---|---|---|---|---|---|
+| 示例内容所有者 | bqSUnNpU67xJ51TxH4PKpQ | 群组 | 示例群组-1 | NCy9C2QPQ1E | 2026.08.01-2026.08.31 | 美国 |
+| 示例内容所有者 | bqSUnNpU67xJ51TxH4PKpQ | 群组 | 示例群组-2 | NCyxxxxxxxxx | 2026.8.1-2026.8.31 | 美国,日本 |
+| 示例内容所有者 | bqSUnNpU67xJ51TxH4PKpQ | 群组 | 示例群组-3 | NCyYYYYYYYYY | 2026.07.01-2026.07.31 | GB,DE,FR |
+| 示例内容所有者 | bqSUnNpU67xJ51TxH4PKpQ | 所有者 | 账号整体 | （留空） | 2026.06.01-2026.06.30 | US |
+| 示例内容所有者 | bqSUnNpU67xJ51TxH4PKpQ | 频道 | 示例频道 | UCxxxxxUCxxxxx | 2026.08.01-2026.08.15 | 日本 |
+| 示例内容所有者 | bqSUnNpU67xJ51TxH4PKpQ | 节目 | 示例节目 | video123456 | 2026.08.01-2026.08.31 | 韩国,日本 |
+
+覆盖场景：单/多国家、中文名与 ISO 代码混用、四种实体类型、带/不带前导零的日期、所有者场景留空实体ID。
+
+## 7. 制作核对清单
+
+- [ ] 至少含「所有者ID」「数据周期」两列（列名可用中英文别名）。
+- [ ] 每行数据周期格式正确，起止日期均含。
+- [ ] 群组/频道/节目行已填实体ID；所有者行可留空实体ID。
+- [ ] 中文国家名已在 countries.json 中，否则改用两位 ISO 代码。
+- [ ] 多国分隔符正确。
+- [ ] 试跑无失败行、无「缺必要列」错误。
+
+试跑命令（项目根目录）：
+
+```bash
+uv run python scripts\build_studio_urls.py -i <输入文件> -o <输出csv>
+```

skills/yt-studio-url-builder/references/troubleshooting.md

@@ -0,0 +1,71 @@
+# 常见问题排查
+
+脚本的错误分三类，先分清类型再定位：
+
+- **提示（stderr，不中断）**：未识别的列、未找到国家映射文件等，仅警告。
+- **致命错误（退出码 1）**：输入文件不存在、格式不支持、缺必要列。
+- **失败行（退出码 2）**：个别需求行生成失败，成功行仍会写出；stderr 逐行打印「第N行 …：原因」。
+
+## 输入相关
+
+### 输入文件不存在
+- 原因：`-i` 路径错误，或文件名大小写/中文名不符。
+- 解决：确认路径存在；PowerShell 中路径含空格时用引号包裹。
+
+### 不支持的输入格式
+- 原因：扩展名不是 `.csv` / `.xlsx` / `.xls`。
+- 解决：另存为支持格式后再跑。
+
+### 输入缺少必要列
+- 原因：清单中没有「所有者ID」或「数据周期」（或其别名）。
+- 解决：补齐列；列名支持别名，见 input-guide.md 第 2 节。
+
+### 未识别的列（提示）
+- 原因：列名不在别名表。
+- 解决：不影响生成；如需在输出中回显，改用别名表中列名。
+
+## 行级失败（第 N 行）
+
+### 缺少所有者ID
+- 原因：该行 `owner_id` 为空。
+- 解决：补充所有者ID。
+
+### 缺少实体ID
+- 原因：实体类型不是所有者（如群组/频道/节目）且 `entity_id` 为空。
+- 解决：补充实体ID；若确为所有者整体场景，把实体类型改为「所有者/账号」并留空实体ID。
+
+### 无法解析数据周期
+- 原因：日期不符合 `yyyy.m.d-yyyy.m.d`（或 `~`/`～` 分隔）的写法。
+- 解决：按 input-guide.md 第 3 节修正。
+
+### 未识别的国家
+- 原因：中文国家名不在 `countries.json`，也不是两位 ISO 代码。
+- 解决：改用两位 ISO 代码，或向 `countries.json` 追加映射。
+
+### 未识别的实体类型
+- 原因：`entity_type` 不在映射表。
+- 解决：使用 群组/所有者/频道/节目 或 GROUP/CONTENT_OWNER/CHANNEL/VIDEO。
+
+## 输出问题
+
+### 输出行数 < 输入行数
+- 原因：存在失败行（退出码 2）。
+- 解决：查看 stderr 失败列表，逐条修复后重跑。
+
+### 输出为空 / Excel 打开乱码
+- 原因：成功记录为 0；或查看方式不对。
+- 解决：确认输入有合法行；脚本以 UTF-8-SIG 写出，Excel 可直接打开正常显示。
+
+### 找不到输出文件
+- 原因：未指定 `-o`，默认输出在**输入文件同目录** `studio_urls_output.csv`。
+- 解决：显式用 `-o` 指定输出路径。
+
+## 编码相关
+
+- CSV 输入乱码/解析异常：脚本先按 UTF-8-SIG 读，失败回退 GBK；仍异常时，把文件另存为 UTF-8 或 GBK 后重试。
+- `countries.json` 建议 UTF-8；脚本按 UTF-8-SIG 读取，带 BOM 无影响。
+
+## 改了固定参数不生效
+
+- 原因：固定参数集中在脚本顶部 `CONFIG`，改后需重跑脚本才会生效。
+- 提示：改 `CONFIG` 只影响 URL 参数，不需要改需求清单。

skills/yt-studio-url-builder/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()

skills/yt-studio-url-builder/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"
+}