OpenCLI Brave Search 适配器实战用浏览器模式把 Brave 搜索变成可脚本化的 CLI【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI导读Brave Search 不提供公开的无认证搜索 API但它是一个服务端渲染的搜索引擎。OpenCLI 通过浏览器模式Browser Mode复用你已登录的 Chrome 会话直接访问search.brave.com用 DOM 查询抽取排名、标题、URL 与摘要把它封装成一条确定性的opencli brave search命令。读完本文你将掌握该适配器的全部命令参数、参数校验边界、分页与输出格式用法并能从源码层面理解它的抽取逻辑、防重与过滤机制以及当前已知的限制。适配器概览一条命令背后的完整链路brave适配器在 OpenCLI 中注册为一张网站命令面其元信息记录在 clis/brave/search.js 的命令注册块中站点名brave域名search.brave.com访问级别read只读不产生任何站点侧写入策略Strategy.PUBLIC公开站点无需账号态模式browser: true即必须通过浏览器执行输出列rank、title、url、snippet对应的文档位于 docs/adapters/browser/brave.md。命令注册的这些元信息会被 OpenCLI 的命令发现与补全机制读取因此在 shell 中输入opencli brave [Tab]时能够自动补全出search子命令。命令与参数详解命令签名opencli brave search keyword [--limit N] [--offset N] [-f json]参数类型默认值约束说明keyword位置参数必填非空搜索关键词源码经requireSearchQuery校验后由encodeURIComponent编码拼入 URL--limitint101 ≤ limit ≤ 18单页抽取结果上限对应 Brave 每页约 18 条结果的布局--offsetint0≥ 0GET 分页偏移量0 为第一页第 N 页传N-1-f / --formatstringtabletable/json/yaml/md/csvOpenCLI 全局输出格式选项参数校验失败发生在导航之前limit与offset的边界校验来自 clis/_shared/search-adapter.js 中的两个共享工具函数requireBoundedInteger(value, 10, 1, 18, --limit)要求整数且在 118 之间非整数或越界会抛出ArgumentErrorrequireNonNegativeInteger(value, 0, --offset)要求非负整数。关键设计是先校验后导航非法参数会在调用page.goto之前直接失败。测试 clis/brave/search.test.js 中明确断言了这一点——传空关键词、limit: 19、offset: -1都会得到code: ARGUMENT的失败且page.goto从未被调用避免了对浏览器的无效请求。分页规则Brave 的 GET 分页通过 URL 上的offset参数实现源码中的 URL 构造逻辑为let url https://search.brave.com/search?q${keyword}; if (offset 0) url offset${offset};即offset1就是第二页。行号的rank也会随之换算rank index 1 offset * 18例如第二页第一条的 rank 是 19见 clis/brave/search.js 中的rows.map。这意味着跨页结果不会出现 rank 重复。使用示例# 基础搜索默认 limit10第一页 opencli brave search machine learning # 限制结果数量最大 18 opencli brave search machine learning --limit 5 # 翻页第二页offset1 opencli brave search machine learning --offset 1 # JSON 输出便于管道给 jq 或 LLM opencli brave search machine learning -f json--format支持的其余格式yaml/md/csv与 OpenCLI 全局约定一致参考 docs/guide/getting-started.md 的Output Formats一节。由于该命令是确定性的同一命令、同一输出 schema结果可以直接写入脚本、进入 CI 或作为 Agent 的工具调用结果。浏览器模式前置条件Brave 适配器是纯浏览器命令运行前需要满足以下任一条件Chrome 正在运行——Standalone 模式下 OpenCLI 会自动拉起浏览器安装 Browser Bridge 扩展——推荐方式详见 docs/guide/browser-bridge.md加载扩展后运行opencli doctor校验扩展与微守护进程的连通性即可无需 token 或手动配置。⚠️ 注意浏览器命令复用你 Chrome 中的登录会话。虽然brave适配器策略为 PUBLIC搜索无需登录但如果你要用浏览器模式访问其他站点必须先在 Chrome 中登录对应网站。执行流程上命令内部通过runBrowserStep包装导航与抽取两个步骤见 clis/_shared/search-adapter.js任何步骤抛出的非ArgumentError错误都会被包装为带COMMAND_EXEC语义的CommandExecutionError避免把浏览器的底层异常原样泄漏给用户。抽取原理DOM 查询与过滤核心抽取脚本抽取通过page.evaluate(buildExtractorJs(limit))在页面上下文内执行一段注入脚本完成见 clis/brave/search.js 的buildExtractorJs遍历document.querySelectorAll(.snippet)找到全部结果容器跳过含standalone或ad类的节点对应 AI 摘要框与广告从.search-snippet-title取标题、.generic-snippet .content取摘要、.result-content a取链接跳过空标题/空链接、href以/开头站内相对链接以及重复 URL用seen集合去重每抽取到一条结果就检查是否已达limit达到即提前break。为什么不需要懒加载等待Brave 的结果是服务端渲染的全部结果都已存在于初始 HTML 中没有懒加载。因此导航后脚本只做一次page.wait({ selector: .snippet, timeout: 10 })的短等待失败则退化为 3 秒等待不需要滚动或增量加载逻辑。值得注意的过滤AI 摘要框Brave 会把 AI 生成的摘要框渲染成第一个结果。该适配器通过.standalone类检查将其过滤掉保证返回结果从真实排名第 1 条开始。结果规范化抽取出的原始三元组[title, href, snippet]在返回前经过 clis/_shared/search-adapter.js 的toHttpsUrl规范化相对链接基于https://search.brave.com解析为绝对 URL非 http/https 协议如javascript:会被丢弃最终只返回url非空的行。测试中对这一行为有直接断言——传入浏览器信封{ session, data }后能正确解包并返回带 rank 的 HTTPS 行。空结果与异常负载的类型化处理与其他 OpenCLI 适配器一致brave 搜索对异常情况采用类型化错误而非静默空数组requireRows会校验浏览器返回值形状若page.evaluate返回的不是数组例如{ rows: [] }这类畸形负载抛出COMMAND_EXEC错误并提示 unexpected payload shape若合法抽取后没有任何行全部被过滤或页面无结果抛出EmptyResultError消息形如No Brave results matched ...。clis/brave/search.test.js 中专门有一条测试验证畸形负载必须类型化失败而不是静默返回[]这正是 OpenCLI 命令面设计里可被 Agent 可靠消费的体现。当前限制与使用注意必须浏览器模式Brave Search 不提供公开无认证搜索 API无法走纯 HTTP 直连DOM 依赖 Svelte 生成类名.snippet、.search-snippet-title等选择器依赖 Brave 前端生成的类名站点改版时可能失效需要随适配器更新空摘要部分结果可能因 Brave 布局原因没有 snippet抽取结果中该行摘要为空字符串属预期行为参数上限硬约束--limit超过 18 会直接报参数错误而不是多给一些再截断。延伸阅读适配器文档docs/adapters/browser/brave.md适配器实现clis/brave/search.js测试用例clis/brave/search.test.js共享校验与规范化工具clis/_shared/search-adapter.js浏览器桥接设置docs/guide/browser-bridge.mdOpenCLI 快速上手与输出格式docs/guide/getting-started.md【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
