xerj：用自动索引让AI少读文件，直接搜索代码与文档
给编码代理搜索本地代码和文档的AI索引器，比grep少耗Token并兼容Elasticsearch。
GitHub xerj-org/xerj 更新 2026-10-16 分支 main 星标 5.7K 分叉 308
Rust AI搜索 Elasticsearch API 本地开发环境

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你希望Claude Code或Cursor通过MCP检索项目和参考仓库
    README命令 xerj init 注明会接入Claude Code/Cursor，并配置MCP和skill
  • 你的语料包含代码、PDF、日志、SQLite或CSV，且不想编写schema
    README“Feed it any folder”章节列出这些格式，并称无需schema或pipeline
  • 你已有Elasticsearch客户端、Kibana或官方客户端库
    README“Elasticsearch compatibility”章节说明这些工具可直接连接localhost:9200
  • 你关注参考编码的Token开销，并接受README中的2.7倍研究结果
    README开头案例研究称相同16/16解题率下输出Token减少2.7倍

不适合，如果你

  • 你需要TLS、API密钥认证或多用户生产边界，而只能使用--insecure
    README明确说明--insecure关闭TLS和API-key auth，所有可达调用者都是超级用户
  • 你的导出流程依赖Elasticsearch scroll遍历任意大小的精确总结果
    README说明scroll是有界快照，超过快照窗口会拒绝并返回400，应改用search_after
  • 你的工作负载核心是高写入洪峰期间的低读延迟p99
    README基准章节称高写入时读p99是全部四项败项的共同差距
  • 你不能接受Jev rerank把搜索结果文本发往TypeSafe服务器
    README“Score results with Jev”章节明确说明启用rerank会发送结果文本

前置条件

  • 安装器提供Linux、macOS和Windows的x86-64及arm64预编译静态二进制
  • The installer provides prebuilt static binaries for x86-64 and arm64 on Linux, macOS, and Windows
  • 启动服务后需等待http://localhost:9200响应，再运行xerj autoindex
  • After starting the service, wait for http://localhost:9200 to respond before running xerj autoindex
  • 无运行时网络的主机需使用air-gapped deployment recipe；默认词法embedder离线，neural mode需预先放置三个模型文件
  • Hosts without runtime internet access need the air-gapped deployment recipe; the default lexical embedder is offline, while neural mode needs three model files staged locally
  • --insecure仅面向单用户开发机；新节点默认绑定127.0.0.1
  • --insecure is intended for a single-user development machine; a fresh node binds to 127.0.0.1 by default

第一步命令（README 原文）

curl -fsSL https://xerj.org/get | sh

要注意

  • 不要把--insecure暴露给非本机网络；它同时关闭TLS和API-key auth
    README安全说明与docs/SECURITY_MODEL.md
  • 大结果集使用search_after，不要依赖scroll超过快照窗口
    README“Elasticsearch compatibility”章节
  • 启用rerank前确认TypeSafe数据外发，并阅读docs/RERANK.md
    README“Score results with Jev”章节
  • Jev分数用于排序而非精确百分比，README称其校准不足
    README“Score results with Jev”章节

替代方案

  • Elasticsearch：需要Elasticsearch内部实现或不接受XERJ的scroll快照语义时更合适
    README“Elasticsearch compatibility”与“Benchmarks”章节
  • grep/sed：只需读取少量文本且不需要XERJ的索引、RAG或文件行号检索时更直接
    README开头与“Why it exists”章节

材料未说明

  • README未给出autoindex对单文件大小、总数据量或持续增量索引的资源上限
  • The README does not specify resource limits for individual files, total corpus size, or continuous incremental indexing
  • README未列出1369个兼容测试中剩余3个失败用例的具体API差异
  • The README does not enumerate the exact API differences in the remaining 3 failures out of 1369 compatibility cases
  • README未说明593个数据集示例所需的CPU、内存和磁盘规格
  • The README does not state the CPU, memory, or disk requirements for the 593-dataset example
  • README未提供Windows安装后的服务管理、后台运行和安全配置细节
  • The README does not provide post-install service management, background execution, or security-configuration details for Windows
  • README未说明neural mode所需三个模型文件的名称、大小和获取方式
  • The README does not specify the names, sizes, or acquisition method of the three model files required by neural mode
  • README未说明发布版本之间的升级、索引迁移和回滚流程
  • The README does not describe upgrade, index migration, or rollback procedures between releases

