Brave API Search v4.2.0 — 重大更新

基于官方 Brave Search API 的实时网页搜索、自动补全、拼写检查与 AI 驱动的答案。共包含四个工具：

• brave_search — 返回带标题、URL 和描述的网页搜索结果，可选 AI 摘要
• brave_suggest — 用户输入时提供查询自动建议，支持可选的丰富元数据
• brave_spellcheck — 拼写校正及“您是指？”类建议
• brave_answers — 基于实时网页搜索的 AI 答案，内嵌引用来源
  | 新增 — v4.2.0：通过 enable-entities 标志启用完整实体抽取

配置

请在本地 .env 文件中设置您的 Brave API 密钥（推荐）：

# .env（切勿提交至版本控制）
BRAVE_SEARCH_API_KEY=your_key_here
BRAVE_ANSWERS_API_KEY=your_key_here
AUTOSUGGEST_API_KEY=your_key_here   # 可选，仅用于 autosuggest
BRAVE_SPELLCHECK_API_KEY=your_key_here   # 可选，仅用于 spellcheck

获取密钥地址：https://api-dashboard.search.brave.com

密钥路由规则：

• brave_search → BRAVE_SEARCH_API_KEY
• brave_answers → BRAVE_ANSWERS_API_KEY
• brave_suggest → AUTOSUGGEST_API_KEY → BRAVE_AUTOSUGGEST_API_KEY → BRAVE_SEARCH_API_KEY（按顺序尝试）
• brave_spellcheck → BRAVE_SPELLCHECK_API_KEY → BRAVE_SEARCH_API_KEY（按顺序尝试）

注意：brave_answers 默认启用流式响应（streaming）。流式响应是获取引用来源、实体信息及研究模式（research mode）所必需的。

适用场景

当满足以下条件时，请使用 brave_search：

• 搜索当前信息、新闻或近期事件
• 查阅文档或技术参考资料
• 需要带排序的搜索结果及对应 URL 以便进一步跟进
• 希望获得搜索结果的 AI 摘要

当满足以下条件时，请使用 brave_suggest：

• 为搜索界面提供自动补全能力
• 帮助用户更快构建更优查询
• 需在用户输入过程中实时返回查询补全项
• 希望建议结果附带丰富元数据（如标题、描述、图片）

当满足以下条件时，请使用 brave_answers：

• 需要带引用来源的综合答案
• 研究受益于多源信息的主题
• 希望获得 AI 驱动且内嵌引用的响应
• 需要深度研究模式（multi-search）

请勿将本技能用于以下场景：

• 问题已在上下文或记忆中得到解答
• 任务本身无需外部信息支持

工具说明

brave_search

返回带标题、URL 和描述的排序网页搜索结果。

brave_search --query "latest Node.js release" --count 5
brave_search --query "TypeScript generics" --extra-snippets true
brave_search --query "current weather Copenhagen" --freshness pd
brave_search --query "React Server Components" --summary true

参数说明：

• query（必填）— 搜索查询词，支持操作符：site:、"exact phrase"、-exclude
• count — 返回结果数量（1–20，默认：10）
• country — 两位国家代码（默认：us）
• freshness — 时间筛选：pd（24 小时内）、pw（7 天内）、pm（31 天内）、py（1 年内）
• extra-snippets — 每条结果额外包含最多 5 段文本摘录（默认：false）
• summary — 获取 Brave AI 摘要结果（默认：false）
• offset — 分页偏移量，用于获取下一页结果

返回值：格式化结果列表，含标题、URL、描述、可选 AI 摘要；若 more_results_available 为真，则附带下一页提示。

brave_suggest

查询自动建议 API，可在用户输入过程中提供智能查询补全。

brave_suggest --query "hello"
brave_suggest --query "pyt" --count 5 --country US
brave_suggest --query "einstein" --rich true

参数说明：

• query（必填）— 待生成建议的不完整查询词
• count — 建议数量（1–10，默认：5）
• country — 两位国家代码（默认：US）
• rich — 启用增强元数据：标题、描述、图片、实体识别（默认：false；需付费 Autosuggest 计划）

返回值：查询建议列表，可选附带丰富元数据。结果缓存时间为 60 秒。

最佳实践：

• 实现防抖（debouncing），延迟 150–300ms 再发起请求，避免用户连续输入时产生过多 API 调用
• 异步加载建议，避免阻塞 UI 渲染

brave_spellcheck

针对搜索查询词的拼写检查与修正功能。

brave_spellcheck --query "articifial inteligence"
brave_spellcheck --query "hello" --country US

参数说明：

• query（必填）— 待检查拼写错误的查询词
• country — 两位国家代码（默认：US）

返回值：返回“您是指：”类建议，或确认无需修正。若配置了 BRAVE_SPELLCHECK_API_KEY 则优先使用，否则回退至 BRAVE_SEARCH_API_KEY。

brave_answers

