メインコンテンツへ移動
AIチュートリアル

Everything Search SkillでAIエージェントからローカルファイルを数百万件検索

HTTPまたはネイティブWin32 IPCを介して、AIコーディングエージェントをVoidtools Everythingのインデックスに接続する方法を解説します。ホストのセットアップ、インストール、コンテナ設定、範囲指定検索、JSON出力、検索フィルター、ページネーション、高度なクエリ例を取り上げます。

約15分で読了
Everything Search SkillでAIエージェントからローカルファイルを数百万件検索

Everything Search Skillの機能

Everything Search Skillを使うと、AIコーディングエージェントからVoidtools Everythingがインデックス化したファイルへ超高速にアクセスできます。NTFSドライブ全体にある数百万件のファイルを検索でき、報告されている応答時間は15ミリ秒未満です。そのため、ソースファイル、設定ファイル、ログ、アセット、プロジェクトディレクトリの検索に役立ちます。

このプロジェクトは、es.exeに共通する制限に対応します。ネイティブのコマンドラインクライアントは、WindowsメッセージングとWin32 IPCを介してEverythingデスクトップアプリケーションと通信します。そのため、Docker、WSL2、Windows Sandbox、分離されたランナー、バックグラウンドセッションで実行されるエージェントでは、次のエラーが発生することがあります。

Error 8: Everything IPC window not found. Please make sure Everything is running.

この障害は、Windows User Interface Privilege IsolationとSession 0 Isolationにより、異なるデスクトップセッションにあるプロセス間で必要なウィンドウメッセージを交換できない場合に発生します。

デュアルモードアーキテクチャの仕組み

このスキルは、Everythingエンジンとの通信に2つの方式をサポートしています。

  1. HTTP RESTモード: サンドボックス、コンテナ、WSL2、リモート環境、Linux、macOSで推奨されるモードです。リクエストはWindowsホスト上で実行されているHTTPサーバーに送信されるため、Win32のセッション制限を回避できます。
  2. CLI IPCモード: ネイティブWindowsデスクトップセッション内で実行されるエージェント向けのフォールバックです。このモードでは、ヘルパーがEverythingの標準IPCメカニズムを介してes.exeを呼び出します。

自動モードでは、PythonヘルパーがまずHTTPを試し、適切な場合はCLIにフォールバックします。Python実装は標準ライブラリのモジュールのみを使用するため、サードパーティ製Python依存関係はありません。

主な機能

  • 高速なインデックス検索: ディレクトリを再帰的にスキャンせず、インデックス化されたNTFSドライブ全体からファイルを検索できます。
  • コンテナ対応: Docker、WSL2、Windows Sandbox、分離されたエージェントランナーをホストのHTTPエンドポイントに接続できます。
  • 範囲を指定した検索: インデックス化されたすべてのドライブを検索するか、ワークスペース内に結果を限定できます。
  • コンテキストに配慮した上限: -n 20などのオプションを使用して、大量の結果がAIエージェントのコンテキストウィンドウを消費するのを防げます。
  • 構造化された結果: PythonおよびPowerShellヘルパーからJSON出力を要求できます。
  • エージェント統合: Cursor、Codex、PI-Desktop、またはカスタムエージェント環境にこのスキルをインストールできます。

前提条件

Voidtools Everythingが実行され、インデックスを利用できるWindowsホストが必要です。ネイティブデスクトップで使用する場合、このスキルはes.exeを介して通信できます。Docker、WSL2、サンドボックス環境、またはリモート環境で使用する場合は、ホスト上でEverythingのHTTPサーバーを有効にしてください。

ステップ1: Everything HTTPサーバーを有効にする

WindowsホストでEverythingを開き、次の手順を実行します。

  1. Toolsを開き、続いてOptionsを選択します。
  2. 左側のナビゲーションでHTTP Serverを選択します。
  3. Enable HTTP Serverを有効にします。
  4. ポートを8080に設定します。
  5. 設定を確定します。

