zvec-grep (zg) 部署教程：本地优先的智能搜索工具

zvec-grep（简称 zg）是一个本地优先的搜索层，专为人类和 AI 智能体设计。它统一了关键词搜索 (ripgrep)、传统排名 (BM25) 和语义向量搜索，让您能通过含义而非精确词汇发现信息，并始终提供带来源链接的排名结果。它完全运行在本地，索引和文件都保留在您的机器上。

本教程将指导您完成 zg 的安装、索引和搜索，并展示如何将其集成到 AI 智能体工作流中。

📦 第一步：安装

zg 是一个 Node.js 命令行工具，要求 Node.js 22 或更新版本。

# 使用 npm 全局安装
npm install -g @zvec/zvec-grep

# 验证安装
zg --version

🚀 第二步：快速开始（示例项目）

让我们用一个经典文学作品集来体验 zg 的核心功能。

创建一个示例项目并下载文本文件：

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 的关键一步。它会扫描项目文件，构建一个包含关键词和语义向量的索引，存储在项目根目录下的 .zvec-grep/ 文件夹中。
1
zg index --embedding local/potion-retrieval-32m
- --embedding local/potion-retrieval-32m 指定了一个本地、轻量级的嵌入模型。您也可以稍后配置其他模型（包括云端 API）。

🔍 第三步：搜索

索引完成后，您就可以用两种方式搜索了。

3.1 作为人类，直接搜索

1	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。结果会按相关性排序并附上来源位置。

3.2 作为 AI 智能体，集成使用

zg 最强大的功能之一是它可以作为工具被 AI 智能体（如 OpenCode、Claude Code 等）调用。

安装到智能体环境：
以 OpenCode 为例，在您的项目目录中运行：
1
zg install --target opencode --yes
这会将 zg 配置为 OpenCode 可用的工具。
让智能体自行调用：
启动您的智能体（如 OpenCode），并给出一个需要查找信息的任务。智能体会在需要时自动决定调用 zg 进行搜索。
1
2
opencode run --model opencode/nemotron-3-ultra-free \
"An unseen creature left a few marks. What did the detective infer? Cite local evidence."
智能体会使用 zg 搜索本地文本，并根据返回的证据给出带引用的答案。

注意：智能体在运行时，会根据上下文自行选择是否、何时以及如何使用 zg 工具，您无需在提示词中明确指定工具名称。

⚙️ 第四步：进阶配置与管理

4.1 查看索引状态

您可以使用 status 命令检查索引的健康状况和失败记录。

1 2	zg status --mode direct --debug # 检查直接模式的索引状态 zg status --mode server --debug # 检查服务器模式的索引状态

4.2 搜索模式

直接模式 (Direct)：每次搜索都执行一次性的命令，适合脚本或单次查询。

服务器模式 (Server)：启动一个常驻后台的本地服务器，可以更快地响应多次查询请求，特别适合智能体频繁调用。

1
2
3

zg server start     # 启动服务器
zg query --human "your query" --mode server  # 使用服务器模式查询
zg server stop      # 停止服务器

4.3 嵌入模型选择

zg 支持多种嵌入模型，您可以根据对搜索质量、速度和隐私的需求进行选择。

本地模型 (Local)：如 local/potion-retrieval-32m，完全离线，数据不上传，适合隐私敏感场景。
云端模型 (Remote)：可配置 OpenAI 等 API 的嵌入模型，通常质量更高，但需要 API 密钥并将数据发送到云端。

您可以在 zg 的配置文件中（通常在 ~/.zvec-grep/config.json）管理模型设置。

🩺 常见问题与排障

安装或运行失败：
1. 确认 Node.js 版本是否为 22 或更高。
2. 在失败的命令后添加 --debug 标志重新运行，以获取详细的诊断信息。
3. 检查网络连接是否能够下载必要的依赖和模型文件。
索引速度慢或卡住：
这通常发生在首次索引大型项目时。zg 默认会智能跳过已索引的文件。如果进程卡住，可以按 Ctrl+C 中断，然后重新运行 zg index，它会从中断点继续。
搜索结果不理想：
1. 确保索引已成功构建（运行 zg status 检查）。
2. 可以尝试调整搜索查询，或更换不同的嵌入模型（如从本地模型切换到云端模型）。
3. 对于代码库，zg 支持符号感知搜索，能更好地理解标识符和函数名。
智能体无法调用 zg：
1. 确认已正确运行 zg install --target <你的智能体>。
2. 检查智能体的配置和权限，确保它允许使用外部工具。
3. 在智能体的对话中，直接询问它是否能够使用搜索工具，并观察其响应。

📚 进一步探索

支持更多智能体：zg 还支持集成到 Codex、Claude Code、Qwen Code、Cursor 等。运行 zg install --help 查看所有目标。
搜索代码库：将 zg 指向你的项目根目录（如 zg index），它会自动识别代码文件，并通过符号和结构进行索引，非常适合代码库的架构探索和问题排查。
查看完整文档：项目提供了详细的 CLI 指南和 MCP 集成指南，涵盖所有命令和配置选项。