feat(scripts): 添加批量生成 YouTube Studio 内容管理器 URL 的脚本
This commit is contained in:
84
skills/yt-studio-url-builder/SKILL.md
Normal file
84
skills/yt-studio-url-builder/SKILL.md
Normal file
@@ -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)：按 现象 → 原因 → 解决 逐条排查。
|
||||
Reference in New Issue
Block a user