名称： serper
描述： 通过 Serper API 进行谷歌搜索，并提取完整页面内容。快速 API 查询 + 并发页面抓取（3秒超时）。一个精心设计的查询即可返回丰富结果——避免多次调用。提供两种模式，支持显式区域设置控制。API 密钥通过 .env 文件配置。
元数据： {"version": "3.0.1", "tags": ["search", "web-search", "serper", "google", "content-extraction"]}

Serper

通过 Serper API 进行谷歌搜索。不仅获取搜索结果，还会读取实际网页，通过 trafilatura 提取干净、完整的文本内容。不只是摘要片段——而是完整的文章正文。

工作原理

1. 调用 Serper API —— 快速执行谷歌搜索，即时返回结果 URL。
2. 并发页面抓取 —— 所有结果页面会并行抓取和提取，使用 trafilatura 库，每个页面超时时间为 3 秒。
3. 流式输出 —— 每个页面处理完成后，结果会逐个打印输出。

每次调用默认返回 5 个结果（默认模式）或最多 6 个结果（当前模式），每个结果都包含完整的页面内容。这已经提供了大量信息。

查询原则

精心设计一个高质量的搜索查询。这几乎总是足够的。

每次调用都会返回多个包含完整页面文本的结果——一个查询就能获得广泛的覆盖范围。不要为了“探索”一个主题而运行多次搜索。一个精心选择、模式正确的查询即可覆盖需求。

最多调用两次，仅当用户的请求确实涉及两个截然不同的主题时（例如，“比较 X 与 Y”，其中 X 和 Y 需要分别搜索；或者针对不同方面分别使用 default 和 current 模式各调用一次）。绝不超过两次。

请勿：
- 用不同措辞重复相同查询以“获取更多结果”。
- 进行连续搜索以“深入挖掘”——完整的页面内容已经足够深入。
- 先搜索一次找到某物，然后再搜索一次跟进——请阅读你已经获取到的内容。

使用场景

在以下情况使用 serper：
- 任何需要从网络获取当前、事实性信息的问题。
- 需要完整文章内容而非仅摘要的研究主题。
- 新闻和时事。
- 产品信息、价格、比较、评论。
- 技术文档、操作指南。
- 任何需要阅读实际页面内容的情况。

不要在以下情况使用此技能：
- 你可以从训练数据中回答的问题。
- 纯数学、代码执行、创意写作。
- 问候、闲聊。

重要提示：此技能已获取并提取完整的页面内容。请勿对返回的 URL 使用 web_fetch、WebFetch 或任何其他 URL 抓取工具。内容已包含在输出中。

两种搜索模式

共有两种模式。根据查询选择正确的模式：

default —— 通用搜索（全时段）

• 全时段谷歌网页搜索，返回 5 个结果，每个结果都附有完整的页面内容。
• 适用于：一般性问题、研究、操作指南、常青主题、产品信息、技术文档、比较、教程，任何非时效性内容。

current —— 新闻和近期信息

• 过去一周的谷歌网页搜索（3 个结果）+ 谷歌新闻（3 个结果），每个结果都附有完整的页面内容。
• 适用于：新闻、时事、近期动态、突发新闻、公告，任何时效性内容。

模式选择指南

区域设置（非英语查询必需）

默认是全球范围 —— 无国家筛选，返回英语结果。这仅适用于英语查询。

当出现以下任何情况时，您必须始终设置 --gl 和 --hl 参数：
- 用户的消息使用非英语语言。
- 您构建的搜索查询使用非英语语言。
- 用户提到了特定的国家、城市或地区。
- 用户在非英语语境下要求本地结果（价格、新闻、商店等）。

如果用户用德语书写，您必须传递 --gl de --hl de。没有例外。

经验法则： 如果查询字符串包含非英语单词，请将 --gl 和 --hl 设置为匹配该语言。

调用方式

python3 scripts/search.py -q "查询内容" [--mode 模式] [--gl 国家代码] [--hl 语言代码]

示例

# 英语，通用研究
python3 scripts/search.py -q "HTTPS 如何工作"

# 英语，时效性内容
python3 scripts/search.py -q "OpenAI 最新公告" --mode current

# 德语查询 —— 设置区域 + 当前模式用于新闻/价格
python3 scripts/search.py -q "aktuelle Preise iPhone" --mode current --gl de --hl de

# 德语新闻
python3 scripts/search.py -q "Nachrichten aus Berlin" --mode current --gl de --hl de

# 法语产品研究
python3 scripts/search.py -q "meilleur smartphone 2026" --gl fr --hl fr

输出格式

输出为流式 JSON 数组 —— 每个页面抓取完成后，元素会逐个打印：

[{"query": "...", "mode": "default", "locale": {"gl": "world", "hl": "en"}, "results": [{"title": "...", "url": "...", "source": "web"}, ...]}
,{"title": "...", "url": "...", "source": "web", "content": "提取的完整页面文本..."}
,{"title": "...", "url": "...", "source": "news", "date": "2 hours ago", "content": "完整的文章文本..."}
]

第一个元素是搜索元数据。随后的每个元素包含一个带有完整提取内容的结果。

结果字段：
- title —— 页面标题
- url —— 源 URL
- source —— "web"、"news" 或 "knowledge_graph"
- content —— 完整提取的页面文本（如果提取失败，则回退到搜索摘要片段）
- date —— 可用时显示（新闻结果始终有，网页结果有时有）

CLI 参考