当 Agent 搜不到 hydratePreferences：zg 把语义检索装进本地 CLI
AI Agent 接到一个任务：「找到启动时恢复主题偏好的代码逻辑」。它先搜 theme preference，没结果；换成 restore theme，还是没有；再试 startup settings……读了一堆无关文件，最后答案还是错的。
代码里，这个函数其实叫 hydratePreferences。
问题不在 Agent，在工具。Agent 拿到的是自然语言意图，默认能用的检索工具 ripgrep（rg）只做精确的关键词匹配。代码命名和自然语言之间的「词汇鸿沟」，让 Agent 陷入猜词循环：每多一轮，就多一次工具调用、多消耗 Token、多等待时间。更麻烦的是，Agent 可能基于不完整信息得出结论，而这种错误很难察觉。
本地检索要补的不是「更快的 grep」，是三块新能力：语义发现、相关性排序、上下文组织。
阿里开源的 zg（zvec-grep） 把 ripgrep、BM25、向量检索三种能力装进同一个本地优先 CLI，既能人在终端里用，也能让 Agent 通过 MCP 协议调用。
GitHub：https://github.com/zvec-ai/zvec-grep
zg 是什么
zg 是 zvec-grep 的缩写：面向人与 AI Agent 的本地优先统一检索层。
它不是要取代 ripgrep，而是把 ripgrep 作为能力矩阵中的一环，与 BM25 关键词检索、向量语义检索放在同一个入口，让使用者根据任务阶段选合适的检索方式。
项目来自阿里的 Zvec 团队——2025 年底开源、主打嵌入式高性能向量检索的 Zvec 数据库。Zvec 已在阿里内部长期运行，是生产级向量检索引擎；zg 是 Zvec 体系里面向终端用户和 AI Agent 的上层应用。
核心设计理念：
- 端到端检索：从模糊意图探索，到相关性排序后的聚焦，再到精确词面验证，每阶段都有对应检索模式
- 多格式支持：能搜代码、Markdown、文档、结构化数据（JSON/YAML/TOML），保留代码符号签名和文档章节结构
- 上下文高效：多路检索融合排序，默认只返回紧凑证据片段，不把整个文件塞进上下文
- 本地优先：文件扫描、索引构建、Embedding 生成都在本机完成，数据不出设备，远程模型需显式授权
快速上手
第一步：安装 zg
# 全局安装
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 秒。
索引存在 <项目根目录>/.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 后，直接在 Codex / Claude Code / Cursor 里提问：
Find how theme preferences are restored on startup.
Agent 会自主判断该用混合检索还是 ripgrep，返回带文件路径和行号的证据。
小结
ripgrep 能成为开发者和 Agent 的标配，不是因为它「最好」，而是因为它在精确、快速、穷尽的词面匹配上足够可靠。
Agent 时代的检索需求变了：想搜的不再是「某个函数叫什么」，而是「启动时恢复主题偏好的逻辑在哪里」「用户权限申请的流程是怎样的」——没有精确关键词，只有模糊意图。
zg 的价值不在新算法，而在把语义检索、BM25、混合排序和 ripgrep 精确匹配组织成一条完整的本地检索流水线，用开发者和 Agent 都能直接用的方式交付。安装一次，索引一次，终端里能搜，Agent 也在同一个索引上搜。本地优先，数据不出设备。