chore: 更新技能引用名称并新增 yt-studio-auth-prep 登录脚本

2026-09-30 10:22:05 +08:00
parent 9020752eed
commit 05b2fc8d65
19 changed files with 513 additions and 162 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # YouTube Studio 工具集

-本项目包含四个 Trae CN 技能（skills）及配套 Python 脚本，覆盖 YouTube Studio 内容管理器（Content Manager）分析的完整工作流：**环境准备 → 批量生成报告 URL → 群组名解析实体 ID → 脚本化下载分析数据**。
+本项目包含五个技能（skills）及配套 Python 脚本，覆盖 YouTube Studio 内容管理器（Content Manager）分析的完整工作流：**工作区准备 → 登录态与鉴权套件预置（每工作区一次） → 群组名解析实体 ID → 批量生成报告 URL → 脚本化下载分析数据**。

 仅支持 Windows。

@@ -8,18 +8,23 @@

 | 技能 | 用途 | 触发示例 |
 |---|---|---|
-| `uv-env-setup` | 用 uv 准备并维护 Python 运行环境（`pyproject.toml` → `uv sync` → `uv run`） | 「帮我准备环境」「装依赖」 |
+| `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` | 复用已登录浏览器会话，脚本化下载分析 CSV（zip） | 「用我的 Chrome 会话下载这份 CSV」 |
-| `yt-studio-groupid-lookup` | 把一批群组名批量解析为 entity_id（groupId），并标注归属的内容所有者 | 「把这些群组名查成 Group ID」 |
+| `youtube-studio-csv-download` | 复用已登录浏览器会话（`.profile`），脚本化下载分析 CSV（zip） | 「用我的 Chrome 会话下载这份 CSV」 |

 ## 项目结构

 ```
 ├── skills/                        # 技能源目录（安装脚本从这里复制）
-│   ├── uv-env-setup/              #   环境准备技能
+│   ├── 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
@@ -39,7 +44,7 @@
 │   ├── install-skills.md          # 安装详细说明
 │   └── adr/                       # 架构决策记录
 ├── assets/                        # 需求输入示例文件
-├── pyproject.toml                 # Python 依赖唯一事实来源（pandas/openpyxl/playwright）
+├── pyproject.toml                 # Python 依赖唯一事实来源（pandas/openpyxl/playwright/requests）
 └── uv.lock                        # uv 依赖锁定（可复现环境）
 ```

@@ -49,7 +54,7 @@

 - 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`，详见 uv-env-setup 技能）
+- [uv](https://docs.astral.sh/uv/) 已安装（未装可 `winget install astral-sh.uv`，装完重开终端；当前会话不识别时先跑 `python -m uv`，详见 yt-download-place 技能）

 ### 第 1 步：安装技能

@@ -72,28 +77,45 @@ scripts\install-skills.bat -Agent all -Skills yt-studio-url-builder,youtube-stud
 scripts\install-skills.bat -DryRun
 ```

-### 第 2 步：准备 Python 运行环境
+### 第 2 步：准备工作区

-两种模式按场景二选一（细节与回退链见 `skills/uv-env-setup/SKILL.md`）：
+用 `yt-download-place` 技能在项目根或任意指定目录创建 uv 项目工作区（细节与回退链见 `skills/yt-download-place/SKILL.md`）：

- **项目环境**（在项目内跑整套流程）：项目根执行 `uv sync`，之后统一 `uv run python <脚本>`。uv 自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright、requests）；本机无兼容 Python 时 uv 会自动下载托管 Python（要求 ≥3.10）。
- **单脚本模式**（技能已装到用户级目录、脱离项目使用）：什么都不用配——脚本头部带 PEP 723 内联依赖声明，直接 `uv run <脚本路径>` 即可。
+- **项目环境**（在工作区内跑整套流程）：技能建好 `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 步：开始使用
+### 第 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 清单。**清单里只有群组名时，先说「帮我把这些群组名解析成 entity_id」走 groupid-lookup 技能补 ID**，再生成 URL。
+把需求整理成 CSV/Excel（格式见 `skills/yt-studio-url-builder/references/input-guide.md`，示例见 `assets/需求输入示例.xlsx`），技能会引导生成 URL 清单。

 > 用我的 Chrome 会话下载这份分析 CSV

-技能会用 Playwright 复用已登录的浏览器会话，自动点击导出并保存 zip。
-
-> 帮我准备/重建环境
-
-技能会引导选择运行分支（项目环境 / 单脚本模式）并完成验证。
+技能会用 Playwright 复用 `.profile` 登录态（或你指定的浏览器会话），自动点击导出并保存 zip。

 ## 后续优化与修改

@@ -129,7 +151,7 @@ scripts\install-skills.bat -DryRun

 ### 新增/修改依赖

-只改根目录 `pyproject.toml` 的 `dependencies`，然后 `uv sync` 更新 `uv.lock`。不要 `pip install` 直装（绕过 lock，环境不可复现）。
+新增依赖用 `uv add <包>`（自动更新根目录 `pyproject.toml` 与 `uv.lock`）。不要 `pip install` 直装（绕过 lock，环境不可复现）。

 ### 修改技能并重新安装

@@ -151,10 +173,10 @@ scripts\install-skills.bat -DryRun
 - **双击 bat 闪退**：在 PowerShell 中手动运行 `scripts\install-skills.bat` 查看报错。
 - **装了技能不触发**：需重启 Trae CN 或新建会话。
 - **`uv sync` 拉包慢**：国内镜像 `$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"` 后重试。
- **技能脚本报 `ModuleNotFoundError`**：项目根执行 `uv sync`，或确认命令用了 `uv run` 前缀。
+- **技能脚本报 `ModuleNotFoundError`**：项目根执行 `uv add pandas openpyxl playwright requests` 补齐缺包，或确认命令用了 `uv run` 前缀。

 更多排查见各技能的 `references/troubleshooting.md`。

 -----

-UPDATE: 2026-08-24
+UPDATE: 2026-09-30