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

.gitignore

@@ -2,4 +2,6 @@
 .venv/
 adr/
 __pycache__/
-.pytest_cache/
+.pytest_cache/
+.chrome-profile-yt/
+StudioSkills*.zip

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」 |
+| `youtube-studio-csv-download` | 复用已登录浏览器会话（`.profile`），脚本化下载分析 CSV（zip） | 「用我的 Chrome 会话下载这份 CSV」 |
-| `yt-studio-groupid-lookup` | 把一批群组名批量解析为 entity_id（groupId），并标注归属的内容所有者 | 「把这些群组名查成 Group ID」 |
 
 ## 项目结构
 
 ```
 ├── 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）。
+- **项目环境**（在工作区内跑整套流程）：技能建好 `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 <脚本路径>` 即可。
+- **单脚本模式**（技能已装到用户级目录、脱离工作区使用）：什么都不用配——脚本头部带 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

docs/install-skills.md

@@ -14,7 +14,8 @@
 
 | 技能 | 用途 |
 |---|---|
-| `uv-env-setup` | 用 uv 准备并维护 Python 运行环境（项目环境 / 单脚本 PEP 723 模式） |
+| `yt-download-place` | 在当前目录或指定路径创建 uv 项目工作区，承载各技能脚本的 uv 运行环境（项目环境 / 单脚本 PEP 723 模式） |
+| `yt-studio-auth-prep` | 在工作区预置登录态与鉴权套件：调试用户目录 `.profile`（YouTube 登录）+ 内容所有者套件 `bundles.json` |
 | `yt-studio-url-builder` | 根据需求清单（CSV/Excel）批量生成 YouTube Studio 内容管理器 explore URL |
 | `yt-studio-groupid-lookup` | 把一批群组名批量解析为 entity_id（groupId），并标注归属的内容所有者 |
 | `youtube-studio-csv-download` | 复用已登录浏览器会话，脚本化下载 YouTube Studio 分析 CSV（zip） |
@@ -71,15 +72,17 @@ scripts\install-skills.bat -Agent trae-cn -DryRun
 
 - **Trae CN**：用户级技能目录即上表；重启 Trae CN 或新建会话后生效。
 - **ZCode**：技能落在 `~\.zcode\skills\` 后由 ZCode 自动发现（本机会话中已验证）；新建会话后生效。zcode 环境里的同名工程技能可能遮蔽用户级技能，排查时注意优先级。
-- **终端方言**：两个 agent 都可能在 PowerShell 或 Git Bash 里执行命令。所有 SKILL.md 的示例统一用正斜杠路径 + 引号写法，两边通用；uv-env-setup 提供 PATH 刷新的两种方言写法。
+- **终端方言**：两个 agent 都可能在 PowerShell 或 Git Bash 里执行命令。所有 SKILL.md 的示例统一用正斜杠路径 + 引号写法，两边通用；yt-download-place 提供 PATH 刷新的两种方言写法。
-- **通用兜底**：无论哪个 agent，跑脚本前都先按 `uv-env-setup` 技能确认 uv 分支（项目环境 / 单脚本模式 / python -m uv 回退）。
+- **通用兜底**：无论哪个 agent，跑脚本前都先按 `yt-download-place` 技能备好 uv 环境（工作区 / 单脚本模式 / python -m uv 回退）。
 
 ## 验证
 
 1. 重启对应 agent（或新建会话）。
 2. 对话中直接提及技能名或相关意图，例如：
-   - 「帮我准备环境」→ `uv-env-setup`
+   - 「帮我准备工作区」→ `yt-download-place`
+   - 「帮我准备 YouTube 登录目录和所有者套件」→ `yt-studio-auth-prep`
    - 「根据这份清单批量生成 Studio URL」→ `yt-studio-url-builder`
+   - 「把这些群组名查成 Group ID」→ `yt-studio-groupid-lookup`
    - 「用我的 Chrome 会话下载这份分析 CSV」→ `youtube-studio-csv-download`
 
 ## 更新与卸载
@@ -98,5 +101,5 @@ scripts\install-skills.bat -Agent trae-cn -DryRun
 
 ## 注意
 
-- 运行时依赖不随技能安装：脚本型技能的 Python 依赖由两层机制承接——项目根 `pyproject.toml`（项目环境）或脚本头部 PEP 723 内联声明（单脚本模式），首次使用按 `uv-env-setup` 技能执行即可。
+- 运行时依赖不随技能安装：脚本型技能的 Python 依赖由两层机制承接——工作区 `pyproject.toml`（项目环境）或脚本头部 PEP 723 内联声明（单脚本模式），首次使用按 `yt-download-place` 技能建好工作区即可。
 - 安装脚本仅支持 Windows（路径与命令均按 Windows 编写）。

docs/usage-guide.md

@@ -4,10 +4,11 @@
 
 如果你需要完成上面这个常见的应用场景，那么，本技能组中的所有技能都是必须的，包括：
 
-- `uv-env-setup`：用于设置必要的 Python 运行环境，以便下面的技能所带的脚本可以正确运行。
+- `yt-download-place`：用于在当前或指定目录创建 uv 项目工作区，为下面的技能所带的脚本提供运行环境。
+- `yt-studio-auth-prep`：用于在工作区预置登录态与鉴权套件——调试用户目录 `.profile`（完成一次 YouTube 账号登录）与内容所有者鉴权套件 `bundles.json`，供后续所有任务复用。
+- `yt-studio-groupid-lookup`：用于从群组名称中提取实体 ID（已预置 `bundles.json` 时离线回放）。
 - `yt-studio-url-builder`：用于构建 YouTube Studio 分析页面 URL。
 - `youtube-studio-csv-download`：用于下载 YouTube Studio 分析数据。
-- `yt-studio-groupid-lookup`：用于从群组名称中提取实体 ID。
 
 对于这样一个任务，对于只有一个群组数据需要下载的情况，这组技能并没有人工下载来的快，更适合批量下载众多群组的数据。也就是，你需要Agent帮你从YouTube Studio的分析页面中，下载众多群组的众多情况的数据时，这组技能可以更好的指导Agent完成工作，也能很好的加速下载。
 
@@ -20,7 +21,14 @@
 
 这里，数据需求，就是你需要下载哪些指标的数据，以及你需要哪些时间段的数据，也包括需要筛选什么信息，同时，你需要的是什么细分的数据，例如：频道数据、内容数据还是其他的数据。
 
-下一步，是获取群组的实体 ID（groupid）。你可以让Agent使用 `yt-studio-groupid-lookup` 技能，来从群组名称中提取实体 ID。这样，前期的准备就算基本完成了。
+有了上面这些东西之后，先做一次环境预置（每个工作区只需一次）：
+
+1. 指示Agent用 `yt-download-place` 创建下载工作区（uv 项目环境，各技能脚本统一以 `uv run` 运行）。
+2. 指示Agent用 `yt-studio-auth-prep` 完成两项预置：在工作区创建调试用户目录 `.profile` 并完成一次 YouTube 账号登录；再提供内容所有者分析页 URL，把鉴权套件捕获到工作区的 `bundles.json`。
+
+预置完成后，后续所有任务都在同一个工作区里复用这份登录态与套件。只有当登录态失效（下载时跳到 Google 登录页）或套件过期（查 Group ID 时全量 401）时，才需要回到这一步刷新。
+
+下一步，是获取群组的实体 ID（groupid）。你可以让Agent使用 `yt-studio-groupid-lookup` 技能，来从群组名称中提取实体 ID；已预置 `bundles.json` 时走离线回放，全程无需打开浏览器。这样，前期的准备就算基本完成了。
 
 然后，指示Agent基于你的需求与获取的实体ID，创建符合需求的分析页面 URL。
 
@@ -30,6 +38,8 @@
 
 ### 检查与确认
 
+预置阶段的检查：`.profile` 登录完成后技能会打印「登录成功」；`bundles.json` 中套件数量应与你提供的所有者分析页 URL 数量一致，可以要求Agent列出每个套件的 ownerId 清单供你核对。
+
 常用的检查就是，需要下载的文件数量需要对应于生成的URL数量。如果数量不对应，那么，就需要检查Agent是否正确生成了URL，或者是否有任何错误或异常情况发生。
 
 另外，在URL生成过程中，也需要检查Agent是否正确解析了群组名称，以及是否有任何错误或异常情况发生。可以要求Agent抽样几个URL打开浏览器进行浏览确认。这个方式也可以确认Agent当前是否正确的读取了浏览器的登录状态，以避免因为登录状态过期而导致的下载失败。

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "StudioLift"
-version = "0.4.0"
+version = "0.5.3"
 description = "StudioLift ：一个 YouTube Studio 工具集，提供 URL 批量拼接、分析 CSV 导出下载等功能。"
 requires-python = ">=3.10"
 dependencies = [

scripts/youtube_export_interceptor.py

@@ -319,7 +319,7 @@ if __name__ == "__main__":
             account_name=args.account_name)
     else:
         selftest()
-        print("\n实际运行需先准备依赖环境（uv sync 或直接 uv run，见 uv-env-setup 技能），"
+        print("\n实际运行需先准备依赖环境（uv sync 或直接 uv run，见 yt-download-place 技能），"
               "再复用登录态（二选一）：\n"
               "  方式 A: python youtube_export_download.py --url \"<explore URL>\" "
               "--channel chrome --user-data-dir <你的 Chrome User Data 目录>\n"

skills/uv-env-setup/SKILL.md

@@ -1,95 +0,0 @@
----
-name: "uv-env-setup"
-description: "用 uv 准备并维护本项目与各技能脚本的 Python 运行环境（项目环境 uv sync / 单脚本 PEP 723 模式）。当用户提到环境准备/装依赖/重建 venv、脚本报 ModuleNotFoundError（pandas/openpyxl/playwright），或 uv/.venv 不可用时使用。"
----
-
-# uv 运行环境准备
-
-三种运行形态共用一个入口 `uv run`：
-
-- **项目环境**：在含 `pyproject.toml` 的项目根运行 `scripts/` 或整套技能。根 `pyproject.toml` 是依赖唯一事实来源，`uv sync` 落地 `.venv\`，`uv run` 免激活执行。
-- **单脚本模式**：脱离项目仓库单独运行某个技能脚本（如技能安装到用户级目录后跨项目使用）。三个脚本头部都带 PEP 723 内联依赖声明（`# /// script ... ///`），`uv run <脚本路径>` 会自动建缓存环境并装依赖，无需任何项目文件。
-- **无 uv 回退链**：uv 完全不可用时按固定顺序降级，见步骤 1。
-
-先按下表选分支，再执行对应步骤。
-
-| 你的情况 | 分支 |
-|---|---|
-| 在本项目目录内跑任何脚本 | A：项目环境 |
-| 技能已安装到用户级目录（如 `~\.trae-cn\skills\`、`~\.zcode\skills\`），当前目录没有 pyproject.toml | B：单脚本模式 |
-| `uv` 命令无法识别 | 先走步骤 1 的回退链，再回到 A/B |
-
-**完成判据（全局）**：最终用于跑业务脚本的那条命令成功打印结果，且不是靠裸 `python` 碰运气。
-
-## 步骤 1：确认 uv 可用（含回退链）
-
-```powershell
-uv --version
-```
-
-失败时**按顺序**尝试，命中即停：
-
-1. **会话内刷新 PATH 再试**（刚装完 uv、不想重开终端）：
-   - PowerShell：`$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")`
-   - Git Bash / zsh：`export PATH="$PATH:$HOME/.local/bin"`
-   - cmd：重开终端（cmd 无法可靠刷新）
-2. **`python -m uv --version`**：只要 uv 以模块存在就可用。此后把本文所有 `uv <子命令>` 都替换为 `python -m uv <子命令>`，其余不变。
-3. **`pip install uv` 装上后回到第 2 条**（winget/官方脚本安装的 uv 对新会话才生效，pip 装的立即随当前 Python 可用）。
-
-**完成判据**：`uv --version` 或 `python -m uv --version` 打印出版本号；若走了第 2 条，记下后续命令都要带 `-m uv`。
-
-## 步骤 2A：项目环境同步
-
-项目根（`pyproject.toml` 所在处）执行：
-
-```powershell
-uv sync
-```
-
-- 首次自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright、requests）。
-- 本机无兼容 Python 时，uv 自动下载托管 Python（`requires-python = ">=3.10"`）。
-- `uv run` 会隐式同步；显式 `uv sync` 是为了把依赖错误一次性暴露。
-
-**完成判据**：退出码 0，且项目根出现 `.venv\` 目录。
-
-## 步骤 2B：单脚本模式（无项目文件）
-
-对任意一个技能脚本直接：
-
-```powershell
-uv run "C:/Users/<you>/.trae-cn/skills/yt-studio-url-builder/scripts/build_studio_urls.py" --help
-```
-
-- uv 读脚本头部的 PEP 723 声明，自动缓存专用环境（默认仅 pandas/openpyxl，或含 playwright）。
-- 环境、路径写法用正斜杠 `/`，在 PowerShell、Git Bash、cmd 中都合法。
-- 首次运行某脚本会下载其依赖，耗时略长属正常现象。
-
-**完成判据**：脚本按预期输出（`--help` 打印用法 / `--selftest` 打印 selftest OK），无需 `.venv` 或 pyproject.toml。
-
-## 步骤 3：验证
-
-项目环境下三条自检：
-
-```powershell
-uv run python -c "import pandas, openpyxl, playwright, requests; print('env OK')"
-uv run python skills/youtube-studio-csv-download/scripts/youtube_export_download.py --selftest
-uv run python skills/yt-studio-groupid-lookup/scripts/lookup_groups.py --selftest
-```
-
-**完成判据**：打印 `env OK` 与两条 `selftest OK`。
-
-## 其他技能如何使用本环境
-
-- 四个业务技能（url-builder、groupid-lookup、csv-download）的 SKILL.md 默认**本技能已跑通**；它们给出的 `uv run python <脚本>` 命令按所选分支执行即可。
-- 统一不裸调 `python`、不手动激活 venv、不向全局 `pip install` 依赖。
-- 各 agent（trae-cn / zcode 等）的终端方言不同：示例中的调用统一写成对两者都安全的形态——正斜杠路径 + 引号包裹；确需 shell 特有能力时区分 PowerShell 与 bash 写法，不要混用。
-
-## 新增依赖
-
-- 项目环境：改根 `pyproject.toml` 的 `dependencies`（唯一入口）后 `uv sync` 更新 `uv.lock`。
-- 单脚本模式：改脚本头部 PEP 723 的 `dependencies`，下次 `uv run` 自动生效。
-- 两个来源不要混着加同一依赖，防止版本漂移；禁止绕过声明直装。
-
-## 排查
-
-网络慢/超时、镜像配置、`.venv` 损坏重建、uv 安装方式差异、无 uv 手动兜底等，查 [references/troubleshooting.md](references/troubleshooting.md)。

skills/youtube-studio-csv-download/SKILL.md

@@ -16,7 +16,7 @@ description: "Download YouTube Studio analytics CSV export (zip) via a Playwrigh
 ## 脚本与依赖
 
 - 脚本：`scripts/youtube_export_download.py`（本技能目录下；若缺失，用代码库全局搜索按 `youtube_export_download.py` 定位）
-- 依赖与环境：见 `uv-env-setup` 技能——项目环境走 `uv sync`；脱离项目时脚本头部带 PEP 723 声明，`uv run <脚本>` 自动备环境（复用系统 Chrome/Edge 时无需 `playwright install chromium`）。
+- 依赖与环境：见 `yt-download-place` 技能——工作区内走 `uv sync`；脱离工作区时脚本头部带 PEP 723 声明，`uv run <脚本>` 自动备环境（复用系统 Chrome/Edge 时无需 `playwright install chromium`）。
 - 登录态必须已存在：脚本不登录，只复用已登录会话。
 
 ## 步骤 1：确认登录态来源（二选一）

skills/youtube-studio-csv-download/references/troubleshooting.md

@@ -9,7 +9,7 @@
 
 ## 环境与依赖
 
-- **`playwright` / `sync_playwright` 找不到**：环境未同步。项目根执行 `uv sync`，或直接用 `uv run python <脚本>`；详见 `uv-env-setup` 技能。复用系统 Chrome/Edge 时无需 `playwright install chromium`。
+- **`playwright` / `sync_playwright` 找不到**：环境未同步。工作区根执行 `uv sync`，或直接用 `uv run python <脚本>`；详见 `yt-download-place` 技能。复用系统 Chrome/Edge 时无需 `playwright install chromium`。
 - **系统找不到浏览器**：确认本机装了 Chrome 或 Edge；用 `--channel` 显式指定 `chrome` 或 `msedge`。
 
 ## 运行过程

skills/youtube-studio-csv-download/scripts/youtube_export_download.py

@@ -319,7 +319,7 @@ if __name__ == "__main__":
             account_name=args.account_name)
     else:
         selftest()
-        print("\n实际运行需先准备依赖环境（uv sync 或直接 uv run，见 uv-env-setup 技能），"
+        print("\n实际运行需先准备依赖环境（uv sync 或直接 uv run，见 yt-download-place 技能），"
               "再复用登录态（二选一）：\n"
               "  方式 A: python youtube_export_download.py --url \"<explore URL>\" "
               "--channel chrome --user-data-dir <你的 Chrome User Data 目录>\n"

skills/yt-download-place/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: "yt-download-place"
+description: "在当前目录或指定路径创建 uv 项目工作区（git 仓库 + pyproject.toml + .venv + assets + data + .gitignore + uv.lock），作为 YouTube 下载类技能脚本的统一运行环境。当用户要求准备工作区/下载目录/新建 uv 项目、为 yt 技能装依赖（pandas/openpyxl/playwright/requests）备环境，或 uv/.venv 报错时使用。"
+---
+
+# yt-download-place：下载工作区
+
+在目标目录落地一套标准 uv 项目结构，让其他 yt 技能（url-builder、groupid-lookup、csv-download）的脚本统一以 `uv run python <脚本>` 运行。一个工作区承载一批下载任务：`assets/` 存中间数据（需求清单、URL 清单、解析产物），`data/` 存最终下载数据（不进 git）。
+
+目标目录 = 用户指定路径，未指定则用当前目录；目录不存在时先创建。目标结构：
+
+```
+<place>/
+├── .git/
+├── .venv/
+├── assets/
+├── data/
+├── .gitignore
+├── pyproject.toml
+├── README.md
+└── uv.lock
+```
+
+## 步骤 1：确认 uv 可用
+
+```powershell
+uv --version
+```
+
+失败时按顺序尝试，命中即停：
+
+1. **会话内刷新 PATH**（刚装完 uv、未重开终端）：
+   - PowerShell：`$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")`
+   - Git Bash / zsh：`export PATH="$PATH:$HOME/.local/bin"`
+   - cmd：重开终端（cmd 无法可靠刷新）
+2. **模块入口**：`python -m uv --version`。可用则本文所有 `uv <子命令>` 改为 `python -m uv <子命令>`，其余不变。
+3. **pip 兜底**：`pip install uv` 后回到第 2 条（pip 装的随当前 Python 立即可用）。
+
+**完成判据**：`uv --version` 或 `python -m uv --version` 打印版本号。
+
+## 步骤 2：搭建工作区骨架
+
+在 `<place>` 下创建两个数据目录（两种 shell 写法二选一；路径统一正斜杠 + 引号，两边通用）：
+
+```powershell
+# PowerShell
+New-Item -ItemType Directory -Force "<place>/assets", "<place>/data" | Out-Null
+```
+
+```bash
+# Git Bash / zsh
+mkdir -p "<place>/assets" "<place>/data"
+```
+
+写入三个文件（已存在则跳过，不覆盖）：
+
+**pyproject.toml**
+
+```toml
+[project]
+name = "yt-download-place"
+version = "0.1.0"
+requires-python = ">=3.10"
+```
+
+依赖不写在这里：四个必需包由步骤 3 的 `uv add` 统一补齐（单一来源，已存在 pyproject.toml 的工作区同样适用）。
+
+**.gitignore**
+
+```gitignore
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.profile
+bundle*.json
+
+# Data folder
+data/
+```
+
+**README.md**
+
+```markdown
+# yt-download-place
+
+YouTube 下载工作区：assets/ 存中间数据，data/ 存下载数据（不入 git）。
+技能脚本一律 `uv run python <脚本>` 运行。
+```
+
+**git 仓库**：`<place>/.git` 不存在时执行 `git init`；已是仓库则复用。
+
+**完成判据**：`<place>` 下存在 `assets\`、`data\`、`pyproject.toml`、`.gitignore`、`README.md`、`.git`，且原有文件未被改动。
+
+## 步骤 3：补齐依赖并同步环境
+
+`<place>` 下执行：
+
+```powershell
+uv add pandas openpyxl playwright requests
+```
+
+- 必需包固定四件：`pandas`、`openpyxl`、`playwright`、`requests`——yt 技能脚本（url-builder、groupid-lookup、csv-download、auth-prep）运行的全部依赖。
+- `uv add` 幂等：已满足的包直接跳过，缺失的写入 `pyproject.toml` 与 `uv.lock` 并同步 `.venv\`；首次准备自动创建 `.venv\`，本机无兼容 Python 时自动下载托管 Python（≥3.10）。
+- 复用已有 `pyproject.toml`（非本模板）的工作区同样适用：只追加缺失的这四个包，其余依赖不动。
+- `uv run` 会隐式同步；显式 `uv add` 是为了把缺包/依赖冲突一次性暴露。
+
+**完成判据**：退出码 0，`<place>` 下出现 `.venv\` 与 `uv.lock`，且 `pyproject.toml` 的 `dependencies` 含这四个包。
+
+## 步骤 4：验证并交付
+
+```powershell
+uv run python -c "import pandas, openpyxl, playwright, requests; print('env OK')"
+```
+
+**完成判据（全局）**：打印 `env OK`。向用户报告工作区路径，此后约定：
+
+- 其他技能脚本都在 `<place>` 下用 `uv run python <脚本>` 执行；不裸调 `python`、不手动激活 venv、不向全局 pip 装依赖。
+- 中间数据写 `<place>/assets/`，下载数据写 `<place>/data/`。
+- 新增依赖：`uv add <包>`（唯一入口，禁止 pip 直装绕过 lock）。
+
+## 排查
+
+uv 不识别、国内镜像加速、`No solution found`、`.venv` 损坏重建、playwright 浏览器下载慢、无 uv 手动兜底等，查 [references/troubleshooting.md](references/troubleshooting.md)。

skills/yt-download-place/references/troubleshooting.md

@@ -1,4 +1,4 @@
-# 环境排查
+# 工作区排查
 
 ## uv 不识别（按序排查）
 
@@ -8,13 +8,7 @@
    - cmd：重开终端。
 2. **试试模块入口**：`python -m uv --version`。可用则后续所有 `uv <子命令>` 都换成 `python -m uv <子命令>`。
 3. **用 pip 兜底安装**：`pip install uv` 后回到第 2 条，立即生效（winget/官方脚本方式要等新终端）。
-4. **彻底没有 Python/uv**：先装 Python 3.10+（或让 `uv` 官方脚本一并装好托管 Python），再走第 3 条。
+4. **彻底没有 Python/uv**：先装 Python 3.10+（或让 uv 官方脚本一并装好托管 Python），再走第 3 条。
-
-## 无 pyproject.toml 的目录跑脚本
-
-- 脚本头部带 PEP 723 声明（`# /// script ... ///`），直接 `uv run <脚本>` 即可，uv 自动建缓存环境。
-- 报「无法解析依赖/找不到脚本」时：确认路径存在且为正斜杠写法；确认脚本头部声明未被删改。
-- 需要重建缓存环境：删除 `%LOCALAPPDATA%\uv\cache\environments-v2` 下对应目录（或整体清 `uv cache clean`）后重试。
 
 ## 网络与镜像（国内环境）
 