リポジトリのPowerShellセットアップスクリプトを実行することもできます。

.\scripts\enable_http.ps1 -Port 8080

HTTPエンドポイントは、分離されたエージェントとホスト上で実行されているEverythingサービスをつなぐ橋渡し役です。

ステップ2: スキルをクローンしてインストールする

PowerShellを開き、リポジトリをクローンしてそのディレクトリに移動し、インストーラーを実行します。

git clone https://github.com/Mayuqi-crypto/everything-search-skill.git
cd everything-search-skill
.\scripts\install.ps1

インストーラーはes.exeを~/.local/bin/に配置し、ユーザーのPATHを設定して、次のエージェント向けの場所にスキルを展開します。

  • ~/.agents/skills/
  • ~/.cursor/skills/
  • ~/.codex/skills/

ステップ3: 基本検索を実行する

デュアルモードのPythonヘルパーはscripts/everything_search.pyにあります。自動モードでは、まずHTTPエンドポイントを試し、利用可能な場合はネイティブCLIのフォールバックを使用します。

python scripts/everything_search.py "package.json" -n 20

-n 20引数により、応答を20件の一致結果に制限します。AIエージェントが出力を利用する場合、結果数の制限は特に重要です。

構造化されたJSONを返す

結果をプログラムで解析する場合は、--jsonを追加します。

python scripts/everything_search.py "ext:tsx component" -n 10 --json

このクエリは、ext:tsxとcomponentの両方に一致するインデックス項目を検索し、最大10件の結果をJSON形式で返します。

検索範囲をプロジェクトに限定する

Pythonヘルパーで-pを使用すると、検索をワークスペース内に限定できます。

python scripts/everything_search.py "main.py" -p "C:\Workspace\repo" -n 5

検索範囲を限定すると、他のプロジェクトからの無関係な一致を減らせるため、特定のリポジトリ内で作業するエージェントにとって出力がより有用になります。

HTTPモードを強制する

エージェントにホストのHTTPサーバーを必ず使用させる場合は、そのモードを明示的に選択します。

python scripts/everything_search.py "exact:Dockerfile" --mode http

exact:演算子はワイルドカード展開を無効にし、ファイル名を完全一致で検索します。

Dockerからスキルを使用する

EVERYTHING_HTTP_URLを使用して、ホストのエンドポイントをコンテナに渡します。リポジトリの例では、特殊なホスト名をホストゲートウェイにマッピングしています。

docker run -e EVERYTHING_HTTP_URL=http://host.docker.internal:8080 \
  --add-host host.docker.internal:host-gateway \
  my-agent-image

コンテナ内でPythonヘルパーを実行します。

python scripts/everything_search.py "package.json" -n 10 --json

リクエストは、コンテナ内からデスクトップIPCを試みるのではなく、TCP経由でEverything HTTPサーバーに送信されます。

WSL2でSkillを使用する

WSL2では、デフォルトルートからWindowsホストのアドレスを取得し、その結果得られたエンドポイントをEVERYTHING_HTTP_URLに設定します。

export EVERYTHING_HTTP_URL="http://$(ip route show | awk '/default/ {print $3}'):8080"
python3 scripts/everything_search.py "ext:py model" -n 10

このクエリは論理ANDを使用します。つまり、各結果はPython拡張子フィルターとmodelという語の両方を満たす必要があります。

ネイティブWindowsセッションでes.exeを使用する

エージェントがEverythingと同じネイティブデスクトップコンテキストで実行されている場合は、es.exeを直接呼び出せます。必ず適切な結果件数の上限を指定してください。

es.exe -n 20 "package.json"

ワークスペースに結果を限定する

es.exe -path "C:\my-repo" -n 20 "index.ts"

ファイルまたはディレクトリだけを返す

ファイルだけを対象にする場合は/a-d、ディレクトリだけを対象にする場合は/adを使用します。

es.exe /a-d -n 15 "ext:tsx component"
es.exe /ad -n 10 "node_modules"