💡 深度解析

6
不适合 我在本地 RAG 中检索敏感代码和日志，想用 Jev 重排结果以提高 nDCG，但不能默认把候选文本发送到 TypeSafe 服务器；我应该启用这个集成吗？
适合读者： 处理敏感代码和日志、同时希望用 Jev 提升检索排序质量的本地 RAG 开发者

不适合在当前数据约束下启用 Jev rerank，因为它会把候选结果文本发送到 TypeSafe 的服务器。

  • README 明确说明，给 _search 添加 "rerank": {} 后，XERJ 会把 top results 发送给 Jev。
  • 公开 FiQA 测试中 nDCG@10 从 0.24 提升到 0.36，648 次搜索总成本约 0.64 美元；这说明它可能有排序收益，但不是离线收益。
  • 功能默认关闭，只有配置 key 才会启用；[rerank] enabled = false 可以明确禁止外发。
  • README 同时提供本地 /v1/systemone 和 /_decide，但它依赖已有标注样本，不能直接等价替代通用 Jev 重排。

因此，敏感数据应保持 Jev 关闭；只有数据分类允许外发且成本与延迟可接受时，才有理由考虑开启。

  • README 章节“Score results with Jev”：`Add "rerank": {} to a _search and XERJ sends the top results to Jev`
  • README：FiQA 的 nDCG@10 从 `0.24 to 0.36`，648 次搜索约 `$0.64`
  • README：`[rerank] enabled = false forbids it completely`
  • README：本地 `POST /v1/systemone` 和 `POST /_decide` 需要 labelled examples
材料未说明：README 未说明 Jev 请求的保留期限、区域位置和 TypeSafe 的数据处理条款。；README 未给出 Jev 请求的额外延迟或失败时的降级行为。；README 未说明本地 systemone 在代码和日志语料上的效果。
适合 我正在使用 Claude Code 或 Cursor 做参考编码，希望代理先索引相近的开源仓库，再检索实现方式，而不是逐文件执行 grep 和 sed；XERJ 是否适合接入现有工作流？
适合读者： 使用 Claude Code 或 Cursor、需要让编码代理检索参考开源仓库并减少上下文消耗的软件工程师

适合，因为 README 将参考编码和编码代理接入列为主要用例，并提供了一条命令配置 MCP 与 skill。

  • xerj init 会把 XERJ 接入 Claude Code/Cursor；autoindex 可索引代码、文档、日志和 PDF。
  • xerj search 返回排序后的片段、文件和行号，xerj def 还能按符号定位定义，减少代理打开完整文件的需要。
  • README 的受控案例声称，在相同 16/16 解决率下，代理输出 token 降低 2.7 倍；这是特定案例结果，不是普遍保证。

如果代理需要写入、删除或重建索引，README 没有说明 MCP 工具的细粒度权限配置；安全边界仍需单独确认。

  • README: “Reference coding is its main use case”
  • README 命令：`xerj init # wire XERJ into Claude Code/Cursor (MCP + skill), one command`
  • README 命令：`xerj search`、`xerj def`
  • README: “cut a coding agent's output tokens by 2.7x at the same 16/16 solve rate”
xerj init                                        # wire XERJ into Claude Code/Cursor (MCP + skill), one command
材料未说明：README 未说明 Claude Code 与 Cursor 的具体 MCP 工具权限是否可以分别限制为只读。；README 未说明持续变化的参考仓库如何自动增量更新索引。
视情况 我需要在无运行时互联网访问的 air-gapped Linux arm64 机器上索引内部代码和安全审计资料，并且不能把内容发送到云端；XERJ 的离线能力是否足够？
适合读者： 在无运行时互联网访问的 air-gapped Linux 或 arm64 环境中处理内部代码和安全审计资料的工程师

