你让 AI Agent 帮你找"启动时恢复主题偏好"的代码逻辑，Agent 拿着这句话开始搜索：先搜 theme preference，没结果；换 restore theme，还是没有；再试 startup settings……几轮下来读了一堆无关文件，最后给出的答案还是错的。
而代码里，这个函数其实叫 hydratePreferences。这不是 Agent 不够聪明，而是它手里的工具不对——默认能用的 ripgrep 只认精确的关键词匹配。代码命名和自然语言描述之间的"词汇鸿沟"，让 Agent 陷入了"猜关键词 → 搜一遍 → 换个词再搜"的恶性循环，每一轮都是真金白银的 Token 消耗。
阿里开源的 zg（zvec-grep）就是冲着这个痛点来的——把 ripgrep、BM25、向量检索三种搜索能力装进同一个本地优先的 CLI 工具，目前已有 1.6K Star。
什么是 zg？
zg 是 zvec-grep 的缩写，一句话概括就是：面向人与 AI Agent 的本地优先统一检索层。它不是要造一个新的 grep，而是把 ripgrep 作为能力矩阵中的一个环节，和 BM25 关键词检索、向量语义检索放在同一个入口里，让使用者可以根据任务阶段选择最合适的检索方式。
项目来自阿里的 Zvec 团队——就是那个在 2025 年开源、主打嵌入式高性能向量检索的 Zvec 数据库。zg 是 Zvec 体系中面向终端用户和 AI Agent 的上层应用。
核心设计理念
- 端到端检索：从模糊的意图探索，到相关性排序后的聚焦，再到精确的词面验证，每个阶段都有对应的检索模式
- 多格式支持：不只是搜代码，还能搜 Markdown、文档、结构化数据（JSON/YAML/TOML），保留代码的符号签名和文档的章节结构
- 上下文高效：多路检索融合排序，默认只返回紧凑的证据片段，不把整文件塞进上下文
- 本地优先：文件扫描、索引构建、Embedding 生成都在本机完成，数据不出设备
快速上手
安装：
npm install -g @zvec/zvec-grep
zg --version安装后自动发现并配置本机已安装的 AI Agent：
zg install也可以手动指定目标：
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 秒。索引增量更新，只重新处理修改过的文件。
想换模型？加上 --embedding 参数即可，也支持远程模型（需配置 API Key 并授权）。
开始搜索
在终端中：
# 混合检索（默认）
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 后直接在 Codex/Claude Code/Cursor 中提问即可，Agent 会自主判断该用混合检索还是 ripgrep。
写在最后
ripgrep 之所以成为开发者和 Agent 的标配，不是因为它"最好"，而是因为它在精确的词面匹配领域足够快、足够全。但 Agent 时代的检索需求正在变——我们想搜的不再只是"某个函数叫什么"，而是"启动时恢复主题偏好的逻辑在哪里"。
zg 的价值在于它把语义检索、BM25、混合排序和 ripgrep 精确匹配组织成了一条完整的本地检索流水线，用一种开发者和 Agent 都能直接用的方式交付出来。安装一次，索引一次，就能在终端里搜，也能让 Agent 在同一个索引上搜。本地优先，数据不出设备。
GitHub：https://github.com/zvec-ai/zvec-grep
