SidneyZhang/StudioLift
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ba00651fa9f993dec8b1c3043dc68029ad0467d8
StudioLift/skills/yt-studio-url-builder/SKILL.md

5.1 KiB
Raw Blame History

name, description
name description
yt-studio-url-builder 根据需求清单（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 生成 CSV/Excel 需求清单（文件格式、列名别名、日期/国家/实体类型写法、完整示例、核对清单）。

完成标准：输入文件包含必要列（所有者ID、数据周期），且列名能被脚本识别（无「缺必要列」错误）。

4. 运行脚本

# 项目根目录下
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 修复后重跑。

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

固定参数（CONFIG）

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

参考