zvec-grep CLI命令完全指南：10个索引、混合搜索与诊断实用技巧

zvec-grep CLI命令完全指南：10个索引、混合搜索与诊断实用技巧

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

zvec-grep（CLI 命令名为zg）是一个本地优先的工作区搜索工具，把 ripgrep 精确匹配、BM25 词法检索和向量语义搜索统一在一个终端界面下，同时服务人类与 AI Agent。本指南带你掌握 zvec-grep CLI 的核心命令：建立索引、混合搜索、控制输出，以及出问题时如何用--debug做诊断排查。

快速上手：一条命令安装并建立索引

zvec-grep 通过 npm 全局安装（需要 Node.js 22+），索引文件存放在项目根的.zvec-grep/目录：

npm install -g @zvec/zvec-grep cd your-repository zg --index --embedding local/potion-code-16m-v2

• 索引会自动排除.git、依赖目录、构建产物和被 ignore 规则忽略的文件；
• 第一次搜索时如果还没有索引，zg会自动用本地嵌入模型建好再搜索；
• 换模型或改范围时，用zg --index --rebuild --embedding <模型>重建，用zg --index --drop --yes彻底删除。

💡 不知道选哪个嵌入模型？代码仓库推荐local/potion-code-16m-v2（小而快），英文文档检索推荐local/potion-retrieval-32m，完整对照表见 docs/07-embedding.md。

混合搜索：4种查询路线一次讲清

zg的位置参数默认走混合检索（词法 + 向量），这是最常用的形态：

zg "where theme preferences are restored"

当你需要更精细的控制时，有 4 条明确的查询路线：

路线	命令	适用场景
混合	zg "<自然语言>"或--hybrid	意图模糊、不知道具体文件名
词法	zg --fts "AuthService"	已知确切标识符，要排名命中
语义	zg --vector "where credentials are validated"	概念相似，无精确关键词
穷举	zg --rg -n -F "AuthService" -g "*.ts" src	需要全量精确匹配，无需索引

还可以用-g（glob）、-t（文件类型）缩小范围，例如zg --fts "loadTheme" -g "src/**" -t ts。路线选择的完整原理见 docs/04-pipeline.md。

多组查询融合：--fuse

同一个问题换个说法往往命中不同文件。--fuse可以把多个查询组融合成一个排名结果：

zg \ --hybrid "authentication flow" \ --fts "ForbiddenError" \ --fuse \ --limit 10

不加--fuse时，多组查询会各自独立展示结果；加上后各组的命中会合并排名，减少重复、覆盖更全。

让结果更紧凑：--limit 与 --preview

• --limit <n>：限制每组返回条数；
• --preview none|short|full：控制索引结果的源码预览长度；
• --compact：强制输出管道友好的紧凑格式（stdout 被重定向时会自动变紧凑）。

用 zg --status 做索引体检

zg --status是索引管理的第一诊断入口，它会显示：选中的根目录、使用的模型、文件数量、刷新状态、截断统计，以及一条建议的下一步操作：

zg --status zg --status --check-ready # 索引未就绪时以非零退出码结束

--check-ready特别适合放进脚本或 CI：索引没准备好就返回失败，方便做健康检查。

诊断三板斧：--debug、--trace 与服务器日志

出问题时按这个顺序排查：

1. 命令级：给任意搜索或--index命令加--debug，在 stderr 输出诊断信息，还能看到被跳过文件的数量与样例；
2. 命中级：加--trace，输出每个命中项的索引搜索追踪，定位"为什么这条没排上去"；
3. 服务级：zg --server status查看守护进程状态，结构化 JSON 日志位于~/.zvec-grep/daemon/logs/server.log（敏感字段已自动过滤）。

zg "plugin lifecycle" --debug --trace zg --server status --check-ready

服务器模式、auto/server/direct三种执行方式的区别详见 docs/06-server.md；CLI 全部选项的权威说明见 docs/02-cli.md。

10个技巧速查清单

#	技巧	命令
1	快速建索引	zg --index --embedding local/potion-code-16m-v2
2	自然语言混合搜索	zg "主题偏好在启动时如何恢复"
3	精确词法搜索	zg --fts "AuthService"
4	纯语义搜索	zg --vector "凭据在哪里校验" --limit 5
5	多组查询融合	zg --hybrid "auth flow" --fts "TokenError" --fuse
6	免索引穷举搜索	zg --rg -i -C 2 -g "*.ts" "dark mode" src
7	缩小搜索范围	-g "src/**" -t ts组合使用
8	索引体检与脚本门禁	zg --status --check-ready
9	换模型重建	zg --index --rebuild --embedding local/jina-embeddings-v2-base-code
10	诊断排查	--debug看诊断、--trace看单条命中

效果如何：基准数据一瞥

项目自带成对 A/B 基准：智能体接入 zg 后，答案质量提升的同时，输入 token 和工具调用次数明显下降——这正是"混合搜索减少无效扫描"的直接体现：

在 Pylint、Matplotlib、Django 三个真实仓库的理解类任务上，符号感知的检索帮助智能体在不知道入口点的情况下也能快速定位跨文件的调用链：

总结

• 一个命令记住：zg "<自然语言>"就是混合搜索，覆盖 80% 的场景；
• 索引是本地资产：存在项目.zvec-grep/下，用--status体检、--rebuild重建；
• 排错有套路：先--debug，再--trace，最后查服务器日志；
• 深入阅读：docs/02-cli.md（CLI 全部选项）、docs/04-pipeline.md（检索管线）、docs/06-server.md（服务器与模式）、docs/07-embedding.md（嵌入模型选择）。

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