youtube-search

YouTube 搜索

通过 Frevana 搜索 YouTube 视频。

用途

此技能用于查找 YouTube 搜索结果。

输入：

• search_query
• 可选的 sp
• 可选的 hl
• 可选的 gl

输出：

• 包含 YouTube 搜索结果的已验证响应 JSON

此技能会验证响应是否为 JSON，并原样返回。除非用户明确要求转换，否则不要改写或重塑返回的数据。

此技能所需内容

• 用户提供的 search_query
• 可选的 sp
• 可选的 hl
• 可选的 gl
• 环境变量中的 FREVANA_TOKEN，或本次运行时显式提供的 --token 覆盖值
• curl
• bash
• python3

执行顺序

按此流程操作，让请求保持简单可靠：

1. 确认用户已提供 search_query 或等效的 YouTube 搜索关键词。
2. 优先使用脚本，而非临时编写 curl 命令。
3. 让脚本先读取 FREVANA_TOKEN。
4. 在交互式 Shell 中，如果缺少 FREVANA_TOKEN，脚本可以提示输入。
5. 在非交互式或 Agent 工作流中，如果缺少 Token，应立即失败，并告知用户设置 FREVANA_TOKEN 或显式传入 --token。
6. 返回已验证的响应 JSON；如果用户不需要完整内容，也可以总结最相关的视频。
7. 适用时，也将 JSON 保存到文件。

命令

基本 YouTube 搜索

bash <skill-path>/scripts/search_youtube.sh \
  --search-query "mrbeast"

--query 可用作 --search-query 的别名。

按国家和语言搜索

bash <skill-path>/scripts/search_youtube.sh \
  --search-query "mrbeast" \
  --gl us \
  --hl en

使用 sp 筛选条件或分页令牌搜索

bash <skill-path>/scripts/search_youtube.sh \
  --search-query "mrbeast" \
  --sp "EgIQAQ%253D%253D" \
  --hl en \
  --gl us

如果用户提供了 YouTube 筛选令牌，或希望使用响应中的后续令牌继续分页结果，请使用 --sp。

将响应 JSON 保存到文件

bash <skill-path>/scripts/search_youtube.sh \
  --search-query "mrbeast" \
  --gl us \
  --hl en \
  --output ./out/youtube-search-result.json

为本次运行覆盖 Token

bash <skill-path>/scripts/search_youtube.sh \
  --search-query "mrbeast" \
  --token "your bearer token"

固定请求格式

脚本会发送以下格式的负载，并省略未提供的可选字段：

{
  "search_query": "mrbeast",
  "sp": "EgIQAQ%253D%253D",
  "hl": "en",
  "gl": "us"
}

只有 search_query 是必需项。用户未提供 sp、hl 或 gl 时，不要自行编造这些值。

Frevana 端点已限定为 YouTube 搜索，因此不要传入不受支持的透传字段，例如 engine、api_key、output、no_cache、async 或 zero_trace。

响应格式

API 返回 JSON。此技能会验证响应是否为 JSON，并原样返回。

输出

• 成功：脚本会验证响应正文是否为 JSON，并将其打印到标准输出
• 使用 --output：同一份 JSON 也会写入指定的文件路径
• 失败：脚本会打印响应正文或解析错误，并以非零状态退出

注意事项

• 必须提供 --search-query 或 --query
• 用户要求指定国家或地区时，使用 --gl
• 用户要求指定语言时，使用 --hl
• 仅当用户提供筛选令牌或分页令牌，或要求使用之前 YouTube 搜索响应中已有的令牌继续获取结果时，才使用 --sp
• 如果缺少 curl，请停止并告知用户安装 curl
• 如果缺少 python3，请停止并告知用户安装 python3
• 不要向用户回显 Bearer Token
• 除非用户要求完整内容，否则应总结用户实际关心的视频，而不是倾倒原始 JSON

示例提示词

中文

• "搜索 YouTube 上的 mrbeast"
• "查一下 YouTube 里 search_query=mrbeast，gl=us，hl=en"
• "用这个 sp 参数继续查 YouTube Search，并保存原始 JSON"

English

• "Search YouTube for mrbeast"
• "Look up YouTube results for mrbeast with gl=us and hl=en"
• "Search YouTube with this sp token and save the raw JSON to a file"