---
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)。