web-search-brave

网页搜索（Brave Search API）

使用 Brave Search API 搜索网页。返回包含描述的网页结果，并可选择包含额外摘要，以及按国家／地区和语言定位搜索结果。

**注意：**此技能需要 Brave Search API 密钥。如需使用 Agent 内置功能进行基础网页搜索，请参阅 web-search。如需获取经过 AI 优化且带相关性评分的结果，请参阅 web-search-tavily。

何时使用此技能

在以下情况下使用此技能：

• 需要查找训练数据中没有的最新信息
• 用户询问近期事件、新闻或更新
• 需要获取特定国家／地区或语言的本地化搜索结果
• 想要使用尊重隐私的搜索替代方案
• 研究需要实时网页数据
• 提及的关键词包括：搜索、查找、在线查找、当前、最新、新闻

在以下情况下不要使用此技能：

• 信息已在知识库中，无需验证
• 用户询问不会变化的历史事实
• 正在处理本地文件或代码（请使用其他工具）
• 存在更适合该任务的专用技能（例如，文档查询）
• 需要 AI 生成的答案摘要（请改用 web-search-tavily）

先决条件

使用此技能前，请确保：

• 已设置 BRAVE_API_KEY 环境变量，且其中包含有效的 API 密钥
• 已安装 Deno（用于运行搜索脚本）
• 可以访问互联网

请在此处获取 Brave Search API 密钥：https://brave.com/search/api/

快速入门

运行简单搜索：

deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "your search query"

使用新鲜度筛选条件的示例：

deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "React 19 new features" --freshness pw

脚本用法

deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts [options] "query"

选项

选项	描述	默认值
--results <n>	返回结果数量（最多 20 条）	5
--freshness <range>	时间筛选：pd、pw、pm 或 py	无
--country <code>	本地化结果的国家／地区代码（例如 US、GB、DE）	无
--lang <code>	搜索语言（例如 en、fr、de）	无
--safesearch <level>	安全搜索：off、moderate 或 strict	moderate
--extra-snippets	包含额外内容摘要	false
--offset <n>	分页偏移量	0
--json	以 JSON 格式输出（供程序使用）	false
--help	显示帮助信息	-

搜索参数

新鲜度值

按时间筛选结果：

• pd：过去一天（最近 24 小时）
• pw：过去一周（最近 7 天）
• pm：过去一个月（最近 30 天）
• py：过去一年（最近 365 天）

国家／地区代码

使用标准的 2 个字符国家／地区代码获取本地化结果：

• US（美国）、GB（英国）、DE（德国）、FR（法国）、JP（日本）等

安全搜索级别

• off：不筛选
• moderate（默认）：筛除露骨内容
• strict：最严格的筛选

输出格式

易读输出（默认）

Search: "React 19 new features"

Found 5 results in 189ms

1. React 19 Release Notes
   https://react.dev/blog/2024/04/25/react-19
   React 19 is now available on npm! This release includes...
   Age: 2 months ago

2. What's New in React 19
   https://example.com/react-19-features
   A comprehensive overview of React 19's new features...

JSON 输出（--json）

{
  "query": "React 19 new features",
  "results": [
    {
      "title": "React 19 Release Notes",
      "url": "https://react.dev/blog/2024/04/25/react-19",
      "description": "React 19 is now available on npm...",
      "age": "2 months ago",
      "language": "en",
      "family_friendly": true
    }
  ],
  "response_time": 189,
  "total_results": 1250000
}

结果字段

字段	类型	描述
title	string	页面标题
url	string	来源 URL
description	string	页面中的相关摘录
extra_snippets	string[]	额外内容摘要（仅在使用 --extra-snippets 时提供）
age	string	结果的时间（例如，“2 hours ago”）
language	string	结果的语言
family_friendly	boolean	结果是否适合家庭阅读

示例

示例 1：搜索时事

场景：查找有关某个技术主题的近期新闻

scripts/search.ts "OpenAI GPT-5 announcement" --freshness pw --results 10

预期输出：过去一周有关 GPT-5 的近期网页搜索结果

示例 2：查找文档

场景：查找特定技术文档

scripts/search.ts "Deno deploy edge functions tutorial" --results 10 --extra-snippets

预期输出：包含文档和教程网站额外摘要的全面结果

示例 3：本地化搜索

场景：查找针对特定国家／地区和语言的结果

scripts/search.ts "aktuelle Nachrichten" --country DE --lang de --freshness pd

示例 4：使用 JSON 输出进行筛选搜索

场景：获取结构化结果，并启用严格的安全搜索

scripts/search.ts "machine learning tutorials" --safesearch strict --extra-snippets --json

预期输出：包含额外摘要片段的 JSON 结果，并筛除不安全内容

常见问题与解决方案

问题：“BRAVE_API_KEY environment variable is not set”

症状：脚本立即退出，并显示 API 密钥错误

解决方案：

1. 从 https://brave.com/search/api/ 获取 API 密钥
2. 设置环境变量：

   export BRAVE_API_KEY="your-api-key-here"
   

3. 或在命令中直接设置变量并运行：

   BRAVE_API_KEY="your-key" deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "query"
   

问题：“Invalid Brave Search API key”

症状：401 身份验证错误

解决方案：

1. 确认 API 密钥正确（没有多余空格）
2. 检查 API 密钥是否已过期
3. 确认 Brave Search API 订阅处于有效状态

问题：“Brave Search API rate limit exceeded”

症状：返回 429 错误

解决方案：

1. 稍等片刻后重试
2. 降低请求频率
3. 考虑升级 Brave Search API 套餐以提高限额

问题：未返回结果

症状：结果数组为空

解决方案：

1. 尝试使用更宽泛的搜索词
2. 移除可能过于严格的国家或语言筛选条件
3. 移除或放宽时效性筛选条件
4. 检查该主题是否存在于网上

限制

此技能存在以下限制：

• 需要保持互联网连接
• API 速率限制取决于你的 Brave Search API 套餐
• 结果取决于 Brave 的索引覆盖范围
• 无法访问付费墙或需要登录的内容
• 不内置 AI 生成的答案摘要（如需此功能，请使用 web-search-tavily）
• 每次请求最多返回 20 条结果
• 额外摘要片段需要付费 API 套餐

相关技能

• web-search：使用 Agent 内置功能进行基础网页搜索
• web-search-tavily：提供相关性评分和答案摘要的 AI 优化搜索
• research-workflow：适用于需要通过多次搜索、规划和综合分析开展的全面研究项目