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/skills/yt-studio-url-builder/SKILL.md
+++ b/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)：按 现象 → 原因 → 解决 逐条排查。
--- a/skills/yt-studio-url-builder/references/input-guide.md
+++ b/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>
+```
--- a/skills/yt-studio-url-builder/references/troubleshooting.md
+++ b/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 参数，不需要改需求清单。
--- a/skills/yt-studio-url-builder/scripts/build_studio_urls.py
+++ b/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()
--- a/skills/yt-studio-url-builder/scripts/countries.json
+++ b/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"
+}