@@ -25,7 +19,7 @@ $env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
 uv sync
 ```
 
-要持久化则写入 `pyproject.toml`：
+要持久化则写入工作区 `pyproject.toml`：
 
 ```toml
 [[tool.uv.index]]
@@ -33,23 +27,16 @@ url = "https://pypi.tuna.tsinghua.edu.cn/simple"
 default = true
 ```
 
-## sync 相关
+## sync / add 相关
 
-- **`No solution found` / 依赖解析冲突**：`dependencies` 里的版本约束互相矛盾。放宽或修正 `pyproject.toml` 后重试。
+- **`No solution found` / 依赖解析冲突**：`dependencies` 里的版本约束互相矛盾（含 `uv add` 追加的包与既有约束冲突）。放宽或修正 `pyproject.toml` 后重试。
-- **lock 与 pyproject 不一致**：`uv.lock` 过期，`uv sync` 会自动更新；若报 lock 损坏，删除 `uv.lock` 后重新 `uv sync`。
+- **缺必需包**：`pyproject.toml` 里没有 pandas/openpyxl/playwright/requests（常见于复用已有项目）。工作区根执行 `uv add pandas openpyxl playwright requests` 补齐（幂等）。
+- **lock 与 pyproject 不一致**：`uv.lock` 过期，`uv sync` / `uv add` 会自动更新；若报 lock 损坏，删除 `uv.lock` 后重新 `uv sync`。
 - **`requires-python` 不满足**：本机 Python 全部低于 3.10。让 uv 自动下载即可：`uv sync -p 3.12`（或省略，uv 自选）。
 
-## 已有 .venv 但缺 pyproject.toml
-
-历史环境是手动 `pip install` 搭的，不是 uv 管理：
-
-1. 在项目根新建 `pyproject.toml`，`dependencies` 写全实际用到的包（参考现有 .venv 里 `pip list`）。
-2. `requires-python` 与现有解释器大版本一致（如 `">=3.12"`），避免 uv 另下新 Python。
-3. `uv sync` 让 uv 接管该 `.venv` 并生成 `uv.lock`。
-
 ## .venv 损坏 / 重建
 
-症状：`uv run` 报奇怪的导入错误、DLL 加载失败，或 `.venv` 被移动过。
+症状：`uv run` 报奇怪的导入错误、DLL 加载失败，或 `.venv` 被移动过。工作区根执行：
 
 ```powershell
 Remove-Item -Recurse -Force .venv
