google-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Search

Google 搜索

Search Google results through Frevana.

通过Frevana获取Google搜索结果。

Purpose

用途

This skill is for finding regular Google Search results.

Inputs:

```
q
```
optional
```
location
```
optional
```
gl
```
optional
```
hl
```
optional
```
num
```
optional
```
start
```
optional
```
safe
```
optional
```
device
```

Output:

validated response JSON with Google Search results
the same validated JSON saved to a local file on every successful run

This skill validates that the response is JSON, saves it to disk, and returns it unchanged on stdout. Do not rewrite or reshape the returned data unless the user explicitly asks for a transformation.

本技能用于获取常规Google搜索结果。

输入参数：

```
q
```
可选参数
```
location
```
可选参数
```
gl
```
可选参数
```
hl
```
可选参数
```
num
```
可选参数
```
start
```
可选参数
```
safe
```
可选参数
```
device
```

输出结果：

包含Google搜索结果的验证后响应JSON
每次运行成功后，会将相同的验证后JSON保存到本地文件

本技能会验证响应是否为JSON格式，将其保存到磁盘，并在标准输出中原样返回。除非用户明确要求转换，否则请勿重写或修改返回的数据。

What This Skill Needs

该技能所需条件

user-provided
```
q
```
optional
```
location
```
optional
```
gl
```
optional
```
hl
```
optional
```
num
```
optional
```
start
```
optional
```
safe
```
optional
```
device
```
```
FREVANA_TOKEN
```
in the environment, or an explicit
```
--token
```
override for the current run
```
curl
```
```
bash
```
```
python3
```

用户提供的
```
q
```
可选参数
```
location
```
可选参数
```
gl
```
可选参数
```
hl
```
可选参数
```
num
```
可选参数
```
start
```
可选参数
```
safe
```
可选参数
```
device
```
环境变量中的
```
FREVANA_TOKEN
```
，或当前运行时显式使用
```
--token
```
覆盖
```
curl
```
```
bash
```
```
python3
```

Execution Order

执行流程

Use this flow so the request stays simple and reliable:

Confirm the user has provided
```
q
```
or an equivalent Google search query.
Prefer the script over ad hoc
```
curl
```
commands.
Let the script read
```
FREVANA_TOKEN
```
first.
In interactive shell usage, if
```
FREVANA_TOKEN
```
is missing, the script may prompt for it.
In non-interactive or agent workflows, fail fast if the token is missing and tell the user to set
```
FREVANA_TOKEN
```
or pass
```
--token
```
explicitly.
Run the script once. It prints the validated JSON to stdout and saves the same JSON to a file.
Use the saved JSON file for any follow-up parsing or summarization instead of calling the search API again.
Return the validated response JSON, or summarize the most relevant search results if the user does not need the full payload.

遵循以下流程可确保请求简单可靠：

确认用户已提供
```
q
```
或等效的Google搜索查询。
优先使用脚本而非临时的
```
curl
```
命令。
让脚本优先读取
```
FREVANA_TOKEN
```
。
在交互式shell使用场景中，如果缺少
```
FREVANA_TOKEN
```
，脚本可能会提示用户输入。
在非交互式或Agent工作流中，如果缺少令牌则立即终止，并告知用户设置
```
FREVANA_TOKEN
```
或显式传递
```
--token
```
。
运行一次脚本。它会将验证后的JSON打印到标准输出，并将相同的JSON保存到文件。
后续的解析或总结操作使用保存的JSON文件，而非再次调用搜索API。
返回验证后的响应JSON；如果用户不需要完整负载，则总结最相关的搜索结果。

Commands

命令示例

Basic Google search

基础Google搜索

bash

bash <skill-path>/scripts/search_google.sh \
  --q "coffee"

--query

is accepted as an alias for

--q

bash

bash <skill-path>/scripts/search_google.sh \
  --q "coffee"

--query

可作为

--q

的别名。

Search with country, language, and location

指定国家、语言和地点的搜索

bash

bash <skill-path>/scripts/search_google.sh \
  --q "coffee" \
  --location "Austin, Texas, United States" \
  --gl us \
  --hl en

bash

bash <skill-path>/scripts/search_google.sh \
  --q "coffee" \
  --location "Austin, Texas, United States" \
  --gl us \
  --hl en

Search with pagination, result count, safe search, and device

指定分页、结果数量、安全搜索和设备的搜索

bash

bash <skill-path>/scripts/search_google.sh \
  --q "coffee" \
  --num 20 \
  --start 20 \
  --safe off \
  --device mobile

bash

bash <skill-path>/scripts/search_google.sh \
  --q "coffee" \
  --num 20 \
  --start 20 \
  --safe off \
  --device mobile

Save response JSON to a specific file

将响应JSON保存到指定文件

bash

bash <skill-path>/scripts/search_google.sh \
  --q "coffee" \
  --gl us \
  --hl en \
  --output ./out/google-search-result.json

bash

bash <skill-path>/scripts/search_google.sh \
  --q "coffee" \
  --gl us \
  --hl en \
  --output ./out/google-search-result.json

Token override for the current run

当前运行时覆盖令牌

bash

bash <skill-path>/scripts/search_google.sh \
  --q "coffee" \
  --token "your bearer token"

bash

bash <skill-path>/scripts/search_google.sh \
  --q "coffee" \
  --token "your bearer token"

Fixed Request Shape

固定请求格式

The script sends this payload shape, omitting optional fields that were not provided:

