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 / 筛选国家 / 地区	美国,日本

注意：

• 「所有者名称 / 实体名称」只进输出回显，不参与 URL 拼装，缺列不影响生成。
• 必要列只有两列：所有者ID、数据周期。

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 代码。
• 多国分隔符正确。
• 试跑无失败行、无「缺必要列」错误。

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

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