@@ -58,10 +45,18 @@ uv sync
 
 ## playwright 相关
 
-- **`ModuleNotFoundError: playwright`**：环境未同步。项目根执行 `uv sync`，或直接用 `uv run python <脚本>`；单脚本模式下直接 `uv run <脚本>`（PEP 723 自动装）。详见 SKILL.md 步骤 1 回退链。
+- **`ModuleNotFoundError: playwright`**（或其他必需包缺失）：环境未同步或缺包。工作区根执行 `uv add pandas openpyxl playwright requests` 补齐，或直接用 `uv run python <脚本>`。
-- **复用系统 Chrome/Edge 无需 `playwright install`**：只有用 uv 环境内置 Chromium 时才需要 `uv run playwright install chromium`。
+- **复用系统 Chrome/Edge 无需 `playwright install`**：只有用工作区内置 Chromium 时才需要 `uv run playwright install chromium`。
 - **`playwright install` 下载浏览器慢**：`$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright"` 后重试。
 
+## 无工作区目录临时跑脚本（PEP 723 兜底）
+
+技能脚本头部带 PEP 723 内联依赖声明（`# /// script ... ///`），在无 `pyproject.toml` 的目录直接 `uv run <脚本>` 也可运行，uv 自动建缓存环境：
+
+- 报「无法解析依赖/找不到脚本」时：确认路径存在且为正斜杠写法；确认脚本头部声明未被删改。
+- 需要重建缓存环境：删除 `%LOCALAPPDATA%\uv\cache\environments-v2` 下对应目录（或整体 `uv cache clean`）后重试。
+- 批量/长期使用仍建议按 SKILL.md 建正式工作区，避免缓存环境碎片化。
+
 ## 无 uv 的最终兜底
 
 uv 完全装不上时，用标准库 venv 手动搭（仅应急，失去 lock 可复现性）：
