SuperAPI AI 工具集

web-search

通用与其它

查看项目

更新于 10-16 06:39

技能介绍

Web Search Skill 是一款为获取实时信息而设计的网页搜索技能,通过 Playwright 控制的浏览器执行搜索,适合在需要超出知识截止时间的信息或强调数据时效性时使用。

【用途与使用场景】 该技能适用于以下情形:获取 2025 年 1 月之后发生的事件、新闻或数据;查询最新框架与库文档(如 React 19、Next.js 15 等);获取股票价格、天气、体育比分等实时数据;进行事实核查,确认项目、公司或技术当前状态;查看社区讨论、GitHub issue、Stack Overflow 回答;做产品对比与最新评测;以及针对具体报错信息搜索解决方案。示例场景包括询问 React 19 新特性、检索最新 Next.js App Router 文档、查询 Rust async 项目状态、查找 Vue 3 性能相关讨论等。

【工作原理与架构】 流程为:Claude 通过 Bash 调用 CLI 脚本,脚本经 HTTP 请求本地 Bridge Server,Bridge Server 再通过 CDP 与 Playwright 控制 Chrome 浏览器,最终访问 Google/Bing 搜索并抽取结果。架构包含:CLI 脚本(面向 Claude 的简单 bash 接口)、Bridge Server(Express HTTP API,由 Electron 自动启动)、Playwright Manager(负责浏览器连接与会话管理)、搜索引擎层(Google 为主,Bing 为回退)、以及可见的 Chrome 浏览器窗口(所有操作对用户透明可见)。

【基本使用方式】 推荐始终使用 $SKILLS_ROOT 环境变量定位技能脚本,以兼容开发与生产环境。基本命令为:

bash "$SKILLS_ROOT/web-search/scripts/search.sh" "search query" [max_results]

对于非 ASCII 查询(中文、日文等),建议使用 UTF-8 文件输入以避免 Windows 下的 shell 编码问题,例如先写入 /tmp/web-query.txt 再以 @ 文件方式传入,并指定结果数量。默认返回 10 条结果。输出为 Markdown 格式,包含查询词、结果数、耗时,以及每条结果的标题、URL 与摘要片段。

【高级用法】 Bridge Server 通常由 Electron 自动管理,一般无需手动启停;如需手动控制,可使用 start-server.sh 与 stop-server.sh,并通过 start-server.sh 查看端点状态。进阶场景可直接调用 HTTP API,例如 POST /api/browser/connect 建立连接、POST /api/search 执行搜索、POST /api/page/navigate 导航到指定 URL、POST /api/page/screenshot 截图。

【最佳实践】 查询应尽量具体,避免过宽泛的关键词;结果数量按需选择,快速查询用 3-5 条,综合研究用 10 条;搜索失败时先检查服务器状态;CLI 脚本会自动缓存连接,同一会话的多次搜索可复用同一浏览器连接以提升性能;对输出结果应进行解析与归纳,而不是直接堆砌全部结果。常见的组合模式包括:查询最新文档、故障排查、时事新闻、对比研究、API/库用法查询。

【错误处理】 服务器未运行时会提示 Bridge Server is not running,可通过 start-server.sh 启动并查看 .server.log;浏览器启动失败通常因未安装 Chrome,可按平台安装;连接超时需停止服务器、清除 .connection 缓存后重启;结果为 0 时建议放宽查询或检查网络;搜索超时建议检查网络、减少结果数或重试。若问题持续,可执行完整的重置流程:停止服务、删除 .connection/.server.pid/.server.log、npm run build、重启并测试。

【安全性】 Bridge Server 仅绑定 127.0.0.1,不对外暴露,其他机器无法访问;使用独立的 Chrome 配置文件,不影响用户主浏览器;所有浏览器操作在可见窗口中展示,过程透明;该技能不处理密码或敏感数据。搜索查询会经由 Google 和/或 Bing,可能被其按各自隐私政策追踪;技能本身不本地存储搜索历史,用户可实时观察全部浏览器活动。

【限制】 不处理 CAPTCHA,若出现验证码需用户手动解决;引擎可用性随网络与地区变化,自动模式在 Google 与 Bing 之间回退;主要面向英文与中文结果;仅抽取标题与摘要,不提取完整页面内容;无法搜索需要登录的页面。不适合需要身份验证的搜索、填写表单或提交数据、需要解验证码的操作、大规模抓取或自动化批量搜索、以及访问付费墙后的页面。

【技术细节与要求】 使用 Playwright Core、Chrome DevTools Protocol、Express.js、Google + Bing 多引擎回退策略与 bash 脚本。系统要求 Node.js 18+、已安装 Google Chrome 或 Chromium、具备互联网连接,Bridge Server 约占 100MB 内存,Chrome 实例约占 200MB。相关文件包括服务端 dist/server/index.js、日志 .server.log、进程文件 .server.pid、连接缓存 .connection。典型延迟:服务器启动约 2 秒(一次性,自动启动)、浏览器启动约 3 秒(每会话一次性)、首次搜索约 2-3 秒、后续搜索约 1 秒。更多资料见 README.md 与 examples/basic-search.md。