前言

Github：https://github.com/HealerJean

博客：http://blog.healerjean.com

项目地址：https://github.com/alibaba/zvec

zvec-grep（zg）：https://github.com/zvec-ai/zvec-grep

官方文档：https://zvec.org

一、认识 zvec 与 zvec-grep

1、zvec 是什么

zvec 是阿里巴巴开源的进程内（in-process）向量数据库——轻量、极速、直接嵌入到应用里跑，不用独立部署服务器。已经在阿里内部广泛使用，2026 年 8 月正式开源，Apache-2.0 协议。

一句话概括：它不是一个”你去连接的向量数据库”，而是一个”你把它嵌到程序里的向量数据库”（类比：SQLite 之于 MySQL）。

核心特性：

2、zvec-grep（zg）是什么

zg 是 zvec 生态里的一把”瑞士军刀”——面向人类和 AI Agent 的本地优先统一检索层，一条 CLI 把 ripgrep、BM25、向量检索三种能力合到一起。

Slogan：Know the words—or don’t. Just zg.

（知道关键词也行，不知道也行，直接 zg 就完事儿了。）

它解决的核心问题：

• ripgrep 快，但只能匹配你记得的字面词
• 向量检索能找意思相似的东西，但不会精确定位
• BM25 擅长关键词排序，但不理解语义

而 AI Agent 在读代码库时，恰好三种能力都需要——zg 就把这三条路合到了一起，并通过 MCP 让 Agent 自动调用。

核心特性：

3、为什么”三合一”是必要的

AI Agent 读代码的痛点：它不知道该 grep 哪个词。

传统的 ripgrep 依赖使用者拿到明确的关键词/正则。但 Agent 在没读过代码的情况下，往往只有一个模糊意图——比如”用户主题偏好在哪里恢复”——它不知道对应的函数叫 loadTheme 还是 restorePreferences 还是 applyUserSettings。

zg 的策略：

1. 向量检索（语义发现）  →  找到语义相关的候选文件
2. BM25 排序（关键词排名）→  把候选按相关度排序
3. ripgrep（精确校验）  →  最后拿到确认后的文件精确 grep

三步走下来，Agent 只需要少量 tool call 就能定位到证据行——而不是撒网式 grep 几十次。

二、快速上手

1、安装

依赖：Node.js 22+

npm install -g @zvec/zvec-grep

# 验证
zg --version
zg help

2、五分钟 Demo：让 zg 侦破福尔摩斯

官方 README 给的入门 demo 特别有意思——用《爱丽丝漫游奇境》和《福尔摩斯探案集》两本书当语料，然后让 zg 用语义回答问题。

1）准备语料

mkdir zg-mystery && cd zg-mystery

curl --retry 3 --retry-all-errors --progress-bar -fL \
  -o alice-in-wonderland.txt https://www.gutenberg.org/files/11/11-0.txt \
  -o sherlock-holmes.txt https://www.gutenberg.org/files/1661/1661-0.txt

2）建索引（用本地 embedding 模型）

zg index --embedding local/potion-retrieval-32m

• local/potion-retrieval-32m：Model2Vec 系列，32M 参数、512 维、1024 token 上下文，纯本地跑，不用 GPU。第一次跑会自动下载模型到 ~/.zvec-grep/models。
• 索引落盘到 <当前目录>/.zvec-grep/

3）人类查询

zg query --human "An unseen creature left a few marks. What did the detective infer?" --limit 3

• --human：给终端友好的富文本输出
• --limit 3：只返回 3 条结果

输出会直接给出 sherlock-holmes.txt:5479-5486 这种带精确行号的结果，还带一段上下文片段。

关键点：查询里根本没提”Holmes”或”Sherlock”，zg 靠语义就定位到了。

4）Agent 查询（以 OpenCode 为例）

zg install --target opencode --yes
opencode models
opencode run --model opencode/nemotron-3-ultra-free "An unseen creature left a few marks. What did the detective infer?"