@@ -71,8 +66,3 @@ python -m venv .venv
 .venv\Scripts\python.exe -m pip install pandas openpyxl playwright requests
 # 此后所有命令用 .venv\Scripts\python.exe 替代 uv run python
 ```
-
-## 与全局环境隔离
-
-- 本项目所有命令都经 `uv run`，不会污染全局 site-packages。
-- 若此前 `pip install` 过 playwright/pandas 到全局，与本 `.venv` 无冲突，但项目内一律走 `uv run`。

skills/yt-studio-auth-prep/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: "yt-studio-auth-prep"
+description: "提前准备 YouTube 下载工作区的登录态与鉴权套件：创建调试用户目录 .profile 并完成 YouTube 账号登录（供 youtube-studio-csv-download 等脚本复用），捕获内容所有者鉴权套件 bundles.json（供 yt-studio-groupid-lookup 离线回放），两者都落在 yt-download-place 工作区。当用户要准备工作区登录/生成 .profile/登录 YouTube、捕获或更新 bundles.json/新增所有者套件，或下游 csv-download、groupid-lookup 报未登录、套件缺失或过期 401 时使用。"
+---
+
+# 登录态与套件预置（.profile + bundles.json）
+
+把下游技能依赖的两项「环境级」产物提前一次性备好，落在 `yt-download-place` 创建的工作区 `<place>` 里：
+
+- **`.profile`**：`<place>/.profile`，专用调试用户目录。登录一次 YouTube 账号后，`youtube-studio-csv-download`、`yt-studio-groupid-lookup` 都以 `--user-data-dir "<place>/.profile"` 复用该登录态；浏览器需保持打开时也可带调试端口启动后改用 `--connect`。
+- **`bundles.json`**：`<place>/bundles.json`，内容所有者鉴权套件数组（在线捕获自动生成），是 `yt-studio-groupid-lookup` 离线回放 `--bundles` 的唯一数据源。结构见其 [input-guide](../yt-studio-groupid-lookup/references/input-guide.md) 第 2 节。
+
+两项均已被工作区 `.gitignore` 忽略（`.profile`、`bundle*.json`），不入 git。
+
+## 何时使用
+
+| 场景 | 走到哪一步 |
+|---|---|
+| 新工作区首次准备 | 全部步骤 |
+| 登录态失效（下游报跳 Google 登录页） | 步骤 2 补登录 |
+| 套件过期（回放全量 401）/ 新增所有者 | 步骤 3 重捕获（命令幂等） |
+| 换浏览器品牌 | 删 `.profile` 后全部重来 |
+
+## 步骤 1：确认工作区与浏览器品牌
+
+- `<place>` 必须已是 `yt-download-place` 工作区（存在 `pyproject.toml` 与 `.venv`）；没有就先跑该技能。
+- 与用户确认浏览器品牌 `chrome` / `msedge`（默认 `chrome`）。**品牌一经选定，该工作区所有下游命令的 `--channel` 必须一致**：`.profile` 与品牌绑定，混用会导致登录态异常。下文命令以 `chrome` 为例。
+
+**完成判据**：`<place>` 可用、品牌已确定。
+
+## 步骤 2：创建 .profile 并完成登录
+
+cwd 在 `<place>` 下执行（目录不存在会自动创建；路径统一正斜杠 + 引号）：
+
+```powershell
+uv run python "E:/WorkPlace/01_WORKING/04_Settlements/ag_ytstudiourl/skills/yt-studio-auth-prep/scripts/login_profile.py" --channel chrome --user-data-dir "<place>/.profile"
+```
+
+- 脚本打开可见浏览器窗口后交给用户：完成 Google/YouTube 登录即可（支持两步验证），脚本轮询确认 `studio.youtube.com` 不再跳登录页，成功后自动关窗退出。
+- 默认等待 600 秒（`--timeout-seconds` 可调）；超时不丢进度，直接重跑同一命令继续。
+
+**完成判据**：打印 `[登录] 登录成功`，退出码 0；`<place>/.profile` 下出现浏览器 profile 文件（如 `Default/`）。
+
+## 步骤 3：捕获 bundles.json
+
+从用户处收集内容所有者分析页 URL（`studio.youtube.com/owner/<ownerId>/analytics?...`，可多个）。先确保 `<place>/bundles.json` 存在（`--bundles` 指向不存在的文件会报错）：
+
+```powershell
+if (!(Test-Path "<place>/bundles.json")) { Set-Content -Path "<place>/bundles.json" -Value "[]" -Encoding utf8 }
+```
+
+cwd 在 `<place>` 下执行（不带 `--names`，只捕获不查询；`--bundles` 与 `--save-bundles` 同路径 = 已有套件按 ownerId 合并覆盖，命令天然幂等）：
+
+```powershell
+uv run python "E:/WorkPlace/01_WORKING/04_Settlements/ag_ytstudiourl/skills/yt-studio-groupid-lookup/scripts/lookup_groups.py" --url "<owner1 URL>" --url "<owner2 URL>" --bundles "<place>/bundles.json" --save-bundles "<place>/bundles.json" --user-data-dir "<place>/.profile" --channel chrome
+```
+
+- 捕获借用 `yt-studio-groupid-lookup` 的在线捕获能力：自动触发群组搜索、过滤 HTTP/2 伪头、捕获时校验鉴权头。页面交互细节见该技能。
+- 首次准备建议一次传齐所有 owner URL；之后刷新/新增所有者都是重跑同一条命令。
+
+**完成判据**：每个所有者打印 `[捕获] 套件就绪：owner=...`，末尾打印 `[套件] 已保存 N 个所有者套件 -> <place>/bundles.json`，且捕获过程无「缺少 Authorization/Cookie/…」警告（出现即按排查重捕获）。
+
+## 步骤 4：校验产物并交付
+
+```powershell
+uv run python -c "import json;bs=json.load(open('<place>/bundles.json',encoding='utf-8'));print('套件',len(bs),'个:',[b.get('ownerId') for b in bs])"
+```
+
+**完成判据（全局）**：套件数量与传入的 owner URL 数一致（同 ownerId 自动去重合并），ownerId 列表符合预期。向用户报告后续用法：
+
+- 登录态：csv-download 用 `--user-data-dir "<place>/.profile" --channel chrome`；浏览器不能关时，`chrome.exe --user-data-dir="<place>/.profile" --remote-debugging-port=9222` 启动后各技能改传 `--connect http://localhost:9222`。
+- 套件：groupid-lookup 回放用 `--bundles "<place>/bundles.json"`。
+- 时效约定：套件是一次性凭据，回放全量 401 就重跑步骤 3；登录态失效重跑步骤 2。
+
+## 排查
+
+按 现象 → 原因 → 解决 逐条排查（登录超时、目录被占用、捕获警告、读取 bundles 失败、品牌切换等），查 [references/troubleshooting.md](references/troubleshooting.md)。

