跳到主要内容

zvec-grep (zg): 代码与文档雷达探针

zvec-grep（常用简写 zg）是专为人类与 AI 助手设计的语义搜索工具。与只能死板匹配完全一致字句的旧式搜索不同，zg 能理解你话里的真实意思，直接帮你指出目标内容具体藏在哪个文件的哪几行。

微信找记录比喻：为什么我们需要它？​

想象你在微信里想找一段半年前的聊天记录：

  • 你只模模糊糊记得当时聊的是*“周末去哪吃火锅”*，但根本记不清确切说了哪几个字。
  • 传统的搜索工具（比如经典的 grep）就像拿着放大镜逐字校对。如果你搜“火锅”，而当时你发的是“四川麻辣锅”，传统搜索直接告诉你：找到 0 条结果。
  • 早期 AI 编程助手为了解决这个问题，采取了最野蛮的做法：一口气把抽屉里几十本厚厚的文件全抱到桌上，从第一页逐行读到最后一页。
    • 惨痛后果：信息暴饮暴食（消化不良）。AI 的短期记忆瞬间被垃圾信息挤爆。它彻底忘了你最初吩咐的规矩，脑子短路，开始自作主张写出一堆谁也跑不通、谁也不想要的复杂垃圾代码（就像当年把 Finance 搞垮的教训一样）。

解决方案：智能图书索引卡​

zvec-grep 就像一个提前读完了你桌上所有笔记本目录的精明助理：

  1. 你用日常大白话问它：“算手续费的代码写在哪里？”
  2. zg 绝不把整座书库倾倒给 AI，而是递给它一张纸条：
    matching.py: 第 148 行至 253 行 (match_fifo_lots)
  3. AI 只看这特定的 100 行代码，干净利落地把问题改好，立刻收手。

它能带来什么实际好处？​

没有 zg（暴力硬读）拥有 zg（精准雷达）
脑容量挤爆：一次硬读 3 个大文件（约消耗 5,000 字记忆），迅速让 AI 丧失注意力。精准聚焦：只返回文件名和行号坐标（仅占约 80 字记忆）。
自作主张走偏：记忆被塞满后，AI 忘了你的约束，开始胡乱加多余功能。老老实实守规矩：工作记忆始终保持清爽，严格按指令只修这一个点。
到处建重复文件：因为找不到已有笔记，AI 在网站里到处新建重复孤岛页面。维护单一真值源：秒级翻出已有页面，就地扩写或修改。
又慢又费钱：反复把海量代码在网络上传输，耗时耗算力。100% 本地纯离线：纯靠本地电脑 CPU 瞬间算完，不把代码发往任何云端。

常用命令速查（你真正用得上的 3 条命令）​

所有命令直接在终端的项目目录下敲击即可：

1. 建立搜索索引（第一次使用时运行）​

让工具记住你的代码和文档大纲：

# 编程项目（Python / JavaScript 等）
npx @zvec/zvec-grep index --embedding local/potion-code-16m-v2

# 多语言文档网站（如包含中英文的本网站）
npx @zvec/zvec-grep index --embedding local/potion-multilingual-128m

2. 用大白话在代码里找逻辑​

不需要猜变量名，直接搜你想表达的意思：

npx @zvec/zvec-grep query "order execution slippage commission fee" -g '*.py' --limit 3 --human

3. 写文档前先查重，杜绝新建垃圾孤岛​

在让 AI 写新文章前，先查查网站里是不是早就有这个主题了：

npx @zvec/zvec-grep query "personal knowledge system" -g 'docs/**' --limit 3

搜出来已有匹配时，直接在原有文件上改，绝不新建第二份文件。

关联生态与延伸阅读​

  • 宏观全景：Agent 记忆与分层检索 — 了解 zg 在防止 AI 失焦的四层金字塔中扮演的角色。
  • 规矩守护者：Basic Memory — 如果说 zg 是负责定位具体位置的雷达，Basic Memory 则是负责管住 AI 不准胡作非为的老板备忘录。
  • 概念档案室：QMD — 负责管理跨项目通用设计原理与历史教训的学术资料馆。

官方资源与源码仓库​