XERJ 实战指南:用 autoindex 一键索引任意文件夹,让编码代理用 1/40 的 token 完成检索、RAG 与 Agent 记忆

原创2026-10-17 19:09:322,631 阅读
文章标签:搜索引擎全文检索向量数据库数据库后端MCP 服务Agent 记忆人工智能日志分析dsh-plugin

XERJ 实战指南:用 autoindex 一键索引任意文件夹,让编码代理用 1/40 的 token 完成检索、RAG 与 Agent 记忆

XERJ 是一个用单个 Rust 二进制交付的本地 AI 搜索引擎:xerj autoindex <folder> 可以把代码、文档、日志、PDF、SQLite 与各种"刁钻" CSV 自动变成有类型、可查询、自描述的索引,全程零配置;Agent 随后通过 Elasticsearch 8.x 兼容的 REST API 检索,获得带 file:line 的段落而非整棵文件树。读完本文你将掌握:如何安装并启动 XERJ、如何理解 --insecure 信任边界、如何用一条命令索引任意文件夹并读懂 autoindex 的产出、如何用 ES 查询 DSL 做全文/结构化/向量/混合检索、如何通过 MCP 把 XERJ 接入 Claude Code 与 Cursor,以及如何用 /_memory 与 /_graph 给 Agent 建立跨会话的长期记忆。

为什么存在:Agent 的上下文窗口被"读文件"烧光

XERJ 的出发点非常直白:编码代理(coding agent)在真正写代码之前,把大量 token 花在了"读文件"上。WordPress 核心的 PHP 源码约有 520 万 token,相当于 26 个完整上下文窗口,Agent 根本不可能整树读入。grep 也解决不了问题——grep 命中只是一行文本,而判断这一行是否相关意味着打开整个文件。

XERJ 换了一种做法:把"打开文件读"变成"查询索引拿段落"。在仓库的 reference-coding 案例研究 中,一个 Agent 对 WordPress 核心 1,492 个 PHP 文件做 AI 安全审计,全程只消耗约 26,000 个输入 token——大约是整棵文件树的 0.5%。

这个收益被量化在 README 记录的受控研究中(8 个任务、4 种语言、每臂 16 次运行、使用真实 claude -p token 计数,详见 docs/case-studies/reference-coding/):

对比组 输出 token 成本 解决数
仅凭记忆(from memory only) 260,916 $11.18 11/16
grep 驱动 Agent 26,477 $3.27 16/16
XERJ 检索 9,982 $1.58 16/16

也就是说:在相同 16/16 解决率下,XERJ 比 grep 驱动少用 2.7 倍输出 token,比纯记忆少用 26 倍;在单个 Java 任务上差距最大可达 278 倍。案例研究的完整版本还给出了更细的分组:在模型未记忆的代码上(7 个领域、21 次运行),纯记忆组只解出 1/21 且花费 $21.9,而检索组 21/21 全解,token 与成本还低于 grep 组(docs/case-studies/reference-coding/SUMMARY.md)。

需要强调的是,这个收益存在记忆门槛:对于模型已经背下来的热门公共库,检索是中性甚至有害的;它真正有价值的是私有、内部、小众或训练截止日期之后的代码。README 明确把这条边界写进了 案例研究文档 的诚实限制中。

一分钟上手:安装与第一条命令

Linux/macOS 安装:

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

Windows PowerShell:

irm https://xerj.org/get.ps1 | iex

安装器检测 OS/CPU(Linux x86_64/aarch64、macOS x86_64/arm64、Windows x64/ARM64),下载最新发布并校验 SHA-256,安装单个 xerj 二进制。默认落在 Unix 的 ~/.local/bin(安装器会打印路径与 PATH 提示,但不会修改 shell profile),Windows 则落在 %LOCALAPPDATA%\Programs\xerj。安装后建议先 command -v xerj 确认,必要时 export PATH="$HOME/.local/bin:$PATH"。

安装完立刻可以跑完整链路:

