用途：zvec-grep（命令 zg）是 Node CLI 兼本地 MCP 服务器，面向本地工作区搜索，把词法排序检索、向量检索和托管 ripgrep 统一在一个限定范围内。它不是网页搜索引擎、生产搜索后端或持久项目记忆库。
主要能力：支持混合、向量、BM25 与穷尽式精确或正则匹配；可索引代码、Markdown、文本、JSON、YAML、TOML、CSV、XML、HTML 及部分图片，自动排除 .git、.zvec-grep、常见生成路径和忽略规则，跳过 PDF、Office、压缩包、可执行文件、数据库和超大或二进制文件。默认 MCP 工具集提供 zvec_grep_search，可选完整工具集增加托管 rg 与索引/状态管理工具。
用法：确认环境 node --version（需 Node.js >= 22）、zg version、zg help。需要索引时先限定根目录与文件范围，例如 zg index --embedding local/potion-code-16m-v2 -g 'src/' -g 'docs/' -g '!dist/**' -t ts，随后 zg status --check-ready。查询用 zg query <query>、zg query --fts、zg query --vector；精确、穷尽或正则查找用 zg query --rg 或原生 rg，无需索引。执行模式可选 auto、server、direct。MCP 默认在 http://127.0.0.1:7999/mcp，仅回环，勿暴露到非回环地址；stdio 传输通过 zg install --mcp-transport stdio 配置。集成目标包括 claude、codex、opencode、cursor、qwen、qoder，安装后需重启智能体并确认工具名可见。
限制：索引用 .zvec-grep/ 保存，属生成的本地状态，宜排除在提交与备份之外；更换模型或端点需显式重建，zg index --drop --yes 为破坏性操作。远端嵌入会把查询或工作区内容发送给配置的提供方，需用户明确授权，凭据不得打印或存储。索引不等于长期记忆，语义检索不能证明某项内容不存在。上游 GitHub main 可能与 npm 0.2.2 不同，命令以已安装 CLI 帮助为准。安装命令：npm install -g @zvec/zvec-grep@0.2.2（缺失二进制时先展示并等待安装请求）。