基于实时网页搜索、具备内嵌引用的 AI 驱动答案。

brave_answers --query "How does React Server Components work?"
brave_answers --query "Compare Postgres vs MySQL for OLAP" --enable-research true
brave_answers --query "Latest Python release notes" --enable-citations true
brave_answers --query "Who is Albert Einstein" --enable-entities true

参数说明：

• query（必填）— 待研究的问题或主题
• country — 搜索上下文目标国家（默认：us）
• enable-citations — 启用内嵌引用来源（默认：true）
• enable-research — 启用多轮搜索的深度研究模式（默认：false）
• enable-entities — 在响应中包含实体信息（默认：false；需启用流式响应）
• stream — 启用流式输出（默认：true；引用、实体及研究模式均需此选项）

返回值：AI 生成的答案，含从响应中提取的引用来源，以及 token 使用量与费用明细。

⚠️ 引用来源、实体信息与研究模式均依赖流式响应（--stream true，该选项默认启用）。 若通过 --stream false 关闭流式响应，则无法获取引用与实体数据。

流式响应输出格式：

• 文本内容逐步流式输出至 stdout
• 实体以 标签形式内联流式解析
• 末尾输出 Entities mentioned（已提及实体）汇总节（v4.2.0 新增）
• 末尾输出引用来源列表（按引用编号排序）
• 包含 token 使用量与费用明细

非流式响应回退方案：使用 --stream false 可获得更简洁的输出，但将丢失引用与实体数据。

计费与配额限制

Brave 采用基于积分（credit）的计费模型，价格可能调整。请不要假定存在固定免费调用量。

当前公开指引（生产环境部署前请务必在 Brave 控制台/文档中核实）：

• 可能提供月度试用积分（例如：$5 in monthly credits）
• Search 与 Answers 功能消耗积分方式不同
• 丰富建议（Rich suggestions）需付费 Autosuggest 计划
• Answers 功能可能还涉及基于 token 的额外计费
• 每秒查询数（QPS）限制取决于您的订阅计划等级

请始终在以下位置查看实时配额与用量：

• https://api-dashboard.search.brave.com
• https://brave.com/search/api/

技术细节

架构

本技能共用一个 utils.js 模块，包含以下功能：

• parseArgs() — CLI 参数解析器
• fetchWithRetry() — 支持指数退避重试的 fetch 函数（对 429 及 5xx 状态码重试）
• createCache() — 基于内存的 TTL 缓存（供 brave_suggest 使用）

brave_search.js

核心搜索脚本，具备以下优化：

• 并行摘要获取：启用 --summary 时，从搜索响应中提取摘要密钥，并与主搜索结果并行获取
• 分页提示：当 more_results_available 为真时，响应中包含下一页偏移量提示
• 限流处理：对 429（遵守 Retry-After 响应头）与 5xx 错误进行指数退避重试

brave_answers.js v4.2.0

AI 答案脚本支持两种模式：

• 流式响应（默认）：渐进式输出，支持实时实体抽取、去重引用、token 使用统计与费用明细
• 非流式响应：通过对批量响应内容调用 parseCitations() 与 parseEntities() 实现完整引用与实体抽取

v4.2.0 关键变更：

• 实体抽取：流式模式增量解析 标签 —— 实体名称随解析过程内联流式输出，并在末尾汇总生成 Entities mentioned 节，含每个实体的 URL 及引用次数
• 引用去重：对重复的来源 URL 进行去重，确保每个来源仅被引用一次（按引用编号排序）
• 非流式模式（v4.2.0）：对批量响应内容完整应用 parseCitations() 与 parseEntities()，即使未启用流式响应，亦可提取引用与实体

brave_suggest.js

自动建议脚本，具备以下优化：

• 内存缓存：以 query|count|country|rich 为键，TTL 60 秒 —— 消除高频连续调用
• 密钥回退链：AUTOSUGGEST_API_KEY → BRAVE_AUTOSUGGEST_API_KEY → BRAVE_SEARCH_API_KEY

brave_answers 流式响应机制

启用流式响应（stream: true）时：

• SSE 数据块实时解析
• 引用来源收集后统一在末尾输出（按引用编号排序）
• 实体项（）增量解析 —— 内联流式输出，并为 Entities mentioned 节做聚合准备
• 用量块（）解析并显示 token 数量与总费用

安全与打包说明

• 本技能仅调用 Brave 官方接口，全部位于 https://api.search.brave.com/res/v1 下。
• 必须配置 BRAVE_SEARCH_API_KEY 与 BRAVE_ANSWERS_API_KEY（请置于 .env 文件中，切勿直接写入命令或对话中）。
• 可选配置 AUTOSUGGEST_API_KEY 或 BRAVE_AUTOSUGGEST_API_KEY 以支持自动建议功能。
• 不申请持久化/系统级权限，不修改系统配置。
• 所有脚本原生兼容 Node.js 18+（无外部依赖）。