Tìm kiếm hàng triệu tệp cục bộ từ tác nhân AI với Everything Search Skill

Everything Search Skill làm gì

Everything Search Skill cung cấp cho các tác nhân lập trình AI quyền truy cập siêu nhanh vào các tệp được Voidtools Everything lập chỉ mục. Công cụ có thể tìm kiếm hàng triệu tệp trên các ổ đĩa NTFS với thời gian phản hồi được báo cáo dưới 15 mili giây, rất hữu ích để định vị tệp mã nguồn, tệp cấu hình, nhật ký, tài sản và thư mục dự án.

Dự án giải quyết một hạn chế phổ biến của es.exe. Ứng dụng khách dòng lệnh gốc giao tiếp với ứng dụng Everything trên máy tính thông qua cơ chế nhắn tin Windows và IPC Win32. Vì vậy, các tác nhân chạy trong Docker, WSL2, Windows Sandbox, trình chạy biệt lập hoặc phiên nền có thể nhận được lỗi sau:

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

Lỗi này có thể xảy ra vì Windows User Interface Privilege Isolation và Session 0 Isolation ngăn các tiến trình trong những phiên máy tính khác nhau trao đổi các thông báo cửa sổ cần thiết.

Kiến trúc hai chế độ hoạt động như thế nào

Skill hỗ trợ hai cách giao tiếp với công cụ Everything:

1. Chế độ HTTP REST: Chế độ được ưu tiên cho sandbox, container, WSL2, môi trường từ xa, Linux và macOS. Các yêu cầu được gửi đến máy chủ HTTP chạy trên máy chủ Windows, tránh các hạn chế về phiên Win32.
2. Chế độ CLI IPC: Phương án dự phòng cho tác nhân chạy trong phiên máy tính Windows gốc. Ở chế độ này, trình trợ giúp gọi es.exe thông qua cơ chế IPC tiêu chuẩn của Everything.

Ở chế độ tự động, trình trợ giúp Python thử HTTP trước và chuyển sang CLI khi phù hợp. Phần triển khai Python chỉ sử dụng các mô-đun thư viện chuẩn, nên không có phần phụ thuộc Python bên thứ ba.

Tính năng chính

• Tìm kiếm nhanh qua chỉ mục: Tìm tệp trên các ổ đĩa NTFS đã lập chỉ mục mà không cần quét đệ quy các thư mục.
• Hỗ trợ container: Kết nối Docker, WSL2, Windows Sandbox và các trình chạy tác nhân biệt lập với điểm cuối HTTP trên máy chủ.
• Tìm kiếm theo phạm vi: Tìm kiếm trên tất cả ổ đĩa đã lập chỉ mục hoặc giới hạn kết quả trong một workspace.
• Giới hạn an toàn cho ngữ cảnh: Sử dụng các tùy chọn như -n 20 để ngăn tập kết quả lớn chiếm hết cửa sổ ngữ cảnh của tác nhân AI.
• Kết quả có cấu trúc: Yêu cầu đầu ra JSON từ các trình trợ giúp Python và PowerShell.
• Tích hợp tác nhân: Cài đặt skill cho Cursor, Codex, PI-Desktop hoặc các môi trường tác nhân tùy chỉnh.

Điều kiện tiên quyết

Bạn cần một máy chủ Windows đang chạy Voidtools Everything và có sẵn các chỉ mục của công cụ. Khi sử dụng trên máy tính Windows gốc, skill có thể giao tiếp thông qua es.exe. Để sử dụng với Docker, WSL2, sandbox hoặc môi trường từ xa, hãy bật máy chủ HTTP của Everything trên máy chủ.

Bước 1: Bật máy chủ HTTP của Everything

Trên máy chủ Windows, mở Everything và thực hiện các bước sau:

1. Mở Tools, sau đó chọn Options.
2. Chọn HTTP Server trong thanh điều hướng bên trái.
3. Bật Enable HTTP Server.
4. Đặt cổng thành 8080.
5. Xác nhận cài đặt.

