企业官网建设流程全解析

为什么你需要zvec-grep：统一ripgrep、BM25与向量搜索的Local-First混合检索神器

【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grep

zvec-grep（命令名zg）是一个 Local-First 的本地混合检索工具：它把ripgrep 精确匹配、BM25 关键词排序和向量语义搜索统一在同一个本地搜索层之下，既能让你在终端里“用自然语言问代码库”，也能让你的 AI Agent 自动调用它，而且文件、索引和本地模型都保留在机器上。

三种检索引擎，为什么非要“统一”？

日常开发中，我们其实同时需要三种搜索能力，却往往要来回切换三个工具：

zvec-grep 的思路是：一个索引，三条检索路径，一个入口。工作区经过一次zg index建立索引后（存储在<工作区>/.zvec-grep/目录），同一个zg命令既可以走“索引化检索”（BM25 + 向量 + RRF 融合排序），也可以直接走“托管 ripgrep”做穷举式精确搜索，详见 docs/05-architecture.md 的架构图与 docs/04-pipeline.md 的检索管线说明。

核心检索编排逻辑位于 src/engine/pipeline/search/index.ts，对外统一的服务层在 src/engine/service/zvec-grep.ts。

快速上手：三步完成首次本地混合检索

🚀 整个过程不到一分钟，且默认使用本地 Embedding 模型，不需要任何云端服务：

1️⃣ 安装（需 Node.js 22+）

npm install -g @zvec/zvec-grep

2️⃣ 在任意仓库根目录建立索引

cd your-repository zg --index --embedding local/potion-code-16m-v2

3️⃣ 用自然语言提问

zg "where authentication is validated"

如果索引还不存在，zg会自动用本地模型建一个再完成搜索。想要显式控制“关键词 + 语义”的组合，可以用：

zg --hybrid "font metrics pipeline" --fts "FontInfo" --vector "where do font glyphs come from" --fuse

更多搜索参数与过滤选项（glob、文件类型、结果预览等）见 docs/02-cli.md。

实测效果：更少 Token、更少工具调用，答案更好

在官方配对 A/B 基准测试中（任务、模型、提示词与限流条件完全一致，唯一变量是能否使用 zg），开启 zg 后：

• Coding 场景（SWE-QA-Bench，20 任务）：LLM 评审得分 80.42 → 81.92，输入 Token −47.3%，工具调用 −58.6%，耗时 −37.5%
• 通用文本检索（BrowseComp-Plus，80 案例）：准确率持平（90.0%），输入 Token −41.7%，工具调用 −37.3%

在真实仓库（pylint、matplotlib、django）的架构理解类问题中，混合检索的优势更明显——pylint 上输入 Token 节省 82.7%、工具调用节省 83.5%、耗时节省 75.7%，且评审得分提升：

一句话总结其收益：语义发现缩小搜索范围 → 排序好的词汇检索锚定精确位置 → 紧凑证据减少无谓的宽扫描和重复工具调用。

让 AI Agent 自动使用：一条命令接入

这是 zvec-grep 最“面向未来”的能力：通过本地 MCP 服务器，Agent 会自己决定何时用zg查语义线索、何时用 ripgrep 查精确文本。

zg --install # 交互式选择已检测到的 Agent zg --install --target codex --yes # 脚本化安装

支持 Codex、Claude Code、Qwen Code、Cursor、GitHub Copilot、VS Code、OpenCode 等主流 Agent，安装时只改本地配置文件。完整列表与配置路径见 docs/01-agents.md，MCP 工具与安全机制见 docs/03-mcp.md。

Local-First：数据到底去了哪里？🔒

对隐私敏感的用户，这是最关键的卖点：

• 工作区索引存放在项目内的.zvec-grep/，全局配置与守护进程状态在~/.zvec-grep/
• 扫描、索引、托管 ripgrep 与本地 Embedding 模型全部在本机执行
• 本地服务器只监听 loopback 地址
• 唯一可能把数据送出机器的路径是“远程 Embedding 提供商”，且必须经过显式的一次性或工作区级授权

信任边界细节见 docs/05-architecture.md。

它适合谁？

• 👨‍💻日常开发者：想在终端里“用一句话问代码库”，不必先知道确切符号名
• 🤖AI Agent 重度用户：让 Agent 少烧 Token、少盲扫，检索证据更紧凑
• 🔐隐私敏感团队：代码与索引不出本机，无需部署向量数据库
• 📚文档/知识库管理者：不只检索代码，Markdown、结构化数据同样可检索

延伸阅读

总结：如果你正在为“关键词搜索找不到语义结果、语义搜索又缺精确锚点”而烦恼，zvec-grep 用 Local-First 的混合检索把 ripgrep、BM25 和向量搜索拧成了一股绳——一次安装、一次索引，人和 Agent 共用同一个本地搜索层。

【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grep