feat(scripts): 支持动态指标和维度参数配置

为 build_studio_urls.py 添加指标和维度的可配置支持，包括： - 新增 metrics.json 和 dimensions.json 映射文件加载 - 支持中文/英文别名映射及指标代码透传 - 列别名扩展以识别"指标"和"维度"列 - 空值时自动回退到 CONFIG 默认值
2026-08-24 15:28:48 +08:00
parent ba00651fa9
commit b8bd749f43
16 changed files with 996 additions and 36 deletions
--- a/skills/yt-studio-url-builder/SKILL.md
+++ b/skills/yt-studio-url-builder/SKILL.md
@@ -22,6 +22,8 @@ description: "根据需求清单（CSV/Excel）批量生成 YouTube Studio 内
 - **数据周期（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` 默认。

 ## 工作流

@@ -44,6 +46,8 @@ description: "根据需求清单（CSV/Excel）批量生成 YouTube Studio 内
 | 实体ID | 视类型 | 群组/频道/节目必填；所有者场景可留空（回退用所有者ID） |
 | 数据周期 | 是 | 见领域词汇「数据周期」 |
 | 国家 | 可空 | 一个或多个，中文名或两位 ISO 代码 |
+| 指标 | 可默认 | 主指标（`metric` 参数）；中文名/英文名或已知指标代码；留空走 CONFIG 默认 |
+| 维度 | 可默认 | 细分维度（`dimension` 参数）；中文名或已知维度代码；留空走 CONFIG 默认 |

 完成标准：对每一条需求，上表要素已确定，或明确「留空走默认」。

@@ -68,17 +72,22 @@ uv run python scripts\build_studio_urls.py -i <输入文件> [-o <输出csv>]

 ### 5. 校验输出并处理失败行

- 检查输出列：所有者名称、所有者ID、实体类型、实体名称、实体ID、数据周期、国家、国家代码、开始时间戳、结束时间戳、URL。
- 抽查 URL 是否包含正确的 `entity_type` / `entity_id` / `time_period` / `ur_values`（国家筛选）。
+- 检查输出列：所有者名称、所有者ID、实体类型、实体名称、实体ID、数据周期、国家、国家代码、指标、指标代码、维度、维度代码、开始时间戳、结束时间戳、URL。
+- 抽查 URL 是否包含正确的 `entity_type` / `entity_id` / `time_period` / `ur_values`（国家筛选）、`metric`（指标）、`dimension`（维度）。
 - 有失败行时脚本以退出码 2 结束，并在 stderr 逐行打印「第N行 …：原因」；逐条按 [references/troubleshooting.md](references/troubleshooting.md) 修复后重跑。

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

 ## 固定参数（CONFIG）

-metric / granularity / dimension / t_metrics / o_column / o_direction / explore_type / comparison_type 等固定参数集中在脚本顶部 `CONFIG` 一处维护。**修改固定参数只需改 `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"]`。

 ## 参考

 - [需求输入制作指南](references/input-guide.md)：列名别名、日期/国家/实体类型写法、完整示例、制作核对清单。
 - [常见问题排查](references/troubleshooting.md)：按 现象 → 原因 → 解决 逐条排查。
+- [映射文件维护指南](references/maintenance-guide.md)：`countries.json` / `metrics.json` / `dimensions.json` 三个映射文件的来源、结构与新增/更新条目方法。
--- a/skills/yt-studio-url-builder/references/input-guide.md
+++ b/skills/yt-studio-url-builder/references/input-guide.md
@@ -21,10 +21,12 @@
 | entity_type 实体类型 | 否 | 实体类型 / 类型 / entity_type / type | 群组 |
 | period 数据周期 | **是** | 数据周期 / 周期 / period / time_period / 日期范围 | 2026.08.01-2026.08.31 |
 | countries 国家 | 否 | 国家 / 国家/地区 / countries / country / 筛选国家 / 地区 | 美国,日本 |
+| metric 指标 | 否 | 指标 / 主指标 / 数据指标 / metric / 指标名 | 观看时长 |
+| dimension 维度 | 否 | 维度 / 细分维度 / dimension / 细分 | 地理位置 |

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

 ## 3. 数据周期格式

@@ -56,16 +58,16 @@

 ## 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 | 韩国,日本 |
+| 所有者名称 | 所有者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。
+覆盖场景：单/多国家、中文名与 ISO 代码混用、四种实体类型、带/不带前导零的日期、所有者场景留空实体ID、指标可选（中文名或留空走默认）、维度可选（中文名或留空走默认）。

 ## 7. 制作核对清单

@@ -74,6 +76,8 @@
 - [ ] 群组/频道/节目行已填实体ID；所有者行可留空实体ID。
 - [ ] 中文国家名已在 countries.json 中，否则改用两位 ISO 代码。
 - [ ] 多国分隔符正确。