OpenCode 会自动选择用 zg 去搜索——提示词里根本没有点名任何工具。

三、zg 命令全景

1、命令总览

内置帮助：

zg help                  # 总览
zg help query            # query 详细
zg help models           # 模型列表
zg help file-types       # 支持的文件类型
zg help environment      # 环境变量与优先级
zg <command> --help      # 每个子命令的帮助

2、zg query — 检索

1）四种查询路径

2）常用示例

# 1. Hybrid（推荐默认）：一句自然语言即可
zg query "where theme preferences are restored"

# 2. 纯词法（BM25）+ 路径过滤
zg query --fts "loadTheme" -g "src/**" -t ts

# 3. 纯语义（向量），不看关键词
zg query --vector "where user preferences are restored" --limit 5

# 4. Hybrid 融合多个查询组
zg query --hybrid "authentication flow" --fts "ForbiddenError" --fuse --limit 10

# 5. 人类富文本输出
zg query --human "plugin lifecycle" --preview full

# 6. 走 managed rg（不需要建索引）
zg query --rg -i -C 2 -g "*.ts" "dark mode" src

3）结果控制

--fuse 什么时候用？ 多个 query 组的候选合并成一个排名（用 RRF — Reciprocal Rank Fusion）。不加 --fuse 就是分组分别排名，同一条命中可能在多个组里都出现。

3、zg index — 索引

1）三种形态

# 1. 首次建/增量更新
zg index [root] [options]

# 2. 强制重建（换模型/换配置时）
zg index [root] --rebuild [options]

# 3. 删除索引
zg index [root] --drop [--yes]

2）核心选项

3）文件过滤

4）示例

# 首次建索引，用代码专用小模型
zg index --embedding local/potion-code-16m-v2

# 只索引 src/ 和 docs/，排除 dist/，只要 ts 文件
zg index --embedding local/potion-code-16m-v2 -g "src/**" -g "docs/**" -g "!dist/**" -t ts

# 增量更新（复用之前的模型和过滤规则）
zg index

# 换模型 → 必须 rebuild
zg index --rebuild --embedding local/jina-embeddings-v2-base-code

# 删除索引
zg index --drop --yes

4、zg status — 索引状态

zg status [root] [--mode direct|server|auto] [--check-ready]

会报告：根目录、使用的模型、文件数、失败数、截断情况、下一步建议。

--check-ready：正常输出，但索引没准备好时退出码非零，可以直接用在 shell 脚本里。

5、zg install — 集成到 Agent

1）支持的 Agent

2）示例

# 交互式选择
zg install

# 明确目标
zg install --target codex --yes
zg install --target claude --target cursor --yes

# 全部一次装完
zg install --target all --yes

关键选项：

注意： zg install 只改动 ZVEC_GREP_START / ZVEC_GREP_END 标记之间的托管块，不会覆盖其他 MCP server 或用户自定义内容。

3）卸载

zg uninstall --target codex --yes
zg uninstall --target all --yes

卸载不会删除索引，也不会 npm uninstall 包本身。卸载后需要重启 Agent 才生效。

6、zg config — 模型与凭据

# 配置远程 embedding provider
zg config provider set qwen --api-key "$DASHSCOPE_API_KEY"

# 设置默认模型
zg config model set qwen/text-embedding-v4 --default

# 给本地模型指定设备
zg config model set local/potion-code-16m-v2 --device metal

全局配置存放在 ~/.zvec-grep/config.json。已经建好的索引会保留自己 stored 的模型，直到显式 --rebuild。

7、zg auth — 远程 embedding 授权

关键概念区分：

• zg config provider set：告诉 zg “这是访问 provider 的 API Key”
• zg auth grant：告诉 zg “允许把 workspace 内容发送到 provider”

这两件事是分开的——配了 Key 也不等于授权数据出机器。

# 授予工作区级别的持久授权
zg auth grant --capability embedding --scope workspace --embedding qwen/text-embedding-v4

