Know the words—or don’t. Just zg.

面向人与 Agent 的本地优先统一检索层。

**zg**（**z**vec-**g**rep），由 [zvec](https://github.com/alibaba/zvec) 驱动，将 ripgrep、BM25 与向量检索统一在一个[本地优先的检索入口](./docs/05-architecture.md)中。既可以由人在终端中搜索，也可以让 Agent 根据问题选择合适的本地检索方式。 ## 🎬 功能演示

安装 Agent 集成、为工作区建索引并让 Agent 使用 zvec-grep 检索本地内容

## 💫 为什么选择 zg？ - **人与 Agent 开箱即用**：安装一次、索引一次，即可在 macOS、Linux 和 Windows 上通过 CLI 或 Agent 复用同一个工作区。 - **不止关键词搜索**：先按语义发现内容、按相关性排序，再在需要时使用精确文本或正则完成验证。 - **多格式检索**：搜索源代码、文档和结构化数据，同时保留有用的内容结构与来源位置。 - **更少搜索，更少上下文**：经过排序并保留来源的结果，可以减少工具调用、 Token 消耗与无关噪声，更快找到所需证据。 - **默认本地运行**：文件、索引与本地模型都留在本机；只有经过你的授权，远程 Embedding 服务才能接收数据。 ## 🚀 动手体验 ### 1. 准备示例书架 ```bash # 需要 Node.js 22 或更新版本。 npm install -g @zvec/zvec-grep mkdir zg-mystery && cd zg-mystery curl --retry 3 --retry-all-errors --progress-bar -fL \ -o alice-in-wonderland.txt https://raw.githubusercontent.com/GITenberg/Alice-s-Adventures-in-Wonderland_11/master/11.txt \ -o sherlock-holmes.txt https://raw.githubusercontent.com/GITenberg/The-Memoirs-of-Sherlock-Holmes_834/master/834.txt zg index --embedding local/potion-retrieval-32m ``` > [!NOTE] > 索引保存在被索引项目根目录的 `.zvec-grep/` 中。 > [!TIP] > `zg index` 或 `zg query` 失败时，在原命令后加 `--debug` 重跑，查看诊断信息（direct 和 server 模式均支持）。 > 在同一项目下，可用 `zg status --mode direct --debug` 或 > `zg status --mode server --debug` 查看已记录的索引错误。 > Server 连接失败时，检查 `zg server status` 和[服务日志](./docs/06-server.md#logs-and-state)。 ### 2. 选择检索方式 #### Agent：通过 OpenCode 提问配置好 [OpenCode](https://opencode.ai/) 后： ```bash zg install --target opencode --yes opencode models opencode run --model opencode/nemotron-3-ultra-free \ "An unseen creature left a few marks. What did the detective infer? Cite local evidence." ``` 免费模型的可用性可能变化。请通过 `opencode models` 检查，并将示例模型替换为当前环境中可用的模型。 Prompt 中没有指定任何工具，OpenCode 会自主选择 zg。

展开查看完整 Agent 调用与回答

```text ⚙ zvec_grep_zvec_grep_search {"root":".../zg-mystery","query":"An unseen creature left a few marks. What did the detective infer?","fts":["marks","unseen creature","inferred","detective"],"fuse":true} → Read sherlock-holmes.txt [offset=5440, limit=120] Answer: The detective is Sherlock Holmes in *The Adventure of the Crooked Man*. From the animal's foot-marks, he inferred: - It was not a dog, cat, monkey, or other familiar creature: its print had five foot-pads, long nails, and was nearly as large as a dessert-spoon (sherlock-holmes.txt:5479-5486). - It had a long body and very short legs: nearly two feet long, but with a stride of only about three inches (sherlock-holmes.txt:5497-5502). - It was carnivorous because it climbed the curtain toward a canary's cage (sherlock-holmes.txt:5509-5510). - It was probably from the weasel or stoat tribe, though unusually large (sherlock-holmes.txt:5514-5516). Holmes also inferred that a man entered through the window with it and later left with the key (sherlock-holmes.txt:5464-5470, 5527-5528). ```

#### 用户：直接检索不通过 Agent，直接搜索同一个书架： ```bash zg query --human "An unseen creature left a few marks. What did the detective infer?" --limit 3 ``` zg 会将 `sherlock-holmes.txt` 中的相关段落排在 `alice-in-wonderland.txt` 前面。 ## 📊 性能测试每项测试均采用配对 A/B 评测：任务、Agent/模型、Prompt、环境和资源限制保持一致，仅 zg 访问权限及使用说明不同。完整结果和复现细节参见[性能测试文档](./benchmarks/README_CN.md)。 ### 1. 跨领域 Agent Benchmark [SWE-QA-Bench](./benchmarks/swe-qa-bench/README_CN.md) 使用 Claude Code 与 Claude Opus 5（high 推理强度）； [BrowseComp-Plus](./benchmarks/browse-comp-plus/README_CN.md) 使用 Codex gpt-5.6-sol 与 medium 推理强度。两项测试中的 zg Profile 均使用 Qwen3.7 Text Embedding。

zg 在 Coding 和通用文本检索场景中的整体测试结果，对比 Baseline 的答案质量、输入 Token、工具调用和 Agent 耗时

- **为何有效：** 语义发现先收窄搜索范围，排序后的词法检索再锚定精确标识符；紧凑的证据结果减少了大范围扫描、重复工具调用和模型上下文。 - **为何通用：** 同一检索流程可以适配不同内容：代码索引保留符号、签名和层级路径，通用文本则按相关 section 与 chunk 返回证据。 ### 2. 真实案例分析

三个代码库理解任务中 Baseline 与 zg 的 Judge、输入 Token、工具调用和耗时对比

- **[Pylint](https://github.com/pylint-dev/pylint) — Python 静态分析器：** 任务需要理解 AST 节点处理如何区分带标注与不带标注的属性初始化；由于架构入口事先未知，保留符号与层级路径的检索更适合定位相关实现。 - **[Matplotlib](https://github.com/matplotlib/matplotlib) — 绘图与渲染库：** 任务需要沿数学文本渲染的多个阶段追踪 `FontInfo` 与字体选择；语义与词法联合排序有助于还原跨文件的数据流和控制流。 - **[Django](https://github.com/django/django) — Web 框架：** 任务关联 username 唯一约束、ORM 事务和 formset 批量操作；紧凑的排序证据便于汇集分散在多处的设计依据。

测试仓库与具体问题

| 仓库 | 问题类型 | 具体问题 | | --- | --- | --- | | **`pylint-dev/pylint`** | What
架构探索 | 使用 AST 节点类型区分带类型标注和不带类型标注的实例属性初始化时，采用了什么架构模式？ | | **`matplotlib/matplotlib`** | Where
数据 / 控制流 | `FontInfo` NamedTuple 在数学文本渲染 Pipeline 中如何传递字体度量和字形数据？控制流如何决定在字符渲染的不同阶段使用 `postscript_name` 还是 `FT2Font` 对象？ | | **`django/django`** | Why
设计原理 | User 模型中 username 字段的唯一约束为什么会与 Django ORM 事务处理产生关联？如果在已有数据库中移除该约束，会对基于 formset 的批量操作产生哪些级联影响？ |

| 💬 钉钉群 | 📱 微信群 | 🎮 Discord | X (Twitter) | | :---: | :---: | :---: | :---: | | 钉钉二维码

| [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)]() | | 扫码加入 | 扫码加入 | 点击加入 | 点击关注 |

## ❤️ 参与贡献始终欢迎社区贡献——缺陷修复、新功能和文档改进都会让 zvec-grep 变得更好。请查阅我们的[贡献指南](./CONTRIBUTING.md)开始参与！