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

为 build_studio_urls.py 添加指标和维度的可配置支持，包括：
- 新增 metrics.json 和 dimensions.json 映射文件加载
- 支持中文/英文别名映射及指标代码透传
- 列别名扩展以识别"指标"和"维度"列
- 空值时自动回退到 CONFIG 默认值

README.md

@@ -102,12 +102,34 @@ uv 自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright
 
 ### 改 URL 固定参数
 
-指标、粒度、维度、排序等固定参数集中在 `skills/yt-studio-url-builder/scripts/build_studio_urls.py` 顶部的 `CONFIG` 字典中，**单点维护**——改完重跑脚本即生效，需求清单无需变动。
+粒度、表格列指标等固定参数集中在 `skills/yt-studio-url-builder/scripts/build_studio_urls.py` 顶部的 `CONFIG` 字典中，**单点维护**——改完重跑脚本即生效，需求清单无需变动。
+
+主指标 `metric`、细分维度 `dimension` 可**按行选择**：在需求清单加一列 `指标`（映射见同目录 `metrics.json` 或填已知指标代码）、一列 `维度`（映射见同目录 `dimensions.json` 或填已知维度代码），留空则走 `CONFIG` 默认。
 
 ### 扩充国家映射
 
 中文国家名 → ISO 代码的映射在 `skills/yt-studio-url-builder/scripts/countries.json`，直接追加条目即可；映射外的两位 ISO 代码（如 `US`）会原样透传。
 
+### 维护映射文件（指标 / 维度 / 国家）
+
+`skills/yt-studio-url-builder/scripts/` 下有三个映射文件，把「中文/英文名」翻译成「URL 内部代码」，均可自行扩充：
+
+| 文件 | 作用 | 新增示例 |
+|---|---|---|
+| `metrics.json` | 指标名 → 指标代码（如 `观看时长` → `EXTERNAL_WATCH_TIME`） | `"新指标名": "SOME_METRIC"` |
+| `dimensions.json` | 细分维度名 → 维度代码（如 `地理位置` → `COUNTRY`） | `"新维度名": "SOME_DIMENSION"` |
+| `countries.json` | 中文国家名 → ISO 两位代码（如 `美国` → `US`） | `"新国名": "XX"` |
+
+方法和规则：
+
+- 都是扁平 `key -> value` 的 JSON 对象，UTF-8 编码；键为人类可读名、值为大写代码。
+- **同一代码可有多个别名**（多对一），例如 `metrics.json` 里 `税前收益` / `税前收入` / `预计收益` 都指向 `TOTAL_ESTIMATED_EARNINGS`。
+- 新增一个指标/维度后，其代码会被脚本自动加入「可透传集合」，可直接在需求清单里填裸代码，无需改 `build_studio_urls.py`。
+- **默认主指标/维度/粒度不在这些 JSON 里**，而在 `build_studio_urls.py` 顶部的 `CONFIG`（见上文「改 URL 固定参数」）。
+- `dimensions.json`、`metrics.json` 的基准数据源是 `assets/YouTube_Studio_细分维度_时间颗粒度_完整清单.xlsx`（「细分维度」「数据指标」两张表）；`countries.json` 基于 ISO 3166-1 标准手工维护。
+
+完整说明（加载方式、从 Excel 重新同步的脚本片段、更新后校验清单与常见坑）见 [skills/yt-studio-url-builder/references/maintenance-guide.md](skills/yt-studio-url-builder/references/maintenance-guide.md)。
+
 ### 新增/修改依赖
 
 只改根目录 `pyproject.toml` 的 `dependencies`，然后 `uv sync` 更新 `uv.lock`。不要 `pip install` 直装（绕过 lock，环境不可复现）。
@@ -138,4 +160,4 @@ uv 自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright
 
 -----
 
-UPDATE: 2026-08-21
+UPDATE: 2026-08-24