简介

XERJ 是一个专为 AI Agent 设计的本地搜索引擎，由 xerj-org 团队开发。它的核心定位是解决 Coding Agent（如 Claude Code、Cursor）在理解陌生代码库时面临的上下文窗口限制问题。传统的做法是让 Agent 使用 grep 定位关键词，然后将包含命中行的整个文件读入上下文，这会导致大量的 Token 浪费——哪怕只需要一个函数，Agent 也可能被迫读取几千行无关代码。

XERJ 通过一条命令自动将任意目录（代码、文档、日志、PDF 等）建立为可查询的索引。Agent 查询时，直接获取确切的代码片段或文档段落，而不是整份文件。它基于 Rust 编写，发布为单一静态二进制文件，无需 JVM 或外部依赖，且完全兼容 Elasticsearch REST API。这意味着现有的 Elasticsearch 客户端、Kibana 以及周边运维工具可以直接连接 XERJ，迁移成本极低。

项目采用 Apache-2.0 协议，GitHub 仓库地址为 xerj-org/xerj，官网及文档位于 xerj.org。实测数据显示，相比 grep 驱动的 Agent，XERJ 能节省约 2.7 倍的输出 Token；相比纯靠模型记忆的方案，节省幅度高达 26 倍。

部署

路线对比

对于开发工程师而言，部署 XERJ 主要有两种路径：一种是拥有服务器和域名的自建私有化部署，另一种是利用免费静态托管服务进行快速体验。由于 XERJ 本身是一个需要持续运行并处理数据索引的服务端程序，所谓的“免费静态托管”通常仅指其官方文档站点的托管，而非 XERJ 引擎本身的托管。因此，实际使用中主要关注本地或服务器端的部署。

方案	适用场景	优点	缺点
本地/服务器部署	日常开发、团队协作、敏感数据内部处理	数据完全本地化，延迟低，功能完整，支持 MCP 集成	需占用本地资源，需自行维护进程
云端容器化部署	团队共享索引、CI/CD 流水线集成	集中管理，多 Agent 可访问	需配置服务器，涉及网络传输安全

注：XERJ 不支持直接部署在 GitHub Pages 等纯静态托管平台，因为它需要后台进程运行搜索引擎。

有服务器、域名环境下的部署

如果你拥有一台 Linux 或 macOS 服务器，或者希望在本地开发机上运行，安装过程非常简洁。XERJ 提供了预编译的二进制文件，支持 x86-64 和 arm64 架构。

安装二进制文件

在 Linux 和 macOS 上，可以通过以下命令一键安装：
```
bash
curl -fsSL https://xerj.org/get | sh
```
在 Windows PowerShell 中，可以使用：
```
powershell
irm https://xerj.org/get.ps1 | iex
```
如果需要启用内置的 AI 模型（如 XERJ Query-1），可以添加 --with-model 参数：
```
bash
curl -fsSL https://xerj.org/get | sh -s -- --with-model
```
启动服务

安装完成后，启动 XERJ 服务。对于本地开发环境，建议使用 --insecure 标志以禁用 TLS 和 API Key 鉴权，简化调试流程：
```
bash
xerj --insecure --data-dir ./data &
```
注意：--insecure 模式意味着任何能连接到该端口的调用方都拥有超级用户权限，仅限单机开发使用。生产环境请参照官方 SECURITY_MODEL.md 配置安全策略。
初始化与索引

启动后，你可以使用 init 命令将 XERJ 接入 Claude Code 或 Cursor 等 Agent 工具：
```
bash
xerj init
```
接着，对目标项目进行自动索引。XERJ 会自动嗅探文件类型，无需手动配置 Schema：
```
bash
xerj autoindex ~/my-project
```

免费静态托管说明

如前所述，XERJ 引擎本身无法部署在静态托管平台上。但开发者可以利用其官方提供的 llms.txt 接口，让 AI Agent 自动完成上述安装和配置步骤。这是一种“零部署”的间接使用方式，适合那些希望让 Agent 自主管理基础设施的场景。