+- [ ] 指标列：中文名/英文名已在 metrics.json 中，或用已知指标代码；留空表示走默认。
+- [ ] 维度列：中文名已在 dimensions.json 中，或用已知维度代码；留空表示走默认。
 - [ ] 试跑无失败行、无「缺必要列」错误。

 试跑命令（项目根目录）：
@@ -81,3 +85,36 @@
 ```bash
 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`、粒度等不受影响。
--- a/skills/yt-studio-url-builder/references/maintenance-guide.md
+++ b/skills/yt-studio-url-builder/references/maintenance-guide.md
@@ -0,0 +1,135 @@
+# 映射文件维护指南
+
+`scripts/` 下有三个映射文件，把「人类可读的中文/英文名」翻译成「URL 内部代码」。本指南说明它们各自的作用、数据来源、结构规则，以及如何新增/更新条目。
+
+- `countries.json`：中文国家名 → ISO 3166-1 alpha-2 代码（两位大写）。
+- `metrics.json`：指标中文/英文名 → 指标代码（大写、下划线风格）。
+- `dimensions.json`：细分维度中文名 → 维度代码（大写）。
+
+三者都是**扁平 `key -> value` 的 JSON 对象**，UTF-8 编码。脚本按 UTF-8-SIG 读取，带 BOM 无影响。
+
+## 1. 脚本如何加载它们
+
+| 文件 | 加载函数 | 参数 | 缺失/文件不存在时的行为 |
+|---|---|---|---|
+| countries.json | `load_country_map` | `--countries` | 仅支持两位 ISO 代码透传，中文名会报「未识别的国家」 |
+| metrics.json | `load_metric_map` | `--metrics` | 仅支持 `CONFIG` 里的已知指标代码透传，中文/英文名会报「未识别的指标」 |
+| dimensions.json | `load_dimension_map` | `--dimensions` | 仅支持 `CONFIG["dimension"]` 已知维度代码透传，中文名会报「未识别的维度」 |
+
+加载时统一做了`strip` + 值 `upper()`，因此**文件里大小写、首尾空格不影响结果**——但建议源文件就保持规范，便于 diff 和阅读。
+
+## 2. 数据来源（Source of Truth）
+
+内部代码的真实来源是 YouTube Studio 后台 explore 报告 URL 里的 `metric=` / `dimension=` / `t_metrics=` 参数（或捕获的 `search_groups`/analytics 请求）。仓库内 `assets/YouTube_Studio_细分维度_时间颗粒度_完整清单.xlsx` 已把已知清单整理好，是当前映射的**基准数据源**：
+
+| 映射文件 | 对应 Excel 表 | 取「同名」列 → 值列 |
+|---|---|---|
+| dimensions.json | `细分维度` 表 | `中文名称（显示名）` → `URL 参数值（dimension=）` |
+| metrics.json | `数据指标` 表 | `中文名称（显示名）` → `URL 参数值（t_metrics=/metric=）` |
+| countries.json | 无 Excel 源 | 基于 ISO 3166-1 alpha-2 标准手工维护 |
+
+`时间颗粒度` 表对应脚本 `CONFIG["granularity"]`，**不落入 JSON 文件**；`URL参数总览` 表是对 URL 各参数的说明，供核对。
+
+## 3. 三个文件的结构与规则
+
+### 3.1 dimensions.json（细分维度）
+
+- 键：维度中文显示名，如 `内容`、`地理位置`、`收入来源`。
+- 值：维度代码（大写），如 `VIDEO`、`COUNTRY`、`EARNINGS_SOURCE_ALL`。
+
+规则：
+- 一个中文名对应一个代码；多个不同中文名可指向**同一**代码（如需，但避免冗余）。
+- 新增一个维度后，其代码会被 `load_dimension_map` 自动加入「可透传集合」——即该代码立刻可作为裸代码在 `维度` 列直接填写，**无需改 `build_studio_urls.py`**。
+- 维度代码只影响 URL 的 `dimension` 参数。
+
+### 3.2 metrics.json（数据指标）
+
+标准条目（来自 Excel「数据指标」表，57 条）：
+- 键：指标中文名，如 `观看次数`、`估算的合作伙伴收入`。
+- 值：指标代码（大写），如 `EXTERNAL_VIEWS`、`TOTAL_ESTIMATED_EARNINGS`。
+
+别名条目（手工追加，用于同义词/英文名，**不会出现在 Excel 中**）：
+- 多个中文同义词 → 同一代码。如 `税前收益`、`税前收入`、`预计收益`、`收益`、`收入` 都指向 `TOTAL_ESTIMATED_EARNINGS`。
+- 英文 snake_case → 同一代码。如 `subscribers_net_change` → `SUBSCRIBERS_NET_CHANGE`。
+
+规则：
+- 一个键对应唯一一个代码（JSON 键唯一，重复键后者覆盖前者，应避免手写重复）。
+- 一个代码可有多个键（同义词），方向只能多对一。
+- 新增一个指标后，其代码会被 `load_metric_map` 自动加入「可透传集合」，可直接作为裸代码填写。
+- 指标只影响 URL 的 `metric` 与 `o_column`（排序字段）两个参数；`t_metrics`（表格列指标集合）仍是 `CONFIG` 固定值，**不在 JSON 里维护**。
+
+### 3.3 countries.json（国家）
+
+- 键：中文国家名（可含别名，如 `台湾`、`中国台湾` 都指向 `TW`）。
+- 值：ISO 3166-1 alpha-2 两位大写代码，如 `US`、`JP`、`CN`。
+
+规则：
+- 值必须为**两位大写字母**。多字/小写虽能被脚本 upper 后处理，但透传逻辑依赖 `[A-Z]{2}` 正则，非两位会走中文名映射路径。
+- 两位 ISO 代码本身**无需在此文件登记**即可透传（`parse_countries` 正则直接识别），所以国家列填 `US` 永远可行；只有在需要「中文名 → 代码」时才在这加一行。
+
+## 4. 当改什么 / 怎么改
+
+| 场景 | 改动位置 | 例子 |
+|---|---|---|
+| 新增一个细分维度 | dimensions.json 加 `"中文名": "代码"` | `"播放来源": "PLAYBACK_SOURCE_TYPE"` |
+| 新增一个指标 | metrics.json 加 `"中文名": "代码"` | `"新增指标": "SOME_NEW_METRIC"` |
+| 给指标加中文同义词/英文别名 | metrics.json 加 `"别名": "同一代码"` | `"税前收益": "TOTAL_ESTIMATED_EARNINGS"` |
+| 给维度加别名 | dimensions.json 加 `"别名": "同一代码"` | `"地区": "COUNTRY"` |
+| 新增中文国家名 | countries.json 加 `"中文名": "XX"` | `"瑞典": "SE"` |
+| 调整默认主指标/维度/粒度 | 改 `build_studio_urls.py` 顶部 `CONFIG`（**不是 JSON 文件**） | `CONFIG["metric"] = "..."` |
+
+## 5. 从 Excel 重新同步（可选脚本）
+
+当 `assets/YouTube_Studio_细分维度_时间颗粒度_完整清单.xlsx` 更新后，可用以下片段把「数据指标」「细分维度」两张表重新导出为 JSON，再合并回文件（别名条目需要手工保留）：
+
+```python
+import openpyxl, json
+
+xlsx = r"assets/YouTube_Studio_细分维度_时间颗粒度_完整清单.xlsx"
+wb = openpyxl.load_workbook(xlsx, data_only=True)
+
+def dump(sheet_name, name_col, code_col):
+    ws = wb[sheet_name]
+    rows = list(ws.iter_rows(values_only=True))
+    header = rows[0]
+    ni, ci = header.index(name_col), header.index(code_col)
+    return {str(r[ni]).strip(): str(r[ci]).strip().upper()
+            for r in rows[1:] if r[ni] and r[ci]}
+
+metrics = dump("数据指标", "中文名称（显示名）", "URL 参数值（t_metrics=/metric=）")
+dims = dump("细分维度", "中文名称（显示名）", "URL 参数值（dimension=）")
+
+json.dump(metrics, open("skills/yt-studio-url-builder/scripts/metrics.json", "w", encoding="utf-8"),
+          ensure_ascii=False, indent=2)
+json.dump(dims, open("skills/yt-studio-url-builder/scripts/dimensions.json", "w", encoding="utf-8"),
+          ensure_ascii=False, indent=2)
+```
+
+> 该片段生成的是「标准条目全量覆盖」，会**丢失**你在 metrics.json 里追加的别名；建议先备份，再把别名手工合并回去。
+
+## 6. 更新后的校验
+
+改完任一 JSON，按下面顺序自检：
+
+1. **JSON 语法有效**：
+   ```bash
+   uv run python -m json.tool scripts\metrics.json > $null
+   uv run python -m json.tool scripts\dimensions.json > $null
+   uv run python -m json.tool scripts\countries.json > $null
+   ```
+2. **键非空、值非空**：加载函数已过滤空键值，但建议源文件里就不要出现空串。
+3. **值大写**：脚本会 `upper()`，但提交前统一大写更清晰；国家值必须是两位字母。
+4. **无重复键**：JSON 标准允许重复键但后者覆盖，属于隐性错误；手改时避免。
+5. **跑一条真实需求验证**：造一行含新中文名/新代码的输入，确认输出 CSV 的「指标代码/维度代码/国家代码」解析正确、URL 里 `metric`/`dimension`/`ur_values` 正确。
+6. **回归测试**：
+   ```bash
+   uv run python -m pytest tests/test_build_studio_urls.py tests/test_build_studio_urls_cli.py -q
+   ```
+
+## 7. 常见坑
+
+- **文件缺失**：三个文件单个缺失只会降级（stderr 提示），名称/代码透传受限；务必恢复同目录下的文件，不要依赖降级路径长期运行。
+- **以为改 JSON 能改默认值**：默认主指标/维度/粒度在 `build_studio_urls.py` 的 `CONFIG`，不在 JSON。JSON 只提供「可按行选择」的名称→代码映射。
+- **`t_metrics` 不在 metrics.json 里**：表格列指标集合是 `CONFIG["t_metrics"]` 固定数组，加指标时若想让其进入表格列，需同时在 `CONFIG["t_metrics"]` 追加（否则只影响 `metric`/`o_column`）。
+- **国家值写三位或带空格**：透传按 `[A-Z]{2}` 匹配，非两位值不会命中透传分支，中文名若也查不到就会报「未识别的国家」。
+- **别名覆盖了标准名**：手动追加别名时不要与现有键重复，否则后者覆盖，标准名会失效。
--- a/skills/yt-studio-url-builder/references/troubleshooting.md
+++ b/skills/yt-studio-url-builder/references/troubleshooting.md
@@ -46,6 +46,14 @@
 - 原因：`entity_type` 不在映射表。
 - 解决：使用 群组/所有者/频道/节目 或 GROUP/CONTENT_OWNER/CHANNEL/VIDEO。

