xerj-org/xerj · 上手攻略

  • 仓库：xerj-org/xerj
  • 链接：https://github.com/xerj-org/xerj
  • 分类：ai / app · 本地优先的 AI agent 检索后端（Elasticsearch 兼容 + 自动索引）
  • 作者：spark
  • 更新：2026-10-15

§0 自检：✅ GitHub README 已 fetch（HTTP 200，14229 字节）；✅ 官方站 anchor xerj.org / llms.txt / case-studies / benchmarks 已核；✅ 关键子模块 anchor（autoindex / search / def / gain / mcp / rerank / system-one）已读。 ✅ 数字 verbatim 已抄：grep 对照 agent 260,916 tokens / $11.18 / 11/16 solved，XERJ 9,982 tokens / $1.58 / 16/16 solved，"2.7x fewer output tokens than grep, 26x vs memory alone"，字段报告端到端约 5x。 ✅ 字段报告锚：user-feedback/11-reference-coding-field-reports/2026-08-11-token-savings-reports.md。 ⚠️ Stars 数（卡面 4306）+ Apache-2.0 + Rust 静态二进制，但 README 强调"加入方式：跑一次 + 交一个字段报告 PR"，社群里 4k+ stars 与该门槛机制的因果关系作者未声明。 ⚠️ 重排序 Jev 与 /v1/systemone / /_decide 走 TypeSafe AI 的服务/能力，README 明示"答案不是 Jev、XERJ 在自己名下回 xerj-history-vote-1"——避免误用为 TypeSafe 官方产品名。

§1 这是什么

xerj（发音 /ˈzɜːrdʒ/）是一个本地优先的 AI 检索后端。它的卖点不是"新的检索算法"，而是"autoindex：对任何文件夹跑一条命令，它就把代码、文档、日志、PDF、SQLite、awkward CSV、Unity 资产等都索引成 typed indices，对外暴露 Elasticsearch HTTP API。"

典型用法是给 coding agent 当检索层：

  • agent 想知道"WAL 段怎么转"，用 xerj search "how do we rotate the WAL segment" 直接拿 ranked passage + file:line，而不是 grep 之后把整文件塞进上下文。
  • 想给 agent 长期记忆：/_memory/{namespace} 写，下次按语义召回。
  • 想给 Cursor / Claude Code 用：xerj mcp 一行就把这个二进制注册成 MCP server。

主参考场景叫 reference coding：让 agent 先索引开源项目再写代码。README 给了一个对照实验数据（同一 16/16 通过率下 token 消耗与成本）：

模式 output tokens cost solved
from memory only 260,916 $11.18 11/16
grep-driven agent 26,477 $3.27 16/16
XERJ 9,982 $1.58 16/16

即在 16/16 通过率不变的前提下，XERJ 比 grep 少 2.7x 输出 token、比纯记忆少 26x；单个 Java 任务上最高 278x 节省。实测细节在 case-studies/reference-coding.html，可复现脚本在 benchmarks/beir-hybrid 与 benchmarks/decisions-as-retrieval。

§2 解决什么问题

  • coding agent 反复把整个文件读进上下文烧 token、还找不到点；
  • 给现有 Elasticsearch 客户端（curl / SDK / Kibana / dashboards）当 drop-in 后端；
  • 让本地数据（私有代码、post-cutoff 库、内部 wiki、PDF 报告）成为 agent 的检索源而不是被遗忘；
  • 给 agent 一种不依赖远端的"长期记忆"。

README 自己定了个边界：对模型已经背下来的热门公开库，中性到负面——收益主要在私有 / 内部 / niche / post-cutoff 内容。

§3 快速安装

3.1 一行脚本（curl）

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

# Windows PowerShell
irm https://xerj.org/get.ps1 | iex

装下来是一个静态二进制（无 JVM、无运行时依赖），预编译覆盖 Linux / macOS / Windows 的 x86-64 与 arm64。

3.2 首次启动 + autoindex

# 开发模式：关 TLS + 关 auth（绑定 127.0.0.1；其它接口显式允许才会开）
xerj --insecure --data-dir ./data &

