zg：把语义检索、BM25 和 ripgrep 装进同一个本地 CLI
你让 AI Agent 找“启动时恢复主题偏好”的代码逻辑，它可能会先按 theme preference 搜，没结果换 restore theme，再换 startup settings……读了一堆无关文件后，答案还是不对。代码里，这个函数实际叫 hydratePreferences。
问题不一定出在 Agent，而在于默认的检索工具：Agent 拿到的是自然语言意图，默认能用的 ripgrep（也就是 rg）却只做精确关键词匹配。代码命名和自然语言描述之间的“词汇鸿沟”，会让 Agent 陷入“猜词 → 搜索 → 信息不足 → 换词再搜”的循环。每轮循环都意味着更多的工具调用和 Token 开销；更麻烦的是，Agent 可能基于不完整信息直接给结论，而这种错误并不容易察觉。
本地检索要补的不是“更快的 grep”，而是三块能力：语义发现、相关性排序、上下文组织。
阿里开源的 zg（zvec-grep）把 ripgrep、BM25、向量检索这三种不同的搜索能力，装进了同一个本地优先的 CLI 工具里。
它既可以让人在终端里用，也可以通过 MCP 协议让 Agent 直接调用。
什么是 zg？
zg 是 zvec-grep 的缩写，定位是：面向人与 AI Agent 的本地优先统一检索层。
它不是要新造一个 grep，也不是取代 ripgrep。zg 把 ripgrep 作为能力矩阵中的一环，和 BM25 关键词检索、向量语义检索放在同一个入口里，让使用者可以根据任务阶段选择最合适的检索方式。
项目来自阿里的 Zvec 团队。Zvec 是 2025 年底开源的嵌入式高性能向量检索引擎，已在阿里内部运行较长时间；zg 是 Zvec 体系中面向终端用户和 AI Agent 的上层应用，把 Zvec 的向量能力包装成日常可用的搜索工具。
zg 的核心设计理念可以概括为四点：
- 端到端检索：从模糊意图探索，到相关性排序后的聚焦，再到精确的词面验证，每个阶段都有对应的检索模式
- 多格式支持：不只搜代码，还能搜 Markdown、文档、结构化数据（JSON/YAML/TOML），甚至保留代码的符号签名和文档的章节结构
- 上下文高效：多路检索融合排序，默认只返回紧凑的证据片段，不把整个文件塞进上下文
- 本地优先：文件扫描、索引构建、Embedding 生成都在本机完成，数据不出设备；远程模型需要显式授权
快速上手
第一步：安装 zg
# 全局安装
npm install -g @zvec/zvec-grep
# 验证安装
zg --version
安装后可以先执行：
# 自动发现并配置本机已安装的 AI Agent
zg install
这条命令会扫描常见的 Agent 客户端并自动写入 MCP 配置。也可以手动指定目标：
zg install --target codex --yes # 只给 Codex 配
zg install --target cursor --yes # 只给 Cursor 配
第二步：为工作区建索引
cd /path/to/your/project
zg index
默认使用轻量级本地模型 local/potion-code-16m-v2，16M 参数，模型缓存约 32MB，不需要 GPU。官方数据显示，在 Apple M4 Pro 上，为 Django（3457 个文件）建索引不到 30 秒。
索引存放在 <项目根目录>/.zvec-grep/ 下。增量更新以文件为单位：修改过的文件删除旧片段后重新抽取、重新嵌入，不需要全量重建。
换模型时加上 --embedding 参数：
# 使用不同的本地模型
zg index --embedding local/jina-embeddings-v2-base-code
# 使用远程模型（需要先配置 API Key 并授权）
zg index --embedding qwen/qwen3.7-text-embedding --allow-remote
第三步：开始搜索
在终端中直接搜：
# 混合检索（默认）
zg query --human "theme preference persistence on startup"
# 纯向量检索
zg query --vector "how does the system cache user session"
# 纯 BM25 关键词检索
zg query --fts "session cache"
# ripgrep 精确匹配（无需索引）
zg query --rg "hydratePreferences"
--human 会把输出格式优化成适合人读的形式。结果按相关性排序，默认返回紧凑的证据片段，不加载完整文件内容。
在 AI Agent 中搜：
配置好 MCP 后，直接在 Agent 里提问：
Find how theme preferences are restored on startup.
Agent 会自主判断该用混合检索还是 ripgrep，然后返回带文件路径和行号的证据。
写在最后
ripgrep 成为开发者和 Agent 的标配检索工具，不是因为它“最好”，而是因为它在精确、快速、穷尽的词面匹配上确实可靠。
但 Agent 场景下的检索需求正在变化：要搜的不只是“某个函数叫什么”，而是“启动时恢复主题偏好的逻辑在哪里”“用户权限申请的流程是怎样的”。这类问题没有精确关键词，只有模糊意图。
zg 的价值不在于发明了什么新算法，而在于把语义检索、BM25、混合排序和 ripgrep 精确匹配组织成一条完整的本地检索流水线，然后用开发者和 Agent 都能直接上手的方式交付。装一次、索引一次，终端和 Agent 共用同一个索引，数据不出设备。
GitHub：https://github.com/zvec-ai/zvec-grep