json

{
  "q": "coffee",
  "location": "Austin, Texas, United States",
  "gl": "us",
  "hl": "en",
  "num": 20,
  "start": 20,
  "safe": "off",
  "device": "mobile"
}

Only

is required. Do not invent

location

gl

hl

num

start

safe

, or

device

values when the user did not provide them.

The Frevana endpoint schema currently exposes only

location

gl

hl

num

start

safe

, and

device

; do not pass unsupported passthrough fields such as

engine

api_key

output

no_cache

async

, or

zero_trace

, and do not pass other unsupported Google Search fields unless the Frevana endpoint schema is expanded first.

脚本会发送以下格式的请求负载，省略未提供的可选字段：

json

{
  "q": "coffee",
  "location": "Austin, Texas, United States",
  "gl": "us",
  "hl": "en",
  "num": 20,
  "start": 20,
  "safe": "off",
  "device": "mobile"
}

仅

为必填项。当用户未提供时，请勿自行生成

location

、

gl

、

hl

、

num

、

start

、

safe

或

device

的值。

Frevana端点目前仅开放

、

location

、

gl

、

hl

、

num

、

start

、

safe

和

device

字段；请勿传递不支持的透传字段，如

engine

、

api_key

、

output

、

no_cache

、

async

或

zero_trace

，除非Frevana端点架构先进行扩展，否则也请勿传递其他不支持的Google搜索字段。

Response Shape

响应格式

The API returns Frevana JSON. Common fields include:

```
search_metadata
```
```
search_parameters
```
```
search_information
```
```
organic_results
```
```
related_questions
```
```
related_searches
```
```
knowledge_graph
```
```
answer_box
```
```
pagination
```

API返回Frevana格式的JSON。常见字段包括：

```
search_metadata
```
```
search_parameters
```
```
search_information
```
```
organic_results
```
```
related_questions
```
```
related_searches
```
```
knowledge_graph
```
```
answer_box
```
```
pagination
```

Output

输出说明

Success: the script validates that the response body is JSON, writes it to a file, prints the saved path to stderr, and prints the JSON to stdout

Default file path:

./out/google-search-<UTC timestamp>-<pid>.json

With
```
--output
```
: the same JSON is written to the specified file path instead of the default path
Failure: the script prints the response body or parsing error and exits non-zero

成功：脚本验证响应体为JSON格式，将其写入文件，将保存路径打印到标准错误输出，并将JSON打印到标准输出

默认文件路径：

./out/google-search-<UTC timestamp>-<pid>.json

使用
```
--output
```
参数：将相同的JSON写入指定路径，而非默认路径
失败：脚本打印响应体或解析错误，并以非零状态码退出

Notes

注意事项

Require
```
--q
```
or
```
--query
```
Do not call the script twice just to save and summarize results. It always saves the same JSON that it prints.
Use
```
--location
```
when the user requests a city, state, or country search origin
Use
```
--gl
```
when the user requests a country or region code
Use
```
--hl
```
when the user requests a language code
Use
```
--num
```
only for result counts from
```
1
```
to
```
100
```
Use
```
--start
```
when the user requests pagination by result offset
Use
```
--safe
```
only for
```
active
```
or
```
off
```
Use
```
--device
```
only for
```
desktop
```
,
```
mobile
```
, or
```
tablet
```
If
```
curl
```
is missing, stop and tell the user to install
```
curl
```
If
```
python3
```
is missing, stop and tell the user to install
```
python3
```
Do not echo the Bearer token back to the user
Summarize the search results the user actually cares about instead of dumping raw JSON unless they ask for the full payload

必须提供
```
--q
```
或
```
--query
```
不要为了保存和总结结果而两次调用脚本。脚本始终会保存与打印的JSON相同的内容。
当用户请求按城市、州或国家作为搜索来源时，使用
```
--location
```
当用户请求国家或地区代码时，使用
```
--gl
```
当用户请求语言代码时，使用
```
--hl
```
```
--num
```
仅支持1到100之间的结果数量
当用户请求按结果偏移量分页时，使用
```
--start
```
```
--safe
```
仅支持
```
active
```
或
```
off
```
值
```
--device
```
仅支持
```
desktop
```
、
```
mobile
```
或
```
tablet
```
值
如果缺少
```
curl
```
，请终止操作并告知用户安装
```
curl
```
如果缺少
```
python3
```
，请终止操作并告知用户安装
```
python3
```
不要向用户回显Bearer令牌
除非用户要求完整负载，否则总结用户真正关心的搜索结果，而非直接输出原始JSON

Example Prompts

示例提示

中文

"搜索 Google 上的 coffee"
"查一下 Google 搜索 q=coffee，location=Austin, Texas, United States，gl=us，hl=en"
"Google 搜索 coffee，第 3 页，移动端结果，并保存原始 JSON"

"搜索 Google 上的 coffee"
"查一下 Google 搜索 q=coffee，location=Austin, Texas, United States，gl=us，hl=en"
"Google 搜索 coffee，第 3 页，移动端结果，并保存原始 JSON"

English

"Search Google for coffee"
"Look up Google results for coffee with location=Austin, Texas, United States, gl=us, hl=en"
"Search Google for coffee on mobile with start=20 and save the raw JSON"

"Search Google for coffee"
"Look up Google results for coffee with location=Austin, Texas, United States, gl=us, hl=en"
"Search Google for coffee on mobile with start=20 and save the raw JSON"