# 等 http://localhost:9200 响应后：
xerj autoindex ~/my-project

第一次 autoindex README 给出的实测：

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

3.3 带 auth 启动（默认开启）

xerj --data-dir ./data &               # 第一次启动会生成 ./data/admin.key
export XERJ_API_KEY="$(cat ./data/admin.key)"
xerj autoindex ~/my-project

README 明示：autoindex 不会从 xerj.toml 里拿 key，必须显式 --api-key 或环境变量，否则 401。

3.4 Windows / air-gap

  • Windows 手装指南在 README "Install by hand" 段。
  • 无外网的机器：docs/recipes/air-gapped-deployment.md。默认 lexical embedder 是离线的；neural 模式需要先把三个模型文件摆在本地。

§4 核心用法

4.1 完整 5 步参考循环

xerj --insecure --data-dir ./data &     # 1. 起服务
xerj init                                # 2. 一行接进 Claude Code / Cursor（MCP + skill）
xerj autoindex ~/my-project              # 3. 自动索引
xerj search "how do we rotate the WAL segment"   # 4. 拿 ranked passage + file:line
xerj def "euler_to_rotationmatrix"       # 5. 跳转到定义
xerj gain                                 # 看实际省了多少 token / cost

4.2 直接当 Elasticsearch 用

# 列索引
curl localhost:9200/_cat/indices

# 全文
curl "localhost:9200/ax-*/_search?q=checkout+error"

# 结构化 + agg
curl localhost:9200/ax-orders/_search -H 'content-type: application/json' -d '{
 "query": { "range": { "total": { "gte": 100 } } },
 "aggs":  { "by_status": { "terms": { "field": "status" } } }
}'

vector / hybrid 用同一套 knn + semantic 语法，任何 Elasticsearch 客户端库指向 localhost:9200 即可。

4.3 MCP server（一行接 Cursor / Claude）

xerj --insecure --data-dir ./data &   # 你要查的节点
xerj mcp                              # stdio MCP server；你的客户端跑它就行

4.4 重排 / 判定（Jev + 自家 System-One）

# 1) 用 TypeSafe 的 Jev 服务重排（可选；要 key；要联网）
#    README 给的数据：fiQA 上 nDCG@10 从 0.24 → 0.36，648 次搜索约 $0.64
#    不开 key 就完全不发；[rerank] enabled = false 直接禁掉
# 2) 本地判定：POST /v1/systemone 或 /_decide，XERJ 自己答（要你已经打过标签的样本）
#    README 引用：AG News (120k 标签) 上 92% 选对标签
#    模型在 XERJ 内部名是 xerj-history-vote-1，不是 Jev

4.5 把 XERJ 装成 agent skill

README 给的 prompt 直接可用：

"Read https://xerj.org/llms.txt, set XERJ up as your search backend, index ./docs, and show me one example query per index it created."

或者：

"Run xerj autoindex . and tell me what is in this data (types, counts and the gotchas it recorded), then answer my questions with search instead of reading files."

4.6 自动索引的类型覆盖

  • 代码：tree-sitter 解析，保留 symbols / line numbers，不当 flat text。
  • 结构化：MCP / JSON / JSONL / XML / YAML / SQLite / CSV。
  • 文档：PDF / DOCX / PPTX（每张幻灯片一条）/ XLSX（每张 sheet 一个 dataset）/ EPUB（每章一条）/ Jupyter（按 heading 分段）。
  • 运维 / 系统：man pages（roff，每节一条）/ 通用 log 格式 / mail（.eml 与 mbox，包括 Google Takeout 导出）/ HTML。
  • Unity 工程：scene/prefab/asset 序列化成"每 GameObject/Component 一条"；.meta 进 GUID→path 表；MonoBehaviour 带 script_class/script_path；Library/ 等生成目录自动跳过并登记。

