zvec-grep：为人类和 AI 智能体统一本地搜索

zvec-grep 与同类工具的性能对比（来源：zvec-ai/zvec-grep）

zvec-grep（命令行别名 zg）是一个本地优先的搜索工具，目标是把 ripgrep（精确文本匹配）、BM25（关键词排序）和向量搜索（语义检索）统一到一个接口下，同时支持人类在终端直接使用和 AI 智能体调用。

它解决什么问题

代码库搜索目前有两种常见模式：用 grep / ripgrep 做精确匹配，速度快但要求你知道确切关键词；用向量检索，可以用自然语言查意思相近的内容，但需要单独部署 embedding 服务和检索引擎。zvec-grep 将两者合并：索引一次，之后可以在同一个命令里混合使用精确匹配和语义检索，结果按相关性排序，并附带文件路径和行号。

设计思路

项目主打「本地优先」：文件、索引和本地 embedding 模型全部留在本机；只有在用户明确同意的情况下，才会向远程 embedding API 发送数据。索引支持源码、文档和结构化数据，保留文件结构信息和来源位置，搜索结果减少了 AI 工具调用所需的 token 数量和噪声。

对 AI 智能体的支持是设计目标之一：项目提供 OpenCode 集成示例，安装后智能体会自动选择 zg 作为搜索工具，无需在 prompt 中指定工具名称。官方演示中，智能体查询「侦探从未见过的生物留下的痕迹推断了什么」，zg 定位到《福尔摩斯回忆录》的相关段落，智能体随后给出了有原文行号引用的完整回答。

安装方式

npm install -g @zvec/zvec-grep
zg index --embedding local/potion-retrieval-32m

索引命令指定本地 embedding 模型；也支持 OpenAI、Cohere 等远程模型。项目支持 macOS、Linux 和 Windows，要求 Node.js 22 或更新版本。

背景

将关键词搜索与向量搜索结合（通常称为「混合检索」）在 RAG 系统设计中是成熟思路，不少商业向量数据库已内置支持。zvec-grep 做的是把类似能力带到本地文件系统和开发者日常工作流，而不是部署成数据库服务。对维护大型本地代码库或文档集合的开发者，以及需要让 AI 智能体在本地环境搜索的场景，是一个值得关注的工具。项目目前处于早期开源阶段，GitHub 地址：github.com/zvec-ai/zvec-grep。