视情况：本地部署和默认词法嵌入器符合离线约束，但若你要求神经语义检索，必须提前准备模型文件。

  • README 提供 air-gapped deployment recipe，并说明预构建二进制覆盖 Linux、macOS、Windows 的 x86-64 与 arm64。
  • 默认 lexical embedder 可离线运行，因此基础索引、全文检索和部分语义能力不必调用外部服务。
  • neural mode 在首次语义操作前需要本地准备三个模型文件；README 没有说明这些文件的下载来源、校验方式或体积。
  • Jev rerank 会把结果文本发送到 TypeSafe 服务器；在内部代码和审计资料场景，这与数据外发约束冲突，除非保持关闭。

所以基础离线搜索可行，神经模式和 Jev 的离线部署细节仍是阻塞项。

  • README 章节“Install by hand”：`For a host with no runtime internet access, follow the air-gapped deployment recipe`
  • README：`Prebuilt for Linux, macOS and Windows on x86-64 and arm64`
  • README：`The default lexical embedder is offline; neural mode needs the three model files staged locally`
  • README 章节“Score results with Jev”：`This sends the text of those results to TypeSafe's servers`
curl -fsSL https://xerj.org/get | sh
材料未说明：README 未提供三个神经模型文件的具体名称、大小、校验和及离线获取流程。；README 未说明 air-gapped 部署是否覆盖所有代码解析器和 PDF 解析依赖。；README 未说明离线环境中的模型更新和漏洞修复流程。
适合 我正在审计约 1,492 个 PHP 文件，希望代理用更少的上下文定位安全相关代码，并且结果必须能回到文件和行号；XERJ 是否比逐文件读取更合适？
适合读者： 需要审计约 1,492 个 PHP 文件并要求代理返回文件与行号的安全工程师

适合用于缩小审计检索范围，但不适合单独承担漏洞确认或完整程序语义分析。

  • README 的 WordPress 核心安全审计案例覆盖 1,492 个 PHP 文件，代理使用约 26,000 tokens；文档称这约等于加载整棵代码树的 0.5%。
  • xerj search 返回 ranked passages、file:line，xerj def 返回定义的 file:line 与 signature，符合可追溯定位要求。
  • XERJ 的代码索引使用符号和行号，而不是只保留扁平文本，因此适合先定位定义、引用和相关片段。
  • 但项目洞察明确指出，跨文件调用、宏生成代码、动态加载、构建条件和运行时配置可能无法仅靠索引准确解释。

它适合作为审计的检索层；最终结论仍不能只依据命中片段。

  • README 章节“Why it exists”：WordPress core 的 AI security audit 覆盖 `1,492 PHP files` 和 `roughly 26,000 tokens`
  • README 命令：`xerj search` 返回 `ranked passages, file:line`
  • README 命令：`xerj def` 返回 `file:line + signature`
  • 项目洞察 common_pitfalls：代码索引不能完整解释跨文件调用、宏生成代码、动态加载等
xerj autoindex ~/my-project
材料未说明：README 未说明 PHP 版本、框架特性和动态代码模式对符号提取覆盖率的影响。；README 未给出安全审计的召回率、误报率或漏洞类型分项结果。；README 未说明如何把检索结果与静态分析器、测试或漏洞数据库联动。
适合 我需要在 Linux、macOS 或 Windows 的 x86-64/arm64 主机上从源码构建 XERJ，并希望部署时不引入 JVM 或其他运行时；这个项目的构建路径是否明确？
适合读者： 希望在 Linux、macOS 或 Windows 的 x86-64/arm64 主机上从 Rust 源码构建本地搜索服务的 Rust 工程师

适合：README 给出了稳定版 Rust 工具链、源码构建命令和无 JVM 的静态二进制定位。

  • 项目主语言是 Rust，源码构建要求 stable Rust toolchain，并明确指定 cargo build --release -p xerj-server。
  • README 说明安装产物是 one static binary、no JVM、no dependencies，预构建目标覆盖 Linux、macOS、Windows 的 x86-64 与 arm64。
  • 构建后可直接用 ./target/release/xerj --insecure --data-dir ./data 启动服务，之后再通过 http://localhost:9200 检查节点响应。
  • Elasticsearch 兼容测试也有可执行的 Rust 命令，便于在构建后验证 API 行为。