+### 未识别的指标
+- 原因：`指标` 列的值不在 `metrics.json` 映射里，也不是已知指标代码。
+- 解决：改用 `metrics.json` 中的中文/英文名或已知指标代码（如 `SUBSCRIBERS_NET_CHANGE`），或向 `scripts/metrics.json` 追加映射；留空该列则走 `CONFIG` 默认。
+
+### 未识别的维度
+- 原因：`维度` 列的值不在 `dimensions.json` 映射里，也不是已知维度代码。
+- 解决：改用 `dimensions.json` 中的中文名或已知维度代码（如 `VIDEO`），或向 `scripts/dimensions.json` 追加映射；留空该列则走 `CONFIG` 默认。
+
 ## 输出问题

 ### 输出行数 < 输入行数
@@ -67,5 +75,5 @@

 ## 改了固定参数不生效

- 原因：固定参数集中在脚本顶部 `CONFIG`，改后需重跑脚本才会生效。
- 提示：改 `CONFIG` 只影响 URL 参数，不需要改需求清单。
+- 原因：粒度、维度、`t_metrics` 等固定参数集中在脚本顶部 `CONFIG`，改后需重跑脚本才会生效。
+- 提示：改 `CONFIG` 只影响 URL 参数，不需要改需求清单；若想按行选主指标，改用需求清单的 `指标` 列（无需改 `CONFIG`）。
--- a/skills/yt-studio-url-builder/scripts/build_studio_urls.py
+++ b/skills/yt-studio-url-builder/scripts/build_studio_urls.py
@@ -15,12 +15,18 @@
    实体类型   : 实体类型 / 类型 / entity_type   (群组/所有者/频道/节目，或 GROUP/CONTENT_OWNER/CHANNEL/VIDEO)
    数据周期   : 数据周期 / 周期 / period / time_period   (yyyy.mm.dd-yyyy.mm.dd 或 yyyy.m.d-yyyy.m.d)
    国家       : 国家 / 国家/地区 / country / countries   (一个或多个，中文名或 ISO 两位代码)