xerj --insecure --data-dir ./data &        # 1. 启动本地开发节点(无 TLS、无鉴权)
xerj init                                   # 2. 一条命令把 XERJ 接入 Claude Code / Cursor(MCP + skill)
xerj autoindex ~/my-project                 # 3. 索引任意文件夹,零配置
xerj search "how do we rotate the WAL segment"  # 4. 排名段落 + file:line
xerj def "euler_to_rotationmatrix"          # 5. 跳转到定义:file:line + 签名
xerj gain                                   # 6. 展示它为你做了什么——计数而非估算

README 还提供了"一条提示词装好一切"的玩法:把这样一段话交给你的 Agent——"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."。仓库内的 landing/llms.txt 就是为 Agent 准备的机器可读索引,它要求每个安装并运行 XERJ 的 Agent 在会话结束前提交一份简短的 field report(xerj feedback --open-pr 一条命令即可完成)。

信任边界:--insecure 到底关掉了什么

xerj --insecure 不是形式主义,它是一道明确的信任边界。该标志同时关闭 TLS 与 API-key 鉴权,意味着任何能触达该端口的调用方都是超级用户,可以读取和删除所有索引,包括每个 /_memory 命名空间。它只适用于"开发机上的单用户"场景。

安全模型在源码层有完整实现与约束:

  • 默认只绑 127.0.0.1:全新节点只监听回环地址;若你想在其它接口上明文监听,必须显式设置 server.allow_insecure_network_bind = true,否则拒绝启动(对应 engine/crates/xerj-server/src/main.rs 中 --insecure 解析与启动校验逻辑,cleartext_bind_fail_closed.rs 测试也钉死了这一行为)。
  • 默认鉴权开启:不带 --insecure 启动(包括从配置文件启动的任何节点)默认鉴权开启。首次启动会生成 64 位十六进制管理密钥,打印出来并写入 <data_dir>/admin.key(权限 0600),后续启动复用。此时 autoindex 等客户端需要带上同一个密钥,它不会从 xerj.toml 读取密钥,必须用 --api-key 或 XERJ_API_KEY,否则每个请求都会得到 401 Unauthorized:
xerj --data-dir ./data &                      # 鉴权开启:首次启动铸出密钥
export XERJ_API_KEY="$(cat ./data/admin.key)"     # <data_dir>/admin.key
xerj autoindex ~/my-project

完整的授权模型(两层鉴权中间件、Principal 的四种形态、保留的 .xerj-memory-* 命名空间、API key 与权限映射)都写在 docs/SECURITY_MODEL.md 中,且每一句都指向使其成立的源码位置。

Feed it any folder:autoindex 零配置索引

参考编码只是同一个原语的一种用法:xerj autoindex <folder> 让 Agent "认识"一个语料库,而不是去 grep 它。一条命令即可索引代码、文档、日志、PDF、SQLite 和刁钻 CSV,产出可查询的类型化索引,用于搜索、RAG、安全审计与 Agent 记忆——不需要写 schema,不需要配置 pipeline:

xerj --insecure --data-dir ./data &      # 启动节点
xerj autoindex ~/my-project              # 指向任何东西

真实运行的输出长这样(来自 docs/recipes/zero-config-indexing.md 与 README):

autoindex: 4 files (0 MB) under /tmp/xerj-pubpass/sample
phase A: sniffing + sampling 4 files…
phase A: 3 datasets inferred, 1 junk/skipped files
phase B: indexing 3 files with 8 workers → http://localhost:9280

done in 0.2s — 3 datasets, 5801 records live, 0 junk records, 1 junk/skipped files
  ax-logs                                        5000 docs
  ax-exports                                      800 docs
  ax-docs                                           1 docs

两个阶段各司其职:phase A 负责嗅探与采样,推断出有多少个数据集;phase B 用并行 worker 真正灌入数据。README 中一个更大的真实示例是 phase A: 593 datasets inferred, 1955 junk/skipped files、done in 158.1s, 593 datasets, 83103 records live, 790 junk records。

