---
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 代码。
- **指标（Metric）**：报表主指标，URL 中的 `metric` 参数；每行可选（`指标` 列），中文名/英文名写在同目录 `metrics.json` 里映射到内部代码，留空走 `CONFIG` 默认。选中后排序字段 `o_column` 一并跟随。
- **维度（Dimension）**：报表细分维度，URL 中的 `dimension` 参数；每行可选（`维度` 列），中文名写在同目录 `dimensions.json` 里映射到内部代码，留空走 `CONFIG` 默认。

## 工作流

### 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 代码 |
| 指标 | 可默认 | 主指标（`metric` 参数）；中文名/英文名或已知指标代码；留空走 CONFIG 默认 |
| 维度 | 可默认 | 细分维度（`dimension` 参数）；中文名或已知维度代码；留空走 CONFIG 默认 |

完成标准：对每一条需求，上表要素已确定，或明确「留空走默认」。

### 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`（国家筛选）、`metric`（指标）、`dimension`（维度）。
- 有失败行时脚本以退出码 2 结束，并在 stderr 逐行打印「第N行 …：原因」；逐条按 [references/troubleshooting.md](references/troubleshooting.md) 修复后重跑。

完成标准：所有需求行均生成 URL，或失败行已定位原因并修复。

## 固定参数（CONFIG）

granularity / dimension / t_metrics / o_direction / explore_type / comparison_type 等固定参数集中在脚本顶部 `CONFIG` 一处维护。**修改这些固定参数只需改 `CONFIG`（单点维护）**，不要逐行携带到需求清单中。

`metric`（主指标）**可按行选择**：在需求清单加一列 `指标`（别名 `主指标` / `数据指标` / `metric`），填中文名/英文名（`metrics.json` 映射）或已知指标代码均可；留空则回退 `CONFIG["metric"]`，选中时 `o_column`（排序字段）一并跟随。

`dimension`（细分维度）**同样可按行选择**：在需求清单加一列 `维度`（别名 `细分维度` / `dimension`），填中文名（`dimensions.json` 映射）或已知维度代码均可；留空则回退 `CONFIG["dimension"]`。

## 参考

- [需求输入制作指南](references/input-guide.md)：列名别名、日期/国家/实体类型写法、完整示例、制作核对清单。
- [常见问题排查](references/troubleshooting.md)：按 现象 → 原因 → 解决 逐条排查。
- [映射文件维护指南](references/maintenance-guide.md)：`countries.json` / `metrics.json` / `dimensions.json` 三个映射文件的来源、结构与新增/更新条目方法。