+    指标       : 指标 / 主指标 / 数据指标 / metric   (可留空，则用 CONFIG 默认；中文名或指标代码)
+    维度       : 维度 / 细分维度 / dimension   (可留空，则用 CONFIG 默认；中文名或维度代码)

 说明:
    - 数据周期起止日期均包含在数据范围内，time_period 结束值取结束日后一天的日界线。
    - 国家为多个时，ur_values 以 '%27' 包裹、'%7C' 连接（如 美国,日本 -> %27US%27%7C%27JP%27）。
    - 中文国家名 -> ISO 代码的映射放在同目录 countries.json（可自行扩充）；已是两位代码的原样透传。
-    - 固定参数（metric/granularity/dimension/t_metrics 等）在本文件 CONFIG 中统一配置。
+    - 指标每行可选（metric 参数，中文名 -> 代码的映射放在同目录 metrics.json，可自行扩充；
+      已是已知指标代码的原样透传）。留空则用 CONFIG 默认，且只影响 metric / o_column。
+    - 维度每行可选（dimension 参数，中文名 -> 代码的映射放在同目录 dimensions.json，可自行扩充；
+      已是已知维度代码的原样透传）。留空则用 CONFIG 默认。
+    - 其余固定参数（granularity/t_metrics 等）在本文件 CONFIG 中统一配置。
 """

 import argparse
@@ -55,6 +61,11 @@ CONFIG = {
    "comparison_type": "NONE",
 }

+# 常用指标代码集合（供指标代码透传；metrics.json 提供中文/英文别名映射）
+KNOWN_METRICS = {CONFIG["metric"], CONFIG["o_column"], *CONFIG["t_metrics"]}
+# 常见维度代码（供维度代码透传；dimensions.json 提供中文别名映射）
+KNOWN_DIMENSIONS = {CONFIG["dimension"]}
+
 # 实体类型 中文/代码 -> URL 参数值（可扩充）
 ENTITY_TYPE_MAP = {
    "群组": "GROUP", "GROUP": "GROUP",
@@ -95,6 +106,12 @@ COLUMN_ALIASES = {
    # 国家
    "国家": "countries", "国家/地区": "countries", "国家地区": "countries",
    "countries": "countries", "country": "countries", "筛选国家": "countries", "地区": "countries",
+    # 指标（每行可选；缺省用 CONFIG）
+    "指标": "metric", "主指标": "metric", "主要指标": "metric", "数据指标": "metric",
+    "metric": "metric", "metric_name": "metric", "metricname": "metric", "指标名": "metric",
+    # 维度（每行可选；缺省用 CONFIG）
+    "维度": "dimension", "细分维度": "dimension", "dimension": "dimension",
+    "dim": "dimension", "细分": "dimension", "维度名": "dimension",
 }


@@ -160,6 +177,66 @@ def parse_countries(text, country_map):
    return codes


+def load_metric_map(path):
+    """加载 指标中文/英文名 -> 指标代码 映射。文件缺失则仅支持已知指标代码透传。"""
+    if not os.path.exists(path):
+        print("[提示] 未找到指标映射文件 %s，仅支持直接填写指标代码" % path, file=sys.stderr)
+        return {}
+    with open(path, "r", encoding="utf-8-sig") as f:
+        data = json.load(f)
+    mapped = {str(k).strip(): str(v).strip().upper() for k, v in data.items()
+              if str(k).strip() and str(v).strip()}
+    # 允许映射中出现的所有指标代码原样透传（大小写不敏感）
+    for code in set(mapped.values()) | KNOWN_METRICS:
+        mapped.setdefault(code.lower(), code)
+    return mapped
+
+
+def parse_metric(text, metric_map):
+    """指标列 -> 指标代码。空则返回 None（走 CONFIG 默认）；具体代码透传；未知则报错。"""
+    if text is None or (isinstance(text, float) and str(text) == "nan"):
+        return None
+    raw = str(text).strip().strip("'\"").strip()
+    if not raw:
+        return None
+    if raw.upper() in KNOWN_METRICS:          # 已是已知指标代码
+        return raw.upper()
+    key = raw.lower()
+    if key in metric_map:                     # 中文/英文别名
+        return metric_map[key]
+    raise ValueError("未识别的指标: %r（不在映射文件中，也不是已知指标代码）" % raw)
+
+
+def load_dimension_map(path):
+    """加载 细分维度中文名 -> 代码 映射。文件缺失则仅支持已知维度代码透传。"""
+    if not os.path.exists(path):
+        print("[提示] 未找到维度映射文件 %s，仅支持直接填写维度代码" % path, file=sys.stderr)
+        return {}
+    with open(path, "r", encoding="utf-8-sig") as f:
+        data = json.load(f)
+    mapped = {str(k).strip(): str(v).strip().upper() for k, v in data.items()
+              if str(k).strip() and str(v).strip()}
+    # 允许映射中出现的所有维度代码原样透传（大小写不敏感）
+    for code in set(mapped.values()) | KNOWN_DIMENSIONS:
+        mapped.setdefault(code.lower(), code)
+    return mapped
+
+
+def parse_dimension(text, dimension_map):
+    """维度列 -> 维度代码。空则返回 None（走 CONFIG 默认）；具体代码透传；未知则报错。"""
+    if text is None or (isinstance(text, float) and str(text) == "nan"):
+        return None
+    raw = str(text).strip().strip("'\"").strip()
+    if not raw:
+        return None
+    if raw.upper() in KNOWN_DIMENSIONS:       # 已是已知维度代码
+        return raw.upper()
+    key = raw.lower()
+    if key in dimension_map:                  # 中文别名
+        return dimension_map[key]
+    raise ValueError("未识别的维度: %r（不在映射文件中，也不是已知维度代码）" % raw)
+
+
 def resolve_entity_type(text):
    """实体类型 -> URL 参数值。空则用默认群组。"""
    if text is None or (isinstance(text, float) and str(text) == "nan") or str(text).strip() == "":
@@ -170,8 +247,11 @@ def resolve_entity_type(text):
    raise ValueError("未识别的实体类型: %r（应为 群组/所有者/频道/节目 或 GROUP/CONTENT_OWNER/CHANNEL/VIDEO）" % key)


-def build_url(row, country_map):
-    """根据一行需求生成 URL。返回 (url, 状态, 错误信息)。"""
+def build_url(row, country_map, metric_map=None, dimension_map=None):
+    """根据一行需求生成 URL。返回 (url, 状态, 错误信息)。
+
+    metric_map / dimension_map 为 名 -> 代码 映射；对应列缺省时回退到 CONFIG 默认。
+    """
    owner_id = row.get("owner_id", "").strip()
    entity_type = resolve_entity_type(row.get("entity_type", ""))
    entity_id = row.get("entity_id", "").strip()
@@ -191,6 +271,15 @@ def build_url(row, country_map):

    codes = parse_countries(row.get("countries", ""), country_map)

+    # 指标：每行可选；空 -> 主指标/排序字段用 CONFIG 默认；非空 -> 二者都跟随所选指标
+    sel_metric = parse_metric(row.get("metric", ""), metric_map or {})
+    metric = sel_metric or CONFIG["metric"]
+    o_column = sel_metric or CONFIG["o_column"]
+
+    # 维度：每行可选；空 -> 用 CONFIG 默认细分维度
+    sel_dimension = parse_dimension(row.get("dimension", ""), dimension_map or {})
+    dimension = sel_dimension or CONFIG["dimension"]
+
    base = "https://studio.youtube.com/owner/%s/analytics/tab-overview/period-default/explore" % owner_id
    params = []
    params.append("o=%s" % owner_id)
@@ -204,12 +293,12 @@ def build_url(row, country_map):
        params.append("ur_exclusive_ends=")
    params.append("time_period=%d%%2C%d" % (start_ms, end_ms))
    params.append("explore_type=%s" % CONFIG["explore_type"])
-    params.append("metric=%s" % CONFIG["metric"])
+    params.append("metric=%s" % metric)
    params.append("granularity=%s" % CONFIG["granularity"])
    for m in CONFIG["t_metrics"]:
        params.append("t_metrics=%s" % m)
-    params.append("dimension=%s" % CONFIG["dimension"])
-    params.append("o_column=%s" % CONFIG["o_column"])
+    params.append("dimension=%s" % dimension)
+    params.append("o_column=%s" % o_column)
    params.append("o_direction=%s" % CONFIG["o_direction"])
    params.append("comparison_type=%s" % CONFIG["comparison_type"])

@@ -222,6 +311,8 @@ def main():
    parser.add_argument("-i", "--input", required=True, help="需求清单文件（.csv / .xlsx / .xls）")
    parser.add_argument("-o", "--output", default=None, help="输出 CSV 路径（默认：输入同目录 studio_urls_output.csv）")
    parser.add_argument("--countries", default=None, help="国家映射 JSON 路径（默认：脚本同目录 countries.json）")
+    parser.add_argument("--metrics", default=None, help="指标映射 JSON 路径（默认：脚本同目录 metrics.json）")
+    parser.add_argument("--dimensions", default=None, help="维度映射 JSON 路径（默认：脚本同目录 dimensions.json）")
    args = parser.parse_args()

    if not os.path.exists(args.input):
@@ -252,18 +343,26 @@ def main():

    countries_file = args.countries or os.path.join(os.path.dirname(os.path.abspath(__file__)), "countries.json")
    country_map = load_country_map(countries_file)
+    metrics_file = args.metrics or os.path.join(os.path.dirname(os.path.abspath(__file__)), "metrics.json")
+    metric_map = load_metric_map(metrics_file)
+    dimensions_file = args.dimensions or os.path.join(os.path.dirname(os.path.abspath(__file__)), "dimensions.json")
+    dimension_map = load_dimension_map(dimensions_file)

    records = []
    errors = []
    for idx, raw in df.iterrows():
        row = {f: ("" if pd.isna(raw[mapping[f]]) else str(raw[mapping[f]])) for f in mapping}
        try:
-            url, status, msg = build_url(row, country_map)
+            url, status, msg = build_url(row, country_map, metric_map, dimension_map)
        except ValueError as e:
            url, status, msg = None, "error", str(e)
        if status == "ok":
            start_ms, end_ms = parse_period(row.get("period", ""))
            codes = parse_countries(row.get("countries", ""), country_map)
+            sel_metric = parse_metric(row.get("metric", ""), metric_map)
+            metric_code = sel_metric or CONFIG["metric"]
+            sel_dimension = parse_dimension(row.get("dimension", ""), dimension_map)
+            dimension_code = sel_dimension or CONFIG["dimension"]
            records.append({
                "所有者名称": row.get("owner_name", ""),
                "所有者ID": row.get("owner_id", ""),
@@ -273,6 +372,10 @@ def main():
                "数据周期": row.get("period", ""),
                "国家": row.get("countries", ""),
                "国家代码": ",".join(codes),
+                "指标": row.get("metric", ""),
+                "指标代码": metric_code,
+                "维度": row.get("dimension", ""),
+                "维度代码": dimension_code,
                "开始时间戳": start_ms,
                "结束时间戳": end_ms,
                "URL": url,
--- a/skills/yt-studio-url-builder/scripts/dimensions.json
+++ b/skills/yt-studio-url-builder/scripts/dimensions.json
@@ -0,0 +1,35 @@
+{
+  "内容": "VIDEO",
+  "流量来源": "TRAFFIC_SOURCE_TYPE",
+  "地理位置": "COUNTRY",
+  "频道": "USER",
+  "资产": "ASSET",
+  "频道所有权": "UPLOADER_TYPE",
+  "版权声明状态": "CLAIMED_STATUS",
+  "内容类型": "CREATOR_CONTENT_TYPE",
+  "播放列表": "PLAYLIST",
+  "观看者年龄": "VIEWER_AGE",
+  "观看者性别": "VIEWER_GENDER",
+  "新观看者和回访观看者": "LOYALTY_STATE",
+  "按观看行为细分的观众群": "AUDIENCE_LOYALTY_SEGMENT",
+  "订阅状态": "SUBSCRIBED_TO_UPLOADER_STATE",
+  "订阅来源": "SUBSCRIPTION_SOURCE_TYPE",
+  "YouTube 产品": "PLAYER_APP_TYPE",
+  "设备类型": "DEVICE_PLATFORM_TYPE",
+  "操作系统": "DEVICE_OS_TYPE",
+  "收入来源": "EARNINGS_SOURCE_ALL",
+  "广告类型": "ADTYPES",
+  "交易类型": "TRANSACTION_BUSINESS_MODEL",
+  "自然流量和付费流量": "AD_STATUS",
+  "日期": "DAY",
+  "字幕": "CAPTION_LANGUAGE",
+  "视频信息语言": "VIDEO_METADATA_LANGUAGE",
+  "是否使用翻译": "IS_CROSS_LANGUAGE",
+  "片尾画面元素": "ENDSCREEN_ELEMENT_ID",
+  "片尾画面元素类型": "ENDSCREEN_ELEMENT_TYPE",
+  "卡片": "INFO_CARD_ID",
+  "卡片类型": "INFO_CARD_TYPE",
+  "播放位置": "PLAYBACK_LOCATION_TYPE",
+  "播放器类型": "EMBEDDED_PLAYER_MODE",
+  "分享服务": "SHARING_SERVICE"
+}
--- a/skills/yt-studio-url-builder/scripts/metrics.json
+++ b/skills/yt-studio-url-builder/scripts/metrics.json
@@ -0,0 +1,86 @@
+{
+  "观看次数": "EXTERNAL_VIEWS",
+  "感兴趣的观看次数": "ENGAGED_VIEWS",
+  "观看时长（小时）": "EXTERNAL_WATCH_TIME",
+  "订阅人数": "SUBSCRIBERS_NET_CHANGE",
+  "平均观看时长": "AVERAGE_WATCH_TIME",
+  "平均观看百分比": "AVERAGE_WATCH_PERCENTAGE",
+  "添加的视频数": "VIDEO_COUNT_NEW",
+  "发布的视频数": "VIDEO_COUNT_FIRST_PUBLISHED",
+  "展示次数": "VIDEO_THUMBNAIL_IMPRESSIONS",
+  "展示点击率": "VIDEO_THUMBNAIL_IMPRESSIONS_VTR",
+  "继续观看": "SHORTS_FEED_IMPRESSIONS_VTR",
+  "唯一身份观看者人数": "ESTIMATED_UNIQUE_VIEWERS",
+  "人均观看次数": "AVERAGE_VIEWS_PER_VIEWER",
+  "获得的订阅人数": "SUBSCRIBERS_GAINED",
+  "流失的订阅人数": "SUBSCRIBERS_LOST",
+  "赞": "RATINGS_LIKES",
+  "不喜欢": "RATINGS_DISLIKES",
+  "赞和不喜欢的比率": "LIKES_PER_LIKES_PLUS_DISLIKES_PERCENT",
+  "分享数": "SHARINGS",
+  "添加的评论数": "COMMENTS",
+  "估算的合作伙伴收入": "TOTAL_ESTIMATED_EARNINGS",
+  "合作伙伴的交易收入": "TRANSACTION_EARNINGS_ALL",
+  "交易次数": "TRANSACTION_COUNT",
+  "合作伙伴的每笔交易收入": "AVERAGE_TRANSACTION_AMOUNT",
+  "YouTube Premium 合作伙伴收入": "SUBSCRIPTION_EARNINGS",
+  "估算的合作伙伴广告收入": "AD_EARNINGS",
+  "估算的合作伙伴 DoubleClick 收入": "YOUTUBE_EARNINGS",
+  "估算的合作伙伴 AdSense 收入": "AFV_EARNINGS",
+  "YouTube 广告收入": "AD_GROSS_REVENUE",
+  "广告展示次数": "IMPRESSIONS",
+  "基于播放的每千次展示费用": "CPM",
+  "每千次展示费用": "IMPRESSIONS_CPM",
+  "估算的获利播放次数": "PLAYBACKS",
+  "每千次展示收入 (RPM)": "EPM",
+  "YouTube Premium 观看次数": "EXTERNAL_YOUTUBE_RED_VIEWS",
+  "YouTube Premium 观看时长（小时）": "EXTERNAL_YOUTUBE_RED_WATCH_TIME",
+  "播放列表观看时长（小时）": "PLAYLIST_WATCH_TIME_HOURS",
+  "播放列表观看次数": "PLAYLIST_VIEWS",
+  "播放列表平均观看时长": "PLAYLIST_AVERAGE_WATCH_TIME",
+  "播放列表平均观看百分比": "PLAYLIST_AVERAGE_WATCH_PERCENTAGE",
+  "播放列表开始播放的次数": "PLAYLIST_STARTS",
+  "播放列表退出次数": "PLAYLIST_EXITS",
+  "播放列表退出率": "PLAYLIST_EXIT_RATE",
+  "播放列表的平均观看时长": "PLAYLIST_AVERAGE_START_DURATION",
+  "播放列表每次开始播放产生的观看次数": "PLAYLIST_AVERAGE_VIEWS_PER_START",
+  "播放列表保存次数": "PLAYLIST_SAVES_NET_CHANGE",
+  "社区剪辑片段观看次数": "CLIP_VIEWS",
+  "社区剪辑片段带来的观看时长（小时）": "CLIP_VIDEO_WATCHTIME",
+  "卡片点击次数": "INFO_CARD_CLICKS",
+  "卡片展示次数": "INFO_CARD_IMPRESSIONS",
+  "卡片每次展示所获得的点击次数": "INFO_CARD_CLICK_RATE",
+  "卡片宣传语点击次数": "INFO_CARD_TEASER_CLICKS",
+  "卡片宣传语展示次数": "INFO_CARD_TEASER_IMPRESSIONS",
+  "卡片宣传语每次展示所获得的点击次数": "INFO_CARD_TEASER_CLICK_RATE",
+  "片尾画面元素点击次数": "ENDSCREEN_ELEMENT_CLICKS",
+  "片尾画面元素展示次数": "ENDSCREEN_ELEMENT_IMPRESSIONS",
+  "片尾画面元素每次展示所获得的点击次数": "ENDSCREEN_ELEMENT_CLICK_RATE",
+  "税前收益": "TOTAL_ESTIMATED_EARNINGS",
+  "税前收入": "TOTAL_ESTIMATED_EARNINGS",
+  "预计收益": "TOTAL_ESTIMATED_EARNINGS",
+  "订阅净增长": "SUBSCRIBERS_NET_CHANGE",
+  "订阅净变化": "SUBSCRIBERS_NET_CHANGE",
+  "净订阅": "SUBSCRIBERS_NET_CHANGE",
+  "订阅变化": "SUBSCRIBERS_NET_CHANGE",
+  "视频发布数": "VIDEO_COUNT_FIRST_PUBLISHED",
+  "发布视频数": "VIDEO_COUNT_FIRST_PUBLISHED",
+  "互动观看": "ENGAGED_VIEWS",
+  "互动观看时长": "ENGAGED_VIEWS",
+  "参与观看": "ENGAGED_VIEWS",
+  "外部观看次数": "EXTERNAL_VIEWS",
+  "外部观看时长": "EXTERNAL_WATCH_TIME",
+  "观看时长": "EXTERNAL_WATCH_TIME",
+  "收益": "TOTAL_ESTIMATED_EARNINGS",
+  "收入": "TOTAL_ESTIMATED_EARNINGS",
+  "estimated_earnings": "TOTAL_ESTIMATED_EARNINGS",
+  "earnings": "TOTAL_ESTIMATED_EARNINGS",
+  "subscribers_net_change": "SUBSCRIBERS_NET_CHANGE",
+  "net_change": "SUBSCRIBERS_NET_CHANGE",
+  "video_count_first_published": "VIDEO_COUNT_FIRST_PUBLISHED",
+  "engaged_views": "ENGAGED_VIEWS",
+  "external_views": "EXTERNAL_VIEWS",
+  "external_watch_time": "EXTERNAL_WATCH_TIME",
+  "average_watch_time": "AVERAGE_WATCH_TIME",
+  "total_estimated_earnings": "TOTAL_ESTIMATED_EARNINGS"
+}