brave-search

核心用法

Brave Search 是一款轻量级命令行工具，提供两大核心功能：网络搜索与网页内容提取。用户可通过 ./search.js 执行关键词搜索，支持自定义结果数量（-n 参数）和内容抓取（--content 标志），输出包含标题、链接、摘要及可选的 Markdown 格式正文。./content.js 则专注于单 URL 内容提取，将任意网页转换为可读性强的 Markdown 文档。使用前需配置 BRAVE_API_KEY 环境变量并执行 npm ci 安装依赖。

显著优点

1. 无浏览器架构：基于 Node.js 和 jsdom 实现，无需启动 Chromium 等重型浏览器，资源占用极低，启动速度快。
2. 内容结构化：集成 Mozilla Readability 和 Turndown，自动提取正文并转换为标准 Markdown，便于后续处理或知识库归档。
3. 开发者友好：纯命令行交互，输出格式清晰，易于集成到自动化脚本、CI/CD 流程或 AI Agent 工作流中。
4. 依赖精简：仅依赖 4 个生产级开源库，均为社区广泛验证的成熟方案，维护成本低。

潜在缺点与局限性

• 功能边界明确：不支持 JavaScript 动态渲染页面，对 SPA（单页应用）或重度依赖前端框架的网站内容提取可能不完整。
• 网络依赖性强：完全依赖 Brave Search API 的可用性和配额限制，无本地缓存或离线能力。
• 无交互能力：纯只读工具，无法执行登录、表单提交等需要状态保持的操作。
• 内容截断：默认限制 5000 字符输出，长文可能需要多次请求或调整参数。

适合的目标群体

• 开发者与工程师：快速检索技术文档、API 参考、错误解决方案
• 研究人员：批量收集学术资料、新闻资讯并整理为 Markdown
• AI Agent 与自动化系统：作为 RAG（检索增强生成）流程的信息源组件
• 内容创作者：高效采集网络素材进行再加工

使用风险

• 服务可用性：Brave API 服务中断或速率限制将直接影响功能
• 内容准确性：提取内容依赖源网站结构，复杂布局可能导致信息丢失或错位
• 依赖更新：jsdom 等底层库的安全更新需及时跟进，建议按报告建议每 90 天审查依赖

核心用法

Brave Search Skill 提供无头化的网页搜索与内容提取能力，无需启动浏览器即可完成信息检索任务。核心功能分为两类：

搜索功能：通过 ./search.js 脚本调用 Brave Search API，支持自定义结果数量（-n 参数）和深度内容提取（--content 标志）。基础调用返回标题、链接和摘要；启用内容标志后，自动抓取目标页面并提取可读文本转为 Markdown。

单页提取：./content.js 可直接对任意 URL 进行内容抓取，利用 Mozilla Readability 算法清理广告、导航等干扰元素，输出结构化 Markdown。

显著优点

• 零浏览器开销：相比 Playwright/Puppeteer 方案，内存占用极低，启动毫秒级
• 内容质量优：集成 Readability + Turndown，转换后的 Markdown 结构清晰、干扰少
• 依赖精简：仅 4 个直接依赖，均为知名开源项目（Mozilla、npm 官方生态）
• 隐私友好：Brave Search 本身以隐私保护著称，无搜索行为追踪

潜在局限

• 内容提取依赖第三方库：jsdom + Readability 组合虽成熟，但引入 40+ 传递依赖，存在供应链风险
• SSRF 风险：用户输入 URL 未经白名单验证，可能访问内网地址（127.0.0.1、RFC1918 私有网等）
• API 成本：Brave Search API 为付费服务（有免费额度），需自行管理 BRAVE_API_KEY
• 动态内容限制：无法执行 JavaScript，对 SPA 单页应用或懒加载内容提取效果差

适合人群

• 需要快速检索文档、API 参考的技术开发者
• 构建知识库、进行事实核查的研究人员
• 对浏览器自动化开销敏感的服务端场景

常规风险

• 密钥泄露：BRAVE_API_KEY 需通过环境变量配置，避免误提交至代码仓库
• 内容版权：抓取网页内容需遵守目标站点的 robots.txt 和服务条款
• 依赖漏洞：建议定期运行 npm audit 监控 jsdom、turndown 等库的 CVE 披露
• SSRF 防护：在不可信输入场景下，建议前置代理层过滤内网地址