Skills
skills/lxmxhh/cc-skill-youtube-download/youtube-download

youtube-download

SKILL.md

YouTube 视频下载工具

一个智能的 YouTube 视频下载工具，支持多种下载策略，自动重试直到成功

功能特点

  • 🎯 优先下载 MP4 格式（兼容性最好）
  • 🔄 多种下载策略自动切换
  • 🍪 智能 Cookie 管理
  • 🔓 支持 n 参数解密（使用 Node.js 运行时）
  • 📊 实时下载进度显示
  • 🎬 支持多种视频质量选择
  • 📝 自动下载字幕（可选）

工作流程

当用户触发这个 Skill 时，按照以下流程执行：

阶段 1: 获取下载 URL

  1. 检查用户是否提供了 YouTube URL
  2. 如果没有提供，询问用户要下载的视频链接
  3. 验证 URL 格式是否正确

阶段 2: 询问下载选项

使用 AskUserQuestion 工具询问用户：

  1. 视频质量:

    • 最高质量（推荐）
    • 1080p
    • 720p
    • 480p
    • 仅音频

  2. 是否下载字幕:

    • 是（下载所有可用字幕）
    • 否

  3. 输出目录:

    • 使用默认目录（当前工作目录）
    • 指定自定义路径

阶段 3: 环境检测

检查必需的工具是否已安装：

# 检查 Python 环境
python --version

# 检查 yt-dlp（推荐安装完整版）
python -m yt_dlp --version

# 检查 EJS 脚本是否已安装
python -c "import yt_dlp_ejs; print('EJS scripts installed:', yt_dlp_ejs.__version__)"

# 检查 Node.js（用于解密 n 参数）
node --version

如果缺少工具，按以下步骤安装:

  1. 安装完整的 yt-dlp（包含 EJS 脚本）:

    # 推荐：安装完整版（包含 JavaScript 解密支持）
pip install -U "yt-dlp[default]"

# 或者基础版（不推荐，会遇到 n 参数解密问题）
pip install yt-dlp

  2. 安装 Node.js（如果未安装）:

    • Windows: 访问 https://nodejs.org 下载安装
    • macOS: brew install node
    • Linux: sudo apt install nodejs 或 sudo yum install nodejs

  3. 验证安装:

    # 测试 n 参数解密功能
python -m yt_dlp --js-runtimes node --list-formats "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# 应该看到 [jsc:node] 日志，表示解密功能正常

阶段 4: 智能下载（核心功能）

使用多种策略依次尝试，直到成功：

策略 1: 直接下载（无 Cookie）

  • 最简单的方式
  • 适用于大多数公开视频
  • 失败后自动进入策略 2
python -m yt_dlp \
  --js-runtimes node \
  --format "bestvideo[ext=mp4][height<=1080]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  --output "%(title)s.%(ext)s" \
  "<youtube_url>"

策略 2: 使用 Cookies 文件

  • 检查 skill 目录下的 cookies.txt
  • 如果存在且未过期，使用它下载
  • 重要: 必须启用 Node.js 运行时来解密 n 参数
  • 失败后自动进入策略 3
python -m yt_dlp \
  --cookies "./cookies.txt" \
  --js-runtimes node \
  --format "bestvideo[ext=mp4][height<=1080]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  --output "%(title)s.%(ext)s" \
  "<youtube_url>"

注意: 使用策略 2 前确保已安装 yt-dlp[default] 完整包：

pip install -U "yt-dlp[default]"

策略 3: 从浏览器提取 Cookies

  • 尝试从 Chrome、Firefox、Edge 等浏览器提取 cookies
  • 按优先级依次尝试：Chrome -> Firefox -> Edge -> Safari
# 尝试 Chrome
yt-dlp --cookies-from-browser chrome --format "..." "<youtube_url>"

# 失败则尝试 Firefox
yt-dlp --cookies-from-browser firefox --format "..." "<youtube_url>"

# 失败则尝试 Edge
yt-dlp --cookies-from-browser edge --format "..." "<youtube_url>"

策略 4: 使用代理（如果前面都失败）

  • 询问用户是否要使用代理
  • 提供代理配置选项
yt-dlp --proxy "http://proxy:port" --format "..." "<youtube_url>"

策略 5: 降级下载（最后手段）

  • 降低视频质量要求
  • 尝试下载任何可用格式
yt-dlp --format "best" "<youtube_url>"

阶段 5: 进度显示

在下载过程中显示：

  • 下载进度百分比
  • 已下载大小 / 总大小
  • 下载速度
  • 预计剩余时间

示例输出：

🎬 正在下载: 视频标题
   策略: 使用 Chrome 浏览器 Cookies

   [████████████████░░░░░░░░] 67.8%
   已下载: 234 MB / 345 MB
   速度: 5.2 MB/s
   剩余时间: 00:21

