zg 正式开源：本地检索，不止于关键词

这是 2026 年的第 56 篇文章

（本文阅读时间：约 10 分钟）

背景：从关键词匹配到语义发现

rg凭借卓越的性能与穷尽式匹配能力，已成为开发者和 Agent 检索本地内容的基石。对于函数名、配置项或错误信息等明确目标，rg 能提供快速且可验证的结果。

然而，随着 Agent 任务转向代码理解、故障定位及知识分析等复杂场景，检索输入已从明确的符号转变为对业务意图的自然语言描述。这类查询往往与实际代码表述缺乏直接词汇对应（例如用户询问“访问权限流程”，而文档表述为“账号授权审批”）。仅依赖文本匹配易导致遗漏，而扩大搜索范围则会产生大量低相关性的噪声。

为定位信息，Agent 常需多轮构造查询、读取文件并拼凑上下文，这不仅增加了工具调用次数、响应时间和 Token 消耗，还可能导致基于不完整信息得出错误结论。

因此，本地检索需在保留 rg 精确匹配优势的基础上，进一步具备语义发现、相关性排序与上下文组织能力。这正是 zg 致力于解决的核心问题。

What is zg?

zg（zvec-grep）是一套面向人与 Agent 的本地优先检索基础设施。它对代码、文档等本地内容进行提取、组织与索引，通过 CLI 与 MCP 提供语义检索、BM25、混合检索及 rg 精确匹配能力，实现从关键词匹配到意图发现的跨越。

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

• 全流程检索：覆盖从模糊探索、相关性收敛到精确验证的完整过程，提供多种检索能力适配不同阶段，减少猜测与遗漏；
• 多文件格式支持：支持代码、文档及结构化数据，采用可扩展的内容提取机制，保留符号、层级与元数据，拓展检索边界；
• 上下文高效：融合多路检索结果并排序，提供带来源位置的预览，减少无关内容带来的阅读与 Token 消耗；
• 本地优先：文件扫描、索引与 Embedding 默认在设备内完成，远程传输需显式授权，确保数据隐私与流向可控。

Why zg?

zg 首个开源版本支持 macOS、Linux 与 Windows，提供向量检索、BM25 与 rg 能力，具备本地 Embedding、嵌入式索引与增量更新功能。以下从上手体验、内容覆盖、效率成本及数据隐私四个维度解析其优势。

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

zg 面向开发者提供CLI，面向 Agent 提供MCP。无需手动部署服务，zg install即可自动发现 Codex、Claude Code、Cursor 等 Agent 并完成配置。

从安装到检索仅需三步：

# 1. 安装 zg
npm install -g @zvec/zvec-grep
# 自动发现本机已安装的 Agent 并完成 MCP 配置
zg install

# 2. 为当前工作区建立本地索引
cd your-repository
# 默认使用轻量本地模型 local/potion-code-16m-v2
zg index

# 3. 开始检索
# 方式一：CLI 检索
zg query --human "theme preference persistence on startup"
# 方式二：在已连接的 Agent 中直接提问（Agent 通过 MCP 调用 zg）

同一份本地索引可由人与 Agent 共享，无需重复构建。

多种搜索、多类内容，一个入口

复杂检索往往需要多步探索。zg 提供语义检索、BM25、混合检索与 rg，允许 Agent 根据线索灵活选择检索策略，从模糊意图逐步收敛至精确目标。

zg 不仅限于代码检索，针对不同内容采用差异化提取策略：

支持通过路径、Glob 及忽略规则限定范围，确保在扩大内容覆盖的同时不增加结果噪声。

少走弯路，更省 Token 与时间

zg 优化了完整检索链路以降低 Agent 的任务成本：

• 检索决策优化：引导 Agent 根据问题特征选择合适工具，避免无效试探；
• 召回与排序优化：联合 BM25 与向量检索，利用 RRF 融合去重，提升相关结果排名；
• 内容组织优化：按符号或章节提取独立信息单元，保留路径位置，降低拼接上下文成本；
• 上下文输出优化：默认返回紧凑结果与预览，按需加载全文，避免无关文本占用 Context。

在SWE-QA-Bench（代码仓库问答）和BrowseComp-Plus（深度研究问答）的评测中，zg 表现优异：

• SWE-QA-Bench：工具调用减少超 50%，输入 Token 减少近 50%，评审得分提升 1.50 分；
• BrowseComp-Plus：准确率提升至 99.00%，输入 Token 减少 37.56%，工具调用减少 43.52%，耗时减少 38.58%。

评测说明：实验保持 Agent、模型、Prompt 及环境一致。Baseline 使用标准工具，zg 方案增加预建索引与 MCP 指引。索引一次性开销经复用后成本可忽略，故未计入表中。

本地优先，数据流向由你决定

针对敏感代码与内部文档，zg 默认全链路本地化处理：文件扫描、提取、Embedding、索引与检索均在设备内完成，无需上传内容。

• 本地 Embedding：内置 11 种端侧模型。默认的local/potion-code-16m-v2为 16M 级静态模型，缓存仅 32 MiB，无需 GPU。在 Django 仓库（3457 文件）测试中，M4 Pro 设备完整索引耗时不超过半分钟，效果接近云端大模型且无远程调用成本；
• 端侧存储与检索：Zvec 以嵌入式方式存储向量与 BM25 索引，无需独立数据库服务，CLI 与 MCP 复用同一本地索引。

若本地模型无法满足需求，用户可显式授权启用远程 Embedding，兼顾能力扩展与隐私安全。

现状与规划

zg 已覆盖本地检索核心链路，并持续向更完整的检索基础设施演进。下表对比了 zg 与其他工具的能力边界：

注：✅/❌表示是否支持，❌*表示规划中。定级考察属性过滤、模型覆盖、格式识别粒度及结构化能力。

未来 zg 将重点推进四个方向：

• 增强检索能力：引入图检索与结构化信号，完善查询规划、重排与解释能力；
• 拓展内容边界：支持 PDF、Office 文档，完善 OCR 与跨模态理解；
• 提高上下文效率：优化去重与预览机制，提升有效信息密度；
• 增强本地能力：优化资源占用，探索 iOS、Android 等移动端适配。

同时，安装、升级、并发访问及诊断等基础工程体验也将持续打磨。

加入我们

zg 基于 Apache 2.0 协议开源。项目处于起步阶段，期待您在以下方面的反馈与贡献：

• 真实场景：分享在大型代码库或 Agent 工作流中的应用效果；
• 检索评测：共同完善 Benchmark 以评估搜索质量与效率；
• 代码与文档：贡献新格式提取、模型支持、集成方案及教程；
• 产品方向：反馈最难检索的任务及最需要的功能。

项目地址：github.com/zvec-ai/zvec-grep

参考资料

欢迎留言一起参与讨论