Serper

通过 Serper API 进行 Google 搜索。不仅获取搜索结果，还自动抓取并解析实际网页内容，使用 trafilatura 提取干净、完整的纯文本 —— 不仅是摘要片段，而是整篇文章的全文。

工作原理

1. Serper API 调用 — 快速执行 Google 搜索，即时返回结果 URL
2. 并发网页抓取 — 所有结果页面并行抓取，并使用 trafilatura 提取内容，每个页面设置 3 秒超时
3. 流式输出 — 每个页面处理完成后立即输出一条结果，无需等待全部完成

每次调用默认返回 5 条结果（default 模式），当前模式最多可返回 6 条结果，每条均附带完整网页正文。这已提供大量信息。

查询规范

精心构造 ONE 个优质搜索查询。这几乎总是足够了。

每次调用即返回多条结果及其完整正文 —— 单次查询即可实现广泛覆盖。切勿为“探索”某一主题而发起多次搜索。一个经过审慎选择的查询，配合恰当的模式，即可全面覆盖需求。

最多两次调用：仅当用户请求确实涵盖两个独立主题时（例如：“对比 X 与 Y”，其中 X 和 Y 需分别搜索；或一次 default + 一次 current 调用以覆盖不同维度）。绝不可超过两次。

请勿执行以下操作：

• 对同一查询使用不同措辞重复调用，以“获取更多结果”
• 按顺序发起多次搜索以“深入挖掘”——全文内容本身已足够深入
• 先用一次搜索定位目标，再用另一次搜索跟进——请直接阅读已有内容

适用场景

在以下情况中使用 serper：

• 任何需从网络获取当前、客观事实信息的问题
• 需获取完整文章内容（而非仅摘要）的研究类问题
• 新闻与时事动态
• 产品信息、价格、对比、评测
• 技术文档、操作指南
• 任何必须阅读原始网页才能准确理解的内容

请勿在以下情况中使用该技能：

• 可通过你的训练数据直接回答的问题
• 纯数学计算、代码执行、创意写作
• 问候语、闲聊类对话

重要提示：该技能已自动抓取并提取网页全文。请勿对本技能返回的 URL 再次调用 web_fetch、WebFetch 或任何其他 URL 抓取工具。相关内容已内置于输出中。

两种搜索模式

仅有两种模式。请根据查询意图选择合适的一种：

default — 通用搜索（全时段）

• 全时段 Google 网页搜索，返回 5 条结果，每条均附带完整网页正文
• 适用于：通用性问题、研究性任务、操作指南、长青型主题（evergreen topics）、产品信息、技术文档、对比分析、教程等 —— 所有非时效性内容

current — 新闻与近期信息

• 过去一周的 Google 网页搜索（3 条结果）+ Google 新闻（3 条结果），每条均附带完整网页正文
• 适用于：新闻、时事动态、最新进展、突发新闻、官方公告等所有具有时效性的内容

模式选择参考表

地域设置（非英语查询时 REQUIRED）

默认为全球范围 — 不应用国家过滤，返回英文结果。此设置 仅适用于英文查询。

当满足以下任一条件时，你 MUST 始终指定 --gl 和 --hl 参数：

• 用户消息使用非英语语言
• 你构造的搜索查询为非英语
• 用户提及特定国家、城市或地区
• 用户要求获取本地化结果（如价格、新闻、门店等），且上下文为非英语环境

若用户使用德语提问，你 MUST 传入 --gl de --hl de。无例外。

经验法则： 若查询字符串中包含非英语词汇，则 --gl 与 --hl 必须设为对应语言的代码。

调用方式

python3 scripts/search.py -q "QUERY" [--mode MODE] [--gl COUNTRY] [--hl LANG]

示例

# 英文，通用研究
python3 scripts/search.py -q "how does HTTPS work"

# 英文，时效性内容
python3 scripts/search.py -q "OpenAI latest announcements" --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 数组 —— 每个页面抓取完成后即刻输出一条 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 参数参考