Bạn cũng có thể chạy tập lệnh thiết lập PowerShell của repository:

.\scripts\enable_http.ps1 -Port 8080

Điểm cuối HTTP là cầu nối giữa tác nhân biệt lập và dịch vụ Everything đang chạy trên máy chủ.

Bước 2: Sao chép và cài đặt Skill

Mở PowerShell, sao chép repository, truy cập thư mục của repository và chạy trình cài đặt:

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

Trình cài đặt đặt es.exe vào ~/.local/bin/, cấu hình PATH của người dùng và triển khai skill vào các vị trí tác nhân sau:

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

Bước 3: Chạy tìm kiếm cơ bản

Trình trợ giúp Python hai chế độ nằm tại scripts/everything_search.py. Ở chế độ tự động, trình trợ giúp trước tiên thử điểm cuối HTTP, sau đó sử dụng phương án CLI gốc khi khả dụng:

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

Đối số -n 20 giới hạn phản hồi ở 20 kết quả khớp. Giới hạn kết quả đặc biệt quan trọng khi tác nhân AI sẽ xử lý đầu ra.

Trả về JSON có cấu trúc

Thêm --json khi kết quả sẽ được phân tích bằng chương trình:

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

Truy vấn này tìm các mục đã lập chỉ mục khớp với cả ext:tsx và component, sau đó trả về tối đa 10 kết quả ở dạng JSON.

Giới hạn tìm kiếm trong một dự án

Sử dụng -p với trình trợ giúp Python để giới hạn tìm kiếm trong một workspace:

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

Giới hạn phạm vi tìm kiếm giúp giảm các kết quả không liên quan từ những dự án khác và làm cho đầu ra hữu ích hơn đối với tác nhân đang làm việc trong một repository cụ thể.

Buộc sử dụng chế độ HTTP

Nếu tác nhân bắt buộc phải sử dụng máy chủ HTTP của máy chủ, hãy chọn rõ chế độ này:

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

Toán tử exact: ngăn mở rộng ký tự đại diện và tìm kiếm đúng tên tệp.

Sử dụng Skill từ Docker

Truyền điểm cuối của máy chủ vào container thông qua EVERYTHING_HTTP_URL. Ví dụ của repository cũng ánh xạ tên máy chủ đặc biệt tới cổng gateway của máy chủ:

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

Bên trong container, chạy trình trợ giúp Python:

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

Yêu cầu được truyền qua TCP đến máy chủ HTTP của Everything thay vì cố gắng sử dụng IPC trên máy tính để bàn từ bên trong container.

Sử dụng Skill từ WSL2

Trong WSL2, lấy địa chỉ máy chủ Windows từ tuyến mặc định và gán endpoint kết quả cho 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

Truy vấn sử dụng phép AND logic: mỗi kết quả khớp phải thỏa mãn cả bộ lọc phần mở rộng Python và thuật ngữ model.

Sử dụng es.exe trong phiên Windows gốc

Khi agent chạy trong cùng ngữ cảnh máy tính để bàn gốc với Everything, bạn có thể gọi trực tiếp es.exe. Luôn chỉ định giới hạn kết quả hợp lý:

es.exe -n 20 "package.json"

Giới hạn kết quả trong một workspace

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

Chỉ trả về tệp hoặc thư mục

Sử dụng /a-d chỉ cho tệp và /ad chỉ cho thư mục:

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

Sắp xếp nhật ký mới nhất trước

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

Thao tác này tìm kiếm các tệp nhật ký của hôm nay và sắp xếp chúng theo ngày sửa đổi, mới nhất trước.

Xây dựng truy vấn Everything chính xác hơn

Cú pháp tìm kiếm của Everything có thể thu hẹp phạm vi tìm kiếm trước khi kết quả được gửi đến agent.

