SidneyZhang/StudioLift
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
05b2fc8d656356d63c1f5e40e37cecb9e790e805
StudioLift/README.md

11 KiB
Raw Blame History

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 或 ZCode（技能装到对应用户级目录）
  • 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。

默认安装全部技能。需要只装部分、指定目标或先预览时，可在命令行加参数（bat 与 ps1 都支持）：

# 装到 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。

新增/修改依赖

新增依赖用 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