web-search

ウェブ検索

1つまたは複数のプロバイダーを横断して検索し、rg、jq、その他のツールに渡せる JSON ファイルを取得します。回答が、学習データに含まれていない可能性のある最新情報に依存する場合は、必ずこれを使用してください。最近のリリース、今日のニュース、今週時点の特定ベンダーの API、ライブラリの実際の使用例、セキュリティ勧告などが該当します。

判断：このスキルを使うべきですか？

質問の内容	ウェブ検索を使う？	理由
「現在の X は？」／「Y の最新情報は？」	はい	時間によって変わる情報です
「ライブラリ Z の使用例を探してください」	はい	実際のコードを調べられます
「ベンダーが今月 A について発表した内容は？」	はい	最近のベンダー発表です
「コマンドラインフラグ B のドキュメントを調べてください」	はい	信頼できる一次資料です
「X の構文は？」（広く知られている言語機能）	いいえ	学習済みの知識を使います
「概念 C と D の違いを説明してください」	場合によります	まず学習済みの知識を使います。ユーザーが出典を求めている場合は検索で確認します
「このコードベースで X を実行するファイルを探してください」	いいえ	grep やコードベースの調査を使います。ウェブ検索ではありません

検索する場合は、以下から適切な呼び出しパターンを選んでください。

呼び出し方法

複雑さの低い順に、3つのパターンがあります。

パターン 1：単一プロバイダー（最も一般的）

python3 scripts/web-search "<your query>"

設定済みのデフォルトプロバイダー（API キーが設定されていない場合は DuckDuckGo）を使用します。人が読めるプレビューと、結果ファイルを示す機械可読なフッターを標準出力に出力します。

=== duckduckgo (10 results, 393ms) ===
  [1] Python (programming language)
      https://en.wikipedia.org/wiki/Python_(programming_language)
      Python is a high-level, general-purpose programming language...
  [2] ...

--- WEBSEARCH ---
RESULT_FILE: /tmp/web-search/20260501T073731Z/combined.json
RUN_DIR:     /tmp/web-search/20260501T073731Z
PROVIDERS:   duckduckgo
TOTAL_RESULTS: 10

パターン 2：特定のプロバイダー

python3 scripts/web-search --provider tavily "<query>"
python3 scripts/web-search --provider perplexity "<query>" --max-results 5
python3 scripts/web-search --provider anthropic "<query>"

既知の機能を使いたい場合は、特定のプロバイダーを選びます。Perplexity は期間を指定した最新情報の検索に、Tavily は整理された LLM スニペットに、Anthropic／OpenAI／xAI はモデルを介した統合に適しています。

パターン 3：複数プロバイダーでの並列検索

# Subset of providers in parallel:
python3 scripts/web-search --providers tavily,brave,perplexity "<query>"

# Every configured provider in parallel:
python3 scripts/web-search --all "<query>"

以下の場合は、複数プロバイダーを使用してください。

• 話題が新しく、さまざまなインデックスを使って相互に照合したい場合
• 最初の検索で、単一のプロバイダーから得られた結果が少ない、または関連性が低い場合
• ユーザーが「徹底的な調査」や「複数の情報源からの調査」を求めた場合

このスキルは各プロバイダーの出力を個別に保存するため、一部でエラーが発生しても有用なデータを取得できます。

パターン 4：順次フォールバックチェーン（設定駆動）

設定に fallback フィールドを追加すると、結果を返したプロバイダーが見つかるまで、スキルがプロバイダーを順番に実行します。

{
  "default": "brave",
  "fallback": ["openai", "duckduckgo", "mwmbl"]
}

これで、python3 scripts/web-search "<query>"（--provider フラグなし）はまず brave を試します。エラーが発生するか、結果が 0 件の場合は openai に切り替わります。認証情報がないプロバイダーは通知なしでスキップされるため、チェーンは duckduckgo などへ進みます。フッターには MODE: fallback と FALLBACK_TRIED: <providers that failed> が表示されます。

以下の場合は、フォールバックチェーンを使用してください。

• 有料プロバイダーのレート制限や障害に対する耐障害性を高めたい場合
• 有料のプライマリプロバイダーの下に、無料の予備手段を用意したい場合
• 将来に備えたい場合。今日チェーンに openai を追加しておけば、apiKey を追加した時点で有効になります

--provider、--providers、--all はすべてチェーンより優先されます。1回の呼び出しで特定の動作を指定する場合に使用してください。

結果の読み取り

実行するたびに、<TMP_ROOT>/<run-id>/ にファイルが書き込まれます。このパスは標準出力の RESULT_FILE: に表示されます。デフォルトの <TMP_ROOT> は、macOS／Linux では /tmp/web-search、Windows では <system-temp>/web-search です。

