google-search

Google 検索

Frevana を通じて Google 検索結果を検索します。

目的

このスキルは、通常の Google 検索結果を見つけるためのものです。

入力：

• q
• 任意の location
• 任意の gl
• 任意の hl
• 任意の num
• 任意の start
• 任意の safe
• 任意の device

出力：

• Google 検索結果を含む、検証済みのレスポンス JSON
• 成功するたびにローカルファイルに保存される、同じ検証済み JSON

このスキルはレスポンスが JSON であることを検証し、ディスクに保存して、変更せずに標準出力へ返します。ユーザーが明示的に変換を依頼しない限り、返されたデータを書き換えたり、構造を変更したりしないでください。

このスキルに必要なもの

• ユーザーが指定した q
• 任意の location
• 任意の gl
• 任意の hl
• 任意の num
• 任意の start
• 任意の safe
• 任意の device
• 環境変数に設定された FREVANA_TOKEN、または今回の実行に限り明示的に指定する --token の上書き値
• curl
• bash
• python3

実行順序

リクエストをシンプルかつ確実に保つため、次の流れに従ってください。

1. ユーザーが q または同等の Google 検索クエリを指定していることを確認します。
2. 即席の curl コマンドよりスクリプトを優先します。
3. まずスクリプトに FREVANA_TOKEN を読み込ませます。
4. 対話型シェルでの使用時に FREVANA_TOKEN が設定されていない場合、スクリプトが入力を求めることがあります。
5. 非対話型またはエージェントのワークフローでは、トークンが設定されていない場合はすぐに失敗させ、FREVANA_TOKEN を設定するか、--token を明示的に渡すようユーザーに伝えます。
6. スクリプトを一度実行します。検証済み JSON が標準出力に表示され、同じ JSON がファイルに保存されます。
7. 追加の解析や要約には、検索 API を再度呼び出すのではなく、保存した JSON ファイルを使用します。
8. 検証済みのレスポンス JSON を返すか、ユーザーがペイロード全体を必要としない場合は、関連性の高い検索結果を要約します。

コマンド

基本的な Google 検索

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

--query は --q の別名として使用できます。

国、言語、場所を指定した検索

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

ページネーション、結果件数、セーフサーチ、デバイスを指定した検索

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

レスポンス JSON を特定のファイルに保存

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

今回の実行に限りトークンを上書き

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

固定のリクエスト形式

スクリプトは、指定されていない任意フィールドを省略して、次の形式のペイロードを送信します。

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

必須項目は q のみです。ユーザーが指定していない場合、location、gl、hl、num、start、safe、device の値を作り出さないでください。

現在、Frevana エンドポイントのスキーマで公開されているのは q、location、gl、hl、num、start、safe、device のみです。engine、api_key、output、no_cache、async、zero_trace などの、サポートされていないパススルーフィールドは渡さないでください。また、Frevana エンドポイントのスキーマが拡張されるまでは、サポートされていない Google 検索フィールドも渡さないでください。

レスポンス形式

API は Frevana JSON を返します。一般的なフィールドは次のとおりです。

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

出力

• 成功時：スクリプトはレスポンス本文が JSON であることを検証し、ファイルに書き込み、保存先のパスを標準エラー出力に表示し、JSON を標準出力に表示します
• デフォルトのファイルパス：./out/google-search-<UTC timestamp>-<pid>.json
• --output を指定した場合：デフォルトのパスではなく、指定したファイルパスに同じ JSON が書き込まれます
• 失敗時：スクリプトはレスポンス本文または解析エラーを表示し、ゼロ以外の終了コードで終了します

注意事項

• --q または --query を必ず指定してください
• 結果を保存して要約するためだけに、スクリプトを 2 回実行しないでください。スクリプトは常に、出力するものと同じ JSON を保存します。
• ユーザーが検索元として都市、州、または国を指定した場合は、--location を使用してください
• ユーザーが国または地域コードを指定した場合は、--gl を使用してください
• ユーザーが言語コードを指定した場合は、--hl を使用してください
• --num は、結果数が 1 から 100 の場合にのみ使用してください
• ユーザーが結果オフセットによるページネーションを指定した場合は、--start を使用してください
• --safe は active または off の場合にのみ使用してください
• --device は desktop、mobile、または tablet の場合にのみ使用してください
• curl がない場合は処理を中止し、ユーザーに curl のインストールを伝えてください
• python3 がない場合は処理を中止し、ユーザーに python3 のインストールを伝えてください
• Bearer トークンをユーザーにそのまま返さないでください
• ユーザーが完全なペイロードを求めていない限り、生の JSON をそのまま出力せず、ユーザーが実際に必要としている検索結果を要約してください

プロンプト例

中国語

• 「Google で coffee を検索して」
• 「location=Austin, Texas, United States、gl=us、hl=en で、Google の検索結果 q=coffee を調べて」
• 「Google で coffee を検索して。3 ページ目のモバイル端末の結果を取得し、生の JSON を保存して」

英語

• 「Google で coffee を検索して」
• 「location=Austin, Texas, United States、gl=us、hl=en で Google の検索結果を調べて」
• 「Google で coffee をモバイル端末向けに検索し、start=20 を指定して、生の JSON を保存して」