Zvec-Grep (zg) 原生代码语义与架构搜索扩展插件，专为 Pi Coding Agent 深度定制。
让 AI 助手能够直接通过语义理解工程宏观架构、梳理跨文件调用链，并精准定位代码。
zvec-grep (zg) 是一款集成了本地向量语义检索、BM25 词法评分与 ripgrep 正则搜索的混合代码检索引擎：
- 混合多路召回：使用 16M 参数的轻量级本地代码嵌入模型（
potion-code-16m-v2），支持 Metal/GPU 硬件加速，零网络延迟与零 API 密钥依赖。 - 倒数排名融合 (RRF)：通过智能融合算法，同时兼顾“语义概念匹配”与“精确代码符号匹配”。
- 架构级调用流梳理：面对庞大陌生的代码库或复杂的微服务工程，只需输入业务链路概念（例如“用户登录后 Token 颁发与权限刷新流程”），即可秒级串联跨模块的核心调用点。
| 对比维度 | 官方 MCP 协议接入 | pi-zg 原生扩展 | 优势提升 |
|---|---|---|---|
| 提示词 Token 消耗 | ~800+ tokens / 轮（冗长 JSON Schema） | ~80 tokens / 轮 | 节省 90% 上下文开销 |
| 调用通信机制 | HTTP / SSE 序列化解析 | pi.exec 本地异步进程直连 |
零网络协议延迟（< 5ms） |
| 终端展示 | 简陋纯文本打印 | @earendil-works/pi-tui 定制卡片 |
高可读性、状态徽章与条目计数 |
| 上下文防撑爆 | 无保护，大文本极易撑爆模型 | 2000 行 / 50KB 自动头截断 + 临时文件落盘 | 保障长对话稳定不溢出 |
在运行 pi-zg 之前，请确保本机已具备以下环境：
需要 Node.js >= 22：
npm install -g @zvec/zvec-grep配置使用轻量级本地模型（纯本地离线运行，支持 GPU/Metal 加速）：
# 设置默认模型为 potion-code-16m-v2，在 Apple Silicon 上开启 metal 加速（Linux/Windows 可使用 cpu 或 cuda）
zg config model set local/potion-code-16m-v2 --default --device metalzg server on首次进入工程目录时，建立语义索引：
zg index /path/to/your/project将本项目克隆或复制至 Pi 的全局扩展目录下（推荐建立子目录）：
mkdir -p ~/.pi/agent/extensions/pi-zg
cp -r . ~/.pi/agent/extensions/pi-zg/启动或重新进入 pi 交互终端，插件即刻自动加载生效！
AI 智能体可直接使用 zg 工具进行检索，支持以下参数：
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
query |
string | 是 | 语义搜索词、自然语言描述、跨文件调用流或架构设计概念 |
fts |
string | 否 | 精确关键词或代码标识符（与语义搜索融合以锁定特定函数/类/字段） |
path |
string | 否 | 限制搜索的目标目录或文件路径（默认为当前工作区根目录） |
glob |
string | 否 | 文件匹配模式，如 '*.ts'、'src/**' 或排除 '!node_modules/**' |
limit |
integer | 否 | 返回的最大匹配条数（默认为 10，上限 30） |
本项目采用 MIT License 协议。