代码、日志和 SQLite 散在各处：用 XERJ 给本地项目建立可被 Agent 查询的检索层
当一个项目把源代码、运行日志、导出的 CSV、SQLite 文件和运维文档分散在不同目录时，AI Agent 面临的第一个问题往往不是“不会写代码”，而是不知道该从哪里找证据。把整个目录递给模型会迅速耗尽上下文；grep 能命中字符串，却无法回答“过去一小时哪个服务的支付错误最多”“这张表有哪些字段”这类需要结构化过滤和聚合的问题。
XERJ 提供了一种不同的本地工作流：它是 Apache-2.0 许可的 Rust 搜索引擎，官方定位为面向 AI Agent 的单二进制检索服务。启动服务后，对目录运行一次 autoindex，它会识别内容类型并为推断出的数据集建立索引；随后既可以通过 Elasticsearch 兼容 API 查询，也可以使用它的原生 HTTP API。对已有 Elasticsearch 客户端、仪表盘或脚本而言，这一点尤其重要：迁移的第一步通常只是把连接地址指向本地端口，而非重新设计全部调用链。
先把“文件夹”变成可查询的数据集
官方 README 列出的自动索引输入不只包括代码和普通文本，还包括 CSV、JSON、JSONL、XML、YAML、SQLite、PDF、DOCX、HTML 与常见日志格式。源代码会经过 Tree-sitter 处理，因此索引不只是把文件当成长文本切块，还会保留符号和行号等代码上下文。它适合下面这类日常排障场景：一个仓库里有服务源码，exports/ 里有订单导出，var/log/ 里有 JSON 日志，旁边还有排障手册；开发者希望先用查询缩小范围，再把少量原文件交给 Agent 阅读。
安装脚本会根据系统和 CPU 下载对应的发行版二进制，并校验 SHA-256。以下是官方 README 给出的最小本地流程：
curl -fsSL https://xerj.org/get | sh xerj --insecure --data-dir ./data & xerj autoindex ~/my-project curl localhost:9200/_cat/indices
这里的 --insecure 不能被误解为“简单部署选项”。官方 CLI 文档明确将它标为仅限开发环境：它会关闭 TLS 与 API-key 认证；当服务绑定地址不是 127.0.0.1 时，生产构建会拒绝以该模式启动。因此，实验时可以把数据目录放进临时路径，但不要把无认证的 9200 端口暴露到局域网、容器入口或反向代理之后。
用同一接口问文本问题和数据问题
自动索引完成后，可以先用全文查询定位故障线索。下面的 URL 中，ax-* 是 XERJ 自动创建索引时使用的前缀；checkout+error 只是一个示例查询词，应替换成项目中的服务名、错误码或领域词。
curl "localhost:9200/ax-*/_search?q=checkout+error"
但真正有价值的部分在于：同一个 Elasticsearch 兼容接口也能做字段过滤与聚合。假设自动推断出的 ax-orders 索引含有数值字段 total 和关键字字段 status，可先筛出金额不低于 100 的记录，再按状态分组：
curl localhost:9200/ax-orders/_search \
-H 'content-type: application/json' \
-d '{
"query": { "range": { "total": { "gte": 100 } } },
"aggs": { "by_status": { "terms": { "field": "status" } } }
}'
这段命令的边界也很重要：它并不保证任意 CSV 都天然拥有 total、status 这两个字段。自动索引会依据实际内容推断数据集，执行前应先检查索引和映射，再按真实字段改写查询。让 Agent 根据查询结果引用少量记录、代码符号和日志片段，通常比让它盲读整个目录更容易复核，也更便于把“猜测”变成可追溯的证据链。
两套 API：兼容层适合接入，原生层适合精确建模
XERJ 的 README 展示了 Elasticsearch 兼容端口 9200；兼容层覆盖创建索引、写入/读取文档、_search、_bulk、_delete_by_query、集群健康检查和索引列表等常用操作。官方文档也说明，尚未支持的调用会返回结构化的 not_supported_yet 错误，而不是伪装成 500。这个设计有助于渐进式试用：先让已有客户端跑通最常用路径，遇到不兼容调用再决定是否替换为原生接口。
如果数据模型需要严格控制，原生 API 的路线更合适。官方 Quickstart 在 http://localhost:8080/v1/indices 下先显式创建含字段类型的索引，再通过 turbo-ingest 写入 NDJSON。也就是说，autoindex 解决“快速盘点混合目录”的问题；显式映射解决“数据契约已知、需要稳定字段类型”的问题。把两者混为一谈，容易在后续分析中把推断字段当成长期接口承诺。
给 Agent 检索层设定四条边界
第一，不要把“支持向量和混合检索”自动等同于外部大模型语义能力。项目公开说明其内置 embedder 是词法哈希式的，适合诚实地描述为词法与向量结合的检索，而不是宣称具备神经语义理解。
第二，索引是副本，不是数据治理的替代品。目录内若包含密钥、客户导出、生产日志或受限文档，先用文件权限、专用目录和脱敏规则划定输入范围；不要因为服务运行在本机，就默认所有内容都适合被任意 Agent 读取。
第三，自动发现很适合探索，不应跳过抽样验证。首次运行后，检查索引数量、记录数量和典型查询结果；对 JSON、SQLite 和日志各抽一条回到原文件核对，能及时发现编码、字段推断或无关文件被纳入的问题。
第四，当前版本仍是 v1.0.0-rc.11 预发布版本。官方 README 的兼容性徽章显示 Elasticsearch YAML 兼容测试为 1365/1368，这能说明其覆盖面，但不能替代你自己的回归测试。生产接入应从只读检索、副本数据和固定查询集开始，而不是直接替换关键搜索集群。
在团队协作里，可以把这条路径拆成两层。第一层由自动索引完成“资产盘点”：哪些目录含日志、哪些导出文件有可分析字段、哪些文档可能解释某个异常。第二层才是面向任务的查询模板，例如按时间窗口、服务名和错误等级过滤日志，或按订单状态聚合导出数据。模板应该进入版本控制，并附带预期结果样本；这样当目录结构、字段名或 XERJ 版本变化时，CI 或日常巡检能发现检索语义已经漂移。
还要避免把检索结果直接升级为执行指令。Agent 从索引中找到了疑似配置、脚本或历史命令，只说明它们“存在且相关”，不说明它们仍适用于当前环境。对于重启、迁移、删除和权限调整，较稳妥的流程是让 Agent 在回答中同时给出索引命中、原文件路径和最后修改时间，由操作者回到原始文件或变更系统确认。检索层的角色是降低发现成本，而不是绕过发布、审计和人工批准。
检索范围也应按权限而不是按便利性设计。可把公开源码、脱敏日志和可共享文档放进一个用于日常问答的目录；把包含客户标识、访问令牌或生产配置的材料放在独立目录，只允许经过批准的维护流程临时索引。若团队确实需要跨目录检索，至少记录每次索引的输入清单，并让查询服务以最小权限账户运行。这样即使 Agent 的提示词、插件或会话记录出现意外暴露，影响面也被限制在经过选择的数据副本内。
最后，数据更新频率决定了索引的可信边界。一次性导出的 CSV 和归档日志适合按批次重建；持续写入的日志或数据库快照，则应明确谁负责重新索引、何时完成和如何处理失败。没有这些约定时，查询得到的可能是“上一次索引时正确”的答案。把索引时间、输入目录和查询版本一起写进排障记录，日后才能解释一个结论基于哪份数据。
对个人项目和小团队来说，XERJ 最实际的价值并非再部署一个“大而全”的搜索平台，而是提供一条本地、可检查的中间路径：先把混合文件转成能过滤、聚合和定位的索引，再让人或 Agent 打开最相关的原始证据。这样既减少无目的扫描，也保留了核验结论的入口。