• Nhiều phần mở rộng: Sử dụng ext:md;txt;json để khớp với nhiều phần mở rộng.
• Kích thước tệp tối thiểu: Sử dụng size:>100MB.
• Phạm vi kích thước: Sử dụng size:1MB..50MB. Các đơn vị được hỗ trợ gồm B, KB, MB và GB.
• Ngày sửa đổi: Sử dụng dm:today, dm:last7days hoặc một giá trị như dm:2025.
• Đường dẫn thư mục cha: Sử dụng path:"C:\Workspace".
• Tên tệp chính xác: Sử dụng exact:Dockerfile.
• AND logic: Phân tách các thuật ngữ bằng khoảng trắng, như trong model user ext:py.
• OR logic: Đặt dấu gạch đứng giữa các lựa chọn, như trong *.jpg | *.png.
• NOT logic: Thêm tiền tố loại trừ bằng !, như trong *.ts !*.test.ts.
• Biểu thức chính quy: Sử dụng tùy chọn -r của CLI gốc, ví dụ es.exe -r "src\\api\\.*\.go$".

Mẹo nâng cao cho quy trình làm việc với agent AI

Ưu tiên phản hồi nhỏ, có cấu trúc

Kết hợp -n với --json khi agent cần chọn tệp hoặc truyền kết quả vào một công cụ khác. Phản hồi có cấu trúc nhỏ sẽ dễ phân tích hơn và ít có khả năng làm tràn ngữ cảnh của mô hình.

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

Giới hạn phạm vi trước khi mở rộng

Bắt đầu với workspace hiện tại whenever đã biết vị trí dự án. Nếu không có kết quả hữu ích, hãy mở rộng truy vấn đến tất cả các ổ đĩa đã lập chỉ mục. Cách tiếp cận này hạn chế nhiễu nhưng vẫn cho phép tìm kiếm trên toàn bộ chỉ mục.

Kết hợp các bộ lọc

Everything xem các thuật ngữ được phân tách bằng khoảng trắng là các điều kiện AND logic. Bạn có thể kết hợp thuật ngữ tên tệp, phần mở rộng, ngày tháng và điều kiện loại trừ trong một truy vấn:

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

Ví dụ này tìm các tệp TypeScript được sửa đổi gần đây, đồng thời loại trừ các tệp kết thúc bằng .test.ts.

Chọn phương thức truyền tải phù hợp

• Sử dụng chế độ tự động cho các hoạt động thông thường và cơ chế dự phòng thuận tiện.
• Sử dụng chế độ HTTP cho Docker, WSL2, sandbox, agent từ xa và các môi trường tách biệt khỏi phiên máy tính để bàn Windows.
• Sử dụng trực tiếp các lệnh es.exe khi chạy tương tác trong phiên máy tính để bàn Windows gốc và cần các tùy chọn riêng của CLI.

Tìm hiểu các thành phần của repository

• SKILL.md chứa đặc tả skill tiêu chuẩn dành cho agent.
• bin/es.exe chứa công cụ CLI chính thức của Voidtools.
• scripts/install.ps1 thực hiện cài đặt và thiết lập PATH.
• scripts/enable_http.ps1 cấu hình máy chủ HTTP.
• scripts/everything_search.ps1 cung cấp trình bao bọc PowerShell hai chế độ.
• scripts/everything_search.py cung cấp trình bao bọc Python hai chế độ, không phụ thuộc thư viện.

Kết luận

Everything Search Skill cho phép các agent lập trình AI tận dụng tốc độ của chỉ mục Everything mà không phụ thuộc hoàn toàn vào IPC máy tính để bàn Win32. Hãy bật máy chủ HTTP trên máy chủ, cài đặt skill, cấu hình endpoint cho các môi trường bị cô lập và sử dụng các truy vấn có phạm vi cùng giới hạn kết quả nghiêm ngặt. Sau đó, trình trợ giúp hai chế độ hỗ trợ cả agent trong container và quy trình làm việc Windows gốc thông qua một giao diện tìm kiếm nhất quán.

Dự án được cung cấp theo Giấy phép MIT. Voidtools Everything và es.exe vẫn thuộc bản quyền của Voidtools.