xerj 命令执行与流程引擎

项目概述

XERJ 是一个社区维护的本地 AI 搜索引擎，通过自动索引任意文件夹，让编码智能体不再逐文件读取源码，而是按需精准拉取所需代码片段。其核心场景是参考式编程：让智能体克隆并索引与当前任务最相关的开源项目，检索它们的既有实现后再编写自己的代码，从而显著减少 token 消耗。

性能对比：参考式编程

在与 claude -p 的端到端对照实验中（8 个任务、4 种语言、每组 16 次运行）：

方案	输出 token	成本	通过率
仅凭记忆	260,916	$11.18	11/16
grep 驱动	26,477	$3.27	16/16
XERJ	9,9982	$1.58	16/16

相比 grep 减少 2.7 倍输出 token，相比纯记忆减少 26 倍，单任务最高达 278 倍。实际开发场景中用户普遍报告约 5 倍降幅。其价值边界在于模型对代码的熟悉程度：对私有、内部、小众或训练截止后的代码收益显著，对热门公共库则基本无差异。

快速安装与启动

一行安装脚本：

curl -fsSL https://xerj.org/get | sh
xerj --insecure --data-dir ./data &      # 启动节点，绑定 127.0.0.1
xerj init                                 # 自动接入 Claude Code/Cursor（MCP + skill）
xerj autoindex ~/my-project               # 索引任意目录
xerj search "how do we rotate the WAL segment"   # 返回带文件:行号的排序段落
xerj def "euler_to_rotationmatrix"       # 跳转定义
xerj gain                                 # 查看实际收益统计

--insecure 表示关闭 TLS 与 API Key 认证，仅适用于单用户开发机。新节点默认绑定 127.0.0.1，绑定其他接口需显式授权。Windows 与离线安装参见官方文档。

文件夹自动索引

autoindex 无需编写 schema 或配置管道，会自动嗅探每个文件并按数据集建立独立索引。源码经 tree-sitter 解析，保留符号与行号，而非纯文本。典型输出：

phase A: 593 datasets inferred, 1955 junk/skipped files
phase B: indexing 25329 files with 8 workers
done in 158.1s, 593 datasets, 83103 records live, 790 junk records

支持格式包括 CSV、JSON、JSONL、XML、YAML、SQLite、PDF、DOCX、PPTX、XLSX、EPUB、Jupyter Notebook、roff man 页、HTML、邮件（.eml/mbox，含 Google Takeout）。Unity 工程享有原生支持：文本序列化的场景、预制体、资源按 GameObject/Component 切分，.meta 文件映射为 GUID 表。

搜索接口

XERJ 兼容 Elasticsearch REST API，可直接使用 Kibana、ES 客户端或 _cat/indices：

curl "localhost:9200/ax-*/_search?q=checkout+error"
curl localhost:9200/ax-orders/_search -H 'content-type: application/json' -d '{
  "query": { "range": { "total": { "gte": 100 } } },
  "aggs":  { "by_status": { "terms": { "field": "status" } } }
}'

向量与混合检索复用 ES 的 knn 与 semantic 语法，默认嵌入器为离线词法特征哈希，神经嵌入模式需下载约 90 MB 模型文件。

MCP 接入

xerj --insecure --data-dir ./data &
xerj mcp        # stdio MCP 服务

MCP 客户端配置：

{
  "mcpServers": {
    "xerj": {
      "command": "/home/you/.local/bin/xerj",
      "args": ["mcp"],
      "env": { "XERJ_URL": "http://localhost:9200" }
    }
  }
}

共暴露 13 个工具，覆盖搜索（全文/语义/向量/混合）、代理记忆（/_memory/{namespace}）、知识图谱、计划生成等。开箱即用，可直接对接 Claude Code、Cursor 等支持 MCP 的客户端。

重排序与本地决策

可选的 rerank 阶段会将顶部结果发送至 TypeSafe AI 的 Jev 服务重排，在 FiQA 测试上将 nDCG@10 从 0.24 提升至 0.36。该功能需显式配置密钥且默认关闭。本地等效能力通过 POST /v1/systemone 与 POST /_decide 提供，基于已有标注样本做相似度匹配，无需联网，在 AG News（120k 标注）上标签预测准确率达 92%。

Elasticsearch 兼容性

实现了索引、文档、bulk、搜索、聚合、映射、kNN、scroll、reindex 与 _cat 等端点。当前一致性测试套件通过 1366/1369 用例，剩余差异公开列在 engine/tests/es-compat-yaml。注意 scroll 为有界快照，超出窗口会返回 400 而非静默截断，大结果集应使用 search_after。

基准测试

对比 Elasticsearch 8.13.4 的闭环测试结果：55 胜、26 平、4 负，摄入吞吐高 1.72 倍、磁盘占用小 1.61 倍。唯一落败项为高写入并发下的读 p99 延迟，详情见对应 playbook。代码索引层面，tree-sitter 解析在 Lucene 检出（6,113 文件、51 MB）上单线程达 约 1,500 文件/秒（13 MB/秒），解析占总耗时约 72%。重复索引走增量：内容字节级一致的文件直接复用上次结果，常见编辑后重跑场景中未变更文件通常超过 95%。

典型用例

• 参考式编程：检索同类项目实现后编写代码。
• 代码库问答与 RAG：返回带文件:行号的段落而非目录列表。
• 安全审计：跨文件类型查询 sink 模式、密钥与危险调用。
• 日志与事件分析：混合格式转为带聚合的索引。
• 代理长期记忆：/_memory/{namespace} 按语义跨会话检索。

从源码构建

git clone https://github.com/xerj-org/xerj
cd xerj/engine
cargo build --release -p xerj-server
./target/release/xerj --insecure --data-dir ./data

运行一致性测试：

cargo run --release -p es-yaml-runner -- --dir tests/es-compat-yaml/yaml

协议与许可

采用 Apache 2.0 协议。社区贡献以一份简短的实地报告 PR 为核心：人类与 AI 代理均可提交，纯报告类豁免 CLA，无需签署即可合并。代码变更需遵循 CONTRIBUTING.md 并签署 CLA（每个贡献者一次）。