後続の自動化に便利なフラグは3つあります。

フラグ	効果
--print-path-only	combined.json の絶対パスのみを出力します。$(...) の中で使用します。
--json	マニフェスト全体の JSON を標準出力に出力します。そのまま jq に渡せます。
--no-preview	人が読めるプレビューを省略し、機械可読なフッターのみを残します。

パイプライン（このスキルの目的）

JSON をディスクに出力する主な目的は、検索を再実行せずに結果をフィルタリング、変換、結合できるようにすることです。以下に例を示します。

# Get every URL across all providers:
RESULT=$(python3 scripts/web-search --all --print-path-only "...")
jq -r '.manifests[].results[].url' "$RESULT"

# Filter results to lines mentioning "release":
rg -i "release" "$RESULT"

# Stream straight from --json without disk:
python3 scripts/web-search --json "..." | jq '.manifests[].results[0]'

# Top result per provider:
jq -r '.manifests[] | "\(.provider): \(.results[0].title) - \(.results[0].url)"' "$RESULT"

# Dedupe across providers, sorted by score:
jq '[.manifests[].results[]] | unique_by(.url) | sort_by(-(.score // 0)) | .[:10]' "$RESULT"

その他のレシピについては、references/pipelines.md をご覧ください。

ラッパーが利用できない場合

ホストに curl はあるものの Python がない場合（Windows マシンの一部、distroless コンテナー、隔離された CI など）は、プロバイダーを直接呼び出してください。各プロバイダーの正確なリクエスト形式は、references/curl-recipes.md に記載されています。出力スキーマはスキルが内部で生成するものと一致しており、フィールドも名前も同じです。

設定

このスキルは設定なしで利用できます。DuckDuckGo と MWMBL は匿名の呼び出しを受け付けます。認証情報を追加すると、利用できるプロバイダーの幅が広がります。次のいずれかの場所に設定ファイルを配置してください。

OS	パス
macOS / Linux	~/.config/web-search/config.json
Windows	%APPDATA%\web-search\config.json
任意（プロジェクト内）	./web-search.json
任意（環境変数）	$WEBSEARCH_CONFIG にファイルのパスを指定

または、対応する環境変数（TAVILY_API_KEY、BRAVE_API_KEY など）を設定すると、スキルがそれを読み込みます。プロバイダーごとのキー取得手順については、references/setup.md を参照してください。

設定を検証します。

python3 scripts/web-search --check
python3 scripts/web-search --list-providers

baseUrl の上書き（すべてのプロバイダー）

すべてのプロバイダーで、デフォルトのエンドポイントを完全に置き換える baseUrl フィールドが利用できます。

{
  "providers": {
    "tavily":    {"apiKey": "tvly-...", "baseUrl": "https://eu.api.tavily.com/search"},
    "anthropic": {"apiKey": "sk-ant-...", "baseUrl": "https://anthropic-gw.internal.example.com/v1/messages"},
    "openai":    {"apiKey": "sk-...", "baseUrl": "http://localhost:8787/openai/v1/responses"}
  }
}

セルフホスト可能なプロキシ、地域別ミラー、企業ゲートウェイ、ローカルモックに使用してください。上書きは完全に置き換えるものであり、スキルがデフォルトの URL に連結することはありません。具体的な例については、references/base-urls.md を参照してください。

クロスプラットフォームでの動作

macOS、Linux、WSL、Git Bash、Windows ネイティブ環境、コンテナーで同じコマンドが動作します。Python スクリプトは標準ライブラリとパス処理用の pathlib.Path のみを使用するため、シェル固有の記法や / と \ の違いによる問題はありません。

Windows 固有の注意点：

# PowerShell:
$env:TAVILY_API_KEY = "tvly-..."
python scripts\web-search "your query"

# cmd.exe:
set TAVILY_API_KEY=tvly-...
python scripts\web-search "your query"

シバン #!/usr/bin/env python3 は Windows では無視されるため、python（または py）を明示的に実行してください。詳しいガイドは references/platform-notes.md を参照してください。

プロバイダー選択ガイド

プロバイダー	認証	最適な用途
duckduckgo	なし	手早い事実確認。「X とは」など
mwmbl	なし	実際のウェブリンクを得るための無料の代替手段
exa	必須	セマンティック検索、技術的なクエリ
tavily	必須	LLM に適した、整形済みのスニペット
brave	必須	独立したインデックス、プライバシーを重視する検索
serper	必須	低コストで Google のオーガニック検索結果を取得
google-cse	必須 + CSE ID	カスタムエンジンを使った公式 Google 検索
z-ai	必須	中国語のクエリ
perplexity	必須	最近の情報に絞った検索。回答の有無を選択可能
xai	必須	Grok の web_search と x_search（X/Twitter の投稿）
openai	必須	GPT が統合したウェブ検索
anthropic	必須	Claude が統合したウェブ検索

