serper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Serper

Google search via Serper API. Fetches results AND reads the actual web pages to extract clean full-text content via trafilatura. Not just snippets — full article text.

通过Serper API实现Google搜索。获取搜索结果并读取实际网页，通过trafilatura提取干净的全文内容。不仅是片段——而是完整的文章文本。

How It Works

工作原理

Serper API call — fast Google search, returns result URLs instantly
Concurrent page scraping — all result pages are fetched and extracted in parallel using trafilatura with a 3-second timeout per page
Streamed output — results print one at a time as each page finishes

Each invocation gives you 5 results (default mode) or up to 6 results (current mode), each with full page content. This is already a lot of information.

Serper API调用 —— 快速Google搜索，立即返回结果URL
并发页面抓取 —— 使用trafilatura并行抓取所有结果页面，每个页面3秒超时
流式输出 —— 每个页面处理完成后立即打印结果

每次调用会返回5条结果（默认模式）或最多6条结果（current模式），每条结果都包含完整页面内容。这已经是大量信息了。

Query Discipline

查询规范

Craft ONE good search query. That is almost always enough.

Each call returns multiple results with full page text — you get broad coverage from a single query. Do not run multiple searches to "explore" a topic. One well-chosen query with the right mode covers it.

At most two calls if the user's request genuinely spans two distinct topics (e.g. "compare X vs Y" where X and Y need separate searches, or one

default

+ one

current

call for different aspects). Never more than two.

Do NOT:

Run the same query with different wording to "get more results"
Run sequential searches to "dig deeper" — the full page content is already deep
Run one search to find something, then another to follow up — read the content you already have

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

每次调用会返回多条带完整页面文本的结果——单个查询即可覆盖广泛内容。不要为了“探索”主题而运行多次搜索。一个选择合适模式的精心查询就能满足需求。

最多两次调用的情况：当用户请求确实涉及两个不同主题时（例如“对比X和Y”，其中X和Y需要单独搜索，或者一次

default

+一次

current

调用以获取不同维度的信息）。绝对不要超过两次。

禁止操作：

使用不同措辞运行相同查询以“获取更多结果”
连续搜索以“深入挖掘”——完整页面内容已经足够深入
先搜索找到内容，再进行后续搜索——先阅读已获取的内容

When to Use This Skill

何时使用此工具

Use serper when:

Any question that needs current, factual information from the web
Research topics that need full article content, not just snippets
News and current events
Product info, prices, comparisons, reviews
Technical docs, how-to guides
Anything where reading the actual page matters

Do NOT use this skill for:

Questions you can answer from your training data
Pure math, code execution, creative writing
Greetings, chitchat

IMPORTANT: This skill already fetches and extracts full page content. Do NOT use web_fetch, WebFetch, or any other URL-fetching tool on the URLs returned by this skill. The content is already included in the output.

在以下场景使用serper：

任何需要从网络获取当前事实信息的问题
需要完整文章内容而非仅片段的研究主题
新闻与时事
产品信息、价格、对比、评测
技术文档、操作指南
任何需要阅读实际页面内容的场景

禁止使用此工具的场景：

可通过训练数据回答的问题
纯数学计算、代码执行、创意写作
问候、闲聊

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

Two Search Modes

两种搜索模式

There are exactly two modes. Pick the right one based on the query:

共有两种模式。根据查询选择合适的模式：

default

— General search (all-time)

default

—— 通用搜索（全时段）

All-time Google web search, 5 results, each enriched with full page content
Use for: general questions, research, how-to, evergreen topics, product info, technical docs, comparisons, tutorials, anything NOT time-sensitive

全时段Google网页搜索，5条结果，每条结果都附带完整页面内容
适用场景：通用问题、研究、操作指南、常青主题、产品信息、技术文档、对比、教程等非时效性内容

current

— News and recent info

current

—— 新闻与近期信息

Past-week Google web search (3 results) + Google News (3 results), each enriched with full page content
Use for: news, current events, recent developments, breaking news, announcements, anything time-sensitive

过去一周的Google网页搜索（3条结果）+ Google新闻（3条结果），每条结果都附带完整页面内容
适用场景：新闻、时事、近期动态、突发新闻、公告等时效性内容

