StudioLift/skills/yt-studio-url-builder/references/input-guide.md

需求输入清单制作指南

输入文件是脚本的唯一数据来源。本指南回答：怎么组织列、怎么写日期和国家、用什么实体类型、以及怎么核对。

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 / 筛选国家 / 地区	美国,日本
metric 指标	否	指标 / 主指标 / 数据指标 / metric / 指标名	观看时长
dimension 维度	否	维度 / 细分维度 / dimension / 细分	地理位置

注意：

• 「所有者名称 / 实体名称」只进输出回显，不参与 URL 拼装，缺列不影响生成。
• 必要列只有两列：所有者ID、数据周期。指标列留空则用脚本 CONFIG 默认主指标。

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 代码。
• 多国分隔符正确。
• 指标列：中文名/英文名已在 metrics.json 中，或用已知指标代码；留空表示走默认。
• 维度列：中文名已在 dimensions.json 中，或用已知维度代码；留空表示走默认。
• 试跑无失败行、无「缺必要列」错误。

试跑命令（项目根目录）：

uv run python scripts\build_studio_urls.py -i <输入文件> -o <输出csv>

8. 指标格式

指标列（指标 / 主指标 / 数据指标 / metric）每行可选，决定 URL 的主指标 metric 参数与排序字段 o_column。

• 留空：用脚本 CONFIG["metric"] 默认主指标（SUBSCRIBERS_NET_CHANGE），排序字段用 CONFIG["o_column"]。
• 中文/英文名：须在 scripts/metrics.json 映射内（可自行扩充），如 观看时长 → EXTERNAL_WATCH_TIME、预计收益 → TOTAL_ESTIMATED_EARNINGS。
• 指标代码：已知代码原样透传，大小写不敏感，如 external_views ↔ EXTERNAL_VIEWS。

metrics.json 内已覆盖完整清单（与 assets/YouTube_Studio_细分维度_时间颗粒度_完整清单.xlsx 的「数据指标」表一致，57 条），并额外收编了常用别名。下面仅列一部分；完整可用映射见该文件，也可自行扩充：

中文名	指标代码	说明
订阅人数 / 订阅净增长	SUBSCRIBERS_NET_CHANGE	主指标/排序默认
观看次数	EXTERNAL_VIEWS	表格列指标
观看时长（小时）	EXTERNAL_WATCH_TIME	表格列指标
估算的合作伙伴收入 / 预计收益 / 税前收益 / 税前收入	TOTAL_ESTIMATED_EARNINGS	表格列指标
平均观看时长	AVERAGE_WATCH_TIME	表格列指标
发布的视频数	VIDEO_COUNT_FIRST_PUBLISHED	表格列指标

指标只影响 metric 与 o_column；t_metrics（表格列指标集合）、粒度等仍是 CONFIG 固定值。

9. 细分维度

维度列（维度 / 细分维度 / dimension）每行可选，决定 URL 的 dimension 参数。

• 留空：用脚本 CONFIG["dimension"] 默认细分维度（USER，即「频道」）。
• 中文名：须在 scripts/dimensions.json 映射内（可自行扩充），如 内容 → VIDEO、地理位置 → COUNTRY、频道 → USER。
• 维度代码：已知代码原样透传，大小写不敏感，如 video ↔ VIDEO。

dimensions.json 内已覆盖完整清单（与「细分维度」表一致，33 条），例如：内容 VIDEO、流量来源 TRAFFIC_SOURCE_TYPE、地理位置 COUNTRY、频道 USER、资产 ASSET、设备类型 DEVICE_PLATFORM_TYPE、操作系统 DEVICE_OS_TYPE、收入来源 EARNINGS_SOURCE_ALL、日期 DAY 等。

维度只影响 dimension 参数；metric、t_metrics、粒度等不受影响。