常见故障对照

在使用 XERJ 过程中，可能会遇到以下常见问题：

现象	可能原因	解决方案
`curl: command not found`	系统未安装 curl 或路径问题	确保 curl 已安装，或使用源码编译方式安装
索引速度慢	文件数量巨大或硬件性能不足	XERJ 支持增量索引，后续修改只需重新索引变更部分；检查 CPU 负载
搜索结果为空	索引尚未完成或查询语法错误	等待 `autoindex` 完成；检查 Elasticsearch DSL 语法是否正确
连接被拒绝	防火墙阻止了端口或绑定地址错误	检查 `--insecure` 模式下的绑定地址（默认 127.0.0.1）；确认端口未被占用
Token 节省不明显	模型已预先训练过该开源库	XERJ 对私有、小众或模型知识截止日期后的代码效果最佳；对热门公共库收益较小

配置

如何与 Harness 结合提高检索效率

这里的 "Harness" 可能指代特定的测试框架或自定义的 Agent 工作流环境。XERJ 的核心优势在于其兼容 Elasticsearch API，这使得它可以无缝集成到任何支持 ES 协议的客户端中。

利用 ES 客户端库

如果你的 Harness 环境支持 Python、Java 或 JavaScript 的 Elasticsearch 客户端，你可以直接使用这些库连接 XERJ。例如，在 Python 中：

python
from elasticsearch import Elasticsearch

es = Elasticsearch("http://localhost:9200")
# 执行搜索
res = es.search(index="ax-*", query={"match": {"content": "checkout error"}})
print(res['hits']['hits'])

参考式编码（Reference Coding）

XERJ 推荐的最佳实践是“参考式编码”。在你的 Harness 工作流中，当 Agent 需要实现某个功能时，先让其索引相关的开源仓库，然后查询这些项目中类似问题的解决方案，再基于这些确切片段进行编码。这比让 Agent 凭空生成或逐文件阅读更高效。

你可以通过以下命令让 Agent 自动设置参考编码环境：
```
bash
Install XERJ (docs: https://xerj.org/llms.txt), index this project's sources, and set up reference coding: clone and index the open-source repos closest to what we're building, and search how they solved a problem before writing code.
```
增量索引优化

XERJ 的重新索引是增量式的。如果文件内容未变，它会跳过解析，复用之前的结果。在 CI/CD 或频繁更新的 Harness 环境中，这能显著降低索引开销。

如何做成 Skill 让其他 Agent 使用

XERJ 原生支持通过 MCP（Model Context Protocol）与其他 Agent 集成，使其成为一个可复用的 Skill。

注册 MCP Server

XERJ 启动后，会暴露一组 MCP 工具。你可以在 llms.txt 中找到针对特定客户端（如 Claude Desktop、Cursor）的配置行。通常，你需要在 Agent 的配置文件中添加 XERJ 的 MCP 服务器地址。
使用 Skill 命令

一旦集成，Agent 可以直接调用 XERJ 的 Skill 命令，例如：
- xerj search: 执行搜索，返回排序后的片段。
- xerj def: 跳转到定义，返回文件路径、行号和函数签名。
- xerj gain: 查看当前会话中节省了多少 Token。
自动化安装与配置

为了让其他 Agent 能够自动发现和使用这个 Skill，你可以将 XERJ 的安装和配置步骤封装成一个标准化的 Prompt 或脚本。Agent 接收到任务后，可以自动执行以下步骤：
- 检查 XERJ 是否已安装。
- 启动 XERJ 服务。
- 索引当前项目目录。
- 注册 MCP 连接。
这种“自我配置”的能力使得 XERJ 不仅仅是一个工具，更是一个可以被 Agent 动态调用的智能组件。通过这种方式，其他 Agent 无需手动干预，即可享受高效的代码检索和参考编码能力。