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

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