介绍
# Serper
通过 Serper API 进行 Google 搜索。获取结果并通过 trafilatura 读取实际网页以提取干净的全文内容。不仅仅是片段——而是完整的文章文本。
## 约束
此技能已经获取并提取了完整的页面内容。请勿对由此技能返回的 URL 使用 WebFetch、web_fetch、WebSearch、browser 工具或任何其他 URL 获取/浏览工具。内容已包含在输出中。切勿进行后续的单独获取——您需要的一切都在结果中。
## 查询规范
精心构建一个良好的搜索查询。这几乎总是足够了。
每次调用都会返回多个包含完整页面文本的结果——您可以从单个查询中获得广泛的覆盖。不要运行多次搜索来“探索”一个主题。一个选择得当且模式正确的查询即可涵盖。
**最多两次调用**，仅当用户的请求确实跨越两个不同的主题时（例如“比较 X 与 Y”，其中 X 和 Y 需要单独搜索，或者针对不同方面进行一次 `default` 调用和一次 `current` 调用）。绝不超过两次。
**请勿：** - 使用不同的措辞运行相同的查询以“获取更多结果” - 运行顺序搜索以“深入挖掘”——完整页面内容已经非常深入 - 运行一次搜索来查找内容，然后再运行另一次进行后续跟进——请阅读您已有的内容
## 两种搜索模式
恰好有两种模式。根据查询选择正确的模式：
### `default` — 通用搜索（全时段）
- 全时段 Google 网络搜索，**5 个结果**，每个都附有完整页面内容 - 用于：一般问题、研究、操作指南、常青话题、产品信息、技术文档、比较、教程以及任何非时效性的内容
### `current` — 新闻和近期信息
- 过去一周的 Google 网络搜索（3 个结果）+ Google 新闻（3 个结果），每个都附有完整页面内容 - 用于：新闻、时事、近期发展、突发新闻、公告以及任何时效性内容
### 模式选择指南
| 查询信号 | 模式 | |---------------|------| | “X 如何工作”、“什么是 X”、“解释 X” | `default` | | 产品研究、比较、教程 | `default` | | 技术文档、指南 | `default` | | 历史话题、常青内容 | `default` | | “新闻”、“最新”、“今天”、“本周”、“近期” | `current` | | “发生了什么”、“突发”、“宣布”、“发布” | `current` | | 时事、政治、体育比分、股价 | `current` |
## 地区设置 (Locale)
**默认为全球**——无国家/地区筛选，英语结果。这仅适用于英语查询。
**当以下任何情况为真时，您必须始终设置 `--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": "Page Title", "url": "https://example.com", "source": "web", "content": "Full extracted page text..."} ,{"title": "News Article", "url": "https://news.com", "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`）。默认：`world` | | `--hl` | 语言代码（例如 `en`、`de`、`fr`）。默认：`en` |
## 边缘情况
- 如果 trafilatura 无法从页面提取内容，结果将回退到搜索片段。 - 某些网站完全阻止爬取——您只能获得片段。 - 如果返回零结果，脚本将以 `{"error": "No results found", "query": "..."}` 退出。 - Serper API 密钥从技能目录中的 `.env` 加载。如果缺失，脚本将退出并显示设置说明。