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

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 代码。
• 指标（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 生成 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（国家筛选）、metric（指标）、dimension（维度）。
• 有失败行时脚本以退出码 2 结束，并在 stderr 逐行打印「第N行 …：原因」；逐条按 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"]。

参考

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