zvec-grep：按含义搜索代码与文档

zvec-grep，简称 zg，是一款本地优先的搜索工具，面向源码、文档和结构化数据。它结合了 ripgrep 的精确文本或正则表达式搜索、BM25 关键词排序，以及按语义相似程度查找内容的向量检索。知道一段代码的用途却不知道名称，或想寻找已有主题文档时，可以用它缩小范围。

已知标识符时，精确搜索通常是最直接的起点。如果只知道“执行手续费在哪里分摊”，即使实现采用了不同措辞，语义搜索也可能提供线索。相似度用于寻找候选位置，并不能证明工具理解了业务规则。

索引提供了什么

建立索引时，工具把文件切分为可搜索的片段，并保留有用的结构和来源位置。代码结果可以包含符号和签名，文档结果可以指向章节和段落，帮助你决定下一步打开哪个文件，而不必先读完所有文件。

结果并不只包含文件坐标。默认输出是面向智能体的精简 Markdown；--human 提供适合终端阅读的格式，默认显示完整预览。输出长度取决于查询、结果数量和预览设置。返回的行范围只是起点：任务需要时，还应阅读调用方、测试、周围定义，乃至整个文件。

向量索引解释近似搜索怎样减少比较；找回的近邻仍需核对原文。

以下示例需要 Node.js 22 或更新版本，以及官方 npm 软件包。未安装时，npx 可能会下载该软件包。在准备建立索引的目录中运行命令，并为这个工作区选择一种初始模型：

# 代码仓库
npx @zvec/zvec-grep index --embedding local/potion-code-16m-v2

如果是多语言文档集合，则改用下面这一种：

npx @zvec/zvec-grep index --embedding local/potion-multilingual-128m

索引保存在项目根目录下的 .zvec-grep/ 中，不应纳入版本控制。本地模型首次使用时可能需要下载；本地推理不等于离线安装。工具也支持远程嵌入服务，向这些服务发送数据需要授权。为敏感资料建立索引前，应先确认所选模型。

在已建立索引的 Python 仓库中，查找手续费相关逻辑：

npx @zvec/zvec-grep query "订单执行 滑点 佣金 手续费" -g '*.py' --limit 3 --human

在包含 docs/ 目录且已建立索引的文档仓库中，查找已有内容：

npx @zvec/zvec-grep query "个人知识系统" -g 'docs/**' --limit 3

这里的 -g 筛选路径，--limit 限制每个查询组返回的结果数。如果已有页面讨论同一主题，可以考虑更新它或添加链接。先看少量结果便于入手，但不能据此判定某个主题不存在。

在当前工作区打开可能相关的结果，用测试或支持文档确认实际行为。如果结果缺失或过时，检查索引范围和状态，必要时刷新索引：

npx @zvec/zvec-grep status
npx @zvec/zvec-grep index

这两条命令假定工作区已有索引，并沿用现有模型配置。搜索相关性和性能会随资料、模型及硬件变化。精简的结果或本地索引都无法保证补丁正确，也不能阻止助手超出请求范围。