zg 正式开源:本地检索,不止于关键词


摘要:人与 Agent 所需的信息,往往散落在大量本地文件中,准确、高效地定位这些信息并不容易。zg(zvec-grep) 是面向人与 Agent 的本地优先检索基础设施,基于 Zvec 提供的向量检索与 BM25 能力,并结合 ripgrep(rg),从代码、文档等本地内容中提取并组织信息,减少搜索轮次与上下文消耗,帮助人与 Agent 高效地发现和定位所需内容。zg 现已开源,欢迎体验,也期待你的反馈与贡献!

01
背景

rg 凭借出色的性能与穷尽式匹配能力,已成为开发者和 Agent 检索本地内容的重要基础工具。对于函数名、配置名、错误信息或文档原文等明确目标,rg 能够提供快速、准确且可验证的结果。

随着 Agent 开始处理代码理解、故障定位、知识问答和资料分析等复杂任务,检索输入逐渐从明确的符号或文本,转变为对业务现象、实现意图和知识概念的自然语言描述。

这类查询与代码或文档中的实际表述往往缺乏直接的词汇对应。例如,“恢复主题偏好”的实现可能被定义为 hydratePreferences,而用户询问的“访问权限申请流程”,在文档中可能被表述为“账号授权与审批”。在缺少准确关键词时,仅依赖文本匹配容易遗漏相关内容;扩大搜索范围,又会产生大量缺少相关性排序的结果。

为定位所需信息,Agent 往往需要多轮构造查询、执行搜索并读取文件,再从分散的文本匹配中整理相关上下文。这不仅增加了工具调用、响应时间与上下文消耗,也可能导致 Agent 基于不完整的信息得出结论。

因此,本地内容检索需要在保留 rg 精确、快速和穷尽能力的基础上,进一步具备语义发现、相关性排序与上下文组织能力。这正是 zg 希望解决的问题。

02
What is zg?

为解决上述问题,我们开源了 zg(zvec-grep):一套面向人与 Agent 的本地优先检索基础设施。zg 对代码、文档等本地内容进行提取、组织与索引,并通过 CLI 与 MCP 提供语义检索、BM25、混合检索和 rg 精确匹配能力,让本地检索从关键词匹配延伸至意图发现、相关结果排序与精确验证。

zg 的核心设计目标是 让分散在本地文件中的信息能够被高效发现和准确定位,设计宗旨包括:

  • 全流程检索:面向从模糊探索、相关性收敛到精确验证的完整过程,提供语义检索、BM25、混合检索与 rg 等不同能力;让每个阶段都能采用适合的检索方式,减少关键词猜测、重复搜索与结果遗漏;
  • 多文件格式支持:面向代码、文档与结构化数据等多类文件格式,采用可扩展的内容提取机制,并尽可能保留符号、标题、层级与元数据;让更多本地文件转化为结构清晰、可准确定位的检索内容,持续拓展 zg 可检索的信息边界;
  • 上下文高效:对多路检索结果进行融合、排序并按需提供预览,同时保留来源与位置;让人与 Agent 更快获得任务所需的信息,减少无关内容带来的阅读、工具调用与 Token 消耗;
  • 本地优先:文件扫描、索引与本地 Embedding 默认在设备内完成,远程内容传输必须经过显式授权;在保障隐私的同时,让用户始终掌握数据流向。
03
Why zg?

基于上述设计目标,zg 的首个开源版本从代码与文本内容入手,提供向量检索、BM25 与 rg,支持通过 CLI 和 MCP 在 macOS、Linux 与 Windows 上使用,并具备本地 Embedding、嵌入式索引与增量更新能力。下面将从上手体验、检索与内容覆盖、检索效率与成本,以及本地运行与数据隐私四个方面展开。

三步上手,人与 Agent 即刻可用

zg 支持 macOS、Linux 和 Windows,面向开发者提供 CLI,面向 Agent 提供 MCP。无需手工部署服务或编写集成配置,zg install 即可自动发现 Codex、Claude Code、Cursor 和 OpenCode,完成 MCP 配置。

从安装到开始检索只需三步:

# 1. 安装 zgnpm install -g @zvec/zvec-grep# 自动发现本机已安装的 Agent,并完成 MCP 配置;# 也可以指定目标,例如:zg install --target codex --yeszg install# 2. 为当前工作区建立本地索引cd your-repository# 默认使用轻量本地模型 local/potion-code-16m-v2zg index# 3. 通过 CLI 或 Agent 开始检索# 方式一:在终端中通过 CLI 检索zg query --human "theme preference persistence on startup"# 方式二:在已连接的 Agent 中直接提问,Agent 会按需通过 MCP 调用 zg# 示例提示词:Find how theme preferences are restored on startup.

同一份本地索引也可由已连接的 Agent 通过 MCP 直接使用,无需重复构建和配置。

多种搜索、多类内容,…

— 以上为试看内容(约 40%),开通会员后阅读全文 —