ClawHub Skills Brave Search 技能使用参考手册

一、概述

ClawHub 是一款专注于简化各类搜索引擎集成、数据抓取与处理的工具平台，而 steipete/brave-search 是 ClawHub 生态中针对 Brave Search（勇敢搜索）的专属集成模块。该模块旨在帮助开发者快速将 Brave Search 的搜索能力嵌入到自有应用、爬虫或数据分析系统中，无需从零开发 Brave Search API 调用、请求签名、响应解析等底层逻辑。

相较于其他搜索引擎集成方案，ClawHub 下的 Brave Search 模块具备轻量、易扩展、适配多语言开发环境的特点，是开发者对接 Brave Search 服务的高效解决方案。

二、功能特性（翻译自原站点核心内容）

一键对接 Brave Search 官方 API，自动处理请求头、鉴权参数拼接；
支持搜索结果的结构化解析（JSON/XML 格式），提取标题、链接、摘要、排名等核心字段；
内置请求频率控制机制，避免触发 Brave Search 接口限流策略；
适配多开发语言（Python/JavaScript/Java），提供统一的调用范式；
支持自定义搜索参数（地域、语言、时间范围、结果条数）；
内置异常处理模块，捕获并返回 API 调用中的网络错误、权限错误、参数错误等。

👤 作者：Shaishav Pidadi
👉 Skills 下载地址：brave-search-1.0.1.zip

三、环境准备

前置条件

已注册 Brave Search 开发者账号，获取 API Key（申请地址：https://api.brave.com/）；
已安装 ClawHub 核心包（支持 Python 3.8+ / Node.js 14+ / Java 8+）；
网络环境可正常访问 Brave Search API 服务（无需科学上网，Brave API 支持直连）。

环境安装（以Python为例）

## 安装ClawHub核心包
pip install clawhub-core
## 安装Brave Search专属集成包
pip install clawhub-brave-search

四、安装与配置步骤

步骤1：配置 Brave Search API 密钥

在项目根目录创建配置文件 clawhub_config.json，填入以下内容（替换为你的真实 API Key）：

{
  "brave_search": {
    "api_key": "你的Brave Search API Key",
    "base_url": "https://api.search.brave.com/res/v1/web/search",  // Brave Search API 官方基础地址
    "timeout": 30,  // 请求超时时间（秒）
    "max_retries": 3  // 失败重试次数
  }
}

步骤2：初始化 ClawHub 客户端

from clawhub_brave_search import BraveSearchClient


## 加载配置文件初始化客户端
client = BraveSearchClient(config_path="./clawhub_config.json")


## 验证配置是否生效（测试连接）
is_connected = client.check_connection()
if is_connected:
    print("Brave Search 服务连接成功！")
else:
    print("Brave Search 服务连接失败，请检查API Key或网络！")

五、核心代码解析（带中文注释）

以下是完整的 Brave Search 调用示例，包含自定义参数、结果解析、异常处理：

from clawhub_brave_search import BraveSearchClient
from clawhub_brave_search.exceptions import (
    ApiAuthError,  # 鉴权错误（API Key无效/过期）
    ApiRateLimitError,  # 限流错误（请求频率过高）
    ApiParamsError  # 参数错误（参数格式/取值非法）
)