# 查看当前授权
zg auth status

# 撤销
zg auth revoke

授权信息落在 <workspace>/.zvec-grep/authorization.json，CLI 与 MCP Server 共享。

单次授权（一次性）：

zg index --embedding qwen/text-embedding-v4 --allow-remote

8、zg server — 共享 MCP 服务器

# 启动（后台）
zg server on [--listen 127.0.0.1:7999] [--token-file <path>] [--mcp-toolset agent|full]

# 前台运行
zg server run

# 停止
zg server off

# 状态
zg server status [--check-ready]

• 默认监听 http://127.0.0.1:7999/mcp（只允许 loopback）
• 一个 zvec-grep home 只能被一个 server 拥有
• zg install 会自动引导启动

四、检索管线（Retrieval Pipeline）

理解索引里到底装了什么、什么会被跳过、索引怎么刷——是用好 zg 的关键。

1、什么会被索引

1）结构感知的代码格式（保留符号结构）

2）文档 / 结构化数据

3）默认跳过（二进制/大文件）

.pdf .doc .docx .ppt .pptx .xls .xlsx
.zip .tar .gz .bz2 .xz .7z .rar
.exe .dll .dylib .so .a .o .obj .wasm .class .jar
.mp3 .mp4 .mov .avi .mkv .db .sqlite

.git 和 .zvec-grep 永远排除。

2、大小限制

未指定 --max-filesize 时的默认上限：

空文件、超限文件、二进制文件被静默跳过——不算作失败，也不计入 filesScanned。用 zg index --debug 才会打印跳过明细。

3、索引存放位置

• <workspace>/.zvec-grep/manifest.json：元数据、运行时设置、（若持久化的）API Key
• <workspace>/.zvec-grep/files.zvec：文件级信息
• <workspace>/.zvec-grep/index.zvec：向量索引本体

建议： 把 .zvec-grep/ 加进 .gitignore。

4、Freshness（新鲜度）与刷新

zg 的结果会打标签：fresh 或 possibly_stale。

Server 模式下：

• 有 file watcher 监听变更（会把 burst 事件合并成目录级更新）
• 每小时全量 reconciliation probe，兜底 watcher 漏事件
• 只有当检测到实际漂移时才会打 possibly_stale

日志路径：~/.zvec-grep/daemon/logs/server.log（JSON Lines 格式，API Key、Token、query 内容会被过滤）。

五、Embedding 模型选型

1、快速选择指南

2、完整模型表

所有模型都用余弦相似度；exact revisions 每个 release 都会 pin。tokens 限制针对每个 fragment，不是整个文件。

3、本地模型的设备

--device auto|cpu|metal|vulkan|cuda

也可以通过 zg config model set ... --device metal 或 ZVEC_GREP_DEVICE 设置。

注意： Model2Vec（Potion 系列）用的是静态查表，GPU 并不会加速。

模型缓存目录：~/.zvec-grep/models（可用 --model-cache 或 ZVEC_GREP_MODEL_CACHE 覆盖）。

4、切换模型必须 rebuild

不同模型的向量空间是不兼容的——哪怕维度一样。切换模型必须：

zg index --rebuild --embedding local/jina-embeddings-v2-base-code

换 remote endpoint 也需要 rebuild（endpoint 是 stored schema 的一部分）。换 API Key、换 device 不需要 rebuild。

5、远程 embedding：两步授权

# 第一步：配 Key（只配置了访问权，还不能发数据）
zg config provider set qwen --api-key "$DASHSCOPE_API_KEY"

# 第二步：授权数据出机器（工作区级别）
zg auth grant --capability embedding --scope workspace --embedding qwen/text-embedding-v4

# 或者单次授权
zg index --embedding qwen/text-embedding-v4 --allow-remote

官方原话： “Credentials configure access to a provider; they do not authorize data transfer.”

凭据只是配置了访问 provider 的权限；它不授权数据传输。