skills/yt-studio-auth-prep/references/troubleshooting.md

@@ -0,0 +1,70 @@
+# 排查：.profile 与 bundles.json
+
+先分清环节：步骤 2 的问题是「登录」，步骤 3 的问题是「捕获」，步骤 4 的问题是「产物数量」。下游技能报错（跳登录页 / 401）都回到本技能对应步骤修复。
+
+## 步骤 2：登录
+
+### 浏览器启动失败 / 目录被占用
+- 现象：`[!] 启动浏览器失败: ... ProcessSingleton / already in use`。
+- 原因：有同品牌浏览器正用着 `<place>/.profile`——上次窗口没关（脚本异常中断）或手动开过。
+- 解决：任务管理器彻底退出该品牌浏览器进程后重跑；脚本正常结束会自动关掉自己开的窗口。
+
+### 登录等待超时（默认 600 秒）
+- 现象：`[!] 600 秒内未完成登录`。
+- 原因：用户没完成登录，或卡在验证码 / 两步验证。
+- 解决：`.profile` 已保留进度，直接重跑同一命令继续；等待不够就加大 `--timeout-seconds`。
+
+### 显示登录成功，下游仍跳 Google 登录页
+- 现象：csv-download / groupid-lookup 运行时停在 accounts.google。
+- 原因：cookie 存在不等于会话有效（服务端已让该会话过期）；或下游 `--channel` 与建目录时品牌不一致。
+- 解决：先核对品牌一致，再重跑步骤 2 补登录一次；不要试图直接改 cookie 文件。
+
+### 想换浏览器品牌
+- 现象：需要从 chrome 切到 msedge（或反之）。
+- 原因：`.profile` 与首次登录的品牌绑定，跨品牌复用会话异常。
+- 解决：删除 `<place>/.profile`，用新品牌重跑步骤 2、步骤 3；bundles.json 会在重捕获时按 ownerId 覆盖更新。
+
+## 步骤 3：捕获
+
+### 报「读取 bundles 失败」
+- 现象：`[!] 读取 bundles 失败: ...`（FileNotFoundError）。
+- 原因：`--bundles` 指向的文件还不存在（首次捕获没先建空文件）。
+- 解决：`<place>/bundles.json` 不存在时先写入 `[]`（见 SKILL.md 步骤 3），再重跑命令。
+
+### 提示「当前会话未登录，已跳转到 Google 登录页」
+- 原因：`.profile` 登录态失效（过期或品牌不一致）。
+- 解决：回步骤 2 补登录，再重跑步骤 3。
+
+### 警告：缺少 Authorization（SAPISIDHASH）/ Cookie / X-YouTube-Delegation-Context
+- 现象：捕获时 stderr 打印 `[捕获] 警告：缺少 ...`。
+- 原因：捕获到的请求头不全（未真正登录或页面语境不对），这套件回放必 401。
+- 解决：直接重跑步骤 3 重新捕获；仍出现则先补登录。
+
+### 警告：externalOwnerId 与 URL ownerId 不一致
+- 原因：页面残留上一个所有者的 delegation 语境，或 URL 本身指错所有者。
+- 解决：确认 URL 是目标所有者，重跑步骤 3（脚本以请求体为准并提示）。
+
+### 未捕获到 search_groups 请求（TimeoutError）
+- 原因：没触发群组搜索，或该页面不是高级模式分析页。
+- 解决：在打开的浏览器窗口里，于该所有者分析页顶部搜索/筛选框输入任意词并回车（每个所有者一次）；等待不够就给命令加 `--wait-seconds`。
+
+## 下游回放
+
+### 回放全量 401
+- 现象：groupid-lookup 离线回放备注大量 `HTTP401`。
+- 原因：套件过期——鉴权头是页面逐请求计算的，属正常时效问题，不是文件坏了。
+- 解决：重跑步骤 3 刷新（同一条幂等命令，按 ownerId 覆盖）。
+
+### HTTP403
+- 现象：回放备注 `HTTP403（无权限或 delegation 语境不符）`。
+- 原因：当前登录账号对该内容所有者无权限（换账号登录过 .profile）。
+- 解决：在 .profile 浏览器里确认登录的是有权限的账号，重跑步骤 2、步骤 3。
+
+## 步骤 4：产物
+
+### bundles.json 套件数量与 owner URL 数不符
+- 原因：某个 URL 捕获失败被跳过；或传入了重复 ownerId（同 ownerId 只保留最新一份，属预期合并行为）。
+- 解决：对照终端捕获日志定位失败的所有者，单独重跑步骤 3（只传该 URL）。
+
+### 验证套件结构
+- 逐套件核对 headers 含 Authorization / Cookie / X-YouTube-Delegation-Context、bodyTemplate 含 delegationContext——结构标准见 `yt-studio-groupid-lookup/references/input-guide.md` 第 2 节。

