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

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

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

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

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

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

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

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

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

基于上述设计目标，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 直接使用，无需重复构建和配置。

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

复杂检索往往不是一次搜索就能完成。Agent 从任务描述出发，在探索过程中逐步获得相关方向、关键词和明确目标；zg 提供语义检索、BM25、混合检索与 rg，让不同阶段都能采用适合的检索能力。

这并非一条必须依次执行的固定流程。Agent 可以根据已有线索直接进入相应阶段，也可以在信息不足时继续探索；用户在 CLI 中同样可以按需选择这些能力，从模糊意图出发，逐步发现并准确定位所需内容。

zg 的检索对象也不局限于代码。针对不同内容，zg 会采用相应的提取与组织方式：

代码仓库、项目文档、研究资料与本地知识库都可以成为检索对象；路径、Glob、文件类型和忽略规则可以进一步限定检索范围，让内容覆盖的扩大不以增加结果噪声为代价。

少走弯路，更省 Token 与时间

zg 关注的不只是单次查询速度，更是 Agent 完成整个任务所需的搜索轮次、Token 与时间。为减少反复尝试关键词、读取无关文件和拼接上下文产生的消耗，zg 对完整检索链路进行了针对性优化：

• 检索决策优化：通过 MCP 工具描述与使用指引，帮助 Agent 根据问题中是否存在明确关键词、位置或符号，选择适合的检索方式，并在信息充分时停止搜索，减少无效试探；
• 召回与排序优化：联合 BM25 与向量检索生成候选结果，通过 RRF（Reciprocal Rank Fusion）完成多路结果融合、去重与统一排序，让相关内容更早出现，减少无关文件读取；
• 内容组织优化：按代码符号、文档章节等结构提取可独立定位的信息单元，并保留文件路径与来源位置，减少 Agent 从完整文件中手工拼接上下文的成本；
• 上下文输出优化：默认返回经过排序的紧凑结果与有限预览，需要时再读取完整内容，避免大量无关文本直接进入 Agent 上下文。

这些优化最终需要在完整任务中体现价值，而不只是让单次查询看起来更快。为此，我们在代码仓库问答 SWE-QA-Bench 和深度研究问答 BrowseComp-Plus 上进行了配对 A/B 评测。其中，SWE-QA-Bench 包含 20 个真实代码仓库问答任务，要求 Agent 跨文件定位实现并完成多步推理；BrowseComp-Plus 包含 80 个深度研究问题，要求 Agent 从大规模固定语料中检索并整合多文档证据。

评测说明：每组实验均保持 Agent、模型、Prompt、运行环境与任务限制一致。Baseline 使用 Agent 的标准工具，zg 方案仅增加预建索引、MCP 工具与使用指引。预建索引会产生一次性时间与计算开销，远程 Embedding 还会带来 Token 与调用费用；但索引可跨查询和 Agent 任务复用，后续仅需增量处理变化内容，成本经持续摊薄后通常可以忽略，因此未计入上表。

在 SWE-QA-Bench 中，zg 在将工具调用减少超过一半、输入 Token 减少近一半的同时，评审得分提升了 1.50 分；在 BrowseComp-Plus 中，准确率由 98.67% 提升至 99.00%，输入 Token 减少 37.56%、工具调用减少 43.52%、Agent 耗时减少 38.58%。两项结果表明，zg 能够在代码与非代码场景中减少无效搜索和上下文消耗，同时保持任务质量。完整评测协议、指标定义与复现方式参见性能测试文档。

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

代码、内部文档等本地内容往往包含未公开或敏感信息，检索过程中的数据流向至关重要。因此，zg 将本地处理设为默认：文件扫描、内容提取、本地 Embedding、索引与检索均在设备内完成，完整流程无需上传内容或依赖外部服务。

这套本地路径由端侧模型与嵌入式索引实现：

• 本地 Embedding：内置十一种端侧模型，覆盖代码、文档、多语言、长输入与轻量运行等不同需求。默认的 local/potion-code-16m-v2 是 16M 级静态模型，本地缓存约 32 MiB，无需 GPU 即可运行；在 SWE-QA-Bench 上，它在取得接近 qwen/qwen3.7-text-embedding 的任务效果的同时，大幅缩短 Embedding 耗时并免去远程调用成本，以 Django 仓库（3,457 个文件）为例，在 Apple M4 Pro 上完整索引耗时不超过半分钟；
  

• 端侧存储与检索：Zvec 以嵌入式方式将向量与 BM25 索引存储在设备内，无需部署和维护独立数据库服务。CLI 与 MCP 可以复用同一份本地索引，让人与 Agent 的核心检索流程无需依赖外部存储服务。

在默认本地路径之外，zg 也保留了模型选择的灵活性。当本地模型无法满足检索质量、多语言覆盖或设备资源条件时，用户可以按需使用远程 Embedding。远程能力不会自动启用，相关文本或查询只有在显式授权后才会离开设备，从而兼顾能力扩展与数据隐私。

目前，zg 已覆盖本地检索的核心链路，并在此基础上向更完整的检索基础设施演进。下表对比了不同工具的产品侧重与能力边界，同时标明 zg 的现有能力与后续方向。

✅ / ❌ 表示当前是否支持，❌* 表示 zg 已规划但尚未支持；High / Medium / Poor 表示能力深度。定级分别考察属性过滤的可用维度、Embedding 的模型覆盖与配置能力，以及代码和文本的格式覆盖、识别粒度、结构化切分与元数据保留。

面向更完整的检索基础设施，zg 将重点推进四个方向：

• 增强检索能力：在 BM25、向量检索与 rg 之外，引入图检索和更多结构化信号，完善查询规划、结果融合、重排与解释能力，更好地覆盖从模糊探索到精确验证的完整过程；
  
• 拓展内容边界：逐步支持 PDF、Word、PowerPoint，并完善图片 OCR、版面结构提取与跨模态理解，让更多本地信息能够被提取、组织和检索；
• 提高上下文效率：持续优化结果去重、组织、预览与上下文选择，提高有效信息密度，让 Agent 用更少的搜索轮次和 Token 获得任务所需的信息；
• 增强本地能力：持续优化本地模型、索引效率与资源占用，在完善 macOS、Windows 和 Linux 体验的同时，探索适配 iOS、Android 及更多资源受限的本地运行环境。

与此同时，安装、升级、卸载、增量索引、并发访问、服务自恢复、运行诊断与索引兼容等基础工程也会持续打磨，为上述能力提供顺畅、一致的使用体验。

zg 基于 Apache 2.0 协议开源。项目仍在起步阶段，我们尤其期待这些反馈与贡献：

• 真实场景：分享 zg 在大型代码库、知识库或 Agent 工作流中的效果与问题；
  
• 检索评测：共同完善搜索质量、性能与 Agent 上下文效率的可复现 Benchmark；
• 代码与文档：贡献新格式提取、模型支持、Agent 集成、缺陷修复与教程；
• 产品方向：告诉我们哪些检索任务最难、哪些结果最有用，以及哪些默认行为仍不够自然。