背景

ripgrep（rg）擅长已知函数名、配置键、报错文本或正则表达式等精确目标，但面对‘主题偏好在启动时如何恢复’这类自然语言问题，查询词与代码中的真实符号可能几乎不重合。Zvec 新开源的 zg（zvec-grep）试图补上这一层：在同一套本地接口中组合向量语义检索、BM25、混合检索和 rg 精确匹配，让人或 Agent 先按意图发现候选，再用准确文本验证位置。

核心机制

  • zg 会抽取并索引本地代码、文档和结构化文本，尽量保留代码符号、Markdown 标题、文件路径和行号等定位信息。
  • 语义检索适合关键词未知的探索，BM25 或混合检索适合按相关性收窄范围，rg 适合最后的穷尽式精确核验；这不是必须依次执行的固定流水线。
  • CLI 与 MCP 共用同一份本地索引，可供终端用户以及 Codex、Claude Code、Cursor、OpenCode 等 Agent 使用。
  • 扫描、抽取、本地嵌入、索引和检索默认在设备上完成；只有用户明确启用远程嵌入时，相关文本或查询才会离开本机。

安装与首次查询

前提是 macOS、Linux 或 Windows，并安装 Node.js 22 或更高版本。最小流程如下：

node --version
npm install -g @zvec/zvec-grep

# 自动发现本机支持的 Agent 并配置 MCP
zg install

# 也可以只配置 Codex
zg install --target codex --yes

# 在目标工作区建立索引
cd your-repository
zg index

# 直接从终端进行自然语言检索
zg query --human "theme preference persistence on startup"

默认使用轻量本地模型 local/potion-code-16m-v2，不要求 GPU；项目索引保存在工作区根目录的 .zvec-grep/。Agent 与 CLI 可以直接复用这份索引，不需要重复构建。

当前可检索内容

首个开源版本重点覆盖代码与文本：

  • 结构化解析 C/C++、Go、Java、JavaScript/TypeScript、Python、Rust，以及 Vue、Svelte 组件中的脚本；其他代码按通用文本处理。
  • 按标题和章节抽取 Markdown，并支持纯文本、reStructuredText、HTML/XML。
  • CSV、JSON、TOML、YAML 等可识别为文本的数据文件也可进入索引。
  • 可使用路径、glob、文件类型和忽略规则限定范围，减少无关结果。

项目公布的评测结果应如何理解

发布方在 SWE-QA-Bench 与 BrowseComp-Plus 上做了配对 A/B 测试：任务、Agent、模型、提示词、运行环境和限制保持一致，实验组只增加预构建索引、MCP 工具和通用使用说明。发布时的报告称，在 SWE-QA-Bench 上，回答评分提高 1.50 分，同时输入 Token 接近减半、工具调用减少一半以上；在 BrowseComp-Plus 上，准确率从 98.67% 升至 99.00%，输入 Token、工具调用和执行时间也有下降。

这些数字是项目方在指定环境中的结果，不应直接外推到所有仓库。索引构建成本被单独统计，Agent 行为本身也具有随机性；当前仓库的基准说明还强调，应进行多次独立运行、确保工具确实可调用，并防止答案或历史报告被索引造成评测泄漏。发布博客与当前仓库文档中的 BrowseComp-Plus 样本数也不同，说明测试集仍可能演进，复现时应固定代码和数据版本。

适用场景与边界

zg 更适合目标位置未知、证据横跨多个文件或模块的架构追踪、调用链分析、故障定位和知识库检索。如果已知准确标识符或报错文本，直接使用 rg 通常仍更简单、更快。

项目仍处于公开预览阶段。当前没有原生 PDF/Office 抽取、图像或多模态检索，也尚未提供图搜索、查询改写和模型重排；这些能力被列为后续方向。远程嵌入虽然可选，但需要自行评估数据外发、API 成本与权限边界。

建议的验证方法

  1. 选一个熟悉的仓库，记录首次索引时间、索引目录体积和增量更新耗时。
  2. 准备一组‘知道准确关键词’与‘只知道意图’的问题，分别比较 rg、zg 以及 Agent 原生工具的命中率和查询次数。
  3. 在 Agent 中做一次独立冒烟测试，确认 MCP 工具真实可见并能返回带文件路径和位置的结果。
  4. 多次重复同一任务，统计答案质量、输入 Token、工具调用和总耗时，避免用单次运行下结论。
  5. 在包含私有代码或文档的工作区确认使用本地嵌入；若启用远程模型，先核对实际传输的数据范围。

项目资料：

原作者：Astralyn
原帖：https://linux.do/t/topic/2848859