youtube-search

YouTube 搜索

按关键词搜索 YouTube，并返回结构化视频元数据——标题、URL、 频道、观看次数、时长、上传日期。使用 yt-dlp 抓取，无需 API 密钥或 OAuth。

前置条件

uv tool install yt-dlp

验证：

yt-dlp --version

用法

基本搜索

yt-dlp "ytsearch10:claude code skills" --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -r '[.title, .url, .channel, .view_count, .duration_string, .upload_date] | @tsv'

• ytsearch10: — 搜索 YouTube，返回 10 条结果（可按需调整数量）
• --dump-json — 以 JSON 格式输出元数据
• --flat-playlist — 不下载，仅列出结果
• --no-warnings — 禁止输出非错误信息

结构化 JSON 输出

yt-dlp "ytsearch5:claude code mcp servers" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq '{
    title: .title,
    url: .url,
    channel: .channel,
    views: .view_count,
    duration: .duration_string,
    upload_date: .upload_date,
    description: (.description // "" | .[0:200])
  }'

按条件排序搜索结果

yt-dlp 不支持服务端排序。若要按观看次数或日期排序，请获取所有 结果，再在客户端排序：

# Sort by view count (descending)
yt-dlp "ytsearch20:AI agents 2026" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -s 'sort_by(-.view_count) | .[:10][] | {title, url, channel, views: .view_count}'

# Sort by upload date (newest first)
yt-dlp "ytsearch20:claude code tutorial" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -s 'sort_by(-.upload_date) | .[:10][] | {title, url, channel, upload_date}'

搜索结果数量

ytsearch 后面的数字决定要获取的结果数量：

模式	结果数
ytsearch5:query	5 条结果
ytsearch10:query	10 条结果（默认建议）
ytsearch20:query	20 条结果
ytsearch50:query	50 条结果（速度较慢，可能触发速率限制）

建议： 获取 15–20 条结果，然后在客户端筛选或排序，选出用户需要的前 N 条。这样既能为有效排序提供足够的数据，也不会获取过多结果。

工作流

User provides search query
        |
        v
+---------------------+
|  Step 0: Deps check |
+----------+----------+
           v
+---------------------+
|  Step 1: Search     |
|  (yt-dlp ytsearch)  |
+----------+----------+
           v
+---------------------+
|  Step 2: Parse JSON |
|  (jq formatting)    |
+----------+----------+
           v
+---------------------+
|  Step 3: Present    |
|  results to user    |
+---------------------+

第 1 步：执行搜索

yt-dlp "ytsearch${COUNT}:${QUERY}" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null

第 2 步：解析和整理格式

使用 jq 提取相关字段。yt-dlp 返回的完整元数据对象包含许多字段；搜索结果中有用的字段包括：

字段	说明
.title	视频标题
.url	完整的 YouTube URL
.channel	频道名称
.view_count	总观看次数（整数）
.duration_string	时长，格式为 H:MM:SS 或 MM:SS
.upload_date	上传日期，格式为 YYYYMMDD
.description	视频说明（可能很长，可截断）
.like_count	点赞数（可能为 null）
.comment_count	评论数（可能为 null）

第 3 步：展示结果

将结果整理为 Markdown 表格，供用户查看：

yt-dlp "ytsearch10:${QUERY}" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -s 'sort_by(-.view_count) | .[] | "| \(.title[:60]) | \(.channel) | \(.view_count) | \(.duration_string) | \(.upload_date) |"' -r

在表格前添加标题行：

| Title | Channel | Views | Duration | Date |
|-------|---------|-------|----------|------|

高级模式

按时长筛选

# Only videos longer than 10 minutes (600 seconds)
yt-dlp "ytsearch20:deep dive AI agents" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -s '[.[] | select(.duration >= 600)] | sort_by(-.view_count) | .[:10][]'

按发布时间筛选

# Only videos from the last 30 days
CUTOFF=$(date -v-30d +%Y%m%d 2>/dev/null || date -d "30 days ago" +%Y%m%d)
yt-dlp "ytsearch20:claude code" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -s --arg cutoff "$CUTOFF" '[.[] | select(.upload_date >= $cutoff)] | sort_by(-.view_count) | .[]'

搜索特定频道

# Search within a specific channel
yt-dlp "ytsearch10:skills site:youtube.com/c/ChannelName" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null

或者直接使用频道 URL：

yt-dlp "https://www.youtube.com/@ChannelName/search?query=skills" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null

仅提取 URL（用于管道传递）

# Get just URLs for feeding into other tools (watch, notebooklm)
yt-dlp "ytsearch10:claude code MCP" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -r '.url'

组合使用

此技能生成的 URL 和元数据可供其他技能使用：

• watch：传入 URL，以获取文字稿概念、带时间戳的视觉证据，以及基于问题的视频分析
• notebooklm：通过 notebooklm source add "URL" 将 URL 作为来源传入

示例流程（手动步骤，非自动化）：

1. /yt-search — 查找 10 个相关视频
2. 用户查看并选择视频
3. 将选定的 URL 传入 notebooklm source add 或 watch

错误处理

错误	原因	解决方法
没有结果	查询过于具体或拼写有误	扩大搜索词范围
JSON 为空	YouTube 对 yt-dlp 实施了速率限制	等待几分钟后重试
yt-dlp: command not found	未安装	uv tool install yt-dlp
结果不完整	部分视频有地区限制或为私有视频	属于正常情况；结果尽力而为
超时	网络或 YouTube 响应缓慢	减少结果数量或重试

限制

• 不支持服务端排序：YouTube 搜索结果按相关性排序。按观看次数或日期排序需要获取更多结果，并在客户端排序。
• 速率限制：过于频繁地抓取（50 个以上结果、快速重复搜索）可能会触发 YouTube 的速率限制。请间隔一段时间再发送请求。
• 元数据完整性：某些字段（.like_count、.comment_count）对于某些视频可能为 null。在 jq 筛选器中务必处理 null 值。
• 无需身份验证：仅使用 YouTube 公开数据。结果中不包含有年龄限制或私密的视频。
• 搜索相关性：初始排序由 YouTube 的搜索算法决定。结果可能与预期不完全一致。