新しいログを先に並べる

es.exe -sort-date-modified-descending -n 10 "ext:log dm:today"

これにより、今日のログファイルを検索し、更新日時の新しい順に並べます。

より正確なEverythingクエリを作成する

Everythingの検索構文を使うと、結果がエージェントに届く前に検索範囲を絞り込めます。

  • 複数の拡張子: 複数の拡張子に一致させるにはext:md;txt;jsonを使用します。
  • 最小ファイルサイズ: size:>100MBを使用します。
  • サイズ範囲: size:1MB..50MBを使用します。対応単位はB、KB、MB、GBです。
  • 更新日: dm:today、dm:last7days、またはdm:2025のような値を使用します。
  • 親パス: path:"C:\Workspace"を使用します。
  • 完全一致のファイル名: exact:Dockerfileを使用します。
  • 論理AND: model user ext:pyのように、語をスペースで区切ります。
  • 論理OR: *.jpg | *.pngのように、候補の間にパイプを置きます。
  • 論理NOT: *.ts !*.test.tsのように、除外条件の先頭に!を付けます。
  • 正規表現: ネイティブCLIの-rオプションを使用します。例: es.exe -r "src\\api\\.*\.go$"。

AIエージェントのワークフロー向け高度なヒント

小さく構造化されたレスポンスを優先する

エージェントがファイルを選択したり、結果を別のツールに渡したりする場合は、-nと--jsonを組み合わせます。小さな構造化レスポンスは解析しやすく、モデルのコンテキストを超過しにくくなります。

python scripts/everything_search.py "ext:json package" -n 10 --json

範囲を限定してから広げる

プロジェクトの場所が分かっている場合は、まず現在のワークスペースを検索します。有用な一致結果が得られなければ、クエリをすべてのインデックス済みドライブに広げます。この方法によりノイズを抑えながら、インデックス全体を検索できます。

フィルターを組み合わせる

Everythingでは、スペースで区切った語が論理AND条件として扱われます。ファイル名、拡張子、日付、除外条件を1つのクエリに組み合わせられます。

python scripts/everything_search.py "ext:ts dm:last7days !*.test.ts" -n 20 --json

この例では、最近更新されたTypeScriptファイルを検索し、.test.tsで終わるファイルを除外します。

適切な通信方式を選ぶ

  • 一般的な操作や便利なフォールバック動作には、自動モードを使用します。
  • Docker、WSL2、サンドボックス、リモートエージェント、Windowsデスクトップセッションから分離された環境では、HTTPモードを使用します。
  • ネイティブWindowsデスクトップセッションで対話的に実行し、CLI固有のスイッチが必要な場合は、直接es.exeコマンドを使用します。

リポジトリの構成要素を理解する

  • SKILL.mdには、標準的なエージェントSkill仕様が含まれています。
  • bin/es.exeには、公式のVoidtools CLIツールが含まれています。
  • scripts/install.ps1は、インストールとPATHの設定を実行します。
  • scripts/enable_http.ps1は、HTTPサーバーを設定します。
  • scripts/everything_search.ps1は、2つのモードに対応したPowerShellラッパーを提供します。
  • scripts/everything_search.pyは、依存関係なしで2つのモードに対応するPythonラッパーを提供します。

まとめ

Everything Search Skillを使うと、AIコーディングエージェントはWin32デスクトップIPCだけに依存せず、Everythingインデックスの高速性を利用できます。ホストHTTPサーバーを有効化し、Skillをインストールし、分離された環境向けにエンドポイントを設定して、厳格な結果件数の上限と範囲を限定したクエリを使用してください。2モード対応のヘルパーにより、コンテナ化されたエージェントとネイティブWindowsワークフローの両方で、一貫した検索インターフェースを利用できます。

このプロジェクトはMITライセンスの下で提供されています。Voidtools Everythingおよびes.exeの著作権はVoidtoolsに帰属します。