feat(scripts): 添加批量生成 YouTube Studio 内容管理器 URL 的脚本

2026-08-21 18:21:03 +08:00
commit c1b39e9466
29 changed files with 4020 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,127 @@
+# YouTube Studio 工具集
+
+本项目包含三个 Trae CN 技能（skills）及配套 Python 脚本，覆盖 YouTube Studio 内容管理器（Content Manager）分析的完整工作流：**环境准备 → 批量生成报告 URL → 脚本化下载分析数据**。
+
+仅支持 Windows。
+
+## 技能清单
+
+| 技能 | 用途 | 触发示例 |
+|---|---|---|
+| `uv-env-setup` | 用 uv 准备并维护 Python 运行环境（`pyproject.toml` → `uv sync` → `uv run`） | 「帮我准备环境」「装依赖」 |
+| `yt-studio-url-builder` | 根据需求清单（CSV/Excel）批量拼接 explore 报告 URL | 「根据这份清单生成 Studio URL」 |
+| `youtube-studio-csv-download` | 复用已登录浏览器会话，脚本化下载分析 CSV（zip） | 「用我的 Chrome 会话下载这份 CSV」 |
+
+## 项目结构
+
+```
+├── skills/                        # 技能源目录（安装脚本从这里复制）
+│   ├── uv-env-setup/              #   环境准备技能
+│   │   ├── SKILL.md
+│   │   └── references/troubleshooting.md
+│   ├── yt-studio-url-builder/     #   URL 拼接技能
+│   │   ├── SKILL.md
+│   │   ├── references/            #     input-guide.md（输入清单指南）、troubleshooting.md
+│   │   └── scripts/               #     build_studio_urls.py、countries.json
+│   └── youtube-studio-csv-download/  # CSV 下载技能
+│       ├── SKILL.md
+│       ├── references/troubleshooting.md
+│       └── scripts/youtube_export_download.py
+├── scripts/
+│   ├── install-skills.bat         # 傻瓜安装入口（双击运行）
+│   └── install-skills.ps1         # 安装逻辑
+├── docs/
+│   ├── install-skills.md          # 安装详细说明
+│   └── adr/                       # 架构决策记录
+├── assets/                        # 需求输入示例文件
+├── pyproject.toml                 # Python 依赖唯一事实来源（pandas/openpyxl/playwright）
+└── uv.lock                        # uv 依赖锁定（可复现环境）
+```
+
+## 快速开始
+
+### 前置条件
+
+- Windows
+- [Trae CN](https://www.trae.cn/) 已安装
+- [uv](https://docs.astral.sh/uv/) 已安装（未装可 `winget install astral-sh.uv`，装完重开终端）
+
+### 第 1 步：安装技能到 Trae CN
+
+双击运行：
+
+```
+scripts\install-skills.bat
+```
+
+看到 `全部安装成功` 即完成。脚本会把 `skills\` 下全部技能复制到 `%USERPROFILE%\.trae-cn\skills\`；同名旧版自动备份到 `~\.trae-cn\skills-backup\`，不会丢数据。详细说明见 [docs/install-skills.md](docs/install-skills.md)。
+
+### 第 2 步：准备 Python 运行环境
+
+项目根目录执行：
+
+```powershell
+uv sync
+```
+
+uv 自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright）。本机无兼容 Python 时 uv 会自动下载托管 Python（要求 ≥3.10）。
+
+### 第 3 步：开始使用
+
+重启 Trae CN（或新建会话）后，在对话中直接说需求即可触发对应技能，例如：
+
+> 根据这份清单批量生成 Studio URL
+
+把需求整理成 CSV/Excel（格式见 `skills/yt-studio-url-builder/references/input-guide.md`，示例见 `assets/需求输入示例.xlsx`），技能会引导生成 URL 清单。
+
+> 用我的 Chrome 会话下载这份分析 CSV
+
+技能会用 Playwright 复用已登录的浏览器会话，自动点击导出并保存 zip。
+
+> 帮我准备/重建环境
+
+技能会引导走 `uv sync` 与验证流程。
+
+所有脚本统一用 `uv run python <脚本>` 执行（自动使用项目环境，免激活、免手动装依赖）。
+
+## 后续优化与修改
+
+### 改 URL 固定参数
+
+指标、粒度、维度、排序等固定参数集中在 `skills/yt-studio-url-builder/scripts/build_studio_urls.py` 顶部的 `CONFIG` 字典中，**单点维护**——改完重跑脚本即生效，需求清单无需变动。
+
+### 扩充国家映射
+
+中文国家名 → ISO 代码的映射在 `skills/yt-studio-url-builder/scripts/countries.json`，直接追加条目即可；映射外的两位 ISO 代码（如 `US`）会原样透传。
+
+### 新增/修改依赖
+
+只改根目录 `pyproject.toml` 的 `dependencies`，然后 `uv sync` 更新 `uv.lock`。不要 `pip install` 直装（绕过 lock，环境不可复现）。
+
+### 修改技能并重新安装
+
+技能就是在 `skills/` 下编辑的 Markdown + 脚本。改完后重新双击 `scripts\install-skills.bat` 即可同步到 Trae CN（旧版自动备份）。建议遵循的写法：
+
+- 每个技能一个文件夹，必须含 `SKILL.md`（frontmatter 的 `name` + `description`，description 写清触发场景）。
+- 大块参考内容放 `references/` 子目录，`SKILL.md` 中按需引用（渐进披露）。
+- 每个步骤给出可检查的完成判据，避免半途而废。
+- 同一信息只在一处维护（单一事实来源），避免重复表述。
+
+### 回滚 / 卸载
+
+- 回滚：把 `~\.trae-cn\skills-backup\<技能名>-<时间戳>\` 复制回 `~\.trae-cn\skills\<技能名>\`。
+- 卸载：删除 `~\.trae-cn\skills\` 下对应技能文件夹。
+- 重置环境：删除项目根 `.venv\` 后重新 `uv sync`。
+
+## 常见问题
+
+- **双击 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` 前缀。
+
+更多排查见各技能的 `references/troubleshooting.md`。
+
+-----
+
+UPDATE: 2026-08-21