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

name, description

name	description
yt-studio-auth-prep	提前准备 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 第 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> 下执行（目录不存在会自动创建；路径统一正斜杠 + 引号）：

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 指向不存在的文件会报错）：

if (!(Test-Path "<place>/bundles.json")) { Set-Content -Path "<place>/bundles.json" -Value "[]" -Encoding utf8 }

cwd 在 <place> 下执行（不带 --names，只捕获不查询；--bundles 与 --save-bundles 同路径 = 已有套件按 ownerId 合并覆盖，命令天然幂等）：

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：校验产物并交付

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。