在 Zvec-Grep 问世之前，我就已经 Vibe Coding 了一个类似的工具。基于 Zvec（向量数据库）实现了一个兼顾 Cli 和 HTTP Server 的工具，功能大体一致。看来自己的想法还算比较前沿。有兴趣的朋友可以看看这一篇。
Zvec-Grep 是一个终端检索工具，支持精确文本，关键词或者语义搜索本地代码和文档。也支持启动本地 MCP 服务端，完成 AI Agent 接入。
安装 zg，建立索引，就可以使用该工具。
安装 Zvec-Grep
这是一个 Typescript 项目，需要 Node.js 22 或更新版本。-g 全局安装，可以在任意目录下执行 zg。
npm install -g @zvec/zvec-grep
构建工作区索引
工作区可以是代码项目，可以是文档。代码支持 C/C++、Python、Go、Java、Typescript、Rust 等。同时也支持结构化的文档，Markdown、Html、Text、Csv、Toml、其它非二进制的文件。这里就不一一列举了，只要在这个工作区用上 zg，你便可以尝试一下。
Zvec-Grep Embedding 模型
本地模型
zg 提供了很多的 Embedding 模型，主要分为三类：Model2Vec、ONNX、GGUF，为了适应不同的场景而生。有以下几个比较常见的场景：代码检索、多语言、以及上下文检索。模型越高级，对机器的性能要求也越高，前期创建索引对机器的性能要求比较高，其次就是检索过程中的推理，比如 local/jina-embeddings-v2-base-code 就需要 GPU 算力。建议普通的机器不要使用 ONNX 和 GGUF 这两类模型，Potion 模型使用静态查表，可以满足日常检索。
# 进入到文档项目目录
cd /xxx/xxx/docs
# 使用 Embedding 模型 local/potion-retrieval-32m 建立索引（英语）
zg index --embedding local/potion-retrieval-32m
# 使用 Embedding 模型 local/potion-multilingual-128m 重新建立索引（多语言）
zg index --rebuild --embedding local/potion-multilingual-128m
远程模型
Zvec-Grep 也支持远程模型，本地模型依赖机器的算力，远程模型不需要在本地推理，通过付费，便捷的使用 qwen 的 Embedding 模型。目前只支持 qwen 的 Embedding 模型，如果为了高效的检索，就不得不使用 qwen 自家的 Embedding 模型。其实也还好，嵌入模型的价格相当便宜。
# 配置 Provider
zg config provider set qwen --api-key "$DASHSCOPE_API_KEY"
zg config model set qwen/text-embedding-v4 --default
# 授权远程访问
zg index --embedding qwen/text-embedding-v4 --allow-remote
zg auth grant --capability embedding --scope workspace \
--embedding qwen/text-embedding-v4
# 撤销授权
zg auth revoke
接入 AI Agent
zg install
zg install --target codex --yes
zg install --target claude --target cursor --yes
执行如上命令之后，可以通过 MCP Tool zvec_grep_search 调用知识库检索。Agent 与 CLI 使用同一个工作区索引。ClI 也必须在当前工作区创建索引，在当前工作区检索。
Error: [INDEX_MISSING] Indexed search requires a built zvec-grep index for /home/xyz. Use an available exact-search fallback when it is sufficient. Creating or rebuilding a persistent index requires explicit user authorization.
个人认为 Zvec-Grep 对自己的定义和职责划分很明确，偏向对检索的理解，返回一个更广的上下文。
本地 Server
本地 Server 默认启动。仅在连续执行 CLI 查询、使用 HTTP MCP 或排查问题时需要主动管理。常驻进程可以：
- 复用已加载的 Embedding 模型和运行时资源；
- 避免每条命令都重新初始化检索资源；
- 降低多个终端或脚本之间的模型冷启动开销。
zg server on 后台启动服务，zg server off 关闭后台服务。