阶段 6: 下载后处理

  1. 验证文件:

    • 检查文件是否完整
    • 验证文件大小
    • 使用 ffprobe 检查视频元数据

  2. 格式转换（如果需要）:

    • 如果下载的不是 mp4 格式，自动转换
    • 使用 FFmpeg 进行转换
    • 保持原始质量

  3. 下载字幕（如果用户选择）:

    • 下载所有可用语言的字幕
    • 优先 VTT 格式，备选 SRT 格式

  4. 生成元数据文件:

    • 创建 JSON 文件包含视频信息
    • 包括标题、时长、上传者、描述等

阶段 7: 输出结果

向用户展示：

  • 下载成功的文件路径
  • 视频信息（标题、时长、大小）
  • 使用的下载策略
  • 字幕文件列表（如果有）

示例输出：

✅ 下载成功！

📁 文件信息:
   标题: 为什么大多数人的努力都是无效的？
   路径: ./为什么大多数人的努力都是无效的？.mp4
   大小: 535 MB
   时长: 26:02
   分辨率: 1920x1080

🎯 下载策略: 使用 Chrome 浏览器 Cookies

📝 字幕文件:
   - 为什么大多数人的努力都是无效的？.zh-Hans.vtt (简体中文)
   - 为什么大多数人的努力都是无效的？.zh-Hant.vtt (繁体中文)
   - 为什么大多数人的努力都是无效的？.en.vtt (英文)

💡 快速预览:
   open "./为什么大多数人的努力都是无效的？.mp4"

关键技术点

1. Cookie 管理策略

Cookie 文件位置: ~/.claude/skills/youtube-download/cookies.txt

Cookie 优先级:

  1. 用户提供的 cookies.txt（skill 目录下）
  2. 从浏览器自动提取（Chrome > Firefox > Edge > Safari）
  3. 无 Cookie 直接下载

Cookie 过期检测:

  • 捕获 "Sign in to confirm you're not a bot" 错误
  • 自动切换到下一个策略

2. 格式优先级

MP4 优先策略:

# 第一优先：MP4 视频 + M4A 音频
bestvideo[ext=mp4][height<=1080]+bestaudio[ext=m4a]

# 第二优先：最佳 MP4
best[ext=mp4][height<=1080]

# 第三优先：任何最佳格式
best[height<=1080]

# 最后：任何格式
best

3. 错误处理

常见错误和解决方案:

错误信息 原因 解决方案
"n challenge solving failed" JavaScript 运行时未配置或 EJS 脚本缺失 见下方 "n 参数解密问题" 详细解决方案
"Sign in to confirm you're not a bot" Cookie 无效/缺失 切换到浏览器 Cookie 提取
"Video unavailable" 视频被删除或私有 提示用户检查 URL
"This video is age restricted" 年龄限制 必须使用有效 Cookie
"HTTP Error 429: Too Many Requests" 请求过多 等待或使用代理
"No video formats found" 地区限制 使用代理

n 参数解密问题（重要）

问题描述: 当出现 WARNING: [youtube] n challenge solving failed: Some formats may be missing 错误时，表示 yt-dlp 无法解密 YouTube 的 n 参数，导致无法获取视频格式。

根本原因:

  • YouTube 使用 JavaScript 混淆来保护视频 URL
  • yt-dlp 需要 JavaScript 运行时来解密这些 URL
  • 默认情况下，只有 Deno 运行时被启用，Node.js 需要手动启用

完整解决方案:

  1. 安装完整的 yt-dlp 包（包含 EJS 脚本）:

    pip install -U "yt-dlp[default]"

    这会安装以下关键组件：

    • yt-dlp-ejs: JavaScript 挑战解决脚本
    • brotli: 用于解压缩
    • pycryptodomex: 加密支持
    • 其他必需的依赖

  2. 确保已安装 Node.js:

    # 检查 Node.js 版本（需要 ≥20.0.0）
node --version

    如果未安装，访问 https://nodejs.org 下载安装

  3. 使用正确的命令参数:

    python -m yt_dlp \
  --cookies cookies.txt \
  --js-runtimes node \
  --output "%(title)s.%(ext)s" \
  --write-auto-sub \
  --sub-langs "zh-Hans,zh-Hant,en" \
  "<youtube_url>"

    关键参数说明:

    • --js-runtimes node: 明确启用 Node.js 作为 JavaScript 运行时
    • --cookies cookies.txt: 使用本地 cookies 文件进行身份验证
    • 可选指定 Node.js 路径: --js-runtimes node:/path/to/node

  4. 验证解密成功: 当看到以下日志时，表示解密成功：

    [youtube] [jsc:node] Solving JS challenges using node

  5. 其他可选的 JavaScript 运行时: 如果 Node.js 不可用，可以尝试：

    • Deno (推荐，默认启用): --js-runtimes deno
    • Bun: --js-runtimes bun
    • QuickJS: --js-runtimes quickjs

  6. 替代方案 - 使用远程 EJS 脚本: 如果不想安装完整包，可以临时下载 EJS 脚本：

    python -m yt_dlp \
  --remote-components ejs:npm \
  --js-runtimes node \
  "<youtube_url>"

