xerj-org/xerj 是 GitHub 上的開源專案，本站記錄時 18,814 星；一天內新增約 725 顆星。我們在一台 RTX A6000 48 GB 工作站 上，從安裝到跑出結果整段錄下終端機；測的是 2026-11-03 的版本（commit dddbbdbc7991）。實測影片公開後會嵌在本文最下方。
背景
AI 代理在處理大型代碼庫時，常因逐行讀取檔案而消耗大量 Token 且延遲高。xerj 提供一個單一的 Rust 執行檔，作為本地優先的搜尋引擎與 MCP 伺服器，讓 AI 代理能透過 BM25 全文搜尋、向量搜尋及混合搜尋，快速從代碼、文件、日誌中提取精確資訊。
它解決了代理「記不住」或「讀太慢」的問題，透過索引本地資料並提供 Elasticsearch 相容的 API，讓代理能像查詢資料庫一樣查詢代碼庫，並回傳帶有引用來源（檔案路徑與行號）的答案，減少幻覺並提升效率。
運作方式與使用方式
xerj 的核心運作方式是將指定目錄索引為可搜尋的資料集，並啟動一個本地 HTTP 服務。我們首先透過官方腳本安裝單一執行檔，接著啟動服務並指定資料存放目錄。服務啟動後，會開啟三個埠：8080（原生 REST）、8081（gRPC）與 9200（Elasticsearch 相容 API）。
使用流程分為兩步：首先使用 xerj autoindex <目錄> 指令自動索引目標資料夾，該指令會分析檔案結構、建立圖譜並寫入索引。完成後，可使用 xerj search '<關鍵字>' 進行查詢，或直接透過 HTTP 請求 Elasticsearch 相容端點。查詢結果會包含匹配的分數、檔案路徑、行號以及原始程式碼片段，方便代理直接引用。
與未使用時的差異
| 情境 | 不用它 | 用它 |
|---|---|---|
| 代理查詢代碼庫特定函式 | 需讀取整個檔案或依賴 grep，Token 消耗高且易遺漏上下文 | 直接搜尋符號或關鍵字，回傳精確行號與程式碼片段，Token 消耗低 |
| 多格式文件檢索 | 需額外工具處理 PDF、JSONL、CSV 等不同格式 | 自動索引代碼、文件、日誌、JSONL/CSV 與 PDF，統一介面查詢 |
| 搜尋結果引用 | 代理需自行標註來源，易產生幻覺或錯誤引用 | 自動回傳 ax_path:line 格式的精確引用，便於驗證 |
| 部署與維護 | 需安裝 Elasticsearch 或向量資料庫，依賴 JVM 或複雜環境 | 單一 Rust 靜態執行檔，無需 JVM，啟動快速且資源佔用低 |
安裝與執行過程
| 步驟 | 指令 | 結果 | |||||
|---|---|---|---|---|---|---|---|
| 檢查環境資訊 | `uname -a; python3 --version; uv --version; node --version; nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv,noheader 2>/dev/null \ | \ | echo '(no GPU)'; lscpu \ | grep 'Model name'; free -g \ | head -2` | 結束碼 0，耗時 0.1 秒。確認環境為 Linux，Python 3.12.3，Node v18.19.1，GPU 為 NVIDIA RTX A6000。 | |
| 取得專案原始碼 | `cd "$LAB" && { [ -d src/.git ] \ | \ | git clone -q --no-checkout --depth 1 https://github.com/xerj-org/xerj src; } && cd src && git fetch -q --depth 1 origin dddbbdbc7991194abd2be603bdfbe2434a2ef34d && git checkout -q dddbbdbc7991194abd2be603bdfbe2434a2ef34d && git log -1 --format='%h %cd %s' --date=short && du -sh . && ls` | 結束碼 0，耗時 1.8 秒。成功 checkout commit dddbbdb，專案大小 297M。 | |||
| 安裝 xerj 執行檔 | `curl -fsSL https://xerj.org/get \ | sh` | 結束碼 0，耗時 31.6 秒。成功下載並安裝 xerj v1.0.0-rc.100 至 ~/.local/bin/xerj，SHA256 驗證通過。 | ||||
| 建立測試專案 | export PATH="$HOME/.local/bin:$PATH" && mkdir -p demo_project && printf 'def hello():\n return "world"\n' > demo_project/main.py && printf '# Demo\n\nhello world example project\n' > demo_project/README.md | 結束碼 0，耗時 0.0 秒。成功建立包含 main.py 與 README.md 的測試目錄。 | |||||
| 啟動 xerj 服務 | `before=$(ss -Hltn 2>/dev/null \ | awk '{print $4}' \ | sort); setsid nohup bash -c 'xerj --insecure --data-dir ./xerj-data' > "$RUN/bg-$(date +%s).log" 2>&1 < /dev/null & echo "背景啟動：xerj --insecure --data-dir ./xerj-data"; for i in $(seq 1 30); do sleep 1; after=$(ss -Hltn 2>/dev/null \ | awk '{print $4}' \ | sort); [ "$after" != "$before" ] && break; done; comm -13 <(echo "$before") <(echo "$after") \ | sed 's/^/ 新開的埠 /'; tail -n 5 "$RUN"/bg-*.log 2>/dev/null` | 結束碼 0，耗時 1.1 秒。服務成功啟動，開啟埠 127.0.0.1:8080, 8081, 9200。日誌顯示 ES-compat 與 gRPC 服務已就緒。 |
| 驗證服務就緒 | `for i in $(seq 1 30); do curl -sf http://localhost:9200/ >/dev/null && break; sleep 1; done; curl -s http://localhost:9200/ \ | head -c 400; echo` | 結束碼 0，耗時 0.0 秒。回傳 JSON 顯示 cluster_name 為 xerj，模擬版本 8.13.0，確認 Elasticsearch 相容性。 | ||||
| 索引測試資料 | xerj autoindex ./demo_project | 結束碼 0，耗時 1.7 秒。成功索引 2 個檔案，產生 3 筆記錄，建立 2 條圖譜邊。輸出顯示 'done in 1.3s' 與 'indexed: 3 documents live'。 | |||||
| 執行全文搜尋 | xerj search 'hello world' | 結束碼 0，耗時 0.1 秒。成功回傳 2 筆結果：README.md 第 3 行（分數 1.74）與 main.py 第 1 行（分數 0.38），並附帶原始碼片段。 | |||||
| 關閉服務 | `pkill -f 'xerj --insecure' \ | \ | true` | 結束碼 0，耗時 0.1 秒。服務正常終止。 |
結果驗證
實測結果符合 README 中關於「單一 Rust 執行檔」與「本地優先」的描述。安裝過程僅需一條 curl 指令，無需編譯或安裝依賴，執行檔大小與啟動速度均表現優異。服務啟動後，Elasticsearch 相容端點（Port 9200）能正確回應標準 ES 查詢格式，這對於已有 ES 生態系的工具鏈非常友善。
在索引效能方面，針對僅有 2 個檔案（共 68 Bytes）的測試專案，autoindex 指令在 1.7 秒內完成索引並建立圖譜。雖然資料量極小，但輸出詳細展示了其內部流程，包括圖譜偵測（graph detectors）、批次索引（phase B）與最終刷新（finalize-refresh）。搜尋結果不僅回傳匹配內容，還精確標註了檔案路徑與行號（如 README.md:3），這對於 AI 代理進行「引用編碼」（reference coding）至關重要，能有效降低幻覺風險。
遇到的問題
這次沒有遇到需要另外處理的問題。
結論
xerj 適合需要在本機快速部署高效能搜尋引擎的開發者，特別是希望讓 AI 代理能精確檢索本地代碼庫與文件的場景。其 Elasticsearch 相容性降低了整合門檻，而自動索引與圖譜功能則提供了超越傳統 grep 的語意理解能力。然而，對於極小專案或僅需簡單關鍵字搜尋的使用者，其完整的索引與圖譜建立流程可能顯得過於厚重；此外，作為 RC 版本（v1.0.0-rc.100），長期穩定性與 API 變動風險仍需觀察。
- 它是什麼、解決什麼問題：XERJ 是什麼：專為 AI 代理設計的本地化 Rust 搜尋引擎
- 照著做的安裝教學：xerj 安裝與使用教學：在 Linux 工作站三步裝好
