名称： yt-dlp-downloader
描述： 使用 yt-dlp 从 YouTube、Bilibili、Twitter 等数千个网站下载视频。当用户提供视频链接并希望下载、提取音频（MP3）、下载字幕或选择视频质量时使用。触发短语包括："下载视频"、"download video"、"yt-dlp"、"YouTube"、"B站"、"抖音"、"提取音频"、"extract audio"。

yt-dlp 视频下载器

使用 yt-dlp 从数千个网站下载视频。

前置条件

下载前，请确保已安装必要的依赖：

# 检查 yt-dlp
which yt-dlp || echo "未安装 yt-dlp。请使用以下命令安装：pip install yt-dlp"

# 检查 ffmpeg（音频提取与格式合并所需）
which ffmpeg || echo "未安装 ffmpeg。请使用以下命令安装：brew install ffmpeg"

如果未安装，请先安装：

pip install yt-dlp
brew install ffmpeg  # macOS

快速开始

基本下载（最佳质量）

yt-dlp -P "~/Downloads/yt-dlp" "视频链接"

YouTube 下载（推荐 - 使用浏览器 Cookies）

YouTube 常因 403 错误阻止直接下载。建议始终使用浏览器 Cookies：

yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "YouTube链接"

支持的浏览器：chrome、firefox、safari、edge、brave、opera

自定义保存路径

yt-dlp -P "/保存路径" -o "%(title)s.%(ext)s" "视频链接"

常用任务

1. 下载视频（默认 - 最佳质量）

yt-dlp -P "~/Downloads/yt-dlp" "视频链接"

2. 仅提取音频（MP3）

yt-dlp -P "~/Downloads/yt-dlp" -x --audio-format mp3 "视频链接"

3. 下载字幕

yt-dlp -P "~/Downloads/yt-dlp" --write-subs --sub-langs all "视频链接"

4. 下载指定画质

720p：

yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo[height<=720]+bestaudio/best[height<=720]" "视频链接"

1080p：

yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" "视频链接"

最佳可用画质：

yt-dlp -P "~/Downloads/yt-dlp" -f "bestvideo+bestaudio/best" "视频链接"

5. 列出可用格式（下载前查看）

yt-dlp -F "视频链接"

然后根据格式 ID 下载：

yt-dlp -P "~/Downloads/yt-dlp" -f 格式ID "视频链接"

6. 下载播放列表

# 下载整个播放列表
yt-dlp -P "~/Downloads/yt-dlp" -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "播放列表链接"

# 下载指定范围（例如第 1-5 项）
yt-dlp -P "~/Downloads/yt-dlp" -I 1:5 "播放列表链接"

7. 下载视频缩略图

yt-dlp -P "~/Downloads/yt-dlp" --write-thumbnail "视频链接"

工作流程

当用户提供视频链接时：

1. 识别平台：

   • YouTube/YouTube Music → 务必使用 --cookies-from-browser chrome
   • 其他网站 → 先尝试不使用 Cookies

2. 询问需求（如未明确）：

   • 仅下载视频？
   • 仅提取音频？
   • 需要字幕？
   • 指定画质？

3. 根据需求构建命令

4. 执行下载：使用 Shell 工具，并设置 required_permissions: ["all", "network"]

5. 处理错误：

   • 403 禁止访问 → 使用 --cookies-from-browser 重试
   • 连接问题 → yt-dlp 会自动续传，直接重试即可
   • 格式不可用 → 使用 -F 列出格式，然后选择

6. 报告结果：文件保存位置及任何错误信息

示例交互

用户："帮我下载这个视频 https://www.youtube.com/watch?v=xxx"

回复：

# YouTube - 使用 Cookies 避免 403 错误
yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "https://www.youtube.com/watch?v=xxx"

用户："下载这个视频的音频 https://www.bilibili.com/video/xxx"

回复：

# Bilibili - 提取音频为 MP3
yt-dlp -P "~/Downloads/yt-dlp" -x --audio-format mp3 "https://www.bilibili.com/video/xxx"

用户："下载这个 Twitter 视频 https://twitter.com/xxx/status/123"

回复：

# Twitter/X - 通常可直接下载
yt-dlp -P "~/Downloads/yt-dlp" "https://twitter.com/xxx/status/123"

支持的网站

yt-dlp 支持数千个网站，包括：
* YouTube, YouTube Music
* Bilibili (B站)
* Twitter/X
* TikTok, Douyin (抖音)
* Vimeo
* Twitch
* 以及更多...

完整列表：https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md

故障排除

常见错误与解决方案

错误："yt-dlp: command not found"

pip install yt-dlp

错误："ffmpeg not found"（音频提取时）

brew install ffmpeg  # macOS

错误：HTTP 403 禁止访问（YouTube）

这是 YouTube 最常见的错误。请始终为 YouTube 使用 Cookies：

# 推荐用于 YouTube 的方法
yt-dlp -P "~/Downloads/yt-dlp" --cookies-from-browser chrome "YouTube链接"

支持的浏览器：chrome、firefox、safari、edge、brave、opera

错误：视频不可用或地区限制

# 尝试使用浏览器 Cookies
yt-dlp --cookies-from-browser chrome "视频链接"

# 或使用特定格式
yt-dlp -F "视频链接"  # 先列出格式
yt-dlp -f 格式ID "视频链接"

错误：下载持续失败

# 更新 yt-dlp 到最新版本
pip install -U yt-dlp

# 强制使用 IPv4（有时有助于解决连接问题）
yt-dlp -4 "视频链接"

最佳实践

1. YouTube 下载：始终使用 --cookies-from-browser chrome
2. 大文件下载：yt-dlp 会自动续传，中断后重试即可
3. 保持 yt-dlp 更新：定期运行 pip install -U yt-dlp
4. 先检查格式：不确定时，先用 -F 命令查看可用格式