zvec-grep：从关键词搜索到 Agent 本地检索层

围绕 zvec-grep 0.2.1 的源码、项目文档和 Qwen Developers 发布内容，建立一套从文件进入索引，到 Agent 获得紧凑证据的完整心智模型。

ripgrep 的强项是“已经知道要找什么”：函数名、错误字符串、配置键、文件路径或正则表达式。Agent 常遇到的却是“知道意图，不知道代码中的叫法”。例如，用户询问“启动时如何恢复主题”，代码可能使用 hydratePreferences，词面几乎不重合。

这一过程不是必须顺序执行的固定流水线；线索充分时可直接跳到精确查找。参见 Qwen 帖子对应的 Zvec 官方文章。

3.1 扫描阶段不是“把整个仓库塞进向量库”

Scanner 会始终排除 .git 与 .zvec-grep，默认跳过依赖、构建、缓存、日志、生成目录与锁文件。它还执行二进制探测、符号链接安全检查、嵌套 Git 仓库判断、文件类型与大小限制。默认上限按内容类型区分：代码 1 MiB、文本/Markdown 256 MiB、结构化数据 16 MiB、图片 10 MiB。

3.2 增量更新采用“便宜判断优先，哈希兜底”

3.3 工作区中的三个持久化部分

实现依据：indexing/index.ts、scanner/index.ts、storage/layout.ts。

向量模型只能处理给定片段。片段边界如果破坏了函数、标题或上下文，即使模型再强，也会得到模糊的向量。因此 zg 的核心价值不仅是“向量化”，还包括把本地文件变成可独立定位的证据单元。

symbol: method hydratePreferences
scope: ThemeService
signature: hydratePreferences(store: Store): Promise<void>
doc: Restore persisted theme settings during startup.

// 原始代码片段……

5.1 底层索引

• FTS 字段：Zvec 的全文索引，tokenizer 为 jieba，并应用 lowercase 过滤；面向“词面相关但需要排名”的检索。
• 向量字段：VECTOR_FP32 + HNSW；当前模型目录统一使用 cosine similarity。
• 属性过滤：file_id、group、symbol_name、symbol_type 使用可过滤索引，先收窄候选空间。

5.2 自适应召回不是固定 top-k

源码初始每条 route 召回 200 条。如果去重后的候选数不足 max(limit × 5, 50)，且当前查询仍“打满”深度，就按 2 倍扩大到 400、800、1600，最多 2000。这是在过滤、group 合并后仍保证候选丰富度的保护机制。

5.3 为什么使用 RRF，而不是直接相加分数

BM25/FTS 分数与余弦相似度不在同一量纲，直接相加需要标定权重。RRF 只使用每条召回路线中的名次：

假设 A 在 FTS 排第 1、向量排第 10，B 只在向量排第 2：

A = 1/(60+1) + 1/(60+10) ≈ 0.03068
B = 1/(60+2)                 ≈ 0.01613

结论：跨路线稳定出现的 A 会优先于只在单一路线靠前的 B。

实现依据：pipeline/search/index.ts 与 storage/zvec.ts。

Qwen3.7 Text Embedding 调用链

源码向服务提交的核心字段是 model、input、dimensions: 1024 与 encoding_format: float，并用 Bearer API key 鉴权。Qwen3.7 只负责把文本映射为向量；“何时检索、走哪些 route、如何融合、读哪些源文件、最终如何回答”仍由 zg 与上层 Agent 协作完成。

模型参数来自 models/catalog.ts；远程请求实现见 models/backends/qwen.ts。

zg install不只添加 MCP server 配置，还会向支持的 Agent 写入检索路由指导。真正影响 Agent 效率的并非多一个工具，而是让它在恰当的时机选择恰当的路线。

默认 MCP 面刻意保持很小

默认 agent toolset 只暴露 zvec_grep_search；索引创建、删除、状态与 managed rg 仅在 full toolset 中出现。这个设计减少 Agent 的工具选择负担，也避免它擅自创建或删除持久化索引。

新鲜度与后台更新

MCP 默认为 http://127.0.0.1:7999/mcp，仅监听 loopback；可额外配置 Bearer token。实现与规则见 mcp/tools.ts 与 daemon/watch-manager.ts。

官方强调的指标不是“单次向量查询快了多少毫秒”，而是 Agent 完成整个问题所消耗的搜索轮数、工具调用、输入 Token 与墙钟时间。它对应的优化链条是：

BrowseComp-Plus 当前公开报告

准确率从 98.67% 提升到 99.00%。报告覆盖 100 个 case、每个条件 3 次试验，共 300 组配对结果；使用 Codex gpt-5.6-sol 与 qwen/qwen3.7-text-embedding。

发布文章还报告：SWE-QA-Bench 20 个问题中，工具调用减少超过一半、输入 Token 接近减半，Judge 分数提高 1.50；这些数字属于项目方控制条件下的结果，真实仓库仍应使用自己的代表性问题做 A/B 测试。

数据来源：BrowseComp-Plus paired report 与 benchmark protocol。

什么时候值得使用

• 大型仓库、跨文件调用链、数据流、生命周期、设计理由等“位置未知”的问题。
• 同一工作区会被反复查询，索引成本能够摊薄。
• Agent 经常用多轮 grep 猜词、反复打开文件，Token 浪费明显。
• 代码与 Markdown 文档混合，需要同一检索入口。

什么时候 rg 已经足够

• 寻找唯一的函数名、错误信息、配置键或正则匹配。
• 一次性的小仓库任务，没有复用索引的机会。
• 必须穷尽全部出现位置，而不是获取排名靠前的样本。

实验 1：本地默认模型建立基线

# Node.js 22+
npm install -g @zvec/zvec-grep

cd /absolute/path/to/your-repository
zg index --embedding local/potion-code-16m-v2
zg status

实验 2：对同一个问题分别检索

# 语义：只描述意图
zg query --vector "where user credentials are validated" --human --limit 5

# 词面：已经知道一个符号
zg query --fts "AuthService" --human --limit 5

# 混合：意图 + 精确锚点
zg query --hybrid "authentication flow" \
  --fts "ForbiddenError" --fuse --human --limit 10

# 穷尽验证：不需要索引
zg query --rg -n -F "AuthService" -g "*.ts" src

实验 3：接入 Agent

zg install --target codex --yes
zg server status --check-ready

# 新开 Agent 会话后，用行为描述提问：
# “查清登录凭据从 HTTP 请求进入后，经过哪些组件完成验证，并引用源码位置。”

实验 4：只有明确需要时才比较 Qwen3.7

zg config provider set qwen --api-key "$DASHSCOPE_API_KEY"

# 单次授权，且必须重建，因为向量空间改变
zg index --rebuild \
  --embedding qwen/qwen3.7-text-embedding \
  --allow-remote