From 05b2fc8d656356d63c1f5e40e37cecb9e790e805 Mon Sep 17 00:00:00 2001 From: Sidney Zhang Date: Wed, 30 Sep 2026 10:22:05 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=9B=B4=E6=96=B0=E6=8A=80=E8=83=BD?= =?UTF-8?q?=E5=BC=95=E7=94=A8=E5=90=8D=E7=A7=B0=E5=B9=B6=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=20yt-studio-auth-prep=20=E7=99=BB=E5=BD=95=E8=84=9A=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 4 +- README.md | 64 +++++--- docs/install-skills.md | 13 +- docs/usage-guide.md | 16 +- pyproject.toml | 2 +- scripts/youtube_export_interceptor.py | 2 +- skills/uv-env-setup/SKILL.md | 95 ------------ skills/youtube-studio-csv-download/SKILL.md | 2 +- .../references/troubleshooting.md | 2 +- .../scripts/youtube_export_download.py | 2 +- skills/yt-download-place/SKILL.md | 130 ++++++++++++++++ .../references/troubleshooting.md | 46 +++--- skills/yt-studio-auth-prep/SKILL.md | 77 ++++++++++ .../references/troubleshooting.md | 70 +++++++++ .../scripts/login_profile.py | 142 ++++++++++++++++++ skills/yt-studio-groupid-lookup/SKILL.md | 2 +- .../references/troubleshooting.md | 2 +- skills/yt-studio-url-builder/SKILL.md | 2 +- uv.lock | 2 +- 19 files changed, 513 insertions(+), 162 deletions(-) delete mode 100644 skills/uv-env-setup/SKILL.md create mode 100644 skills/yt-download-place/SKILL.md rename skills/{uv-env-setup => yt-download-place}/references/troubleshooting.md (56%) create mode 100644 skills/yt-studio-auth-prep/SKILL.md create mode 100644 skills/yt-studio-auth-prep/references/troubleshooting.md create mode 100644 skills/yt-studio-auth-prep/scripts/login_profile.py diff --git a/.gitignore b/.gitignore index d1366e3..ea28786 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,6 @@ .venv/ adr/ __pycache__/ -.pytest_cache/ \ No newline at end of file +.pytest_cache/ +.chrome-profile-yt/ +StudioSkills*.zip \ No newline at end of file diff --git a/README.md b/README.md index 6992a27..5f239bc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # YouTube Studio 工具集 -本项目包含四个 Trae CN 技能（skills）及配套 Python 脚本，覆盖 YouTube Studio 内容管理器（Content Manager）分析的完整工作流：**环境准备 → 批量生成报告 URL → 群组名解析实体 ID → 脚本化下载分析数据**。 +本项目包含五个技能（skills）及配套 Python 脚本，覆盖 YouTube Studio 内容管理器（Content Manager）分析的完整工作流：**工作区准备 → 登录态与鉴权套件预置（每工作区一次） → 群组名解析实体 ID → 批量生成报告 URL → 脚本化下载分析数据**。 仅支持 Windows。 @@ -8,18 +8,23 @@ | 技能 | 用途 | 触发示例 | |---|---|---| -| `uv-env-setup` | 用 uv 准备并维护 Python 运行环境（`pyproject.toml` → `uv sync` → `uv run`） | 「帮我准备环境」「装依赖」 | +| `yt-download-place` | 在当前目录或指定路径创建 uv 项目工作区（`uv add` 装齐 pandas/openpyxl/playwright/requests → `uv run`），承载各技能脚本的运行环境 | 「准备工作区」「建下载目录」 | +| `yt-studio-auth-prep` | 在工作区预置登录态与鉴权套件：创建调试用户目录 `.profile` 并完成 YouTube 登录，捕获内容所有者套件 `bundles.json` | 「准备工作区登录」「捕获/更新 bundles.json」 | +| `yt-studio-groupid-lookup` | 把一批群组名批量解析为 entity_id（groupId），并标注归属的内容所有者（可用 `bundles.json` 离线回放） | 「把这些群组名查成 Group ID」 | | `yt-studio-url-builder` | 根据需求清单（CSV/Excel）批量拼接 explore 报告 URL | 「根据这份清单生成 Studio URL」 | -| `youtube-studio-csv-download` | 复用已登录浏览器会话，脚本化下载分析 CSV（zip） | 「用我的 Chrome 会话下载这份 CSV」 | -| `yt-studio-groupid-lookup` | 把一批群组名批量解析为 entity_id（groupId），并标注归属的内容所有者 | 「把这些群组名查成 Group ID」 | +| `youtube-studio-csv-download` | 复用已登录浏览器会话（`.profile`），脚本化下载分析 CSV（zip） | 「用我的 Chrome 会话下载这份 CSV」 | ## 项目结构 ``` ├── skills/ # 技能源目录（安装脚本从这里复制） -│ ├── uv-env-setup/ # 环境准备技能 +│ ├── yt-download-place/ # 下载工作区技能（创建 uv 项目结构） │ │ ├── SKILL.md │ │ └── references/troubleshooting.md +│ ├── yt-studio-auth-prep/ # 登录态与套件预置技能（.profile + bundles.json） +│ │ ├── SKILL.md +│ │ ├── references/troubleshooting.md +│ │ └── scripts/login_profile.py │ ├── yt-studio-url-builder/ # URL 拼接技能 │ │ ├── SKILL.md │ │ ├── references/ # input-guide.md（输入清单指南）、troubleshooting.md @@ -39,7 +44,7 @@ │ ├── install-skills.md # 安装详细说明 │ └── adr/ # 架构决策记录 ├── assets/ # 需求输入示例文件 -├── pyproject.toml # Python 依赖唯一事实来源（pandas/openpyxl/playwright） +├── pyproject.toml # Python 依赖唯一事实来源（pandas/openpyxl/playwright/requests） └── uv.lock # uv 依赖锁定（可复现环境） ``` @@ -49,7 +54,7 @@ - Windows - agent 之一：[Trae CN](https://www.trae.cn/) 或 [ZCode](https://github.com/ZhipuAI)（技能装到对应用户级目录） -- [uv](https://docs.astral.sh/uv/) 已安装（未装可 `winget install astral-sh.uv`，装完重开终端；当前会话不识别时先跑 `python -m uv`，详见 uv-env-setup 技能） +- [uv](https://docs.astral.sh/uv/) 已安装（未装可 `winget install astral-sh.uv`，装完重开终端；当前会话不识别时先跑 `python -m uv`，详见 yt-download-place 技能） ### 第 1 步：安装技能 @@ -72,28 +77,45 @@ scripts\install-skills.bat -Agent all -Skills yt-studio-url-builder,youtube-stud scripts\install-skills.bat -DryRun ``` -### 第 2 步：准备 Python 运行环境 +### 第 2 步：准备工作区 -两种模式按场景二选一（细节与回退链见 `skills/uv-env-setup/SKILL.md`）： +用 `yt-download-place` 技能在项目根或任意指定目录创建 uv 项目工作区（细节与回退链见 `skills/yt-download-place/SKILL.md`）： -- **项目环境**（在项目内跑整套流程）：项目根执行 `uv sync`，之后统一 `uv run python <脚本>`。uv 自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright、requests）；本机无兼容 Python 时 uv 会自动下载托管 Python（要求 ≥3.10）。 -- **单脚本模式**（技能已装到用户级目录、脱离项目使用）：什么都不用配——脚本头部带 PEP 723 内联依赖声明，直接 `uv run <脚本路径>` 即可。 +- **项目环境**（在工作区内跑整套流程）：技能建好 `pyproject.toml` + `assets/` + `data/` + `.gitignore` 后执行 `uv add pandas openpyxl playwright requests`，生成 `.venv\` 与 `uv.lock`，之后统一 `uv run python <脚本>`。`uv add` 幂等，复用已有 pyproject 的工作区只补缺失包；本机无兼容 Python 时 uv 会自动下载托管 Python（要求 ≥3.10）。 +- **单脚本模式**（技能已装到用户级目录、脱离工作区使用）：什么都不用配——脚本头部带 PEP 723 内联依赖声明，直接 `uv run <脚本路径>` 即可。 -### 第 3 步：开始使用 +### 第 3 步：预置登录态与套件（每个工作区一次） + +用 `yt-studio-auth-prep` 技能在工作区备好两项环境级产物（细节见 `skills/yt-studio-auth-prep/SKILL.md`），之后的查 ID、生成 URL、下载数据全部复用： + +- **调试用户目录 `.profile`**：在工作区创建 `/.profile`，打开浏览器完成一次 YouTube 账号登录，供 csv-download、groupid-lookup 复用登录态；浏览器品牌（chrome/msedge）一经选定全工作区统一。 +- **鉴权套件 `bundles.json`**：提供内容所有者分析页 URL（可多个），在线捕获鉴权套件存到 `/bundles.json`，供 groupid-lookup 离线回放（无需再开浏览器）。 + +日常使用无需重复本步；仅当登录态失效（下游跳 Google 登录页）或套件过期（回放全量 401）时，重跑对应步骤刷新。 + +### 第 4 步：开始使用 重启对应 agent（或新建会话）后，在对话中直接说需求即可触发对应技能，例如： +> 帮我准备工作区/重建环境 + +技能会在当前或指定目录创建 uv 工作区并完成验证（项目环境 / 单脚本模式二选一）。 + +> 帮我准备这个工作区的 YouTube 登录目录和所有者套件 + +技能会创建 `.profile` 并引导完成一次 YouTube 登录，再按所有者分析页 URL 捕获套件到 `bundles.json`（即第 3 步，日常无需重复）。 + +> 把这些群组名解析成 entity_id + +**清单里只有群组名时先走这一步补 ID**；已预置 `bundles.json` 时离线回放，无需浏览器。 + > 根据这份清单批量生成 Studio URL -把需求整理成 CSV/Excel（格式见 `skills/yt-studio-url-builder/references/input-guide.md`，示例见 `assets/需求输入示例.xlsx`），技能会引导生成 URL 清单。**清单里只有群组名时，先说「帮我把这些群组名解析成 entity_id」走 groupid-lookup 技能补 ID**，再生成 URL。 +把需求整理成 CSV/Excel（格式见 `skills/yt-studio-url-builder/references/input-guide.md`，示例见 `assets/需求输入示例.xlsx`），技能会引导生成 URL 清单。 > 用我的 Chrome 会话下载这份分析 CSV -技能会用 Playwright 复用已登录的浏览器会话，自动点击导出并保存 zip。 - -> 帮我准备/重建环境 - -技能会引导选择运行分支（项目环境 / 单脚本模式）并完成验证。 +技能会用 Playwright 复用 `.profile` 登录态（或你指定的浏览器会话），自动点击导出并保存 zip。 ## 后续优化与修改 @@ -129,7 +151,7 @@ scripts\install-skills.bat -DryRun ### 新增/修改依赖 -只改根目录 `pyproject.toml` 的 `dependencies`，然后 `uv sync` 更新 `uv.lock`。不要 `pip install` 直装（绕过 lock，环境不可复现）。 +新增依赖用 `uv add <包>`（自动更新根目录 `pyproject.toml` 与 `uv.lock`）。不要 `pip install` 直装（绕过 lock，环境不可复现）。 ### 修改技能并重新安装 @@ -151,10 +173,10 @@ scripts\install-skills.bat -DryRun - **双击 bat 闪退**：在 PowerShell 中手动运行 `scripts\install-skills.bat` 查看报错。 - **装了技能不触发**：需重启 Trae CN 或新建会话。 - **`uv sync` 拉包慢**：国内镜像 `$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"` 后重试。 -- **技能脚本报 `ModuleNotFoundError`**：项目根执行 `uv sync`，或确认命令用了 `uv run` 前缀。 +- **技能脚本报 `ModuleNotFoundError`**：项目根执行 `uv add pandas openpyxl playwright requests` 补齐缺包，或确认命令用了 `uv run` 前缀。 更多排查见各技能的 `references/troubleshooting.md`。 ----- -UPDATE: 2026-08-24 +UPDATE: 2026-09-30 diff --git a/docs/install-skills.md b/docs/install-skills.md index f13c947..82b2e69 100644 --- a/docs/install-skills.md +++ b/docs/install-skills.md @@ -14,7 +14,8 @@ | 技能 | 用途 | |---|---| -| `uv-env-setup` | 用 uv 准备并维护 Python 运行环境（项目环境 / 单脚本 PEP 723 模式） | +| `yt-download-place` | 在当前目录或指定路径创建 uv 项目工作区，承载各技能脚本的 uv 运行环境（项目环境 / 单脚本 PEP 723 模式） | +| `yt-studio-auth-prep` | 在工作区预置登录态与鉴权套件：调试用户目录 `.profile`（YouTube 登录）+ 内容所有者套件 `bundles.json` | | `yt-studio-url-builder` | 根据需求清单（CSV/Excel）批量生成 YouTube Studio 内容管理器 explore URL | | `yt-studio-groupid-lookup` | 把一批群组名批量解析为 entity_id（groupId），并标注归属的内容所有者 | | `youtube-studio-csv-download` | 复用已登录浏览器会话，脚本化下载 YouTube Studio 分析 CSV（zip） | @@ -71,15 +72,17 @@ scripts\install-skills.bat -Agent trae-cn -DryRun - **Trae CN**：用户级技能目录即上表；重启 Trae CN 或新建会话后生效。 - **ZCode**：技能落在 `~\.zcode\skills\` 后由 ZCode 自动发现（本机会话中已验证）；新建会话后生效。zcode 环境里的同名工程技能可能遮蔽用户级技能，排查时注意优先级。 -- **终端方言**：两个 agent 都可能在 PowerShell 或 Git Bash 里执行命令。所有 SKILL.md 的示例统一用正斜杠路径 + 引号写法，两边通用；uv-env-setup 提供 PATH 刷新的两种方言写法。 -- **通用兜底**：无论哪个 agent，跑脚本前都先按 `uv-env-setup` 技能确认 uv 分支（项目环境 / 单脚本模式 / python -m uv 回退）。 +- **终端方言**：两个 agent 都可能在 PowerShell 或 Git Bash 里执行命令。所有 SKILL.md 的示例统一用正斜杠路径 + 引号写法，两边通用；yt-download-place 提供 PATH 刷新的两种方言写法。 +- **通用兜底**：无论哪个 agent，跑脚本前都先按 `yt-download-place` 技能备好 uv 环境（工作区 / 单脚本模式 / python -m uv 回退）。 ## 验证 1. 重启对应 agent（或新建会话）。 2. 对话中直接提及技能名或相关意图，例如： - - 「帮我准备环境」→ `uv-env-setup` + - 「帮我准备工作区」→ `yt-download-place` + - 「帮我准备 YouTube 登录目录和所有者套件」→ `yt-studio-auth-prep` - 「根据这份清单批量生成 Studio URL」→ `yt-studio-url-builder` + - 「把这些群组名查成 Group ID」→ `yt-studio-groupid-lookup` - 「用我的 Chrome 会话下载这份分析 CSV」→ `youtube-studio-csv-download` ## 更新与卸载 @@ -98,5 +101,5 @@ scripts\install-skills.bat -Agent trae-cn -DryRun ## 注意 -- 运行时依赖不随技能安装：脚本型技能的 Python 依赖由两层机制承接——项目根 `pyproject.toml`（项目环境）或脚本头部 PEP 723 内联声明（单脚本模式），首次使用按 `uv-env-setup` 技能执行即可。 +- 运行时依赖不随技能安装：脚本型技能的 Python 依赖由两层机制承接——工作区 `pyproject.toml`（项目环境）或脚本头部 PEP 723 内联声明（单脚本模式），首次使用按 `yt-download-place` 技能建好工作区即可。 - 安装脚本仅支持 Windows（路径与命令均按 Windows 编写）。 diff --git a/docs/usage-guide.md b/docs/usage-guide.md index c2f1b85..1334fe2 100644 --- a/docs/usage-guide.md +++ b/docs/usage-guide.md @@ -4,10 +4,11 @@ 如果你需要完成上面这个常见的应用场景，那么，本技能组中的所有技能都是必须的，包括： -- `uv-env-setup`：用于设置必要的 Python 运行环境，以便下面的技能所带的脚本可以正确运行。 +- `yt-download-place`：用于在当前或指定目录创建 uv 项目工作区，为下面的技能所带的脚本提供运行环境。 +- `yt-studio-auth-prep`：用于在工作区预置登录态与鉴权套件——调试用户目录 `.profile`（完成一次 YouTube 账号登录）与内容所有者鉴权套件 `bundles.json`，供后续所有任务复用。 +- `yt-studio-groupid-lookup`：用于从群组名称中提取实体 ID（已预置 `bundles.json` 时离线回放）。 - `yt-studio-url-builder`：用于构建 YouTube Studio 分析页面 URL。 - `youtube-studio-csv-download`：用于下载 YouTube Studio 分析数据。 -- `yt-studio-groupid-lookup`：用于从群组名称中提取实体 ID。 对于这样一个任务，对于只有一个群组数据需要下载的情况，这组技能并没有人工下载来的快，更适合批量下载众多群组的数据。也就是，你需要Agent帮你从YouTube Studio的分析页面中，下载众多群组的众多情况的数据时，这组技能可以更好的指导Agent完成工作，也能很好的加速下载。 @@ -20,7 +21,14 @@ 这里，数据需求，就是你需要下载哪些指标的数据，以及你需要哪些时间段的数据，也包括需要筛选什么信息，同时，你需要的是什么细分的数据，例如：频道数据、内容数据还是其他的数据。 -下一步，是获取群组的实体 ID（groupid）。你可以让Agent使用 `yt-studio-groupid-lookup` 技能，来从群组名称中提取实体 ID。这样，前期的准备就算基本完成了。 +有了上面这些东西之后，先做一次环境预置（每个工作区只需一次）： + +1. 指示Agent用 `yt-download-place` 创建下载工作区（uv 项目环境，各技能脚本统一以 `uv run` 运行）。 +2. 指示Agent用 `yt-studio-auth-prep` 完成两项预置：在工作区创建调试用户目录 `.profile` 并完成一次 YouTube 账号登录；再提供内容所有者分析页 URL，把鉴权套件捕获到工作区的 `bundles.json`。 + +预置完成后，后续所有任务都在同一个工作区里复用这份登录态与套件。只有当登录态失效（下载时跳到 Google 登录页）或套件过期（查 Group ID 时全量 401）时，才需要回到这一步刷新。 + +下一步，是获取群组的实体 ID（groupid）。你可以让Agent使用 `yt-studio-groupid-lookup` 技能，来从群组名称中提取实体 ID；已预置 `bundles.json` 时走离线回放，全程无需打开浏览器。这样，前期的准备就算基本完成了。 然后，指示Agent基于你的需求与获取的实体ID，创建符合需求的分析页面 URL。 @@ -30,6 +38,8 @@ ### 检查与确认 +预置阶段的检查：`.profile` 登录完成后技能会打印「登录成功」；`bundles.json` 中套件数量应与你提供的所有者分析页 URL 数量一致，可以要求Agent列出每个套件的 ownerId 清单供你核对。 + 常用的检查就是，需要下载的文件数量需要对应于生成的URL数量。如果数量不对应，那么，就需要检查Agent是否正确生成了URL，或者是否有任何错误或异常情况发生。 另外，在URL生成过程中，也需要检查Agent是否正确解析了群组名称，以及是否有任何错误或异常情况发生。可以要求Agent抽样几个URL打开浏览器进行浏览确认。这个方式也可以确认Agent当前是否正确的读取了浏览器的登录状态，以避免因为登录状态过期而导致的下载失败。 \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index db9dd15..737f442 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "StudioLift" -version = "0.4.0" +version = "0.5.3" description = "StudioLift ：一个 YouTube Studio 工具集，提供 URL 批量拼接、分析 CSV 导出下载等功能。" requires-python = ">=3.10" dependencies = [ diff --git a/scripts/youtube_export_interceptor.py b/scripts/youtube_export_interceptor.py index 0fa568f..4517aba 100644 --- a/scripts/youtube_export_interceptor.py +++ b/scripts/youtube_export_interceptor.py @@ -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 \"\" " "--channel chrome --user-data-dir <你的 Chrome User Data 目录>\n" diff --git a/skills/uv-env-setup/SKILL.md b/skills/uv-env-setup/SKILL.md deleted file mode 100644 index 229dbbc..0000000 --- a/skills/uv-env-setup/SKILL.md +++ /dev/null @@ -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//.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)。 diff --git a/skills/youtube-studio-csv-download/SKILL.md b/skills/youtube-studio-csv-download/SKILL.md index 89e611d..0343aab 100644 --- a/skills/youtube-studio-csv-download/SKILL.md +++ b/skills/youtube-studio-csv-download/SKILL.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：确认登录态来源（二选一） diff --git a/skills/youtube-studio-csv-download/references/troubleshooting.md b/skills/youtube-studio-csv-download/references/troubleshooting.md index 3052985..4e2288f 100644 --- a/skills/youtube-studio-csv-download/references/troubleshooting.md +++ b/skills/youtube-studio-csv-download/references/troubleshooting.md @@ -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`。 ## 运行过程 diff --git a/skills/youtube-studio-csv-download/scripts/youtube_export_download.py b/skills/youtube-studio-csv-download/scripts/youtube_export_download.py index 0fa568f..4517aba 100644 --- a/skills/youtube-studio-csv-download/scripts/youtube_export_download.py +++ b/skills/youtube-studio-csv-download/scripts/youtube_export_download.py @@ -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 \"\" " "--channel chrome --user-data-dir <你的 Chrome User Data 目录>\n" diff --git a/skills/yt-download-place/SKILL.md b/skills/yt-download-place/SKILL.md new file mode 100644 index 0000000..09e1085 --- /dev/null +++ b/skills/yt-download-place/SKILL.md @@ -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）。 + +目标目录 = 用户指定路径，未指定则用当前目录；目录不存在时先创建。目标结构： + +``` +/ +├── .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：搭建工作区骨架 + +在 `` 下创建两个数据目录（两种 shell 写法二选一；路径统一正斜杠 + 引号，两边通用）： + +```powershell +# PowerShell +New-Item -ItemType Directory -Force "/assets", "/data" | Out-Null +``` + +```bash +# Git Bash / zsh +mkdir -p "/assets" "/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 仓库**：`/.git` 不存在时执行 `git init`；已是仓库则复用。 + +**完成判据**：`` 下存在 `assets\`、`data\`、`pyproject.toml`、`.gitignore`、`README.md`、`.git`，且原有文件未被改动。 + +## 步骤 3：补齐依赖并同步环境 + +`` 下执行： + +```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，`` 下出现 `.venv\` 与 `uv.lock`，且 `pyproject.toml` 的 `dependencies` 含这四个包。 + +## 步骤 4：验证并交付 + +```powershell +uv run python -c "import pandas, openpyxl, playwright, requests; print('env OK')" +``` + +**完成判据（全局）**：打印 `env OK`。向用户报告工作区路径，此后约定： + +- 其他技能脚本都在 `` 下用 `uv run python <脚本>` 执行；不裸调 `python`、不手动激活 venv、不向全局 pip 装依赖。 +- 中间数据写 `/assets/`，下载数据写 `/data/`。 +- 新增依赖：`uv add <包>`（唯一入口，禁止 pip 直装绕过 lock）。 + +## 排查 + +uv 不识别、国内镜像加速、`No solution found`、`.venv` 损坏重建、playwright 浏览器下载慢、无 uv 手动兜底等，查 [references/troubleshooting.md](references/troubleshooting.md)。 diff --git a/skills/uv-env-setup/references/troubleshooting.md b/skills/yt-download-place/references/troubleshooting.md similarity index 56% rename from skills/uv-env-setup/references/troubleshooting.md rename to skills/yt-download-place/references/troubleshooting.md index 711008b..6a0dc1f 100644 --- a/skills/uv-env-setup/references/troubleshooting.md +++ b/skills/yt-download-place/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`。 diff --git a/skills/yt-studio-auth-prep/SKILL.md b/skills/yt-studio-auth-prep/SKILL.md new file mode 100644 index 0000000..80a1000 --- /dev/null +++ b/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` 创建的工作区 `` 里： + +- **`.profile`**：`/.profile`，专用调试用户目录。登录一次 YouTube 账号后，`youtube-studio-csv-download`、`yt-studio-groupid-lookup` 都以 `--user-data-dir "/.profile"` 复用该登录态；浏览器需保持打开时也可带调试端口启动后改用 `--connect`。 +- **`bundles.json`**：`/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：确认工作区与浏览器品牌 + +- `` 必须已是 `yt-download-place` 工作区（存在 `pyproject.toml` 与 `.venv`）；没有就先跑该技能。 +- 与用户确认浏览器品牌 `chrome` / `msedge`（默认 `chrome`）。**品牌一经选定，该工作区所有下游命令的 `--channel` 必须一致**：`.profile` 与品牌绑定，混用会导致登录态异常。下文命令以 `chrome` 为例。 + +**完成判据**：`` 可用、品牌已确定。 + +## 步骤 2：创建 .profile 并完成登录 + +cwd 在 `` 下执行（目录不存在会自动创建；路径统一正斜杠 + 引号）： + +```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 "/.profile" +``` + +- 脚本打开可见浏览器窗口后交给用户：完成 Google/YouTube 登录即可（支持两步验证），脚本轮询确认 `studio.youtube.com` 不再跳登录页，成功后自动关窗退出。 +- 默认等待 600 秒（`--timeout-seconds` 可调）；超时不丢进度，直接重跑同一命令继续。 + +**完成判据**：打印 `[登录] 登录成功`，退出码 0；`/.profile` 下出现浏览器 profile 文件（如 `Default/`）。 + +## 步骤 3：捕获 bundles.json + +从用户处收集内容所有者分析页 URL（`studio.youtube.com/owner//analytics?...`，可多个）。先确保 `/bundles.json` 存在（`--bundles` 指向不存在的文件会报错）： + +```powershell +if (!(Test-Path "/bundles.json")) { Set-Content -Path "/bundles.json" -Value "[]" -Encoding utf8 } +``` + +cwd 在 `` 下执行（不带 `--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 "" --url "" --bundles "/bundles.json" --save-bundles "/bundles.json" --user-data-dir "/.profile" --channel chrome +``` + +- 捕获借用 `yt-studio-groupid-lookup` 的在线捕获能力：自动触发群组搜索、过滤 HTTP/2 伪头、捕获时校验鉴权头。页面交互细节见该技能。 +- 首次准备建议一次传齐所有 owner URL；之后刷新/新增所有者都是重跑同一条命令。 + +**完成判据**：每个所有者打印 `[捕获] 套件就绪：owner=...`，末尾打印 `[套件] 已保存 N 个所有者套件 -> /bundles.json`，且捕获过程无「缺少 Authorization/Cookie/…」警告（出现即按排查重捕获）。 + +## 步骤 4：校验产物并交付 + +```powershell +uv run python -c "import json;bs=json.load(open('/bundles.json',encoding='utf-8'));print('套件',len(bs),'个:',[b.get('ownerId') for b in bs])" +``` + +**完成判据（全局）**：套件数量与传入的 owner URL 数一致（同 ownerId 自动去重合并），ownerId 列表符合预期。向用户报告后续用法： + +- 登录态：csv-download 用 `--user-data-dir "/.profile" --channel chrome`；浏览器不能关时，`chrome.exe --user-data-dir="/.profile" --remote-debugging-port=9222` 启动后各技能改传 `--connect http://localhost:9222`。 +- 套件：groupid-lookup 回放用 `--bundles "/bundles.json"`。 +- 时效约定：套件是一次性凭据，回放全量 401 就重跑步骤 3；登录态失效重跑步骤 2。 + +## 排查 + +按 现象 → 原因 → 解决 逐条排查（登录超时、目录被占用、捕获警告、读取 bundles 失败、品牌切换等），查 [references/troubleshooting.md](references/troubleshooting.md)。 diff --git a/skills/yt-studio-auth-prep/references/troubleshooting.md b/skills/yt-studio-auth-prep/references/troubleshooting.md new file mode 100644 index 0000000..71623bb --- /dev/null +++ b/skills/yt-studio-auth-prep/references/troubleshooting.md @@ -0,0 +1,70 @@ +# 排查：.profile 与 bundles.json + +先分清环节：步骤 2 的问题是「登录」，步骤 3 的问题是「捕获」，步骤 4 的问题是「产物数量」。下游技能报错（跳登录页 / 401）都回到本技能对应步骤修复。 + +## 步骤 2：登录 + +### 浏览器启动失败 / 目录被占用 +- 现象：`[!] 启动浏览器失败: ... ProcessSingleton / already in use`。 +- 原因：有同品牌浏览器正用着 `/.profile`——上次窗口没关（脚本异常中断）或手动开过。 +- 解决：任务管理器彻底退出该品牌浏览器进程后重跑；脚本正常结束会自动关掉自己开的窗口。 + +### 登录等待超时（默认 600 秒） +- 现象：`[!] 600 秒内未完成登录`。 +- 原因：用户没完成登录，或卡在验证码 / 两步验证。 +- 解决：`.profile` 已保留进度，直接重跑同一命令继续；等待不够就加大 `--timeout-seconds`。 + +### 显示登录成功，下游仍跳 Google 登录页 +- 现象：csv-download / groupid-lookup 运行时停在 accounts.google。 +- 原因：cookie 存在不等于会话有效（服务端已让该会话过期）；或下游 `--channel` 与建目录时品牌不一致。 +- 解决：先核对品牌一致，再重跑步骤 2 补登录一次；不要试图直接改 cookie 文件。 + +### 想换浏览器品牌 +- 现象：需要从 chrome 切到 msedge（或反之）。 +- 原因：`.profile` 与首次登录的品牌绑定，跨品牌复用会话异常。 +- 解决：删除 `/.profile`，用新品牌重跑步骤 2、步骤 3；bundles.json 会在重捕获时按 ownerId 覆盖更新。 + +## 步骤 3：捕获 + +### 报「读取 bundles 失败」 +- 现象：`[!] 读取 bundles 失败: ...`（FileNotFoundError）。 +- 原因：`--bundles` 指向的文件还不存在（首次捕获没先建空文件）。 +- 解决：`/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 节。 diff --git a/skills/yt-studio-auth-prep/scripts/login_profile.py b/skills/yt-studio-auth-prep/scripts/login_profile.py new file mode 100644 index 0000000..c982d38 --- /dev/null +++ b/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 "/.profile" --channel + - yt-studio-groupid-lookup : 同上（在线捕获套件时） + +用法（cwd 任意；目录不存在会自动创建）： + python login_profile.py --channel chrome --user-data-dir "/.profile" + python login_profile.py --channel msedge --user-data-dir "/.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="调试用户目录路径，如 /.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 必填，如 /.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() diff --git a/skills/yt-studio-groupid-lookup/SKILL.md b/skills/yt-studio-groupid-lookup/SKILL.md index eb2b782..c9a2902 100644 --- a/skills/yt-studio-groupid-lookup/SKILL.md +++ b/skills/yt-studio-groupid-lookup/SKILL.md @@ -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 登录页。 ## 选择运行分支 diff --git a/skills/yt-studio-groupid-lookup/references/troubleshooting.md b/skills/yt-studio-groupid-lookup/references/troubleshooting.md index 7e367f6..b010e20 100644 --- a/skills/yt-studio-groupid-lookup/references/troubleshooting.md +++ b/skills/yt-studio-groupid-lookup/references/troubleshooting.md @@ -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`。 diff --git a/skills/yt-studio-url-builder/SKILL.md b/skills/yt-studio-url-builder/SKILL.md index c9eb266..2295fd1 100644 --- a/skills/yt-studio-url-builder/SKILL.md +++ b/skills/yt-studio-url-builder/SKILL.md @@ -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 步的运行命令可直接执行。 diff --git a/uv.lock b/uv.lock index 374d492..ac4603f 100644 --- a/uv.lock +++ b/uv.lock @@ -815,7 +815,7 @@ wheels = [ [[package]] name = "studiolift" -version = "0.3.4" +version = "0.4.0" source = { virtual = "." } dependencies = [ { name = "openpyxl" },