def brave_search_demo():
    """
    Brave Search 调用示例函数
    功能：搜索“Python 爬虫教程 2024”，提取前10条结果的标题、链接、摘要
    """
    # 1. 初始化客户端
    client = BraveSearchClient(config_path="./clawhub_config.json")

    
    # 2. 定义搜索参数（中文注释说明每个参数含义）
    search_params = {
        "q": "Python 爬虫教程 2024",  # 搜索关键词
        "lang": "zh",  # 搜索语言（zh=中文，en=英文）
        "country": "cn",  # 地域（cn=中国，us=美国）
        "count": 10,  # 返回结果条数（最大50）
        "freshness": "month",  # 时间范围（day=1天内，week=1周内，month=1个月内）
        "safesearch": "moderate"  # 安全搜索（strict=严格，moderate=适中，off=关闭）
    }


    try:
        # 3. 调用搜索接口
        response = client.search(** search_params)

        
        # 4. 结构化解析结果（中文注释说明解析逻辑）
        results = response.get("web", {}).get("results", [])
        for idx, result in enumerate(results, 1):
            # 提取核心字段
            title = result.get("title", "无标题")
            url = result.get("url", "无链接")
            summary = result.get("description", "无摘要")

            
            # 打印解析结果
            print(f"【第{idx}条结果】")
            print(f"标题：{title}")
            print(f"链接：{url}")
            print(f"摘要：{summary}\n")


    except ApiAuthError as e:
        # 捕获鉴权错误，提示检查API Key
        print(f"鉴权失败：{str(e)}，请检查API Key是否有效！")
    except ApiRateLimitError as e:
        # 捕获限流错误，提示降低请求频率
        print(f"请求限流：{str(e)}，请等待10分钟后重试或降低请求频率！")
    except ApiParamsError as e:
        # 捕获参数错误，提示检查参数格式
        print(f"参数错误：{str(e)}，请检查搜索参数是否符合要求！")
    except Exception as e:
        # 捕获其他未知错误
        print(f"搜索失败：{str(e)}")


## 执行示例函数
if __name__ == "__main__":
    brave_search_demo()

代码关键注释说明

异常类导入：针对性捕获 Brave Search API 调用中的常见错误，便于精准排查问题；
搜索参数配置：每个参数均标注中文含义，适配中文开发者的使用习惯；
结果解析逻辑：从 API 响应中提取核心业务字段，过滤冗余数据；
异常处理分支：不同错误类型给出明确的排查提示，降低调试成本。

六、完整使用流程（实操示例）

步骤1：获取 Brave Search API Key

访问 https://api.brave.com/ 并注册开发者账号；
进入「API Keys」页面，点击「Create API Key」创建密钥；
复制生成的 API Key（注意：密钥仅显示一次，需妥善保存）。

步骤2：运行示例代码

将上述核心代码保存为 brave_search_demo.py；
在 clawhub_config.json 中替换为真实 API Key；
执行代码：
```
python brave_search_demo.py
```

步骤3：验证结果

正常情况下，控制台会输出10条“Python 爬虫教程 2024”的搜索结果，包含标题、链接、摘要；若报错，根据提示排查（如 API Key 错误、参数格式错误等）。

步骤4：扩展开发（自定义需求）

如需将结果存入数据库：在解析结果后添加数据库插入逻辑（如 MySQL/Redis）；
如需批量搜索：封装搜索函数，遍历关键词列表实现批量调用；
如需异步调用：使用 asyncio 改造代码，提升并发效率。

七、常见问题与解决方案

问题现象	原因分析	解决方案
鉴权失败（ApiAuthError）	API Key 无效/过期/格式错误	1. 检查 API Key 是否复制完整；2. 重新生成 API Key；3. 确认账号是否欠费（Brave Search 部分接口有免费额度，超额后需付费）
请求限流（ApiRateLimitError）	短时间内请求次数超过 Brave Search 限制	1. 增加请求间隔（如每次调用休眠1-2秒）；2. 降低批量请求的并发数；3. 联系 Brave 提升限流额度
参数错误（ApiParamsError）	语言/地域参数取值非法、结果条数超过50	1. 参考 Brave Search API 文档确认参数取值；2. 将 count 参数控制在1-50之间
无搜索结果返回	关键词无匹配结果、地域/语言筛选过严	1. 简化关键词；2. 放宽地域/语言限制；3. 取消 freshness 时间范围限制

八、总结

ClawHub 下的 steipete/brave-search 模块极大简化了 Brave Search API 的对接成本，开发者无需关注底层的 HTTP 请求、参数拼接、异常处理等细节，只需聚焦业务逻辑即可快速实现搜索能力集成。

无论是做数据分析、爬虫开发，还是自有应用的搜索功能扩展，该模块都能提供稳定、高效的解决方案。建议开发者在使用过程中遵循 Brave Search 的 API 使用规范，合理控制请求频率，避免违规使用。