Mode Selection Guide

模式选择指南

Query signals	Mode
"how does X work", "what is X", "explain X"	`default`
Product research, comparisons, tutorials	`default`
Technical documentation, guides	`default`
Historical topics, evergreen content	`default`
"news", "latest", "today", "this week", "recent"	`current`
"what happened", "breaking", "announced", "released"	`current`
Current events, politics, sports scores, stock prices	`current`

查询信号	模式
“X的工作原理”、“什么是X”、“解释X”	`default`
产品调研、对比、教程	`default`
技术文档、指南	`default`
历史主题、常青内容	`default`
“新闻”、“最新”、“今日”、“本周”、“近期”	`current`
“发生了什么”、“突发”、“宣布”、“发布”	`current`
时事、政治、体育比分、股价	`current`

Locale (REQUIRED for non-English queries)

区域设置（非英文查询必填）

Default is global — no country filter, English results. This ONLY works for English queries.

You MUST ALWAYS set
--gl
and
--hl
when ANY of these are true:

The user's message is in a non-English language
The search query you construct is in a non-English language
The user mentions a specific country, city, or region
The user asks for local results (prices, news, stores, etc.) in a non-English context

If the user writes in German, you MUST pass
--gl de --hl de
. No exceptions.

Scenario	Flags
English query, no country target	(omit --gl and --hl)
German query OR user writes in German OR targeting DE/AT/CH	`--gl de --hl de`
French query OR user writes in French OR targeting France	`--gl fr --hl fr`
Any other non-English language/country	`--gl XX --hl XX` (ISO codes)

Rule of thumb: If the query string contains non-English words, set

--gl

and

--hl

to match that language.

默认是全局——无国家筛选，返回英文结果。仅适用于英文查询。

当满足以下任一条件时，必须设置
--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
以匹配该语言。

How to Invoke

调用方式

bash

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

bash

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

Examples

示例

bash

undefined

bash

undefined

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

德语查询 —— 设置区域+current模式获取新闻/价格

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

---

python3 scripts/search.py -q "meilleur smartphone 2026" --gl fr --hl fr

---

Output Format

输出格式

The output is a streamed JSON array — elements print one at a time as each page is scraped:

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..."}
]

The first element is search metadata. Each following element contains a result with full extracted content.

Result fields:

```
title
```
— page title
```
url
```
— source URL
```
source
```
—
```
"web"
```
,
```
"news"
```
, or
```
"knowledge_graph"
```
```
content
```
— full extracted page text (falls back to search snippet if extraction fails)
```
date
```
— present when available (news results always, web results sometimes)

输出为流式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 Reference

CLI参考

Flag	Description
`-q, --query`	Search query (required)
`-m, --mode`	`default` (all-time, 5 results) or `current` (past week + news, 3 each)
`--gl`	Country code (e.g. `de` , `us` , `fr` , `at` , `ch` )
`--hl`	Language code (e.g. `en` , `de` , `fr` )

参数	描述
`-q, --query`	搜索查询（必填）
`-m, --mode`	`default` （全时段，5条结果）或 `current` （过去一周+新闻，各3条）
`--gl`	国家代码（例如 `de` 、 `us` 、 `fr` 、 `at` 、 `ch` ）
`--hl`	语言代码（例如 `en` 、 `de` 、 `fr` ）

serper

Original

Translation

Serper

Serper

How It Works

工作原理

Query Discipline

查询规范

When to Use This Skill

何时使用此工具

Two Search Modes

两种搜索模式

`default`
— General search (all-time)

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

`current`
— News and recent info

`current`
—— 新闻与近期信息

Mode Selection Guide

模式选择指南

Locale (REQUIRED for non-English queries)

区域设置（非英文查询必填）

How to Invoke

调用方式

Examples

示例

English, general research

英文，通用研究

English, time-sensitive

英文，时效性内容

German query — set locale + current mode for news/prices

德语查询 —— 设置区域+current模式获取新闻/价格

German news

德语新闻

French product research

法语产品调研

Output Format

输出格式

CLI Reference

CLI参考