Brave Api Search

核心功能

brave-api-search 是一套完整的搜索技能套件，基于 Brave 官方 Search API 构建，提供四大核心能力：

| 工具 | 用途 |

|------|------|

| `brave_search` | 实时网页搜索，返回标题、URL、描述，可选 AI 摘要 |

| `brave_suggest` | 查询自动补全，支持富元数据（标题、图片、实体） |

| `brave_spellcheck` | 拼写纠错与 "Did you mean?" 建议 |

| `brave_answers` | AI 驱动的实时答案，带内联引用与实体提取 |

v4.2.0 重大更新

• 实体提取：通过 --enable-entities 自动识别并提取答案中的关键实体，附带引用计数
• 流式优化：实体与引用实时解析、去重，支持渐进式输出
• 非流式模式增强：即使禁用流式，也能完整提取引用与实体

显著优点

• 实时性与权威性：直接调用 Brave 搜索索引，信息新鲜度优于训练数据截止的模型
• 引用溯源：brave_answers 自动标注信息来源，支持学术研究、事实核查场景
• 多 API 密钥降级策略：brave_suggest 和 brave_spellcheck 支持多级密钥回退，降低配置门槛
• 零依赖轻量：纯 Node.js 18+ 实现，无外部 npm 依赖
• 智能缓存：brave_suggest 内置 60 秒 TTL 内存缓存，减少重复调用

潜在局限

• 成本不可预测：采用信用积分制，无固定免费额度，需实时监控仪表板
• 富建议需付费：--rich 模式依赖独立的 Autosuggest 付费计划
• 流式强制依赖：引用、实体、研究模式必须开启流式（--stream true），否则功能降级
• 地理限制：部分功能需指定国家代码，全球化场景需额外配置

适合人群

• 需要实时信息检索的开发者、研究人员、新闻工作者
• 构建搜索增强型 AI 应用的产品团队（RAG 场景）
• 追求答案可溯源的企业知识库、客服系统架构师

常规风险

• API 密钥泄露：需严格管理 .env 文件，避免提交至版本控制
• 速率限制：429 错误需配合指数退避重试，高并发场景需评估 QPS 限额
• 成本超支：积分消耗与 token 用量挂钩，建议设置用量告警
• 信息时效幻觉：虽优于静态模型，但仍受 Brave 索引更新频率制约

核心用法

brave-api-search 提供四个互补工具覆盖完整搜索场景：

| 工具 | 核心能力 | 典型场景 |

|------|---------|---------|

| `brave_search` | 实时网页搜索+AI摘要 | 查文档、新闻、技术资料 |

| `brave_suggest` | 智能联想补全 | 搜索框自动完成、Query优化 |

| `brave_spellcheck` | 拼写纠错 | "Did you mean?" 体验 |

| `brave_answers` | 带引用AI合成答案 | 研究型问答、多源信息整合 |

关键参数示例：

• 时效过滤：--freshness pd（24h）/ pw（7天）/ pm（31天）/ py（1年）
• 深度研究：--enable-research true 多轮搜索合成
• 实体提取（v4.2.0新增）：--enable-entities true 自动识别并链接知识实体
• 智能摘要：--summary true 并行获取Brave AI网页摘要

显著优点

1. 架构纯净：纯Node.js原生实现，零npm依赖，无供应链攻击风险
2. 安全设计：

3. 功能深度：

4. 成本透明：内置token用量与费用拆分显示（answers工具）

• 仅访问 api.search.brave.com 官方端点
• 输入白名单验证（freshness/country等参数Set校验）
• 环境变量精确读取（不遍历process.env）
• 自动重试+退避（429/5xx容错）
• 流式传输支持实时实体提取与引用标注
• 智能缓存（suggest结果60秒TTL去重）
• API Key优雅降级链（autosuggest/spellcheck可共用search key）

潜在缺点与局限

| 局限类型 | 具体说明 |

|---------|---------|

| **付费门槛** | 非固定免费额度，需监控dashboard用量；rich suggest需付费计划 |

| **地理覆盖** | country参数仅支持2字母代码，复杂区域定向受限 |

| **流式依赖** | citations/entities/research三大特性强制依赖streaming，关闭后降级明显 |

| **错误透传** | API错误响应直接输出stderr，虽经评估风险低，但理论上可能泄露调试信息 |

| **无本地缓存** | 除suggest外无持久化缓存，重复查询产生重复计费 |

适合人群

• 开发者/技术写作者：快速查官方文档、追踪技术动态、验证API变更
• 研究员/分析师：多源信息交叉验证、带引用的简报生成
• 产品团队：为自有产品集成搜索建议、拼写纠错能力
• 内容创作者：实时事实核查、热点话题追踪

常规风险

1. API密钥管理：需妥善保管 .env 文件，避免意外提交至版本控制（SKILL.md已明确警示）
2. 查询隐私：用户搜索内容经TLS加密发送至Brave服务器，虽符合GDPR/CCPA，但敏感查询仍需谨慎
3. 成本失控：Answers功能含token计费，深度研究模式消耗倍增，建议生产环境设置预算告警
4. 服务可用性：依赖Brave Search API SLA，关键业务建议设计降级策略

---

版本亮点（v4.2.0）：实体提取功能完善，非流式模式也支持完整引用解析，架构成熟度显著提升。