导读2026 年 8 月 27 日，zvec-grep（简称 zg）发布 v0.2.0 Public Preview，把 ripgrep、BM25、向量检索和 Agent 的 MCP 接入放进同一个本地优先检索层。它真正值得看的地方，不是又多了一个搜索工具，而是把 Agent 的本地检索重新拆成了几个不同阶段：不知道答案在哪里时先做语义发现，找到候选后按相关性收敛，已经知道关键词或符号时再用精确匹配验证。本文沿着这条链路解释它解决的是什么问题，也把当前仍处于 Preview 的边界说清楚。
本文 2280 字，阅读约 6 分钟｜Agent 的问题，不是不会搜索，而是不知道该怎么搜索 → zg 做的第一件事，是把搜索阶段放回正确的位置 → 对 Agent 来说，最有价值的不是“搜到更多”，而是更早拿到可用证据 → 本地优先，解决的是数据流向和部署摩擦 → 它现在能做什么，又还不能承诺什么 → Agent 的检索层，下一步比“换一个更强模型”更具体
Agent 的问题，不是不会搜索，而是不知道该怎么搜索
这里的 Agent，指能够调用搜索、读取文件等工具来完成任务的 AI 系统。我们已经习惯了用 rg（ripgrep，一款高速的本地文本搜索工具）查代码：输入函数名、配置项、错误信息或一段原文，它会快速返回匹配结果。这个过程很可靠，因为查询词和文件里的实际表述基本一致。它解决的是“我知道要找哪段文字”，不是“我还不知道实现会用什么词”。
但 Agent 接到的任务往往不是这样。用户可能会问：“主题偏好是在应用启动时怎么恢复的？”代码里却没有“恢复主题偏好”这几个字，真正的实现可能叫 hydratePreferences，也可能散落在启动流程、状态管理和配置读取几个文件里。
这时，单纯扩大关键词搜索范围通常不是好办法。搜得太窄，容易漏掉同义表达；搜得太宽，又会得到一堆没有排序的结果。Agent 只好不断猜关键词、打开文件、读上下文，再根据新线索发起下一轮搜索。
所以，问题不只是“搜索能力不够强”，而是不同搜索方式承担的任务没有被分开：探索阶段需要发现，收敛阶段需要排序，确认阶段需要精确验证。如果一上来就要求一种工具包办全部工作，Agent 很容易在错误的搜索模式里消耗上下文。
zg 做的第一件事，是把搜索阶段放回正确的位置
zg（zvec-grep）是一个面向人与 AI Agent 的本地优先工作区检索层。官方仓库把它的核心能力概括为：把 ripgrep、BM25 和向量检索放到同一个接口里，既能从终端使用，也能让 Agent 通过 MCP（Model Context Protocol，模型上下文协议）调用。
这里的关键不是把三种算法简单并排摆放，而是让它们对应不同的问题。
向量检索适合“我知道自己想找什么，但不知道文件会怎么说”。它会把查询和文本转换成向量，通过语义相似度发现表达不同但意思接近的内容。比如“启动时恢复主题偏好”，就有机会找到 hydratePreferences 这样的实现线索。这里的 Embedding（嵌入）就是把文字转换成向量的表示方式。
BM25 适合“查询里已经有一些重要词，但还需要相关性排序”。它仍然关注词项匹配，却不只是把所有命中的文件平铺出来，而是根据词频、稀有度和文档长度等因素给候选结果排序。
ripgrep 适合“我已经知道要验证什么”。当目标是一个确定的函数名、路径、正则表达式或错误信息时，精确匹配的价值恰恰在于穷尽和可复核。语义检索可以帮你发现方向，但不能替代最后的文本确认。
官方发布说明还提到，zg 可以把 BM25 和向量检索的结果通过 RRF（倒数排名融合）合并：同一个结果在不同检索路线中排名越靠前，综合排序通常越靠前。之后还可以用路径、文件类型、符号类型或修改时间等条件缩小范围。换句话说，它不是要求用户永远走“向量检索优先”的单一路线，而是允许 Agent 根据已知信息量切换搜索模式。
可以把这条关系压缩成三个阶段：
对 Agent 来说，最有价值的不是“搜到更多”，而是更早拿到可用证据
还是用“启动时如何恢复主题偏好”这个问题举例，真实的代码理解任务通常可以这样推进：
第一步，用户只提供现象或目标，Agent 还不知道实现在哪里。这时应该做语义发现，寻找可能相关的文件、模块和概念，先找到启动流程、偏好状态或 hydratePreferences 一类线索。
第二步，候选范围已经出现，但结果还比较散。此时需要用 BM25、向量检索的混合排序，以及路径、文件类型或符号等过滤条件，把真正参与启动恢复的文件排到前面。
第三步，Agent 已经知道要确认某个函数、配置项或调用关系。这时继续做模糊搜索反而会增加噪声，应该切换到 rg，确认 hydratePreferences 的定义、调用位置和相关配置。
这个过程的收益，不只是少执行几次命令。排序后的结果如果同时保留文件路径、来源位置和有限预览，Agent 就不必为了理解一个小问题把整份文件塞进上下文。检索工具真正影响的，是 Agent 如何获得证据，以及它需要为这些证据支付多少上下文成本。
这也是 zg 与普通“给代码加一个向量数据库”思路的差别：它试图把检索决策本身也纳入工具说明和 MCP 工作流，让 Agent 知道什么时候应该探索、什么时候应该收敛、什么时候应该停止搜索。MCP 在这里不是另一种检索算法，而是让 Agent 能调用这些检索能力的接口层。
产品信息与代码
官方仓库： https://github.com/zvec-ai/zvec-grep/
v0.2.0 发布说明： https://github.com/zvec-ai/zvec-grep/releases/tag/v0.2.0
本地优先，解决的是数据流向和部署摩擦
Agent 检索的对象通常是代码、内部文档、研究资料和个人笔记。这些内容未必适合上传到远程服务，所以 zg 把工作区扫描、索引存储、检索和本地 Embedding 推理设为默认的本地路径。
官方发布说明还明确提到，远程 Embedding 可以作为可选能力，但发送工作区内容或查询文本需要单独、显式的授权。这一点比“支持本地模型”更值得关注：它把数据是否离开设备变成一个可检查的边界，而不是隐藏在默认配置里。
这条边界可以概括为：默认路径留在本地，远程能力是经过授权才打开的分支。
同时，本地优先不等于没有成本。第一次建立索引需要扫描文件和计算 Embedding，索引也需要随着工作区变化而更新。它适合那些会反复询问同一个代码库或知识库的场景；如果只是一次性查一个确定的字符串，直接用 rg 可能更简单。
它现在能做什么，又还不能承诺什么
zg v0.2.0 已经覆盖代码、Markdown、纯文本、配置文件和部分结构化数据，也提供 CLI 与 MCP 接入，并支持 Codex、Claude Code、Qwen Code、OpenCode、Cursor 等 Agent 集成。对开发者来说，官方推荐的使用路径很直白：安装工具，为工作区建立索引，然后从终端查询或让 Agent 通过 MCP 复用同一份索引。
但它还不是一个可以脱离版本变化长期承诺的稳定基础设施。官方明确将 v0.2.0 标为 Public Preview，并提醒 CLI 与 MCP 合约、配置默认值、索引兼容性和安装行为可能继续变化。官方路线图也把图检索、更多文档格式、图片 OCR 和跨模态能力列为后续方向。
因此，比较准确的判断是：zg 已经把 Agent 本地检索中几个最容易混在一起的问题，整理成了一条可运行的工程链路；但它还需要更多真实工作流来验证检索质量、索引维护和不同 Agent 的稳定性。
Agent 的检索层，下一步比“换一个更强模型”更具体
很多 Agent 的失败，表面上像是模型不会推理，实际上可能只是没有拿到正确的上下文。模型再强，如果搜索阶段漏掉了关键文件，后面的答案也只能在不完整证据上继续推理。
从这个角度看，zg 的价值不在于宣布关键词搜索过时，也不在于证明向量检索可以替代 rg。它提供的是一种更符合真实任务的组合：不知道去哪找时，用语义能力发现；知道大致范围时，用排序能力收敛；知道要核对什么时，用精确匹配确认。
由于项目仍处于 Preview 阶段，不同代码库、不同语言和不同 Agent 之间的稳定性还需要更多公开验证。但对正在搭建本地 Agent 工作流的人来说，至少有一个判断可以先确定：检索不是模型调用前的一步准备工作，而是 Agent 获取证据、控制上下文和保持可复核性的基础设施。
参考资料
zvec-grep 官方仓库： https://github.com/zvec-ai/zvec-grep/
zvec-grep v0.2.0 Public Preview： https://github.com/zvec-ai/zvec-grep/releases/tag/v0.2.0
zvec-grep 官方路线图： https://github.com/zvec-ai/zvec-grep/blob/main/docs/08-roadmap.md
用户提供的微信公众号原始链接（《zg 正式开源：本地检索，不止于关键词》）： https://mp.weixin.qq.com/s/WFE5TmKetIagHIVujhKGFg
— THE END —
文章仅做学术分享，如有侵权请联系删除，非常感谢！