介绍
# Serper
通过 Serper API 进行 Google 搜索。不仅获取结果，还会通过 trafilatura 读取实际的网页以提取干净的全文内容。不仅仅是片段，而是完整的文章文本。
### 工作原理
1. **Serper API 调用** — 快速的 Google 搜索，立即返回结果 URL 2. **并发页面抓取** — 所有结果页面均使用 trafilatura 并行获取和提取，**每个页面超时 3 秒** 3. **流式输出** — 每个页面完成后逐个打印结果
每次调用为您提供 5 个结果（默认模式）或最多 6 个结果（当前模式），每个结果都包含完整的页面内容。这已经包含大量信息。
---
## 查询规范
**构建一个好的搜索查询。这几乎总是足够了。**
每次调用返回多个包含完整页面文本的结果 — 您可以从单个查询获得广泛的覆盖。不要运行多次搜索来“探索”一个主题。一个精心选择的查询配合正确的模式即可覆盖。
**最多两次调用**，如果用户的请求确实跨越两个不同的主题（例如“比较 X 与 Y”，其中 X 和 Y 需要单独搜索，或者针对不同方面进行一次 `default` 调用和一次 `current` 调用）。绝不超过两次。
**不要：** - 使用不同的措辞运行相同的查询以“获得更多结果” - 运行顺序搜索以“深入挖掘” — 完整的页面内容已经很深入了 - 运行一次搜索来寻找某物，然后再运行另一次来跟进 — 阅读您已有的内容
---
## 何时使用此技能
**使用 serper 当：** - 任何需要来自网络的当前、事实性信息的问题 - 需要完整文章内容而不仅仅是片段的研究主题 - 新闻和时事 - 产品信息、价格、比较、评论 - 技术文档、操作指南 - 任何需要阅读实际页面内容的情况
**不要将此技能用于：** - 您可以从训练数据中回答的问题 - 纯数学、代码执行、创意写作 - 问候、闲聊
**重要提示：此技能已经获取并提取了完整的页面内容。不要对由此技能返回的 URL 使用 web_fetch、WebFetch 或任何其他 URL 获取工具。内容已包含在输出中。**
---
## 两种搜索模式
正好有两种模式。根据查询选择合适的一种：
### `default` — 通用搜索（所有时间） - 所有时间的 Google 网络搜索，**5 个结果**，每个都包含完整的页面内容 - 用于：一般问题、研究、操作指南、常青主题、产品信息、技术文档、比较、教程、任何非时效性的内容
### `current` — 新闻和近期信息 - 过去一周的 Google 网络搜索（3 个结果）+ Google 新闻（3 个结果），每个都包含完整的页面内容 - 用于：新闻、时事、近期进展、突发新闻、公告、任何时效性的内容
#### 模式选择指南
| 查询信号 | 模式 | |---------------|------| | “X 是如何工作的”、“什么是 X”、“解释 X” | `default` | | 产品研究、比较、教程 | `default` | | 技术文档、指南 | `default` | | 历史主题、常青内容 | `default` | | “news”、“latest”、“today”、“this week”、“recent” | `current` | | “what happened”、“breaking”、“announced”、“released” | `current` | | 时事、政治、体育比分、股价 | `current` |
---
## 区域设置（非英语查询必需）
**默认为全球** — 无国家过滤器，英语结果。这仅适用于英语查询。
**当以下任何情况为真时，您必须始终设置 `--gl` 和 `--hl`：** - 用户的消息是非英语语言 - 您构建的搜索查询是非英语语言 - 用户提到了特定的国家、城市或地区 - 用户在非英语环境中询问本地结果（价格、新闻、商店等）
**如果用户用德语书写，您必须传递 `--gl de --hl de`。毫无例外。**
| 场景 | 标志 | |----------|-------| | 英语查询，无特定国家目标 | *(省略 --gl 和 --hl)* | | 德语查询 或 用户用德语书写 或 目标为 DE/AT/CH | `--gl de --hl de` | | 法语查询 或 用户用法语书写 或 目标为法国 | `--gl fr --hl fr` | | 任何其他非英语语言/国家 | `--gl XX --hl XX` (ISO 代码) |
**经验法则：** 如果查询字符串包含非英语单词，请设置 `--gl` 和 `--hl` 以匹配该语言。
---
## 如何调用
```bash python3 scripts/search.py -q "QUERY" [--mode MODE] [--gl COUNTRY] [--hl LANG] ```
### 示例
```bash # English, general research python3 scripts/search.py -q "how does HTTPS work"
# English, time-sensitive python3 scripts/search.py -q "OpenAI latest announcements" --mode current
# German query — set locale + current mode for news/prices python3 scripts/search.py -q "aktuelle Preise iPhone" --mode current --gl de --hl de
# German news python3 scripts/search.py -q "Nachrichten aus Berlin" --mode current --gl de --hl de
# French product research python3 scripts/search.py -q "meilleur smartphone 2026" --gl fr --hl fr
```
---
## 输出格式
输出是一个**流式 JSON 数组** — 每个页面被抓取时逐个打印元素：
```json [{"query": "...", "mode": "default", "locale": {"gl": "world", "hl": "en"}, "results": [{"title": "...", "url": "...", "source": "web"}, ...]} ,{"title": "...", "url": "...", "source": "web", "content": "Full extracted page text..."} ,{"title": "...", "url": "...", "source": "news", "date": "2 hours ago", "content": "Full article text..."} ] ```
第一个元素是搜索元数据。随后的每个元素包含一个带有完整提取内容的结果。
结果字段： - `title` — 页面标题 - `url` — 源 URL - `source` — `"web"`、`"news"` 或 `"knowledge_graph"` - `content` — 完整的提取页面文本（如果提取失败则回退到搜索片段） - `date` — 可用时显示（新闻结果总是显示，网页结果有时显示）
---
## CLI 参考
| 标志 | 描述 | |------|-------------| | `-q, --query` | 搜索查询（必需） | | `-m, --mode` | `default`（所有时间，5 个结果）或 `current`（过去一周 + 新闻，各 3 个） | | `--gl` | 国家代码（例如 `de`、`us`、`fr`、`at`、`ch`） | | `--hl` | 语言代码（例如 `en`、`de`、`fr`） |