§5 典型适用场景

  • Coding agent 在大型私有代码库里干活：reference coding 是主要赢面。
  • 本地 RAG：不想把私有仓库传远端，XERJ 全部在机器上跑。
  • 审计 / 安全扫描：把目标树索引起来，对 sink patterns / secrets / 危险调用一次 query 全文类型都查。
  • 日志 / 事件分析：混合格式自动归类，typed index + aggregation 像 Elasticsearch。
  • Agent 长期记忆：用 /_memory/{namespace} 写、按语义读。
  • 接进现有 ES 工具链：dashboards / Kibana 面板不动后端直接指 XERJ。

§6 坑与注意（≥5 条现象/影响/修复）

  1. --insecure 不是"开发可选"而是"信任边界" 现象：关 TLS + 关 auth 后，任何能到达端口的调用者都是超级用户，能读写 /_memory 全部命名空间。 影响：把它暴露在共享主机上 = 数据库裸奔。 修复：本地 127.0.0.1 跑通就行；要共享就开 auth（默认就是开），按 XERJ_API_KEY 传 key。完整安全模型在 docs/SECURITY_MODEL.md。

  2. autoindex 不会从 xerj.toml 读 key 现象：开了 auth 又忘了 --api-key / XERJ_API_KEY，所有 autoindex 请求 401。 影响：用户怀疑"是不是服务挂了"。 修复：第一次启动后立刻把 ./data/admin.key 落到 .envrc 或导出环境变量，再 autoindex。

  3. Jev 重排需要联网 + key 现象：默认不开；启用要走 docs/RERANK.md。 影响：把"重排"当免费功能会失败。 修复：要么显式开 key 并把发到 TypeSafe 的文本类型列入审查清单；要么用 /v1/systemone 或 /_decide 做本地判定（要先有打过标签的样本）。

  4. Wins 是 gated by memorisation 现象：README 自陈对"模型已经背下来的热门公开库"中性到负面。 影响：拿 XERJ 索引 react、requests 这种，结果可能反而比纯记忆差。 修复：把索引目标放在私有 / 内部 / niche / post-cutoff 内容上；热门库别 index。

  5. 重排分数是排序依据，不是精确概率 现象：README 给的数字 0.24 → 0.36 是 nDCG@10，不是"0.36 = 36% 正确"。 影响：拿分数当置信度会误用。 修复：在产品里把它当 re-rank 信号用，别当概率。

  6. Unity 资产序列化有前置条件 现象：二进制序列化的资产不可读；Library/ 等生成目录才会被自动跳过。 影响：开了 Force Text 才有 symbol；不开启的话 Unity 工程索引质量下降。 修复：Project Settings → Asset Serialization 选 Force Text；或者接受"部分 Unity 数据不可检索"。

  7. 加入项目的"门票"是 field report PR 现象：README 明示"加入 XERJ = 跑一次 + 一个字段报告 PR"。 影响：评估活跃度时不要只看 stars，要看 user-feedback/ 目录的 PR 频度。 修复：如果你要引用它做社区成熟度证据，建议同时给 user-feedback/16-agent-field-reports/ 链接。

§7 与同类对比

维度 XERJ 传统 Elasticsearch ls / ripgrep + 手写 RAG
安装 静态二进制 + 一行脚本 JVM + 集群配置 已有
索引 autoindex（sniff + tree-sitter） 手动 mapping 自己写 chunker + embedder
接口 完整 Elasticsearch HTTP API 同 各自
向量 / hybrid 支持（knn + semantic） 需 ES 8+ / 插件 自己拼
Coding agent 集成 MCP + skill + init 无 无
长期记忆 /_memory/{namespace> 自己造 自己造
重排 可选 Jev / 本地 System-One 需插件 自己造
离线性 默认离线 lexical embedder 全离线 全离线
边界条件 私域赢，热门库平到负 通吃但要你写 完全自己负责

§8 一句话推荐结论

如果你受够了 agent 把整文件塞 context 还找不到点，xerj 是当下最容易上手的本地检索后端——一行安装 + 一行 autoindex + 一行接进 MCP，先拿 reference coding 这个最被 README 实测过的场景跑一遍，赢了再扩展到 /_memory 和 Jev 重排。