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-grepzvec-grepCLI 命令名为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需要全量精确匹配无需索引还可以用-gglob、-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 与服务器日志出问题时按这个顺序排查命令级给任意搜索或--index命令加--debug在 stderr 输出诊断信息还能看到被跳过文件的数量与样例命中级加--trace输出每个命中项的索引搜索追踪定位为什么这条没排上去服务级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.mdCLI 全部选项的权威说明见 docs/02-cli.md。10个技巧速查清单#技巧命令1快速建索引zg --index --embedding local/potion-code-16m-v22自然语言混合搜索zg 主题偏好在启动时如何恢复3精确词法搜索zg --fts AuthService4纯语义搜索zg --vector 凭据在哪里校验 --limit 55多组查询融合zg --hybrid auth flow --fts TokenError --fuse6免索引穷举搜索zg --rg -i -C 2 -g *.ts dark mode src7缩小搜索范围-g src/** -t ts组合使用8索引体检与脚本门禁zg --status --check-ready9换模型重建zg --index --rebuild --embedding local/jina-embeddings-v2-base-code10诊断排查--debug看诊断、--trace看单条命中效果如何基准数据一瞥项目自带成对 A/B 基准智能体接入 zg 后答案质量提升的同时输入 token 和工具调用次数明显下降——这正是混合搜索减少无效扫描的直接体现在 Pylint、Matplotlib、Django 三个真实仓库的理解类任务上符号感知的检索帮助智能体在不知道入口点的情况下也能快速定位跨文件的调用链总结一个命令记住zg 自然语言就是混合搜索覆盖 80% 的场景索引是本地资产存在项目.zvec-grep/下用--status体检、--rebuild重建排错有套路先--debug再--trace最后查服务器日志深入阅读docs/02-cli.mdCLI 全部选项、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考