zvec-grep：给人和 agent 共用的本地代码搜索层
现在让 AI coding agent 读一个大仓库，常见问题不是它不会搜，而是它会搜得太散：先全局 grep，再打开一堆文件，再因为上下文不够重新扫一遍。人自己查代码也类似，知道函数名时 rg 很快，知道语义但不知道关键词时就要靠猜。最尴尬的是，人和 agent 往往各用一套入口，索引、权限和证据格式都不统一。
今天看的是 zvec-ai/zvec-grep。它的命令叫 zg，定位是 local-first workspace search layer，把 ripgrep、BM25 full-text search 和 vector search 放在一个 CLI / MCP 接口后面。README 的核心想法很直接：同一个工作区先索引一次，然后人可以在终端里查，agent 也可以通过 MCP 使用同一份本地索引和同一套搜索规则。
按 GitHub repository API、README、package.json、latest release、tags 和 commits API 在 2026-08-30 18:04 Asia/Shanghai 能核验的信息，zvec-ai/zvec-grep 当前有 23 stars、4 forks。主要语言是 TypeScript，许可证是 Apache-2.0，默认分支是 main，仓库创建于 2026-07-10 02:58:07 UTC，latest push 是 2026-08-28 08:42:13 UTC。最近提交是 8551a93，提交时间 2026-08-28 05:39:40 UTC，主题是更新 BrowseComp benchmark 结果。最新 GitHub Release 是 v0.2.0，发布时间 2026-08-27 16:15:11 UTC；package.json 里的 npm 包名是 @zvec/zvec-grep，版本也是 0.2.0，运行要求是 Node.js 22+。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | zvec-ai/zvec-grep |
| 定位 | 本地优先的混合工作区搜索层，面向 CLI 用户和 AI agent |
| Stars | 23 |
| Forks | 4 |
| 主要语言 | TypeScript |
| 许可证 | Apache-2.0 |
| 创建时间 | 2026-07-10 02:58:07 UTC |
| Latest push | 2026-08-28 08:42:13 UTC |
| 最近提交 | 8551a93，2026-08-28 05:39:40 UTC |
| 最新 Release | v0.2.0，2026-08-27 16:15:11 UTC |
| 关键词 | ripgrep、BM25、vector search、MCP、local-first、agent search |
它解决的是搜索入口分裂
zvec-grep 不想替代 ripgrep，而是把精确搜索和语义发现放在同一个工具里。你知道标识符、路径或正则时，可以走 managed ripgrep；你只知道“主题偏好在哪里恢复”这类意图时，可以让 indexed search 用 BM25 和 vector retrieval 混合排序，再返回带源位置的短证据。
这个设计对人有用，对 agent 更有用。人类通常会在 rg、IDE search、文档搜索之间切换；agent 则更容易在“不知道入口文件”的情况下反复扩大搜索半径。zvec-grep 的价值在于先承认两类查询都存在：精确文本应该用确定性的工具查，语义探索则应该用索引缩小候选范围。把两者统一起来，比给 agent 再塞一个单独的向量库更务实。
README 里提到的结果形态也值得注意。默认输出刻意保持紧凑，包含排序、文件分组、源位置和有限 preview；--human 则给终端用户更多可读内容。这种“同一检索层，不同展示密度”的取向，比直接把大段文件塞进模型上下文要干净。
MCP 集成是主线，不是附属 demo
很多搜索工具可以被 agent 调用，但 zvec-grep 把 agent 集成放在相当靠前的位置。v0.2.0 release 说明列出 Codex、Claude Code、Qwen Code、OpenCode 和 Cursor 的 managed MCP integrations。README 里的 zg install 会检测并配置支持的 agent，也可以显式指定 --target codex 或 --target qwen。
这里有一个细节很实际：安装器不只是暴露 MCP tool，还会写入 retrieval guidance，帮助 agent 判断什么时候用语义搜索、什么时候用精确查找、什么时候两者结合，以及什么时候证据已经足够。对 agent 来说，工具可用只是第一步；能不能少扫、少读、少把无关内容塞进上下文，更多取决于工具的使用策略。
它的本地 server mode 也服务于这个方向。zg server on 可以让共享本地服务协调 workspace runtime、后台刷新、MCP access 和已加载的 embedding model。CLI 操作则可以在 auto、server、direct 模式之间选择；managed ripgrep 不需要索引或 embedding model。这保留了一个很重要的降级路径：即使语义索引还没准备好，精确搜索仍然可用。
本地优先的边界比较清楚
zvec-grep 的 README 多次强调 local-first。workspace scanning、index storage、retrieval、本地 embedding inference 默认都在本机；共享服务监听 loopback；索引保存在 <workspace>/.zvec-grep/。远程 Qwen text / multimodal embedding 也支持，但把工作区内容或查询文本发给远程 provider 需要额外明确授权。
这对代码搜索类工具不是装饰性卖点。一个工作区里可能有客户代码、配置、实验笔记、内部文档和临时凭据痕迹。把索引和模型调用默认留在本机，至少让团队能先在敏感仓库里做受控试验，而不是一开始就卡在数据外发审批。
它还支持搜索不只是源码：Markdown、JSON、YAML、TOML、CSV、HTML、XML、plain text，以及多种语言的 structure-aware extraction。对 agent 来说，这很重要，因为实际问题经常横跨代码、配置、README、ADR 和测试 fixture。只索引 .ts 或 .py 文件，通常会漏掉真正解释设计意图的材料。
benchmark 部分可以看，但别过度解读
仓库里有 SWE-QA-Bench 和 BrowseComp-Plus 两组 paired A/B benchmark，release note 也把 answer quality、input tokens、tool calls、agent execution time 和 traces 作为比较维度。README 给出的三个 repo case study 是 Pylint、Matplotlib、Django，强调语义发现缩小搜索空间、lexical retrieval 锚定精确标识符、短证据减少 broad scan。
这些 benchmark 对判断项目方向有帮助：作者不是只做一个漂亮 CLI，而是在验证“更好的检索层能不能减少 agent 的上下文浪费”。但它仍然是 preview 阶段的项目，benchmark 结果应该看方法和可复现性，不要当成通用承诺。不同模型、不同仓库结构、不同问题类型都会改变收益。
适合谁
第一类是经常维护中大型代码库的开发者。你已经熟悉 rg，但常遇到“我知道大概发生了什么，却不知道关键词”的搜索。zg query --human 这种入口可以作为语义发现层，再回到精确文件和行号做确认。
第二类是正在给 AI coding agent 补工具链的人。与其让 agent 在仓库里漫无边界地 grep，不如给它一个能返回短证据、能选择 exact / semantic route、能复用索引的 MCP 工具。尤其是当问题跨多个文件、模块或文档时，这类检索层更容易体现价值。
第三类是对数据外发敏感的小团队。Node.js 22+、npm 全局安装、本地索引、本地模型 catalog、显式远程授权，这些约束让它适合先在单机或小团队内试验，而不是马上引入一整套托管搜索平台。
Caveats
第一，它很新。仓库 2026-07-10 才创建，stars 只有 23，latest release v0.2.0 也明确是 public preview。CLI、MCP contract、配置默认值、索引兼容性和安装行为都可能继续变化。
第二，它对运行环境有要求。package.json 和 README 都写明需要 Node.js 22 或更新版本；如果团队机器或 CI 镜像还停在旧 Node LTS，要先处理基础环境。
第三，语义检索不是银弹。它适合入口不明、证据分散、需要跨文件理解的问题；如果只是查一个函数名或固定字符串，managed ripgrep 才是更确定的路径。真正用好它，要让人和 agent 都养成先看证据、再打开文件的习惯。
总结
zvec-ai/zvec-grep 有意思的地方，是它没有把“给 agent 搜代码”做成另一个封闭向量索引，而是把 rg、BM25、vector search、MCP guidance 和本地 server 放进一个连续的工作流。人可以用，agent 也可以用；精确查找可以用，语义探索也可以用；默认本地，必要时才显式走远程 embedding。
它还处在 preview 阶段，不适合在关键流程里无脑铺开。但如果你的痛点是 agent 读仓库太散、上下文浪费太多，或者人类搜索经常卡在“知道意思但不知道关键词”，zvec-grep 是一个值得试的小工具。