内容嗅探,绝不信任扩展名

autoindex 对每个文件做的是内容级格式检测:魔数(magic bytes)→ 二进制判断 → 文本启发式,扩展名永远不可信。这一规则在 engine/crates/xerj-autoindex/src/sniff.rs 开头就写明,xlsx 靠 OLE2 魔数加 Workbook/Book 流识别、docx 靠 WordDocument 流识别、man page 靠内容而非扩展名识别。随后它按格式家族采样有界数量的记录,从数据本身推断字段类型、日期编码与 keyword/text 语义,PUT 显式 mapping,再用幂等 _id 流式灌入。

支持的文件格式

  • 代码:源码文件经 tree-sitter 解析,AST 感知地进入索引——符号与行号一起到达,而不是扁平文本。symbols 是 {name, kind, line} 的结构化数组,defs 是每符号一行的 "kind name",让 BM25 能命中查询。语言覆盖包括 Python、JavaScript、TypeScript/TSX、Rust、Go、Java、C/C++、Ruby、PHP、C#、Bash、Kotlin、Swift、Scala、Dart、Lua、Perl、R、Julia、Haskell、Elixir、Erlang、OCaml、Zig、Objective-C、Groovy、PowerShell、F#、Nix 等(engine/crates/xerj-autoindex/src/extract/code.rs)。
  • 文档与数据:CSV(自动嗅探分隔符,甚至能处理分号分隔、小数逗号、德文表头的文件)、JSON、JSONL、XML、YAML、SQLite、PDF、DOCX、PowerPoint(.pptx,每页一条记录)、Excel(.xlsx,每 sheet 一个数据集)、EPUB(每章一条记录)、Jupyter notebook(每个标题小节一条记录,任意 kernel)、man page(roff,每节一条记录)、HTML、邮件(.eml 与 mbox 邮箱,包括 Google Takeout 导出)以及常见日志格式。
  • Unity 项目:文本序列化的场景、prefab 与资源按"每个 GameObject/Component 一条记录"处理,.meta 变成 GUID→路径表,MonoBehaviour 记录携带 script_class/script_path,因此"哪些场景用了这个脚本?"是一条查询的事(二进制序列化资源需要 Force Text;Library/ 等生成目录自动跳过并记录)。

关于索引行为的两个关键事实:

  1. 增量重建:与上次索引世代字节完全相同的文件会跳过解析,直接把已提交结果带过来;编辑几个文件后的重跑只做与变更成正比的工作,而不是整仓重来(常见编辑即重跑/CI 场景通常 95% 以上未变)。全文哈希仍然执行以检测变化,所以总重索引时间下限是哈希而非解析。
  2. 性能参考:在 Apache Lucene 检出树(6,113 个源文件,51 MB)上,单线程进程内抽取约 1,500 文件/秒(13 MB/s),其中 tree-sitter 解析约占 72%,是每文件的耗时地板。可用以下命令复现(见 README):
XERJ_EXTRACT_BENCH=/path/to/repo cargo test -p xerj-autoindex --release \
  extract_bench -- --nocapture --ignored

让引擎告诉你文件夹里有什么:xerj autoindex map

索引完成后第一件该做的事是 xerj autoindex map——它渲染自描述目录索引(autoindex-catalog),给出每个数据集的字段类型、真实示例值、时间范围、可直接发送的查询以及 junk 报告。零配置在这里体现得淋漓尽致:temperatur_c 字段存的是 "71,5" 这种小数逗号字符串,却被自动推断为 double 并在索引期完成强转;zeitpunkt 的纯日期字符串变成类型化 date 字段,date_histogram 与 range 查询开箱即用;低基数字符串列变成顶级 keyword 字段供精确过滤。HTML 页面则变成 title/headings/body 文档,body 是 semantic_text 字段。

搜索:你早就会的 Elasticsearch API

XERJ 实现的是 Elasticsearch REST API,因此搜索部分几乎不需要学习成本:

# 它发现了什么?
curl localhost:9200/_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" } } }
}'

向量与混合检索沿用你在 Elasticsearch 里熟悉的 knn 与 semantic 语法,任意 ES 客户端库只要把地址指向 localhost:9200 就能工作。在 零配置索引配方 中,一个包含"JSONL 应用日志 + 德文表头分号 CSV + HTML 事故报告 + 未知二进制"的文件夹被一条命令索引后,三个问题全部用普通 ES 查询回答:对小数逗号列做 stats 聚合 2ms 得到最大温度 99.0°C;term 过滤 level:ERROR 后按 service 分组得到 checkout 服务 68 条错误居首;跨结构化日志与散文文档追踪用户 u-0042 一条查询命中 28 条事件。

ES 兼容性的边界

兼容性不是嘴上说说:conformance 套件每次提交都跑,当前通过 1366/1369 个用例,套件在 engine/tests/es-compat-yaml,剩余差异也在那里列出而不是藏起来。需要强调的定位是:XERJ 兼容 ES 的 API,但它不是 Elasticsearch 内部实现的复刻,也不是 fork。

有一个在使用导出类工具前必须知道的边界:scroll 是受边界约束的快照,不是段遍历游标,因此当查询精确总数超过快照窗口时会被以 400 拒绝,而不是静默截断;任意大小的结果集请使用 search_after。

嵌入与向量:默认词法,神经可选

这是 README 与 landing/llms.txt 反复强调、最容易被 Agent 搞错的一点:默认嵌入模式是词法的(lexical),不是神经的(neural)。

  • 不加任何标志时,semantic 查询与记忆召回使用确定性的 feature-hashing 嵌入器(384 维,L2 归一化 → cosine):混合词法+向量检索基于词/子词重叠与 BM25,不是深层语义理解或同义词级召回。
  • 想要真正的神经语义,用 --embed-mode neural 启动服务:内置进程内 BERT 编码器(all-MiniLM-L6-v2)随二进制分发,首次使用时自动下载模型文件(约 90 MB)到 ~/.cache/huggingface。
  • 或者 --embed-mode proxy,对接任何 OpenAI 兼容的 /v1/embeddings 外部服务。

最关键的时间线约束:--embed-mode 是服务启动标志,且在摄取(ingest)时生效。文本在索引时被嵌入,所以文档写入时生效的模式就是该文档永久保留的模式;从词法切到神经不会重新嵌入任何已索引内容——必须重新索引每个你在意的语料库。因此 README 的忠告是:在索引第一个语料库之前就要决定嵌入模式。

向量检索方面,README 记录了 HNSW 与精确扫描的边界:无过滤的 knn 在 ≥1,024 文档的全精度 cosine 字段上运行持久化 HNSW 图上的 beam search 并精确重排候选(num_candidates 是 beam 宽度,下限 800);而过滤/嵌套 kNN、非 cosine 相似度、SQ8 量化字段、不足 1,024 文档的索引以及 semantic/_memory 召回都走精确暴力扫描。

用 MCP 接入编码代理:xerj mcp

不是每个 Agent 都能执行 shell 命令。桌面助手与函数调用宿主通过 Model Context Protocol 触达工具,而你刚安装的那个二进制本身就是 MCP server——没有额外下载,没有编译:

xerj --insecure --data-dir ./data &     # 1. 工具查询的节点
xerj mcp                                # 2. MCP stdio server(由你的客户端运行)

