feat(scripts): 添加批量生成 YouTube Studio 内容管理器 URL 的脚本

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

@@ -0,0 +1,83 @@
+# 需求输入清单制作指南
+
+输入文件是脚本的唯一数据来源。本指南回答：怎么组织列、怎么写日期和国家、用什么实体类型、以及怎么核对。
+
+## 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 代码。
+- [ ] 多国分隔符正确。
+- [ ] 试跑无失败行、无「缺必要列」错误。
+
+试跑命令（项目根目录）：
+
+```bash
+uv run python scripts\build_studio_urls.py -i <输入文件> -o <输出csv>
+```

skills/yt-studio-url-builder/references/troubleshooting.md

@@ -0,0 +1,71 @@
+# 常见问题排查
+
+脚本的错误分三类，先分清类型再定位：
+
+- **提示（stderr，不中断）**：未识别的列、未找到国家映射文件等，仅警告。
+- **致命错误（退出码 1）**：输入文件不存在、格式不支持、缺必要列。
+- **失败行（退出码 2）**：个别需求行生成失败，成功行仍会写出；stderr 逐行打印「第N行 …：原因」。
+
+## 输入相关
+
+### 输入文件不存在
+- 原因：`-i` 路径错误，或文件名大小写/中文名不符。
+- 解决：确认路径存在；PowerShell 中路径含空格时用引号包裹。
+
+### 不支持的输入格式
+- 原因：扩展名不是 `.csv` / `.xlsx` / `.xls`。
+- 解决：另存为支持格式后再跑。
+
+### 输入缺少必要列
+- 原因：清单中没有「所有者ID」或「数据周期」（或其别名）。
+- 解决：补齐列；列名支持别名，见 input-guide.md 第 2 节。
+
+### 未识别的列（提示）
+- 原因：列名不在别名表。
+- 解决：不影响生成；如需在输出中回显，改用别名表中列名。
+
+## 行级失败（第 N 行）
+
+### 缺少所有者ID
+- 原因：该行 `owner_id` 为空。
+- 解决：补充所有者ID。
+
+### 缺少实体ID
+- 原因：实体类型不是所有者（如群组/频道/节目）且 `entity_id` 为空。
+- 解决：补充实体ID；若确为所有者整体场景，把实体类型改为「所有者/账号」并留空实体ID。
+
+### 无法解析数据周期
+- 原因：日期不符合 `yyyy.m.d-yyyy.m.d`（或 `~`/`～` 分隔）的写法。
+- 解决：按 input-guide.md 第 3 节修正。
+
+### 未识别的国家
+- 原因：中文国家名不在 `countries.json`，也不是两位 ISO 代码。
+- 解决：改用两位 ISO 代码，或向 `countries.json` 追加映射。
+
+### 未识别的实体类型
+- 原因：`entity_type` 不在映射表。
+- 解决：使用 群组/所有者/频道/节目 或 GROUP/CONTENT_OWNER/CHANNEL/VIDEO。
+
+## 输出问题
+
+### 输出行数 < 输入行数
+- 原因：存在失败行（退出码 2）。
+- 解决：查看 stderr 失败列表，逐条修复后重跑。
+
+### 输出为空 / Excel 打开乱码
+- 原因：成功记录为 0；或查看方式不对。
+- 解决：确认输入有合法行；脚本以 UTF-8-SIG 写出，Excel 可直接打开正常显示。
+
+### 找不到输出文件
+- 原因：未指定 `-o`，默认输出在**输入文件同目录** `studio_urls_output.csv`。
+- 解决：显式用 `-o` 指定输出路径。
+
+## 编码相关
+
+- CSV 输入乱码/解析异常：脚本先按 UTF-8-SIG 读，失败回退 GBK；仍异常时，把文件另存为 UTF-8 或 GBK 后重试。
+- `countries.json` 建议 UTF-8；脚本按 UTF-8-SIG 读取，带 BOM 无影响。
+
+## 改了固定参数不生效
+
+- 原因：固定参数集中在脚本顶部 `CONFIG`，改后需重跑脚本才会生效。
+- 提示：改 `CONFIG` 只影响 URL 参数，不需要改需求清单。