六、代码库全是英文没中文注释怎么办

一个很常见的问题：“我代码全是英文标识符、没中文注释，我用中文查询能命中吗？”

答案：能，但取决于两个东西——Embedding 模型的语言能力，以及代码本身的命名质量。

1、zg 搜的到底是什么

zg 索引代码时，CodeExtractor 会把「符号名 + 签名 + 面包屑 + 周围源码」都塞进 embedding。也就是说：

• zg 搜的不是”字面文本”，是符号的语义 + 上下文
• 只要命名有语义，就能被向量空间”认出来”
• 中文注释缺失不是问题，命名混乱才是问题

2、两个决定因素

核心：多语言模型能解决”语言不同”，但解决不了”名字没意义”。

3、选对多语言模型（第一步）

默认的 local/potion-retrieval-32m 是英文优化的，中文查询效果差。要做中→英跨语言检索，换成：

# 轻量多语言（101 种语言）
zg index --rebuild --embedding local/potion-multilingual-128m

# ONNX 多语言，效果更稳
zg index --rebuild --embedding local/multilingual-e5-small

# 效果最好，但要远程 + 授权数据出机器
zg index --rebuild --embedding qwen/qwen3.7-text-embedding

为什么能跨语言？ 多语言模型训练时把”用户认证”和 authenticate user 映射到了向量空间的相近位置。你搜中文命中英文代码是语义匹配，不是翻译。

4、命名质量决定天花板

同样一段代码、同样的多语言模型：

没救的情况： 代码全是缩写、无注释、类型缺失——这种情况 zg 只能退化到 --rg，但 --rg 需要你自己知道要搜什么词。属于代码本身的问题，任何工具都救不了。

5、实操策略（四种姿势）

1）优先走词法路径 + 英文查询

代码库里的”事实关键词”就是类名 / 函数名本身。用英文猜一个可能的命名去 --fts：

# 猜命名 → 词法搜（同一 --fts 传多次即代表多个 BM25 group，不要在字符串里写 OR）
zg query --fts "auth" -t java
zg query --fts "login" --fts "authenticate" --fts "credential" -t ts

2）拿到锚点后走符号扩展

一旦 --fts 命中一个符号，立刻切到符号视角：

zg query --prefer-symbol --symbol-type function "auth"

或者接 CodeGraph 展开调用链——这是”全英文代码库”最实用的组合：zg 帮你找入口，CodeGraph 帮你看邻居。

3）中文意图 + 英文关键词组合 fuse

多语言模型 + --fuse 融合中英双路：

zg query --hybrid "用户登录流程" --fts "login" --fts "auth" --fuse --limit 10

• 中文走向量路径 → 找语义相近符号
• 英文走 BM25 → 精确锚定
• 两路结果用 RRF 融合，recall 最高

4）用 .context/ 建中英映射（最治本）

在 .context/ 里用中文写领域词汇表，标注对应的英文命名：

# .context/glossary.md

## 领域词汇表（中文意图 ↔ 英文符号）

- **用户认证** → `AuthService` / `authenticate()`
- **主题偏好** → `ThemePreference` / `loadTheme()`
- **订单退款** → `RefundService` / `processRefund()`
- **库存扣减** → `InventoryService` / `deductStock()`

AI 读了这个文件，就自动学会”中文意图 → 英文符号”的翻译，再交给 zg 就精准了。这是”上下文知识库 + zg“组合最有价值的场景。

6、无注释 + 无好命名的历史屎山

如果代码烂到向量也 embed 不出东西：

• 老实用 zg query --rg + 英文关键词穷举
• 或者让 AI 先给关键模块加一层 JSDoc / 中文注释，再 --rebuild 索引（一次性投入，长期收益）

7、决策树

代码库全英文、无中文注释
    ├─ 命名规范好         → 换多语言 embedding 即可，中文查询照搜
    ├─ 命名一般           → 多语言 embedding + --fuse 融合中英查询
    ├─ 命名差、无 doc     → .context/ 建中英词汇表映射
    └─ 屎山、缩写、无救   → 老实 --rg + 硬找

