SearXNG 网络搜索

使用自托管的 SearXNG 实例进行网络搜索。本技能通过 SearXNG JSON API 提供对网络搜索结果的访问，内置速率限制、错误处理与结果格式化功能。

适用场景

当您需要执行以下操作时，请使用本技能：

• 查找最新信息或近期新闻
• 研究超出您知识截止时间（knowledge cutoff）的主题
• 查阅文档或技术参考资料
• 核实事实或检查当前状态
• 查找特定主题相关的 URL 或资源
• 搜索代码示例或解决方案

配置

将 SEARXNG_URL 环境变量设为您部署的 SearXNG 实例地址：

export SEARXNG_URL="http://localhost:8888"

若未设置该变量，则默认使用 http://localhost:8888。

使用方法

使用您的查询语句执行搜索脚本：

bb scripts/search.clj "您的搜索查询"

高级选项

可额外传入 JSON 格式的参数：

bb scripts/search.clj "您的查询" '{"category": "news", "time_range": "day", "num_results": 10}'

支持的参数如下：

• category —— 按类别筛选：general、news、images、videos、it、science
• time_range —— 时间范围筛选：day、week、month、year
• language —— 语言代码（默认为 en）
• num_results —— 返回结果数量（默认为 5）

输出格式

脚本以纯文本形式返回格式化的搜索结果：

Search Results for "your query"
Found 42 total results

1. Result Title [Score: 1.85]
   URL: https://example.com/page
   Description snippet from the page...
   Engines: google, bing

2. Another Result [Score: 1.62]
   ...

错误处理

脚本能优雅地处理常见错误：

• 网络超时（30 秒超时）
• SearXNG 不可用（显示清晰的错误信息）
• 无效查询（提供详细的错误信息）
• 速率限制（HTTP 429 响应）
• 无结果返回（给出提示性消息）

速率限制

脚本实现了基础的速率限制机制：

• 请求之间至少间隔 1 秒
• 基于文件系统的状态记录（.searxng-last-request）
• 防止意外产生大量请求（spam）

示例

基础搜索

bb scripts/search.clj "NixOS configuration"

新闻搜索

bb scripts/search.clj "AI developments" '{"category": "news", "time_range": "week"}'

技术类搜索

bb scripts/search.clj "babashka http client" '{"category": "it", "num_results": 3}'

仅返回最新结果

bb scripts/search.clj "product launch" '{"time_range": "day"}'

故障排查

“SEARXNG_URL not set”

• 设置环境变量：export SEARXNG_URL="http://localhost:8888"

连接超时

• 确认 SearXNG 正在运行：curl $SEARXNG_URL/search?q=test&format=json
• 检查防火墙配置
• 检查服务状态：systemctl status searx

无返回结果

• 尝试更宽泛的查询语句
• 移除筛选条件后重试
• 查看 SearXNG 日志：journalctl -u searx -n 50

速率限制错误

• 两次搜索之间等待数秒
• 脚本已自动强制执行最小 1 秒延迟

实现说明

搜索脚本（scripts/search.clj）使用了以下组件：

• 使用 babashka.http-client 发起 HTTP 请求
• 使用 Clojure 的 cheshire.core 解析 JSON
• 基于文件系统的速率限制机制
• 30 秒超时，并配备恰当的错误提示
• 对搜索结果进行评分与排序，确保最优结果优先返回

如需详细 API 文档，请参阅 references/api-guide.md。