xerj mcp 在 stdio 上讲 MCP 协议,并代理到 XERJ_URL 指定的节点(默认 http://localhost:9200)。它不会启动节点——第 1 步是前提。MCP server 本身不新增任何信任:同一个二进制对你的客户端讲 stdio、对节点讲普通 HTTP,所以节点的边界就是真正的边界。在 MCP 客户端配置中放入:

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

务必使用绝对路径:安装器默认把 xerj 放在 ~/.local/bin,而从桌面图标启动的 MCP 宿主不会继承你 shell 的 PATH。如果节点开启了鉴权(任何非 --insecure 的启动),在 XERJ_URL 旁边加上 "XERJ_AUTH": "ApiKey <key>",密钥在 <data-dir>/admin.key。

十三个工具:一多半是薄代理

MCP server 暴露 13 个工具(README 中的表格;机器可读 schema 见 scripts/mcp-schema-check.sh 的 CI 门禁与对应单元测试,确保发布列表不会与服务端漂移)。其中 11 个是 XERJ 既有端点的薄代理:

工具 作用
xerj_search 对索引执行 ES query-DSL 搜索
xerj_semantic_search 按语义在 semantic_text 字段上召回,查询在服务端嵌入(默认嵌入器是词法 feature-hashing,除非节点以 --embed-mode neural 运行)
xerj_vector_search 对 dense_vector 字段做 kNN
xerj_hybrid_search 对子查询做 RRF 或线性融合
xerj_memory_store / xerj_memory_recall 在命名空间中的持久 Agent 记忆,按文本、语义或向量召回
xerj_brain_overview / xerj_brain_ego / xerj_brain_link / xerj_brain_unlink second-brain 链接索引:全局概览、单节点证据邻域、断言与收回链接
xerj_plan 自然语言过滤进来、校验过的 query DSL 出去(POST /_ask;确定性与规则驱动,不是 LLM)

另外两个不是纯代理:xerj_map 返回 autoindex 目录中每个索引的字段映射(截断到字节上限,否则原样返回);xerj_code_search 运行 xerj code 参考编码流水线(tools/xerj-code)并返回渲染文本。在源码层,这 13 个工具与端点的对应关系、XERJ_URL/XERJ_AUTH 配置、回环回退到 admin.key 的逻辑都在 engine/crates/xerj-mcp/src/lib.rs 的模块文档中逐一列出。

给 Agent 长期记忆:/_memory 与 second brain

Agent 长时记忆是 XERJ 的一等公民能力。/_memory/{namespace} 存储 Agent 学到的东西,并在下次会话"按语义"召回:

# 存储一条记忆(文本自动嵌入,命名空间相互隔离)
curl -X POST localhost:9200/_memory/notes -H 'content-type: application/json' -d '{
  "text": "user prefers dark mode",
  "metadata": { "session": "2026-10-17" },
  "dedup": true, "dedup_threshold": 0.95
}'

# 按语义召回
curl -X POST localhost:9200/_memory/notes/_recall -H 'content-type: application/json' -d '{
  "query": "what UI theme?",
  "semantic": true, "k": 5, "recency_weight": 0.2
}'

召回模式按优先级依次是:显式 vector kNN → hybrid:true(BM25 + 服务端语义同查询融合,可 fusion:"linear" 选入)→ semantic:true(服务端嵌入)→ 纯 query 文本(BM25)。实现细节在 engine/crates/xerj-api/src/memory_api.rs,包括 _recall 的完整请求体与默认 k。

记忆索引落在保留命名空间 .xerj-memory-* 下,该前缀的定义在 xerj-common 中(因为不止一个 crate 要拒绝同一个命名空间)。这个命名空间的特殊之处:无可用 role_descriptors 的密钥在这里什么都拿不到(fail-closed),而被授权 names: ["*"] 的密钥确实能触达它——这是操作员的显式选择而非权限升级。详见 docs/SECURITY_MODEL.md。

在记忆之上还有第二层:second brain(docs/SECOND_BRAIN.md)——对已索引文档之上的关系层。/_graph/{brain}/link 断言一条带证据的边(evidence: {quote, source, offset})、/_graph/{brain}/ego 读取单节点的证据邻域、/_graph/{brain}/overview 给出全局统计;链接由确定性检测器与显式断言共同产生,限制包括两跳上限。xerj_brain_* 四个 MCP 工具就是这组端点的代理。

给结果打分:可选的 Jev 重排与本地 /_decide