七、Agent 集成与 MCP

1、Agent 怎么选择 zg vs 原生 grep

关键原则：“Code versus non-code is not the boundary”（代码 vs 非代码不是边界）。真正的边界是：你知不知道要搜什么。

2、MCP 端点与工具

端点： http://127.0.0.1:7999/mcp（Streamable HTTP，只监听 loopback）

1）默认 agent 工具集（只 1 个工具）

只暴露 zvec_grep_search——因为对于 Agent 来说，”能不能自动决定用它”比”能不能全能”更重要。

zvec_grep_search 参数：

要求：至少要有 query、queries、fts、vector 之一。

2）full 工具集（6 个工具）

用 zg server on --mcp-toolset full 或 ZVEC_GREP_MCP_TOOLSET=full 打开：

注意：zvec_grep_index 的 wait 默认 false（返回一个 job ID）。文档明确要求：”Agent 不得静默创建、重建或删除持久索引“。

3、在不同 Agent 里验证已装好

安装后先跑：

zg server status --check-ready

然后在新会话里检查工具名：

Shell fallback（Agent 出问题时人肉验证）：

zg query "where theme preferences are restored"
zg query --rg -F "loadTheme" src

4、Bearer 鉴权（可选）

Server 默认不开 token，因为只监听 loopback。要打开：

export ZVEC_GREP_SERVER_TOKEN="<至少32字符的强 token>"
zg server on

# 或者用文件
zg server on --token-file /path/to/token

zg install 可以让 Agent 从环境变量读 token：

zg install --target codex --mcp-token-env ZVEC_GREP_SERVER_TOKEN

注意作用域： MCP Bearer token 保护的是本地 server，它不授权 remote embedding。数据出机器需要 zg auth grant。

八、架构与信任边界

1、系统总览

Human/Script        Agent (Codex/Claude/Cursor/...)
     │                       │
     ▼                       ▼
  zg CLI              MCP client (stdio/HTTP)
     │                       │
     │ auto/server/direct    │ 始终走 Server
     └──────────┬────────────┘
                ▼
       ┌──────────────────┐
       │  Search Engine   │
       │                  │
       │ ① Indexed search │ ← BM25 + Vector + RRF
       │ ② Managed rg     │ ← 免索引，exhaustive
       │ ③ Indexing       │ ← scan/extract/embed
       └────────┬─────────┘
                │
                ▼
   ┌──────────────────────────┐
   │ <workspace>/.zvec-grep/  │
   │   manifest.json          │
   │   files.zvec             │
   │   index.zvec             │
   └──────────────────────────┘

要点：

• CLI 的 auto/server/direct 只影响进程生命周期与协调，不影响搜索行为
• Agent 走 MCP → 一定走 Server（--rg 除外，它不需要 index 也不需要 server）
• Indexed search 和 managed rg 是同一个产品边界下的两条路径

2、执行模式：auto / server / direct

managed rg 不管 Server 是否可用，都在本地跑。

3、状态存放

信任边界：

• 扫描、rg、索引存储、本地 embedding → 全在设备上
• Server 只监听 loopback
• 唯一例外： 使用远程 embedding provider 会把 query 或 workspace 内容发到远端——zg 会先要求显式的一次性或工作区级别授权

九、环境变量参考

优先级规则：

• 新索引模型： 显式 --embedding → ZVEC_GREP_EMBEDDING → 全局默认
• 已有索引： 除非 --embedding + --rebuild 组合，否则保留 stored 的模型
• Embedding 运行时（endpoint/device 等）： 显式命令参数 → workspace snapshot → 全局 config → 环境变量
• zg index 在 server/auto 模式下会转发 ZVEC_GREP_EMBEDDING；直连 MCP 走的是 daemon 启动时继承的环境

