zvec-grep（终端命令名 zg）是一个开源的本地搜索工具，它把三种检索方式——关键词全文搜索、相关性排序、语义搜索——合并到同一个命令行程序里，让开发者和 AI 编程助手用同一套索引快速查找工作区里的代码与文档。它解决的问题很具体：你在一堆文件里找某个函数、一条报错信息或一段说明时，不用再记多个工具的用法，也不会因为记不清准确拼写而搜不到。所有索引和搜索结果都保存在本机，不上传任何数据。它适合日常写代码的开发者，也适合配置了 AI 编码助手的个人和团队。

三种检索方式：关键词、排序与语义

先解释工具合并的三种技术，都是搜索领域的老方法：

  • ripgrep：以速度出名的文本搜索命令行工具，用正则表达式（一种描述「文本模式」的语法，例如匹配所有以 get 开头的函数名）在文件里逐行查找。VS Code 等编辑器的内置搜索底层用的就是它。
  • BM25：经典的关键词排序算法。它不只看文件里有没有某个词，还根据词出现次数、文档长度等因素给匹配结果打分排序，是搜索引擎早期的核心组件。
  • 向量搜索（语义搜索）：把文本转换成一串数字（向量），含义相近的文字，数字也相近。这样搜「如何找出所有未使用的变量」时，能匹配到用词不同但意思相同的代码段，而不只是字面相同的句子。

zvec-grep 把三者统一成一个入口：先用语义搜索缩小候选范围，再用精确关键词和正则校验结果，最后按相关性排序输出带文件位置的证据。向量检索能力由开源向量数据库 zvec 提供。

人和 AI 用同一个搜索层

这个工具的特点是「装一次、索引一次，人和 AI 都能用」。

  • 人用：在终端运行 zg query --human 直接提问，结果按相关度排序，附文件路径和行号。
  • AI 用：项目提供 MCP（Model Context Protocol，一种让 AI 编程工具调用外部能力的开放协议）接入方式，官方支持 Codex、Claude Code、Qwen Code、Qoder、Cursor、OpenCode 六款编程助手。以 OpenCode 为例，运行 zg install --target opencode 后，AI 回答问题时可以自己调用 zg 搜索本地文件，并给出具体出处。

接入的收益是减少 AI 的无效扫描：官方基准测试（SWE-QA-Bench、BrowseComp-Plus）显示，接入 zg 后 AI 完成任务所需的工具调用次数和上下文消耗（一次对话能参考的内容量）更低，因为搜索结果已按相关度排好、可直接引用。

本地优先：数据默认不出本机

索引存放在被搜索项目的 .zvec-grep/ 目录下；把文本转成向量的嵌入模型（embedding model，负责把文字变成数字向量的模型）默认使用本地小模型 potion-retrieval-32m（约 3200 万参数，普通电脑即可运行）。只有用户明确授权，工具才会调用远程向量化服务。文件、索引、模型都在本机，这是「本地优先」的含义，也是它对隐私敏感用户的价值。

项目现状

zvec-grep 由 zvec-ai 团队维护，仓库当前约 3300 个 star、188 个 fork、243 次提交，采用 Apache-2.0 开源许可，曾登上 trendshift（开源项目趋势榜）。项目用真实仓库做过验证：在 Pylint、Matplotlib、Django 三个大型开源项目上回答架构类问题，检索结果能帮助 AI 快速定位跨文件的调用链与数据流。仓库带中文版 README（README_CN.md），社区群覆盖钉钉、微信、Discord 和 X。

安装与首次使用

需要 Node.js 22 或更高版本，支持 macOS、Linux、Windows 三个平台：

npm install -g @zvec/zvec-grep
zg index --embedding local/potion-retrieval-32m
zg query --human 你想找什么

第一条命令安装工具，第二条在工作区建立索引，第三条开始搜索。

结论

zvec-grep 是一个开源的本地命令行工具：把关键词搜索、排序检索和语义搜索统一成一个命令，人和 AI 编程助手共用同一套索引，数据全程留在本机。经常在大型代码库里找不到东西、或想让 AI 助手少做无效扫描的开发者，可以直接上手试用。