配置文件方式（推荐）: 将参数添加到 yt-dlp 配置文件避免每次手动输入：

创建/编辑 ~/.config/yt-dlp/config (Linux/Mac) 或 %APPDATA%\yt-dlp\config.txt (Windows):

--js-runtimes node

测试解密功能:

# 测试命令，应该能看到 [jsc:node] 日志
python -m yt_dlp --js-runtimes node --list-formats "<youtube_url>"

4. 进度显示

使用 yt-dlp 的进度钩子实时更新：

  • 下载百分比
  • 下载速度
  • ETA（预计完成时间）
  • 已下载/总大小

5. 并发下载

如果用户提供多个 URL：

  • 询问是否并发下载
  • 限制并发数（建议 3 个）
  • 显示整体进度

Python 脚本说明

download_video.py

核心下载脚本，实现智能重试机制：

def download_with_strategies(url, quality, output_dir):
    """
    使用多种策略依次尝试下载
    返回：成功使用的策略和文件路径
    """
    strategies = [
        ('direct', download_direct),
        ('cookies_file', download_with_cookies_file),
        ('browser_chrome', download_from_browser_chrome),
        ('browser_firefox', download_from_browser_firefox),
        ('browser_edge', download_from_browser_edge),
        ('fallback', download_fallback)
    ]

    for strategy_name, strategy_func in strategies:
        try:
            result = strategy_func(url, quality, output_dir)
            return strategy_name, result
        except Exception as e:
            print(f"❌ 策略 {strategy_name} 失败: {e}")
            continue

    raise Exception("所有下载策略都失败了")

check_cookies.py

检查和管理 Cookies：

def check_cookies_validity(cookies_path):
    """检查 cookies 文件是否有效"""
    # 尝试使用 cookies 获取视频信息
    # 如果失败，返回 False

def export_cookies_from_browser(browser_name):
    """从浏览器导出 cookies"""
    # 使用 yt-dlp 的内置功能
    # 保存到 cookies.txt

convert_format.py

格式转换工具：

def convert_to_mp4(input_path, output_path):
    """
    将任何视频格式转换为 MP4
    使用 FFmpeg
    """

用户体验优化

1. 智能建议

根据视频信息给出建议：

  • 如果视频很大（>1GB），建议降低质量
  • 如果是音乐视频，建议"仅音频"选项
  • 如果是教程视频，建议下载字幕

2. 批量下载

支持播放列表和多个 URL：

# 播放列表
yt-dlp --yes-playlist "<playlist_url>"

# 多个 URL
# 从文件读取 URLs

3. 断点续传

如果下载中断：

  • 自动检测未完成的下载
  • 询问是否继续
  • 使用 --continue 参数

4. 下载历史

记录下载历史：

  • 保存在 ~/.claude/skills/youtube-download/history.json
  • 避免重复下载
  • 提供历史查询功能

配置文件

config.json

{
  "default_quality": "1080p",
  "default_output_dir": "~/Downloads/YouTube",
  "auto_download_subtitles": false,
  "preferred_subtitle_languages": ["zh-Hans", "zh-Hant", "en"],
  "cookies_path": "./cookies.txt",
  "max_concurrent_downloads": 3,
  "enable_download_history": true,
  "auto_convert_to_mp4": true
}

使用示例

示例 1: 基本下载

用户: /youtube-download https://youtube.com/watch?v=xxxxx
助手:
  - 询问质量选项（选择：最高质量）
  - 询问是否下载字幕（选择：是）
  - 开始下载（策略1失败 -> 策略2成功）
  - 显示结果

示例 2: 批量下载

用户: /youtube-download 下载这个播放列表 <playlist_url>
助手:
  - 检测到播放列表
  - 显示播放列表信息（23个视频）
  - 询问是否全部下载
  - 并发下载（3个同时）

示例 3: 错误恢复

用户: /youtube-download <url>
助手:
  - 策略1失败（需要登录）
  - 策略2失败（cookies过期）
  - 策略3成功（从Chrome提取新cookies）
  - 自动保存新cookies供下次使用

开始执行

当用户触发此 Skill 时：

  1. 立即获取 URL（从参数或询问用户）
  2. 询问下载选项（质量、字幕、输出目录）
  3. 检查环境（yt-dlp、Python、FFmpeg）
  4. 开始智能下载（自动尝试多种策略）
  5. 显示实时进度
  6. 验证和后处理
  7. 展示结果

核心价值:

  • 🎯 智能重试: 自动尝试多种方式，不需要用户干预
  • 🍪 Cookie 管理: 智能处理 YouTube 的身份验证
  • 📦 开箱即用: 一次配置，永久使用
  • 🔄 容错性强: 遇到问题自动切换策略

让我们开始吧！

Weekly Installs
4
Repository
lxmxhh/cc-skill…download
First Seen
Feb 6, 2026
Security Audits
Gen Agent Trust HubFail
SocketPass
SnykWarn
Installed on
opencode4
gemini-cli4
github-copilot4
codex4
kimi-cli4
amp4