---
name: jusou-web-search
description: 聚搜GO——一个 Key 调多家搜索引擎（exa / serpapi / tavily / serper / anysearch / brave / bocha / baidu）。需要联网查最新资讯、网页、事实核对时使用；1–4 积分/次，Exa 部分参数另加，失败不扣分。
---

# 聚搜GO 联网搜索

## 何时用
- 需要最新信息、网页原文、事实核对、找资料来源时。
- 常识或已确定的内容不要搜：每次调用都扣积分。

## 准备
- 密钥在环境变量 `JUSOU_KEY`，请求头 `Authorization: Bearer $JUSOU_KEY`；不要把密钥写进代码、日志或回复。
- 用户在对话里直接给了 Key（`jsk_` 开头）：先 `export JUSOU_KEY=<Key>` 再调用，之后只用环境变量，不要在回复里复述。
- 用户问 Key 在哪 / 丢了：登录控制台后可随时查看 / 复制 Key；Key 也是控制台登录凭证，请妥善保存、不要外传；忘了或泄露可在控制台重置（旧 Key 立即失效）。
- 支持 MCP 的客户端可直接接远程 MCP `https://jusouai.cn/mcp`（同一请求头），工具 `web_search` / `list_engines` / `get_balance`。

## 选引擎
想用某家就指定 `engine`；不指定则用默认引擎（`anysearch`）；想对比就传 `engines`。失败不会自动换别家，换引擎要你自己指定。
- `exa`（Exa）：英文/语义找资料、找同类网页
- `serpapi`（SerpApi）：Google 搜索结果，参数与返回同 SerpApi 官方
- `tavily`（Tavily）：给 Agent 的干净结果、新闻
- `serper`（Serper）：Google 搜索结果，速度快
- `anysearch`（AnySearch）：中文与通用网页、垂直领域 tag
- `brave`（Brave）：海外网页、给 AI 的正文上下文
- `bocha`（博查）：国内中文网页与长摘要
- `baidu`（百度）：国内中文网页与 AI 速答

## 统一接口
```bash
curl https://jusouai.cn/v1/search -H "Authorization: Bearer $JUSOU_KEY" -H "Content-Type: application/json" \
  -d '{"engine": "exa", "query": "2026 年固态电池量产进展", "num_results": 5}'
```
- 换引擎只改 `engine` 的值（如 `"serpapi"`），其他参数写法不变；去掉 `engine` 就用默认引擎；返回的 `engine` 字段（响应头 `x-engine`）是实际用的引擎。
- 返回 `results[{title, url, snippet, content, published_at}]` 和 `billing`（`points` 本次扣分、`balance` 剩余、`summary` 一句话）。
- 可选：`num_results`（1–10；Exa 1–100，超过 10 条每多 10 条加收）、`depth`（basic 默认 / advanced / deep，越深越贵）、`time_range`（day / week / month / year）、`include_domains` / `exclude_domains`、`extra`（引擎专属参数，原样透传）。

## 多引擎
- 用 `"engines": ["exa", "serpapi"]` 代替 `engine`（一次最多 4 家）：返回 `by_engine` 按引擎分组，每家各自扣分，失败的那家不扣。
- 加 `"merge": true` 另给一份去重合并的 `results`，每条带 `engines` 标出哪几家搜到。

## 扣分与余额
- 一份积分，所有引擎通用；1–4 积分/次，Exa 部分参数另加（按引擎与档位）；成功（含空结果）才扣，参数错、引擎故障、超时、繁忙都不扣。
- 响应头 `x-points-charged` 是本次扣分、`x-points-tier` 是档位；`GET https://jusouai.cn/v1/me` 查余额，`GET https://jusouai.cn/v1/pricing` 看各档位的触发条件与扣分。
- 默认档最省；需要更深的结果时再提高 depth。一次要花较多积分（多引擎、深度档、批量）时先问用户。

## 错误处理
- 402 `insufficient_points`：积分不足，提醒用户兑换卡密续费，不要重试。
- 429 `rate_limited` / `engine_busy`：等几秒再试，最多 2 次。
- 503 `engine_unavailable`：该引擎暂不可用，换上面列出的另一个引擎。
- 400 `invalid_request`：按 message 修正参数（不扣分）。错误里的 `error.hint` 是一句「怎么办」，可直接转告用户。

## 更多
原生兼容接口（与官方请求体、返回体一致）、完整参数、价目与错误码：https://jusouai.cn/docs.md
