zg（zvec-grep）

Qwen 开发团队正式发布了 zg (zvec-grep)，这是一个专为编码代理（Coding Agents）设计的开源本地搜索工具。它创造性地将传统的词法搜索（ripgrep）、统计相关性搜索（BM25）和语义向量搜索整合在一个统一的接口下，旨在解决 AI 代理在代码库中“迷路”的问题，大幅降低工具调用次数和 Token 消耗。

🚀 核心痛点与解决方案

编码代理在执行任务时，往往面临两难：

• 已知符号：使用 ripgrep 能精确找到，但无法理解自然语言描述的行为。
• 未知术语：关键词匹配失效，代理只能盲目猜测术语或读取大量文件，导致极高的 Token 成本和延迟。

zg 的解决方案：通过一次索引，提供四种检索路径，让代理根据意图选择最合适的搜索方式，从而减少“绕路”。

一个索引，四种检索路径

zg 对工作区进行一次索引后，支持以下查询模式：

1. 混合默认路径：结合意图理解和词法锚点，平衡语义与精确匹配。
2. --fts (Full-Text Search)：基于 BM25 算法的精确词项排名，适合已知关键词的场景。
3. --vector：纯语义向量搜索，忽略词法排名，适合概念相似性查找。
4. --rg (ripgrep)：穷举字面或正则表达式匹配，无需索引，适合未索引仓库或精确符号查找。

智能 freshness 状态：索引结果会报告 fresh 或 possibly_stale，允许代理在结果足够好时直接行动，无需每次先运行状态预检。

为代理优化的 MCP 界面

zg 通过 MCP (Model Context Protocol) 与 Codex、Claude Code、Cursor 等代理无缝集成，其设计极具克制性：

• 极简工具集：默认仅暴露两个工具：
  • zvec_grep_search：用于意图已知但确切字符串未知的场景。
  • zvec_grep_rg：用于已知符号、路径或正则的场景。
• CLI 管理生命周期：索引的创建、删除和重建保留在 CLI 中，防止代理静默修改持久化索引，确保安全性。
• 上下文经济：结果按文件分组并带行跨度，默认省略预览以节省 Token；拒绝 ripgrep 的冗余输出标志，保持结果紧凑。

本地优先与隐私保护

• 设备端嵌入：默认使用 local/potion-code-16m-v2（Model2Vec 静态模型），无需 GPU 即可快速运行。支持多种本地模型（如 Jina, EmbeddingGemma, Qwen3-Embedding）。
• 受控远程访问：若需使用远程大模型嵌入（如 Qwen3.7-Text-Embedding），必须通过 --allow-remote 或 zg auth grant 显式授权，确保数据不出境。
• 跨平台支持：支持 macOS、Linux、Windows，需 Node.js 22+。

性能表现（初步基准）

在 Qwen 团队的内部 A/B 测试中，zg 展现了显著的效率提升：

注：样本量较小且为供应商自测，独立复现仍在进行中。

快速开始

# 安装
npm install -g @zvec/zvec-grep

# 初始化索引
zg index

# 启动 MCP 服务器（供 Claude Code/Cursor 等使用）
zg server on