frederico-kluser/surf-skill

surf-skill は何をしますか？

npm i -g surf-skill — AI コーディングエージェント向けのマルチプロバイダ（Tavily + Parallel AI）Web スキル。CLI + Node ライブラリ、自動フォールバック、マルチキーローテーション、クロスプラットフォーム、バッチ検索。

概要

surf-skill は、AI エージェントが Web から情報を取得するための柔軟なツールです。Tavily と Parallel AI の両方をプロバイダとしてサポートし、一方が利用できない場合に自動的に他方にフォールバックします。また、環境変数に複数の API キーを設定しておくことで、キーを自動ローテーションしながら検索を実行できます。

インストール

npm install -g surf-skill

または、プロジェクトの依存関係として追加する場合：

npm install surf-skill

環境変数

以下の環境変数を設定することで、Tavily と Parallel AI の API キーを指定できます。

• TAVILY_API_KEY — Tavily の API キー（カンマ区切りで複数指定可能）
• PARALLEL_API_KEY — Parallel AI の API キー
• SURF_PROVIDER — 使用するプロバイダ（tavily、parallel、または auto）。デフォルトは auto

export TAVILY_API_KEY="key1,key2,key3"
export PARALLEL_API_KEY="your-parallel-key"
export SURF_PROVIDER="auto"

CLI の使用法

# 基本的な検索
surf "今日の天気は？"

# プロバイダを指定
surf --provider tavily "Python の最新トレンド"

# 結果の最大数を指定
surf --max-results 5 "機械学習ニュース"

# バッチ検索（複数クエリ）
surf --batch queries.txt

引数

引数	説明
query	検索クエリ（単一またはバッチファイル内）
--provider, -p	使用するプロバイダ（tavily、parallel、auto）
--max-results, -n	返す結果の最大数（デフォルト: 10）
--batch, -b	バッチモード（ファイルパスまたはクエリのカンマ区切りリスト）
--help, -h	ヘルプを表示

Node ライブラリとしての使用法

import surf from 'surf-skill';

// 単一クエリ
const results = await surf.search('人工知能の最新研究');
console.log(results);

// オプションを指定
const results = await surf.search('量子コンピューティング', {
  provider: 'tavily',
  maxResults: 5
});
console.log(results);

// バッチ検索
const queries = ['AI', '機械学習', '深層学習'];
const allResults = await surf.batchSearch(queries);
console.log(allResults);

API リファレンス

surf.search(query, options?)

• query (string) — 検索クエリ
• options.provider (string) — プロバイダ名（tavily、parallel、auto）。デフォルトは環境変数 SURF_PROVIDER の値、または auto
• options.maxResults (number) — 結果の最大数。デフォルトは 10
• 戻り値: Promise<SearchResult[]>

surf.batchSearch(queries, options?)

• queries (string[]) — 検索クエリの配列
• options — 上記と同じオプション
• 戻り値: Promise<SearchResult[][]>

結果オブジェクト

interface SearchResult {
  title: string;
  url: string;
  content: string;
  score?: number;
}

フォールバックとキーローテーション

auto プロバイダモードでは、以下の順序でプロバイダが試行されます：

1. Tavily（複数キーが設定されている場合は順に試行）
2. Parallel AI（Tavily が失敗した場合）

キーローテーションは、API レート制限やキーの無効化を回避するために、環境変数にカンマ区切りで指定されたキーを巡回します。

export TAVILY_API_KEY="key1,key2,key3,key4"

この場合、最初の検索では key1、次は key2 というように使用されます。すべてのキーが使用されると、再度 key1 に戻ります。

クロスプラットフォーム対応

surf-skill は以下の OS で動作確認済みです：

• Linux（Ubuntu、Debian、Fedora など）
• macOS（Intel および Apple Silicon）
• Windows（PowerShell、CMD、WSL）

例

天気予報を取得する CLI エージェント

surf "東京 明日の天気" --max-results 3

ニュース記事をバッチで収集する Node スクリプト

import surf from 'surf-skill';

const topics = ['テクノロジーニュース', 'スポーツ', '政治'];
const results = await surf.batchSearch(topics);

results.forEach((topicResults, index) => {
  console.log(`トピック: ${topics[index]}`);
  topicResults.forEach(result => {
    console.log(`- ${result.title}: ${result.url}`);
  });
});

ライセンス

MIT