zvec-grep که با فرمان zg اجرا میشود، یک لایه جستوجوی Local-first برای انسان و AI Agent است. ابزار، جستوجوی دقیق ripgrep، رتبهبندی BM25 و Vector Search را ترکیب میکند تا بدون دانستن نام دقیق Function یا عبارت موجود در فایل، بخش مرتبط کد و سند پیدا شود.
پروژه بر پایه zvec ساخته شده و رابط TypeScript/Node.js آن در مخزن رسمی zvec-grep مستند شده است. Index و مدل محلی بهطور پیشفرض روی دستگاه میمانند؛ Embedding راه دور فقط وقتی استفاده میشود که کاربر آن را انتخاب کند.
چرا ripgrep بهتنهایی کافی نیست؟
ripgrep وقتی عالی است که واژه یا Pattern را میدانید. اما پرسشی مانند «کجا دسترسی کاربر پیش از حذف پروژه بررسی میشود؟» ممکن است با نامهایی مثل authorizeOwner یا canDeleteWorkspace پیاده شده باشد. Vector Search معنا را نزدیک میکند، BM25 واژههای مهم را رتبه میدهد و Search دقیق نتیجه را با Source قابل بررسی نگه میدارد.
| روش | نقطه قوت | محدودیت |
|---|---|---|
| ripgrep | دقیق، سریع و مناسب Regex | به واژه یا Pattern نزدیک نیاز دارد. |
| BM25 | رتبهبندی واژهمحور بهتر | رابطه معنایی را کامل نمیفهمد. |
| Vector Search | یافتن مفهوم مشابه | ممکن است نتیجه ظاهراً مشابه ولی نادرست بدهد. |
| Hybrid | ترکیب Recall معنایی و Evidence متنی | به Index و تنظیم وزنها نیاز دارد. |
نصب zvec-grep
نسخه فعلی Node.js 22 یا جدیدتر میخواهد:
npm install -g @zvec/zvec-grep
zg --helpبرای پروژه حساس، نسخه Package را Pin کنید، Lockfile و منبع انتشار را بررسی و نصب را ابتدا در محیط آزمایشی انجام دهید.
ساخت Index محلی
cd your-project
zg index --embedding local/potion-retrieval-32m
zg status --mode directIndex در پوشه .zvec-grep/ داخل ریشه پروژه ذخیره میشود. قبل از Commit تصمیم بگیرید این پوشه باید در .gitignore باشد یا نه. Repositoryهای حاوی Secret، Dump یا داده مشتری را بدون پاکسازی Index نکنید.
جستوجوی معنایی مستقیم
zg query --human "Where is tenant authorization checked before deletion?" --limit 5نتیجه باید به فایل و موقعیت Source اشاره کند. Agent نباید خلاصه Vector Search را حقیقت قطعی فرض کند؛ فایل اصلی و Test مرتبط را بعد از Retrieval بخوانید.