zg：本地优先的统一代码与文档检索工具

2026-09-08 12:32 0 阅读

zg 是什么

zg（全称 zvec-grep）是一个开源的命令行工具，目标很明确：让开发者和 AI Agent 能用自然语言在本地代码库或文档中找东西。它不是简单的关键词搜索，而是把三种检索方式——语义向量、BM25 词频排序和 ripgrep 精确匹配——串成一条完整的链路。

你问“怎么恢复用户的主题偏好？”，它不会只返回包含“恢复”“主题”“偏好”字眼的行，而是理解你的意图，找到实际实现该逻辑的函数，比如 hydratePreferences。整个过程默认完全在你的电脑上跑：扫描文件、生成 Embedding、建索引、查结果，都不需要上传数据，也不依赖 GPU 或远程 API。

背后是 Zvec AI 团队做的，核心思路是“本地优先 + Agent 原生”。工具内置了 11 种轻量级 Embedding 模型，最小的只有 16M 参数，普通笔记本也能跑。索引存在本地，基于 Zvec 自研的进程内数据库，不用额外部署 Redis 或 PostgreSQL 这类服务。

核心功能拆解

zg 的能力可以分成几个层次，从模糊到精确，覆盖了实际开发中常见的搜索场景。

语义检索：用意图找代码

这是最接近“AI 搜索”的部分。你输入一句自然语言问题，比如“用户登录后怎么跳转到首页？”，zg 会把它转换成向量，和代码/文档片段的向量做相似度计算。即使代码里没出现“跳转”“首页”这些词，只要逻辑相关，就可能被召回。

它能处理 Markdown、JSON、YAML、各种编程语言，还会自动解析结构。比如在 TypeScript 文件里，它知道哪些是函数定义、哪些是类方法；在 Markdown 里，能识别标题层级。这样返回的结果不仅相关，还能精确到“第几行”“哪个函数”“哪一节”。

BM25：传统但有效的词频排序

光靠语义有时不够稳。比如你搜“API key 配置”，语义模型可能联想到“认证”“密钥管理”，但你其实只想找配置文件里写死的那行 api_key = "xxx"。这时候 BM25 就派上用场了。

BM25 是一种经典的文本相关性算法，基于词频和逆文档频率加权。它不理解语义，但对关键词匹配非常敏感。zg 把 BM25 作为一路独立召回源，和语义结果并行处理。

混合检索与 RRF 融合

zg 不是简单拼接两种结果，而是用 RRF（Reciprocal Rank Fusion）算法把它们融合。RRF 的基本思想是：如果一个结果在语义和 BM25 两路都排得靠前，那它最终得分就更高。同时自动去重，避免同一个文件片段出现两次。

这种多路召回+融合的策略，比单一方法更鲁棒。实测中，混合检索在模糊查询和精确查询之间取得了不错的平衡。

ripgrep 精确验证

最后一步是精确匹配。当你已经通过语义或 BM25 锁定几个候选文件，zg 会调用 ripgrep 对这些文件做穷尽式搜索，确认具体符号是否存在。比如你怀疑某个函数叫 initAuth，就用正则或字面量快速验证。

这一步保证了结果的可验证性——不是“可能相关”，而是“确实存在”。

本地端侧 Embedding 与增量索引

所有 Embedding 默认在本地生成。工具内置了多种模型，包括专为代码优化的版本。首次运行 zg index 时会为整个目录建索引，之后只处理新增或修改的文件，速度很快。

索引文件保存在项目目录下的 .zg 文件夹里，CLI 和多个 AI Agent 可以共享同一份索引，不用重复构建。

怎么用

安装很简单：

npm install -g @zvec/zvec-grep

然后进到你的项目目录，建索引：

zg index

建完就能搜了：

zg query --human "怎么处理跨域请求？"

结果会按相关性排序，每条都带文件路径、行号，甚至函数名或章节标题。

如果你装了支持 MCP（Model Context Protocol）的 AI 编辑器，比如 Cursor、Codex 或 Claude Code，还可以一键集成：

zg install

这个命令会自动检测本机已安装的 Agent，并配置好 MCP 连接。之后你在编辑器里直接问问题，Agent 就会通过 zg 在本地检索，不用自己翻文件。

为什么不是直接用 ripgrep？

ripgrep（rg）是目前最快的递归文本搜索工具，但它有个硬伤：必须知道准确的关键词或正则表达式。如果你不清楚代码里具体怎么命名的，rg 就帮不上忙。

举个例子：你想找“用户登出逻辑”，但代码里可能叫 logoutUser、signOut、clearSession，甚至藏在 auth.reset() 里。用 rg 得猜好几个词，效率很低。

Loomy

zg 的优势在于先用语义缩小范围，再用 BM25 和 rg 精确定位。它解决的是“词汇鸿沟”问题——自然语言描述和代码实际命名之间的不一致。

另外，rg 没有相关性排序，结果按文件遍历顺序输出。而 zg 会打分排序，最相关的放前面。对大型项目来说，这点体验差异很大。

Agent 集成的实际价值

AI 编程助手现在很火，但它们有个通病：每次查代码都得读一堆文件，消耗大量 Token，还可能漏掉关键信息。zg 给 Agent 提供了一个高效的“记忆外挂”。

通过 MCP 协议，Agent 可以把自然语言问题直接发给 zg，拿到结构化、已排序的结果，而不是原始文件内容。Zvec AI 官方测试显示，这种方式能减少 40% 以上的工具调用次数和上下文 Token 消耗。

更重要的是隐私。很多公司不允许代码上传到云端模型。zg 全本地运行，Embedding 不出设备，索引也存在本地，符合企业安全要求。

适用场景

探索陌生代码库：接手一个新项目，不知道从哪看起。问“支付流程怎么走的？”，zg 返回相关函数和调用链。
故障排查：用户反馈“改完设置没生效”，用自然语言搜“设置保存后怎么应用？”，快速定位到状态同步逻辑。
跨文件理解：一个功能涉及前端、后端、配置文件，zg 能一次性找出所有相关片段，不用手动切换目录。
本地知识库问答：把技术文档、会议记录、设计稿说明建索引，以后直接问“上次讨论的缓存策略是什么？”，秒回原文位置。

局限与注意事项

zg 不是万能的。语义检索依赖 Embedding 模型质量，对非常冷门或领域特定的术语可能不准。另外，首次建索引会花点时间，尤其是大项目。不过后续增量更新很快。

它目前主要支持文本类文件，二进制文件（如图片、编译后的产物）会被跳过。多语言支持不错，但某些小众语言的结构解析可能不完整。

最后，虽然叫“统一检索”，但它本质上还是面向开发者的工具。普通用户可能觉得 CLI 门槛高，不过随着 MCP 集成普及，未来在编辑器里用起来会越来越简单。

开源与社区

zg 已在 GitHub 开源，地址是 https://github.com/zvec-ai/zvec-grep。项目采用 MIT 许可证，欢迎贡献代码或反馈问题。团队也在维护一个 Discord 社区，方便用户交流使用经验。

总的来说，zg 填补了一个空白：在本地环境中，把现代语义搜索的能力带给开发者和 AI Agent，同时守住隐私和效率的底线。如果你经常在代码里“大海捞针”，值得一试。