不过，README 没有说明各平台的编译工具链、交叉编译配置、安装包签名或构建可复现性，因此复杂发布流水线仍需补充验证。

  • 项目核心数据：`main_language: Rust`
  • README 章节“Build from source”：`You need a stable Rust toolchain`
  • README 章节“Build from source”：`cargo build --release -p xerj-server`
  • README 章节“Install by hand”：`One static binary, no JVM, no dependencies`，以及 Linux/macOS/Windows x86-64 和 arm64
  • README 章节“Build from source”：`cargo run --release -p es-yaml-runner -- --dir tests/es-compat-yaml/yaml`
git clone https://github.com/xerj-org/xerj
材料未说明：README 未说明 Windows 从源码构建所需的具体 linker、SDK 和 Rust target。；README 未说明 Linux/macOS/Windows 二进制是否都有签名或供应链校验信息。；README 未提供完整的交叉编译和可复现构建配置。
视情况 我已经依赖 Elasticsearch 官方客户端、Kibana、bulk、aggregations 和 kNN 查询，想把本地代码库接入一个无需 JVM 的 Rust 服务；XERJ 能否作为兼容替代？
适合读者： 已有 Elasticsearch 官方客户端、Kibana 和聚合查询的开发者，想把本地代码与文档接入而不重写搜索层

视情况：常用 Elasticsearch REST 工作流大体可迁移，但不能把它当作 Elasticsearch 内部实现的完全替代。

  • README 列出 indices、documents、bulk、search、aggregations、mappings、kNN、scroll、reindex 和 _cat 接口，并说明 Kibana 与官方客户端可直接连接。
  • 兼容测试当前通过 1366/1369 个案例，仍有 3 个差异，说明边界行为需要逐项核对。
  • scroll 是有界的预先快照；若精确总量超过窗口会返回 400，而不是静默截断，README 要求大结果集使用 search_after。
  • 其优势是单一静态二进制、无需 JVM；但 README 没有承诺 Elasticsearch 的内部执行计划、插件或全部边缘 API 行为。

因此，依赖标准 REST API 的本地搜索较合适；依赖完整 Elasticsearch 语义的导出或生产系统则不能直接替换。

  • README 章节“Install by hand”：`One static binary, no JVM, no dependencies`
  • README 章节“Elasticsearch compatibility”：列出 bulk、aggregations、mappings、kNN、scroll、reindex 和 `_cat`
  • README: “The conformance suite ... currently passes 1366 of 1369 cases”
  • README: “scroll is a bounded up-front snapshot ... Use `search_after` for result sets of any size”
cargo run --release -p es-yaml-runner -- --dir tests/es-compat-yaml/yaml
材料未说明：README 未列出 3 个未通过兼容案例的具体 API 和影响范围。；README 未说明 Kibana 的具体版本覆盖范围。；README 未给出在现有 Elasticsearch 数据上进行迁移、重建索引和回滚的完整流程。

✨ 核心亮点

  • autoindex 一命令索引代码、PDF、日志与SQLite
  • 参考编码研究显示输出Token减少2.7倍
  • 兼容Elasticsearch客户端、Kibana与官方库
  • 最新兼容测试通过1366/1369个用例
  • --insecure关闭TLS和API密钥认证

🔧 工程化

  • xerj autoindex 自动识别数据集并建立类型化索引
  • xerj search 返回排序段落、文件名与行号
  • tree-sitter为代码保留符号和行号信息
  • Elasticsearch REST API支持聚合、kNN和scroll

⚠️ 风险

  • --insecure下可达端口的调用者都是超级用户
  • 非本机明文绑定必须显式允许，否则节点拒绝启动
  • scroll是有界快照，超出窗口会返回400
  • 高写入并发下读请求p99是四项基准败项
  • Jev rerank会把结果文本发送到TypeSafe服务器

👥 适合谁？

  • 需要让Claude Code或Cursor检索代码的开发者
  • 维护代码、文档、日志和PDF本地语料的团队
  • 已有Elasticsearch客户端但想运行单静态二进制的用户
  • 需要离线默认词法搜索的隔离环境用户