zg Rust 版：本地检索，性能再进一步

摘要：zg 推出 Rust 版本，通过原生实现与执行链路优化，缩短索引构建时间，降低内存开销。同时新版本带来更简洁的 CLI、更直观的交互，以及更多 Agent 的集成。

从 Node.js 到 Rust

zg 是面向开发者与 AI Agent 的本地检索工具，将语义检索、BM25 与 grep 精确匹配整合到统一入口，帮助用户从文档和代码中找到相关内容。

在 Node.js 版 zg 中，每次独立的 CLI 调用都需要启动运行时并加载模块，部分索引路径还涉及 JavaScript 对象转换和工作线程间的数据传递，增加了处理开销与内存分配。面向大型工作区和频繁调用的 Agent 工作流，索引耗时、查询延迟与资源占用直接影响使用体验。为此，我们用 Rust 重构核心执行链路，进一步优化本地检索的运行效率。

性能对比：索引更快，资源占用更低

对于本地检索工具，第一次建立索引的耗时，直接影响用户开始语义检索前的等待时间，也是本地检索体验的重要一环。

我们使用相同环境和数据集，对比了 Node.js 0.2.2 与 Rust 0.3.0 的性能和资源占用。

测试环境为 Apple M3 Pro、18 GB 内存、macOS 27.2，Node.js 运行时为 v24.16.0。索引测试选取 BEIR 中的 SciFact、NFCorpus、ArguAna 和 FiQA 四个公开语料，共 75,128 篇文档。两版使用相同的本地 Embedding 模型，均采用 CPU 推理，Embedding 并发设为 4。

索引耗时为四个语料的合计，内存为各语料构建峰值的平均值；MCP 检索耗时在模型与索引加载完成后测量。

索引构建总耗时减少约 65%

四组语料测试中，Rust 版将索引构建总耗时从约 3 分 39 秒缩短至约 1 分 18 秒，减少 64.5%。

每组统计的是完整构建过程，包含程序启动、模型初始化、文件扫描、内容切片、Embedding 计算、索引写入和最终优化，对应执行索引命令后到索引准备就绪的实际等待时间；表格汇总了四组耗时。两版索引的文件集合、原文大小和切片数量均一致。

对于首次接入 zg 的项目，或需要重新建立索引的工作区，这意味着可以更早进入搜索、代码理解和资料分析等后续工作。

平均构建峰值内存降低约 53%

四组测试中，Rust 版的平均构建峰值 RSS 从约 4.11 GiB 降至约 1.92 GiB，降低 53.2%。在完成相同文件集合索引的同时，Rust 版在每组测试中都降低了构建阶段的峰值内存占用。

对于同时运行编辑器、Agent 和其他开发工具的本地环境，缩短等待时间和降低内存压力同样重要。这两项改善，让建立大型工作区索引的过程更高效，也减少了构建期间对本机资源的需求。

性能提升背后的优化

Rust 版 zg 对启动、计算、数据流转和资源管理等环节进行了多项优化，例如：

• 原生启动，减少运行时准备。Rust 版直接执行编译后的原生程序，省去了 Node.js 运行时初始化和 JavaScript 模块加载环节，减少独立 CLI 调用的启动开销。
• 优化本地计算路径。部分文本编码与向量计算直接在原生代码中完成，使用明确的数值类型和连续数组，为编译器优化计算循环提供条件。
• 减少中间数据转换。将计算结果保留为原生数值数组，减少 JavaScript 普通数组与类型化数组之间的转换，降低相关的数据复制与临时分配开销。
• 共享资源，统一调度。在支持的本地推理路径中，计算线程共享已加载的分词器和模型数据，减少重复初始化，并由原生线程池统一调度计算任务。

这些优化共同作用，让本地索引构建更高效，并降低了构建阶段的内存开销。

使用体验优化：更顺手的 CLI，更可靠的本地检索

性能之外，Rust 版也重新梳理了命令行交互与结果呈现。

命令更简洁，检索更顺手

新版 CLI 借鉴了 rg 的命令风格，采用“查询 + 选项”的形式，直接在 zg 后输入问题即可搜索。索引、状态等管理操作统一使用 --index、--status 等选项，搜索与管理的入口更加清晰。

# 按含义搜索，默认使用混合检索
zg "用户权限在哪里校验"

# 为当前工作区建立索引
zg --index

# 精确匹配，查看对应源码行
zg --rg -n "AuthService" src

我们也统一了终端界面的配色、排版和提示信息，并完善模型选择、索引进度与错误引导等细节，让界面更清晰、操作更直观。

例如，在交互式终端中首次搜索尚未建立索引的工作区时，zg 会引导用户选择本地或远程模型，展示索引构建进度，并在完成后继续查询。

此外，在已有的 Qwen Code、Claude Code、Codex、OpenCode 等集成基础上，新版本增加了对 GitHub Copilot、Grok Build、VS Code 和 Pi 的集成支持。通过 zg --install，即可为支持的客户端配置 zg 检索工具。

更可靠的日常使用

本次还修复了一批影响日常使用的问题，例如：

• 文件变更识别：修复文件删除后在同一路径重新创建时，旧删除事件可能覆盖新状态的问题。
• 搜索结果定位：修正部分结果预览中的行号偏差，让展示内容与源文件位置准确对应。
• 索引管理：避免后台刷新意外重新创建用户已删除的索引。
• 配置与平台兼容：完善 Agent 配置中注释和无关设置的保留，以及 Windows 路径与终端颜色处理。

欢迎前往 zg 项目仓库体验新版，也欢迎反馈问题与建议。