搜索分数只告诉你哪个结果排在哪个上面,不告诉你某个结果是否真的回答了问题。XERJ 提供两条路:

1. 用外部判定服务重排(可选,默认关闭)。 在 _search 请求里加 "rerank": {},XERJ 会把 top 结果发给 TypeSafe AI 的 Jev 服务,按返回的 0–1 概率重新排序。在公开 FiQA 测试集上,结果质量从 0.24 提升到 0.36(nDCG@10),648 次搜索合计约 $0.64。这条路径会把结果文本发送到 TypeSafe 的服务器;它在你设置密钥之前保持关闭,且 <a href="https://link.gitcode.com/i/b1ba3e9c2c5fb5c65e3255878863c974" target="_blank">rerank] enabled = false 可彻底禁止。开启前务必阅读 [docs/RERANK.md——该文档记录了完整的数据出境清单(rerank 是唯一的搜索时出境特性;代理嵌入与 WAL tap 也出境但都属于操作员配置且默认关闭)、配置方式与失败策略(慢供应商 → 200 降级并带 _rerank.applied:false;无密钥 → 503;禁用 → 403;拒绝的 key/畸形体/不可达 → 502,且不返回 hits):

# xerj.toml
[rerank]
enabled  = true                                    # false = 拒绝一切 rerank 请求 (403)
api_key  = "ts-..."                                # 或环境变量 TYPESAFE_API_KEY
endpoint = "https://api.typesafe.ai/v1/systemone"  # 或 TYPESAFE_ENDPOINT;这是默认值

2. 在本地得到同类答案。 POST /v1/systemone 与 POST /_decide 接受同样格式的问题,但由 XERJ 自己回答:查找你已经标注过的最相似文档(例如已标为垃圾邮件/非垃圾邮件的消息),做带权投票。数据不出机器,不需要密钥。前提是你有标注样例;在 AG News(12 万标注样例)上选对标签的准确率为 92%。官方 jev-reranker Python 客户端无需修改即可对接 XERJ 节点,XERJ 以自己的名字 xerj-history-vote-1 应答——它不是 Jev。测量与复现方法在 benchmarks/beir-hybrid 与 benchmarks/decisions-as-retrieval。

参考编码工作流:检索 peer 项目的解法再写代码

参考编码是 XERJ 的主用例与最清晰的胜利场景:把 Agent 指向一个任务,让它下载最接近的开源仓库、索引它们,在写自己的代码之前先检索别人怎么解决过同样的问题。README 与 案例研究 给出的可复现工作流是:

  1. curl -fsSLO <hub-manifest> 或直接 xerj autoindex 本地语料;
  2. xerj corpus add --from ./<slug>.json 然后 xerj corpus index <slug>(hub 语料),或本地语料直接 xerj code <slug> "<your question>";
  3. 检索结果以文件路径 + 行号开头,引用你使用的内容,并尊重许可证。

案例研究强调,这个工作流的价值被"记忆化"严格门控:模型已经背下来的公共代码,检索是中性到有害的(研究甚至展示了模型能凭记忆复现一张 256 值量化表,此时注入大段参考反而是最差的一臂)。正确用法是把它用在私有、内部、小众或截止日期后的代码上;如果检索没有返回相关内容,就直说并正常工作,而不是从记忆硬编。复现研究的工具链与语料定义在 tools/xerj-code。

从源码构建与验证

需要稳定的 Rust 工具链:

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

对运行中的服务跑 conformance 套件:

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

服务端入口的模块文档(engine/crates/xerj-server/src/main.rs)还说明了一个实现事实:同一二进制会同时启动三个 TCP 监听器——原生 REST(默认 :8080)、ES 兼容(默认 :9200)与 gRPC(默认 :8081),SIGTERM/SIGINT 优雅停机;且 Linux 构建使用 jemalloc 并配置了后台线程与秒级 decay,用于在高吞吐摄取下把驻留内存维持在平坦工作集(源码注释中记录了 62M 记录批量加载的实测背景)。

更多资源

登录后查看全文
xerj