十、和 Superpowers 的组合姿势

如果你已经在用 Superpowers 那套工作流，zg 补的是“AI 读代码库时的手感”这一环。

1、痛点补齐

2、和 brainstorming / systematic-debugging 的接续

Superpowers 流程                        zg 的位置
─────────────────                       ──────────
brainstorming（澄清需求）              ← zg 帮你先查现有代码怎么写
    ↓
writing-plans（拆解任务）              ← zg 帮你确认相关文件清单
    ↓
subagent-driven-development（执行）    ← 每个 subagent 用 zg 快速定位现有实现
    ↓
systematic-debugging（找 bug）         ← zg 帮你定位错误路径的调用点
    ↓
verification-before-completion（验证） ← zg 帮你确认改动没漏地方

对于 Claude Code 用户：zg install --target claude --yes 装完，Superpowers skill + zg MCP 就在同一个会话里协同工作了。

十一、和「上下文知识库 / CodeGraph / GitNexus」的组合

一句话结论：能组合，而且高度互补——它们分别属于四个不同粒度层，几乎不重叠。

1、先摆定位：四者到底各干什么

一句话四连：

• .context/ 是”框架”——先告诉 AI 这个项目在做什么
• zg 是”发现”——不知道叫什么、在哪儿时用它撒网
• CodeGraph 是”理解”——找到符号后看它的调用邻居
• GitNexus 是”评估”——动手改前看爆炸半径

2、为什么可以组合（不打架）

数据源、粒度、时机都不重叠：

MCP 工具名字不冲突、索引目录不冲突、语义边界清晰——AI Agent 可以按需路由，不会打架。

3、典型协同工作流

1）读一个陌生项目

Step 1: 读 .context/                        ← 先了解项目在做什么、有哪些域
   ↓
Step 2: zg query "..."                      ← 用自然语言定位相关文件
   ↓
Step 3: codegraph_explore <关键符号>          ← 展开找到的符号看调用链
   ↓
Step 4: mcp__gitnexus__impact <关键符号>      ← 想动手前，看这个符号被谁依赖

2）改一个 API

Step 1: zg query "订单退款流程"                ← 语义定位实现在哪
   ↓
Step 2: mcp__gitnexus__api_impact /refund     ← 看 route 消费者、mismatch、风险
   ↓
Step 3: codegraph_node RefundService          ← 展开符号定义 + callers
   ↓
Step 4: 改代码
   ↓
Step 5: mcp__gitnexus__detect_changes         ← 未提交改动影响哪些 process
   ↓
Step 6: zg query --rg <关键字> 补漏            ← 精确校验

3）修一个 Bug

Step 1: zg query "错误消息片段"                ← 定位到抛错点
   ↓
Step 2: codegraph_explore <抛错函数>          ← 展开调用链找到源头
   ↓
Step 3: mcp__gitnexus__impact <修复点>        ← 评估修复影响面
   ↓
Step 4: 改代码 + 补测试

4、和 Superpowers 流程的整体嵌入

把第十章的 Superpowers 工作流展开成”每一步用哪些工具”：

brainstorming（澄清需求）
    ↓ 用什么：.context/  +  zg query
    │  ── .context/ 告诉 AI 域边界，避免出圈
    │  ── zg query 帮 AI 快速验证"这个功能是不是已有实现"
    ↓
writing-plans（拆解任务）
    ↓ 用什么：zg query  +  codegraph_explore
    │  ── zg 定位相关文件清单
    │  ── codegraph 展开被影响符号的调用邻居
    ↓
subagent-driven-development（执行）
    ↓ 用什么：zg query  +  codegraph_node
    │  ── 每个 subagent 用 zg 快速定位现有实现
    │  ── 用 codegraph_node 拿到符号完整源码
    ↓
systematic-debugging（找 Bug）
    ↓ 用什么：zg query  +  codegraph_explore
    │  ── zg 找错误消息 / 抛错路径
    │  ── codegraph 溯源调用链
    ↓