API 形式、サーバーの上限、注意点を含む全プロバイダー一覧は、references/providers/index.md を参照してください。各プロバイダーには専用のページがあります（例：providers/tavily.md、providers/anthropic.md）。

ドメインフィルタリング

特定のドメインに結果を絞り込む、または特定のドメインを除外します。

python3 scripts/web-search "..." --include docs.python.org,python.org
python3 scripts/web-search "..." --exclude reddit.com,medium.com

--include と --exclude はどちらも、カンマ区切りのリストを受け付けます。一部のプロバイダー（z-ai、xAI）には、より厳しい上限があります。詳細は references/providers/ 配下の各プロバイダーページを参照してください。呼び出し時に、許可リストとブロックリストを同時に指定することはできません。

コストへの配慮

料金区分	プロバイダー
無料、キー不要	duckduckgo、mwmbl
キーがあれば無料（無料枠は少量）	tavily、serper、google-cse、perplexity（少量）
呼び出しごとに有料	brave、z-ai、perplexity（大量利用）、xai、openai、anthropic

モデルを介するプロバイダー（xai、openai、anthropic）は、呼び出しごとに加えてトークンごとにも課金されます。エージェントのループが際限なく続くのを防ぐには、設定で maxUses（Anthropic）または max_tool_calls（OpenAI）を指定してください。広範な検索には、より安価な非モデル系プロバイダーを優先し、LLM を介した検索は情報の統合に限定して使用してください。

失敗パターン

症状	原因	対処方法
config error: No default provider configured	キーが設定されておらず、デフォルトも未設定です	--check を実行し、少なくとも 1 つのプロバイダーを設定するか、--provider duckduckgo を使用してください
[provider] HTTP 401	API キーが無効、または期限切れです	キーをローテーションし、--check で確認してください
[provider] HTTP 429	レート制限に達しています	--parallelism を下げる、実行間に遅延を追加する、またはプロバイダーを切り替えてください
Failed to parse response: ...	上流のスキーマが変更された、または baseUrl が誤ったパスを指しています	実行ディレクトリにある <provider>-raw.json を確認してください
プレビューが空で、結果が 0 件	クエリが絞り込まれすぎている、またはプロバイダーに関連するインデックスがありません	--all を試すか、別のプロバイダーを使用してください

上流からの未加工のレスポンスは常に <run-dir>/<provider>-raw.json に保存されるため、再クエリせずに失敗内容を確認できます。

リファレンス索引

ファイル	内容
references/providers/index.md + プロバイダーごとのページ	12 個の各プロバイダーについて、エンドポイント、認証、リクエスト／レスポンスの形式、セットアップ、curl のレシピ、特記事項、baseUrl のパターンを説明しています。索引には比較表と選択ガイドがあります。
references/setup.md	各プロバイダーの API キー取得手順
references/pipelines.md	結果のフィルタリングと結合に使う rg / jq / awk のレシピ
references/curl-recipes.md	プロバイダーごとの curl の直接実行例 — Python を使わない代替方法
references/multi-provider.md	並列ファンアウト戦略、コンセンサスによるランキング、障害の分離
references/result-schema.md	標準 JSON 出力スキーマ、プロバイダーごとのフィールド対応
references/platform-notes.md	macOS / Linux / Windows / WSL / コンテナーに関する注意事項
references/base-urls.md	プロキシ、ゲートウェイ、モック、ミラー向けの baseUrl 上書きパターン

クイックリファレンス

python3 scripts/web-search [OPTIONS] "<query>"

  --provider NAME         Single provider (overrides default)
  --providers a,b,c       Comma-separated subset, run in parallel
  --all                   Run every configured provider in parallel
  --max-results N         Cap per provider (default 10)
  --include DOMAIN[,...]  Allow-list domains
  --exclude DOMAIN[,...]  Block-list domains
  --config PATH           Override config file
  --tmp-dir PATH          Override output directory
  --json                  Print full manifest to stdout
  --print-path-only       Print only the result file path
  --raw                   Print raw upstream JSON
  --list-providers        Show configured providers and exit
  --check                 Validate config, exit 0 if any provider works

迷った場合は、次のようにしてください。

python3 scripts/web-search --provider duckduckgo "<query>"   # always works, no key needed