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

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