183 lines
11 KiB
Markdown
183 lines
11 KiB
Markdown
# YouTube Studio 工具集
|
||
|
||
本项目包含五个技能（skills）及配套 Python 脚本，覆盖 YouTube Studio 内容管理器（Content Manager）分析的完整工作流：**工作区准备 → 登录态与鉴权套件预置（每工作区一次） → 群组名解析实体 ID → 批量生成报告 URL → 脚本化下载分析数据**。
|
||
|
||
仅支持 Windows。
|
||
|
||
## 技能清单
|
||
|
||
| 技能 | 用途 | 触发示例 |
|
||
|---|---|---|
|
||
| `yt-download-place` | 在当前目录或指定路径创建 uv 项目工作区（`uv add` 装齐 pandas/openpyxl/playwright/requests → `uv run`），承载各技能脚本的运行环境 | 「准备工作区」「建下载目录」 |
|
||
| `yt-studio-auth-prep` | 在工作区预置登录态与鉴权套件：创建调试用户目录 `.profile` 并完成 YouTube 登录，捕获内容所有者套件 `bundles.json` | 「准备工作区登录」「捕获/更新 bundles.json」 |
|
||
| `yt-studio-groupid-lookup` | 把一批群组名批量解析为 entity_id（groupId），并标注归属的内容所有者（可用 `bundles.json` 离线回放） | 「把这些群组名查成 Group ID」 |
|
||
| `yt-studio-url-builder` | 根据需求清单（CSV/Excel）批量拼接 explore 报告 URL | 「根据这份清单生成 Studio URL」 |
|
||
| `youtube-studio-csv-download` | 复用已登录浏览器会话（`.profile`），脚本化下载分析 CSV（zip） | 「用我的 Chrome 会话下载这份 CSV」 |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── skills/ # 技能源目录（安装脚本从这里复制）
|
||
│ ├── yt-download-place/ # 下载工作区技能（创建 uv 项目结构）
|
||
│ │ ├── SKILL.md
|
||
│ │ └── references/troubleshooting.md
|
||
│ ├── yt-studio-auth-prep/ # 登录态与套件预置技能（.profile + bundles.json）
|
||
│ │ ├── SKILL.md
|
||
│ │ ├── references/troubleshooting.md
|
||
│ │ └── scripts/login_profile.py
|
||
│ ├── yt-studio-url-builder/ # URL 拼接技能
|
||
│ │ ├── SKILL.md
|
||
│ │ ├── references/ # input-guide.md（输入清单指南）、troubleshooting.md
|
||
│ │ └── scripts/ # build_studio_urls.py、countries.json
|
||
│ ├── youtube-studio-csv-download/ # CSV 下载技能
|
||
│ │ ├── SKILL.md
|
||
│ │ ├── references/troubleshooting.md
|
||
│ │ └── scripts/youtube_export_download.py
|
||
│ └── yt-studio-groupid-lookup/ # 群组名->entity_id 解析技能
|
||
│ ├── SKILL.md
|
||
│ ├── references/ # input-guide.md（名单/套件指南）、troubleshooting.md
|
||
│ └── scripts/lookup_groups.py
|
||
├── scripts/
|
||
│ ├── install-skills.bat # 傻瓜安装入口（双击运行）
|
||
│ └── install-skills.ps1 # 安装逻辑
|
||
├── docs/
|
||
│ ├── install-skills.md # 安装详细说明
|
||
│ └── adr/ # 架构决策记录
|
||
├── assets/ # 需求输入示例文件
|
||
├── pyproject.toml # Python 依赖唯一事实来源（pandas/openpyxl/playwright/requests）
|
||
└── uv.lock # uv 依赖锁定（可复现环境）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 前置条件
|
||
|
||
- Windows
|
||
- agent 之一：[Trae CN](https://www.trae.cn/) 或 [ZCode](https://github.com/ZhipuAI)（技能装到对应用户级目录）
|
||
- [uv](https://docs.astral.sh/uv/) 已安装（未装可 `winget install astral-sh.uv`，装完重开终端；当前会话不识别时先跑 `python -m uv`，详见 yt-download-place 技能）
|
||
|
||
### 第 1 步：安装技能
|
||
|
||
双击运行（默认装到 Trae CN）：
|
||
|
||
```
|
||
scripts\install-skills.bat
|
||
```
|
||
|
||
或用 `-Agent` 指定目标：`trae-cn`（默认）/ `zcode` / `all`（全部目标）。脚本会把 `skills\` 下全部技能复制到对应用户级目录（trae-cn: `%USERPROFILE%\.trae-cn\skills\`；zcode: `%USERPROFILE%\.zcode\skills\`）；同名旧版自动备份到该目录旁的 `skills-backup\`，不会丢数据。详细说明见 [docs/install-skills.md](docs/install-skills.md)。
|
||
|
||
**默认安装全部技能**。需要只装部分、指定目标或先预览时，可在命令行加参数（bat 与 ps1 都支持）：
|
||
|
||
```powershell
|
||
# 装到 ZCode
|
||
scripts\install-skills.bat -Agent zcode
|
||
# 全部目标只安装指定的几个技能
|
||
scripts\install-skills.bat -Agent all -Skills yt-studio-url-builder,youtube-studio-csv-download
|
||
# 只预览将安装/覆盖/备份的技能，不实际复制
|
||
scripts\install-skills.bat -DryRun
|
||
```
|
||
|
||
### 第 2 步：准备工作区
|
||
|
||
用 `yt-download-place` 技能在项目根或任意指定目录创建 uv 项目工作区（细节与回退链见 `skills/yt-download-place/SKILL.md`）：
|
||
|
||
- **项目环境**（在工作区内跑整套流程）：技能建好 `pyproject.toml` + `assets/` + `data/` + `.gitignore` 后执行 `uv add pandas openpyxl playwright requests`，生成 `.venv\` 与 `uv.lock`，之后统一 `uv run python <脚本>`。`uv add` 幂等，复用已有 pyproject 的工作区只补缺失包；本机无兼容 Python 时 uv 会自动下载托管 Python（要求 ≥3.10）。
|
||
- **单脚本模式**（技能已装到用户级目录、脱离工作区使用）：什么都不用配——脚本头部带 PEP 723 内联依赖声明，直接 `uv run <脚本路径>` 即可。
|
||
|
||
### 第 3 步：预置登录态与套件（每个工作区一次）
|
||
|
||
用 `yt-studio-auth-prep` 技能在工作区备好两项环境级产物（细节见 `skills/yt-studio-auth-prep/SKILL.md`），之后的查 ID、生成 URL、下载数据全部复用：
|
||
|
||
- **调试用户目录 `.profile`**：在工作区创建 `<place>/.profile`，打开浏览器完成一次 YouTube 账号登录，供 csv-download、groupid-lookup 复用登录态；浏览器品牌（chrome/msedge）一经选定全工作区统一。
|
||
- **鉴权套件 `bundles.json`**：提供内容所有者分析页 URL（可多个），在线捕获鉴权套件存到 `<place>/bundles.json`，供 groupid-lookup 离线回放（无需再开浏览器）。
|
||
|
||
日常使用无需重复本步；仅当登录态失效（下游跳 Google 登录页）或套件过期（回放全量 401）时，重跑对应步骤刷新。
|
||
|
||
### 第 4 步：开始使用
|
||
|
||
重启对应 agent（或新建会话）后，在对话中直接说需求即可触发对应技能，例如：
|
||
|
||
> 帮我准备工作区/重建环境
|
||
|
||
技能会在当前或指定目录创建 uv 工作区并完成验证（项目环境 / 单脚本模式二选一）。
|
||
|
||
> 帮我准备这个工作区的 YouTube 登录目录和所有者套件
|
||
|
||
技能会创建 `.profile` 并引导完成一次 YouTube 登录，再按所有者分析页 URL 捕获套件到 `bundles.json`（即第 3 步，日常无需重复）。
|
||
|
||
> 把这些群组名解析成 entity_id
|
||
|
||
**清单里只有群组名时先走这一步补 ID**；已预置 `bundles.json` 时离线回放，无需浏览器。
|
||
|
||
> 根据这份清单批量生成 Studio URL
|
||
|
||
把需求整理成 CSV/Excel（格式见 `skills/yt-studio-url-builder/references/input-guide.md`，示例见 `assets/需求输入示例.xlsx`），技能会引导生成 URL 清单。
|
||
|
||
> 用我的 Chrome 会话下载这份分析 CSV
|
||
|
||
技能会用 Playwright 复用 `.profile` 登录态（或你指定的浏览器会话），自动点击导出并保存 zip。
|
||
|
||
## 后续优化与修改
|
||
|
||
### 改 URL 固定参数
|
||
|
||
粒度、表格列指标等固定参数集中在 `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)。
|
||
|
||
### 新增/修改依赖
|
||
|
||
新增依赖用 `uv add <包>`（自动更新根目录 `pyproject.toml` 与 `uv.lock`）。不要 `pip install` 直装（绕过 lock，环境不可复现）。
|
||
|
||
### 修改技能并重新安装
|
||
|
||
技能就是在 `skills/` 下编辑的 Markdown + 脚本。改完后重新双击 `scripts\install-skills.bat` 即可同步到 Trae CN（旧版自动备份）。建议遵循的写法：
|
||
|
||
- 每个技能一个文件夹，必须含 `SKILL.md`（frontmatter 的 `name` + `description`，description 写清触发场景）。
|
||
- 大块参考内容放 `references/` 子目录，`SKILL.md` 中按需引用（渐进披露）。
|
||
- 每个步骤给出可检查的完成判据，避免半途而废。
|
||
- 同一信息只在一处维护（单一事实来源），避免重复表述。
|
||
|
||
### 回滚 / 卸载
|
||
|
||
- 回滚：把 `~\.trae-cn\skills-backup\<技能名>-<时间戳>\` 复制回 `~\.trae-cn\skills\<技能名>\`。
|
||
- 卸载：删除 `~\.trae-cn\skills\` 下对应技能文件夹。
|
||
- 重置环境：删除项目根 `.venv\` 后重新 `uv sync`。
|
||
|
||
## 常见问题
|
||
|
||
- **双击 bat 闪退**：在 PowerShell 中手动运行 `scripts\install-skills.bat` 查看报错。
|
||
- **装了技能不触发**：需重启 Trae CN 或新建会话。
|
||
- **`uv sync` 拉包慢**：国内镜像 `$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"` 后重试。
|
||
- **技能脚本报 `ModuleNotFoundError`**：项目根执行 `uv add pandas openpyxl playwright requests` 补齐缺包，或确认命令用了 `uv run` 前缀。
|
||
|
||
更多排查见各技能的 `references/troubleshooting.md`。
|
||
|
||
-----
|
||
|
||
UPDATE: 2026-09-30
|