chore: 更新技能引用名称并新增 yt-studio-auth-prep 登录脚本
This commit is contained in:
@@ -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)。
|
||||
@@ -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：确认登录态来源（二选一）
|
||||
|
||||
@@ -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`。
|
||||
|
||||
## 运行过程
|
||||
|
||||
@@ -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"
|
||||
|
||||
130
skills/yt-download-place/SKILL.md
Normal file
130
skills/yt-download-place/SKILL.md
Normal file
@@ -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)。
|
||||
@@ -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 条。
|
||||
|
||||
## 无 pyproject.toml 的目录跑脚本
|
||||
|
||||
- 脚本头部带 PEP 723 声明（`# /// script ... ///`），直接 `uv run <脚本>` 即可，uv 自动建缓存环境。
|
||||
- 报「无法解析依赖/找不到脚本」时：确认路径存在且为正斜杠写法；确认脚本头部声明未被删改。
|
||||
- 需要重建缓存环境：删除 `%LOCALAPPDATA%\uv\cache\environments-v2` 下对应目录（或整体清 `uv cache clean`）后重试。
|
||||
4. **彻底没有 Python/uv**：先装 Python 3.10+（或让 uv 官方脚本一并装好托管 Python），再走第 3 条。
|
||||
|
||||
## 网络与镜像（国内环境）
|
||||
|
||||
@@ -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` 后重试。
|
||||
- **lock 与 pyproject 不一致**：`uv.lock` 过期，`uv sync` 会自动更新；若报 lock 损坏，删除 `uv.lock` 后重新 `uv sync`。
|
||||
- **`No solution found` / 依赖解析冲突**：`dependencies` 里的版本约束互相矛盾（含 `uv add` 追加的包与既有约束冲突）。放宽或修正 `pyproject.toml` 后重试。
|
||||
- **缺必需包**：`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 回退链。
|
||||
- **复用系统 Chrome/Edge 无需 `playwright install`**：只有用 uv 环境内置 Chromium 时才需要 `uv run playwright install chromium`。
|
||||
- **`ModuleNotFoundError: playwright`**（或其他必需包缺失）：环境未同步或缺包。工作区根执行 `uv add pandas openpyxl playwright requests` 补齐，或直接用 `uv run python <脚本>`。
|
||||
- **复用系统 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`。
|
||||
77
skills/yt-studio-auth-prep/SKILL.md
Normal file
77
skills/yt-studio-auth-prep/SKILL.md
Normal file
@@ -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)。
|
||||
70
skills/yt-studio-auth-prep/references/troubleshooting.md
Normal file
70
skills/yt-studio-auth-prep/references/troubleshooting.md
Normal file
@@ -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 节。
|
||||
142
skills/yt-studio-auth-prep/scripts/login_profile.py
Normal file
142
skills/yt-studio-auth-prep/scripts/login_profile.py
Normal file
@@ -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()
|
||||
@@ -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 登录页。
|
||||
|
||||
## 选择运行分支
|
||||
|
||||
@@ -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`。
|
||||
|
||||
@@ -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 步的运行命令可直接执行。
|
||||
|
||||
Reference in New Issue
Block a user