youtube-search

YouTubeSearch

按查询词搜索 YouTube，并返回包含元数据和互动指标的结构化易读结果。

功能说明

使用 yt-dlp 在 YouTube 上执行搜索，返回前 N 条结果（默认 20 条），并筛选出近期时间范围内的视频（默认 6 个月）。每条结果包含：

• 标题和URL
• 频道名称和订阅者数量
• 观看次数和时长
• 上传日期
• 互动比率（观看次数 / 订阅者数量）——快速判断视频表现是否超出或低于频道受众规模的指标

数字采用易读格式（例如，1.2M、45.3K）。结果之间用分隔线隔开，便于浏览。

要求

• 已安装 yt-dlp，且位于 PATH 中
• 已安装 jq，且位于 PATH 中
• 已安装 bc（macOS/Linux 上的标准组件）

用法

运行随附的脚本：

bash ~/.claude/skills/YouTubeSearch/scripts/yt-search.sh "<search query>" [--count N] [--months N]

参数

标志	默认值	说明
（位置参数）	—	搜索查询词（必填）
--count	20	返回的结果数量
--months	6	仅包含最近 N 个月内的视频

示例

# Basic search — top 20 results from last 6 months
bash ~/.claude/skills/YouTubeSearch/scripts/yt-search.sh "kubernetes security best practices"

# Narrow to 5 results from the last month
bash ~/.claude/skills/YouTubeSearch/scripts/yt-search.sh "rust async tutorial" --count 5 --months 1

# Broader window — last 2 years
bash ~/.claude/skills/YouTubeSearch/scripts/yt-search.sh "home lab setup" --months 24

解读互动比率

观看次数与订阅者数量的比率有助于找出表现突出的内容：

• > 1.0x — 视频的观看次数超过频道订阅者数量。这表明主题引起了共鸣，或算法对视频进行了推荐。
• 0.3x - 1.0x — 成熟频道的典型范围。
• < 0.3x — 触达率低于平均水平。可能是主题比较小众、缩略图/标题表现不佳，或频道受众已经转移兴趣。

此指标最适合用于比较同一主题下的视频——小频道的比率达到 5.0x，通常意味着内容引起了强烈共鸣。

Claude 应如何使用此工具

当用户要求搜索 YouTube 或查找视频时：

1. 使用用户的查询词和指定的任何标志运行脚本
2. 展示结果——脚本输出已采用适合在终端中阅读的格式
3. 如果用户需要分析（例如“这些视频中哪些值得看？”），使用互动比率和观看次数来指出表现突出的内容
4. 如果许多结果的订阅者数量显示为“N/A”，这是正常的——yt-dlp 并不总能从搜索结果中获取频道元数据

故障排除

• 没有结果：尝试扩大查询范围或增加 --months
• 速度慢：每条结果都需要获取元数据。减少 --count 可加快结果返回速度。
• 订阅者数量显示为“N/A”：yt-dlp 有时无法从搜索结果中解析频道粉丝数。其他字段仍会正常填充。

---

注意事项

• API 的 order=date 仍会应用相关性排名——近期上传的视频可能会被排到较后位置。可通过合并两次查询（日期 + 相关性）解决。
• 配额按项目按天计算——搜索开销较大（每次查询 100 个单位）；短时间内大量请求会导致项目当天无法继续使用。
• regionCode 参数会改变结果——相同查询在不同地区会返回不同视频；默认使用观看者 IP 所在地区。
• 字幕 API 与搜索 API 相互独立——字幕是否可用取决于具体视频；有些视频没有字幕，API 也不会返回错误。
• 频道 ID 与频道用户名：handle（@name）、旧式用户名和 ID 是三种不同的标识符；解析时需要显式调用频道列表接口。
• 上传者禁止嵌入的视频：搜索可能会返回这些视频，但下游的嵌入工具会在没有警告的情况下失败——请检查 status.embeddable。