初始发布: 21 个 skills (Claude Code / Codex / DSH)

youtube-download/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: youtube-download
+description: "Download YouTube videos at the highest available quality (up to 4K) as merged MP4 files with the best audio track (native Opus). Default spec: best video + best audio merged into one MP4 only — do not download a separate audio-only file unless the user explicitly asks for 音频/audio-only. Handles the modern yt-dlp requirements — a JS runtime (bun/deno/node) for YouTube's JS challenges, and browser cookies for videos blocked by bot detection / login / age gates. Use when asked to download, save, or grab a YouTube video, playlist item, or a high-quality/HD/4K copy of a YouTube URL."
+---
+
+# YouTube 高清下载 (youtube-download)
+
+用 `yt-dlp` 把 YouTube 视频下成本地最高画质 MP4（最高 4K），也可以只下最高音质音频。已经踩平了 2025/2026 年 yt-dlp 下 YouTube 的两个主要坑：需要 JS 运行时、以及机器人检测要 cookie。
+
+## 什么时候用
+
+用户给一个或多个 YouTube 链接，要求“下载 / 保存 / 下高清 / 下 4K / 下最高画质”时。
+
+## 默认规格（每次照此执行）
+
+- 默认只下「视频版」：最高画质视频（最高 4K）+ 最佳音质音轨（原生 Opus），合并成单个 MP4，存到用户「下载」文件夹。
+- 除非用户明确说「只要音频 / 音频版 / 单独下音频」，否则**不要**额外下载 audio-only 文件。
+- 链接带 `&list=` / `start_radio=1` 时默认只下当前这一个视频（`--no-playlist`），除非用户要求整个播放列表/电台。
+
+## 核心命令（能跑通的那条）
+
+```
+yt-dlp \
+  --cookies "cookies.txt" \                # 仅当视频需要登录/被机器人拦时必需，见下
+  --js-runtimes "bun:$(command -v bun)" \   # 必需：YouTube 现在要求解 JS 挑战（bun/deno/node 任选）
+  -f "bestvideo+bestaudio/best" \
+  --merge-output-format mp4 \
+  --ffmpeg-location "<ffmpeg bin 目录>" \   # 合并视频+音频需要 ffmpeg
+  -o "<输出目录>/%(title)s [%(height)sp].%(ext)s" \
+  --no-playlist \                          # 链接带 &list= 时只下当前这一个
+  "https://www.youtube.com/watch?v=VIDEO_ID"
+```
+
+**推荐直接用打包好的脚本**（自动准备工具、找 ffmpeg、带 cookie）：
+
+- Windows：`scripts/yt-download.ps1`
+- Linux/macOS：`scripts/yt-download.sh`
+
+```powershell
+# Windows 示例：下一个或多个视频到「下载」文件夹
+powershell -ExecutionPolicy Bypass -File scripts\yt-download.ps1 "https://www.youtube.com/watch?v=xxxx"
+powershell -ExecutionPolicy Bypass -File scripts\yt-download.ps1 URL1 URL2 URL3
+```
+
+```bash
+# Linux/macOS 示例
+bash scripts/yt-download.sh "https://www.youtube.com/watch?v=xxxx"
+```
+
+脚本行为：
+- 默认就是最高画质视频 + 最佳音质音轨合并 MP4；不会单独下载音频。
+- JS 运行时自动选 `bun`（已装）；没有则用 `deno`，再退到 `node`。也可用环境变量 `JS_RUNTIME=bun|deno|node` 指定。
+- 找不到 `yt-dlp`（Windows 版还会找 `deno`）会自动下载到脚本旁的 `bin/` 目录。
+- 自动探测 `ffmpeg`（PATH 里没有会提示安装）。
+- 如果脚本目录里存在 `cookies.txt`，会自动带上。
+- 输出文件名格式：`标题 [1080p].mp4`，默认存到当前用户「下载」文件夹（可用 `-OutDir` / `$2` 改）。
+
+## 三个关键坑（务必知道）
+
+1. **必须有 JS 运行时。** 否则报 `No supported JavaScript runtime could be found` 或直接 `Sign in to confirm you're not a bot`。装 `bun` / `deno` / `node` 任一即可（macOS 上已装 bun，脚本默认用 bun），或给 yt-dlp 传 `--js-runtimes "bun:路径"`。
+   - ⚠️ yt-dlp 已把 bun 标记为 deprecated，只支持 bun 1.2.11–1.3.14（本机 1.3.13 可用）。若以后升级 bun 或 yt-dlp 报 bun 不支持，用 `JS_RUNTIME=deno` / `JS_RUNTIME=node` 切换即可（deno 已随 brew 版 yt-dlp 装好）。
+
+2. **机器人检测 → 需要 cookie。** 如果 API 返回 `LOGIN_REQUIRED` / “Sign in to confirm you're not a bot” 且 0 个格式，就必须提供你 YouTube 账号的 cookie：
+   - 浏览器（登录着 YouTube）装扩展 **“Get cookies.txt LOCALLY”**（开源、纯本地不上传）。
+   - **切到 youtube.com 标签页**（当前激活），点扩展图标 → Export，导出 Netscape 格式的 `www.youtube.com_cookies.txt`。
+   - 把它改名/放成脚本目录下的 `cookies.txt`（或用 `--cookies` 指定路径）。
+   - **公开视频不需要 cookie**，脚本没检测到 cookie 也能下公开视频。
+
+3. **cookie 会过期/轮换。** 出现 `The provided YouTube account cookies are no longer valid` 时，按第 2 步重新导出覆盖 `cookies.txt` 即可。公开视频不受影响。
+
+## 输出编码说明
+
+YouTube 最高画质通常是 **AV1 视频 + Opus 音频**（封装成 mp4）。较新，VLC / PotPlayer / 新版系统播放器都能放；个别老设备放不了。需要更通用时：
+
+- 想要 H.264（兼容性最好，但 YouTube 上 H.264 最高只到 1080p）：把格式改成
+  `-f "bestvideo[vcodec^=avc1]+bestaudio[ext=m4a]/best[vcodec^=avc1]"`
+- 或下完后用 ffmpeg 转码成 H.264/H.265。
+
+## 小抄
+
+- 仅当用户明确要求音频时才用：
+  - 只下音频（m4a）：`-f "bestaudio[ext=m4a]/bestaudio" -x --audio-format m4a`
+  - 只下最高音质音频（保留 YouTube 原生 Opus，不转码、音质最好）：`-f "bestaudio/best" -o "%(title)s.%(ext)s"`
+- 限制最高 1080p：`-f "bestvideo[height<=1080]+bestaudio/best[height<=1080]"`
+- 整个播放列表：去掉 `--no-playlist`
+- 看有哪些格式：`-F`
+- 下字幕：`--write-subs --sub-langs "en,zh-Hans" --convert-subs srt`