AI 튜토리얼

Everything 검색 스킬로 AI 에이전트에서 수백만 개의 로컬 파일 검색

HTTP 또는 네이티브 Win32 IPC를 통해 AI 코딩 에이전트를 Voidtools Everything 인덱스에 연결하는 방법을 알아보세요. 이 튜토리얼에서는 호스트 설정, 설치, 컨테이너 구성, 범위 지정 검색, JSON 출력, 검색 필터, 페이지 매김, 고급 쿼리 예제를 다룹니다.

2026년 9월 19일약 13분 소요

Everything 검색 스킬로 AI 에이전트에서 수백만 개의 로컬 파일 검색

Everything Search Skill이 하는 일

Everything Search Skill은 Voidtools Everything에서 색인된 파일에 AI 코딩 에이전트가 초고속으로 접근할 수 있게 합니다. 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 사용자 인터페이스 권한 격리와 세션 0 격리로 인해 서로 다른 데스크톱 세션의 프로세스가 필요한 창 메시지를 주고받지 못할 수 있기 때문에 이 오류가 발생할 수 있습니다.

이중 모드 아키텍처의 작동 방식

이 스킬은 Everything 엔진과 통신하는 두 가지 방식을 지원합니다.

HTTP REST 모드: 샌드박스, 컨테이너, WSL2, 원격 환경, Linux 및 macOS에 권장되는 모드입니다. 요청은 Windows 호스트에서 실행 중인 HTTP 서버에 전달되므로 Win32 세션 제한을 피할 수 있습니다.
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을 열고 다음 단계를 완료하세요.

Tools를 연 다음 Options를 선택합니다.
왼쪽 탐색 메뉴에서 HTTP Server를 선택합니다.
Enable HTTP Server를 활성화합니다.
포트를 8080으로 설정합니다.
설정을 확인합니다.

저장소의 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에 모두 일치하는 색인 항목을 찾은 다음 JSON 형식으로 최대 10개의 결과를 반환합니다.

프로젝트로 검색 제한

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 조건으로 처리합니다. 한 쿼리에서 파일 이름 항목, 확장자, 날짜, 제외 조건을 결합할 수 있습니다.

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은 이중 모드 PowerShell 래퍼를 제공합니다.
scripts/everything_search.py는 종속성 없이 작동하는 이중 모드 Python 래퍼를 제공합니다.

결론

Everything Search Skill을 사용하면 AI 코딩 에이전트가 Win32 데스크톱 IPC에만 의존하지 않고 Everything 색인의 빠른 검색 기능을 이용할 수 있습니다. 호스트 HTTP 서버를 활성화하고, Skill을 설치하고, 격리된 환경을 위한 엔드포인트를 구성한 다음, 엄격한 결과 제한과 함께 범위가 지정된 쿼리를 사용하세요. 그러면 이중 모드 도우미가 일관된 검색 인터페이스를 통해 컨테이너화된 에이전트와 네이티브 Windows 워크플로를 모두 지원합니다.