skills/yt-studio-auth-prep/scripts/login_profile.py

@@ -0,0 +1,142 @@
+# -*- coding: utf-8 -*-
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "playwright>=1.40",
+# ]
+# ///
+r"""
+调试用户目录 .profile 生成 + YouTube 账号登录脚本（yt-studio-auth-prep 技能）。
+
+职责单一：在指定目录创建（或复用）一个独立的浏览器用户数据目录，打开可见浏览器
+窗口交给用户手动完成 Google/YouTube 登录，轮询确认 studio.youtube.com 不再跳转
+登录页后关闭窗口退出。登录态持久化在该目录，供下游脚本复用：
+
+  - youtube-studio-csv-download : --user-data-dir "<place>/.profile" --channel <brand>
+  - yt-studio-groupid-lookup    : 同上（在线捕获套件时）
+
+用法（cwd 任意；目录不存在会自动创建）：
+  python login_profile.py --channel chrome --user-data-dir "<place>/.profile"
+  python login_profile.py --channel msedge --user-data-dir "<place>/.profile" --timeout-seconds 600
+
+注意：
+  - channel 一经选定，整个工作区所有下游命令必须用同一品牌（chrome/msedge）；
+    换品牌 = 删除 .profile 后重跑本脚本，并重新捕获 bundles.json。
+  - 登录态失效（下游报跳 Google 登录页）时直接重跑本脚本补登录，.profile 保留原数据。
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import time
+
+STUDIO_URL = "https://studio.youtube.com/"
+DEFAULT_TIMEOUT_SECONDS = 600
+
+
+def classify_url(url: str) -> str:
+    """当前页面 URL 归类：google=登录页，studio=已进 Studio，other=其他。"""
+    u = (url or "").lower()
+    if "accounts.google" in u:
+        return "google"
+    if "studio.youtube.com" in u:
+        return "studio"
+    return "other"
+
+
+def selftest():
+    assert classify_url("https://accounts.google.com/v3/signin/identifier?x=1") == "google"
+    assert classify_url("https://studio.youtube.com/channel/UCxx/analytics") == "studio"
+    assert classify_url("https://www.youtube.com/") == "other"
+    assert classify_url("") == "other"
+    print("selftest OK：URL 分类逻辑通过")
+
+
+def wait_login(page, start_url: str, timeout_seconds: int) -> bool:
+    """轮询等待用户完成登录；首次到达 studio 后回访一次，防会话弹回登录页。"""
+    page.goto(start_url, wait_until="domcontentloaded")
+    deadline = time.time() + timeout_seconds
+    hinted = False
+    last_report = time.time()
+    while time.time() < deadline:
+        kind = classify_url(page.url)
+        if kind == "studio":
+            page.wait_for_timeout(3000)
+            page.goto(start_url, wait_until="domcontentloaded")
+            if classify_url(page.url) == "studio":
+                return True
+        elif kind == "google":
+            if not hinted:
+                print("[登录] 请在打开的浏览器窗口中完成 Google/YouTube 登录"
+                      "（支持两步验证），完成后本脚本自动检测……")
+                hinted = True
+            page.wait_for_timeout(2000)
+        else:
+            page.wait_for_timeout(3000)
+            page.goto(start_url, wait_until="domcontentloaded")
+        if time.time() - last_report >= 30:
+            print(f"[登录] 仍在等待登录……剩余 {max(0, int(deadline - time.time()))} 秒")
+            last_report = time.time()
+    return False
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="创建调试用户目录 .profile 并完成 YouTube 账号登录")
+    ap.add_argument("--selftest", action="store_true",
+                    help="仅跑 URL 分类自测（无需浏览器）")
+    ap.add_argument("--user-data-dir", help="调试用户目录路径，如 <place>/.profile")
+    ap.add_argument("--channel", choices=["chrome", "msedge"], default="chrome",
+                    help="浏览器品牌，默认 %(default)s；选定后全工作区统一")
+    ap.add_argument("--start-url", default=STUDIO_URL,
+                    help="登录检测起始页，默认 %(default)s")
+    ap.add_argument("--timeout-seconds", type=int, default=DEFAULT_TIMEOUT_SECONDS,
+                    help="等待登录的最长秒数，默认 %(default)s")
+    args = ap.parse_args(argv)
+
+    if args.selftest:
+        selftest()
+        return
+    if not args.user_data_dir:
+        ap.error("--user-data-dir 必填，如 <place>/.profile")
+
+    os.makedirs(args.user_data_dir, exist_ok=True)
+    print(f"[登录] 打开 {args.channel}（profile={args.user_data_dir}），"
+          f"最长等待 {args.timeout_seconds} 秒……")
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        raise SystemExit("[!] 缺少 playwright：在工作区（yt-download-place）内用"
+                         " uv run python 重试，或先 uv sync。")
+
+    with sync_playwright() as p:
+        try:
+            context = p.chromium.launch_persistent_context(
+                user_data_dir=args.user_data_dir,
+                channel=args.channel,
+                headless=False,
+                args=["--disable-blink-features=AutomationControlled"],
+            )
+        except Exception as e:  # noqa: BLE001
+            raise SystemExit(
+                f"[!] 启动浏览器失败: {e}\n"
+                f"    多为 {args.channel} 正被占用（上次窗口未关/手动开过 .profile）。"
+                "任务管理器彻底退出该品牌浏览器进程后重跑。")
+        try:
+            page = context.new_page()
+            ok = wait_login(page, args.start_url, args.timeout_seconds)
+        finally:
+            context.close()
+
+    if not ok:
+        raise SystemExit(
+            f"[!] {args.timeout_seconds} 秒内未完成登录。.profile 已保留进度，"
+            "直接重跑同一命令继续；等待不够就加大 --timeout-seconds。")
+    print(f"[登录] 登录成功：{args.user_data_dir}（channel={args.channel}）")
+    print(f"[i] 该工作区所有下游命令统一使用 --channel {args.channel} "
+          f"--user-data-dir {args.user_data_dir}")
+
+
+if __name__ == "__main__":
+    main()

skills/yt-studio-groupid-lookup/SKILL.md

@@ -27,7 +27,7 @@ description: "把一批群组名批量解析为 entity_id（即 groupId），并
 ## 脚本与依赖
 
 - 脚本：`scripts/lookup_groups.py`（本技能目录下；若缺失，用代码库全局搜索按 `lookup_groups.py` 定位）。
-- 依赖与环境：见 `uv-env-setup` 技能——项目环境走 `uv sync`；脱离项目时脚本头部带 PEP 723 声明，`uv run <脚本>` 自动备环境。
+- 依赖与环境：见 `yt-download-place` 技能——工作区内走 `uv sync`；脱离工作区时脚本头部带 PEP 723 声明，`uv run <脚本>` 自动备环境。
 - 登录态必须已存在：脚本不登录，只复用已登录 YouTube Studio 会话，否则跳 Google 登录页。
 
 ## 选择运行分支

skills/yt-studio-groupid-lookup/references/troubleshooting.md

@@ -109,4 +109,4 @@
 
 ### 缺依赖报 ModuleNotFoundError
 - 现象：`ModuleNotFoundError: No module named 'requests'` 或 `'playwright'` 或 `'openpyxl'`。
-- 解决：项目根 `uv sync` 后统一用 `uv run` 前缀执行；脱离项目时直接 `uv run <脚本>`（脚本头部 PEP 723 声明会自动装依赖，见 `uv-env-setup` 技能）；或单独 `pip install requests playwright openpyxl`。
+- 解决：工作区根 `uv sync` 后统一用 `uv run` 前缀执行；脱离工作区时直接 `uv run <脚本>`（脚本头部 PEP 723 声明会自动装依赖，见 `yt-download-place` 技能）；或单独 `pip install requests playwright openpyxl`。

skills/yt-studio-url-builder/SKILL.md

@@ -32,7 +32,7 @@ description: "根据需求清单（CSV/Excel）批量生成 YouTube Studio 内
 ### 1. 定位脚本与依赖
 
 - 脚本默认位于 `scripts/build_studio_urls.py`；若缺失，用代码库全局搜索按 `build_studio_urls.py` 定位。
-- 运行环境由 `uv-env-setup` 技能统一管理：项目环境走 `uv sync` + `uv run`；脱离项目时脚本头部带 PEP 723 声明，`uv run <脚本>` 自动备环境。首次运行前先按该技能选好分支。
+- 运行环境由 `yt-download-place` 技能统一管理：工作区内走 `uv sync` + `uv run`；脱离工作区时脚本头部带 PEP 723 声明，`uv run <脚本>` 自动备环境。首次运行前先按该技能建好工作区。
 - 中文国家名 → ISO 代码的映射在 `scripts/countries.json`，可自行扩充。
 
 完成标准：脚本路径已确定，且第 4 步的运行命令可直接执行。

uv.lock

@@ -815,7 +815,7 @@ wheels = [
 
 [[package]]
 name = "studiolift"
-version = "0.3.4"
+version = "0.4.0"
 source = { virtual = "." }
 dependencies = [
     { name = "openpyxl" },