verification-before-completion（验证）
    ↓ 用什么：GitNexus detect_changes  +  zg query --rg
    │  ── detect_changes 检查改动影响的 process
    │  ── zg --rg 精确 grep 校验漏改
    ↓
finishing-a-development-branch（收尾）
    ↓ 用什么：更新 .context/（可选）
       ── 如果本次改动引入了新领域概念，同步进 .context/

5、什么时候不组合也行

不是所有项目都要装全套——组合姿势要看规模：

6、组合的成本与 .gitignore

推荐 .gitignore：

.zvec-grep/
.codegraph/

唯一需要提交的是 .context/——因为它是人工审阅过的领域知识，是团队和 AI 共享的”项目宪法”。

7、AI Agent 侧的路由规则（推荐写进 CLAUDE.md）

# 检索路由（按优先级从高到低）

1. 打开新任务先读 .context/README.md 和相关域的 CONTEXT.md
2. 关键词/正则/文件名明确             → 原生 grep / rg / Read
3. 词法或位置不明 / 需要跨文件综合     → zvec_grep_search
4. 需要调用关系、找 callers          → codegraph_explore / codegraph_node
5. 改动前评估影响面                  → mcp__gitnexus__impact / api_impact
6. 改动后自检                       → mcp__gitnexus__detect_changes

8、组合的价值：Token 效率

四者叠加带来的最实际收益是 token 效率——每个工具都在自己擅长的粒度上给”精准结果”，而不是塞一堆全文让 AI 去筛：

AI 少调用 tool = 少烧 token = 上下文不膨胀 = 回答质量更高——这是组合的本质收益。

十二、常见问题

1、zg 和 ripgrep 什么关系

• zg 不是替代 ripgrep——它包含了 ripgrep（zg query --rg）。
• 语义/BM25 是 zg 提供的额外能力。
• 需要精确正则匹配时，ripgrep 依然是首选路径。

2、我该建索引吗

该建：

• 需要频繁语义搜索的代码仓
• Agent 会读这个仓
• 语料相对稳定，不是分钟级大改

不该建：

• 一次性查一个明确关键词 → zg query --rg 就够了
• 完全不重复访问的临时目录

3、索引会不会污染 git

会。建议：

echo ".zvec-grep/" >> .gitignore

4、切换模型很慢怎么办

先想清楚再切——切了必须全量 rebuild。建议：

1. 小仓上先 A/B 试
2. zg query --debug 看 recall 差异
3. 确认后再对大仓做 --rebuild

5、Server 起不来 / Agent 找不到工具

排查顺序：

# 1. Server 状态
zg server status --check-ready
# 退出码非零 → 起 server
zg server on

# 2. 端口占用？换端口
zg server on --listen 127.0.0.1:8999
export ZVEC_GREP_SERVER_URL=http://127.0.0.1:8999/mcp

# 3. 重装 Agent 集成
zg uninstall --target claude --yes
zg install --target claude --yes
# 重启 Claude Code

# 4. 看日志
tail -f ~/.zvec-grep/daemon/logs/server.log

十三、速查表

1、最常用 10 条命令

# ── 装 & 起 ──
npm install -g @zvec/zvec-grep
zg install --target claude --yes       # 集成到 Claude Code
zg server on                           # 起 MCP server

# ── 建索引 ──
zg index --embedding local/potion-code-16m-v2   # 首次
zg index                                        # 增量更新
zg index --rebuild --embedding <new-model>     # 换模型重建

# ── 查询 ──
zg query "自然语言意图"                          # 混合检索
zg query --fts "loadTheme" -t ts                # 精确关键词
zg query --rg -F "AuthService" src              # 免索引穷尽 rg
zg status                                        # 看索引健康度

2、Agent 端最常用工具

zvec_grep_search(
  root="/abs/path",
  query="where the plugin lifecycle is set up",
  limit=10,
  fuse=true
)

3、模型速查