企业官网建设流程全解析

zvec-grep MCP接口详解：zvec_grep_search如何让Agent少调工具、少耗Token

【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grep

zvec-grep是一个 Local-first 的工作区搜索引擎，同时服务于人类与 AI Agent。它通过MCP 接口把zvec_grep_search这一个混合检索工具暴露给 Agent：一次调用即可同时走语义、BM25 词法与向量三路召回，并以紧凑的文本证据直接回填上下文。官方基准测试显示，接入后 Agent 的输入 Token 最高减少 47.3%、工具调用减少 58.6%，答案质量还略有提升。

如果你在用 Codex、Claude Code、Cursor 等编码 Agent，这篇文章会带你理解它的 MCP 设计如何"少调工具、少耗 Token"，并给出可直接落地的配置建议。

60秒接入：一条命令连接你的 Agent

zvec-grep 的 MCP 端点默认运行在本地回环地址http://127.0.0.1:7999/mcp（Streamable HTTP）。安装集成只需两步：

npm install -g @zvec/zvec-grep zg --install --target codex --yes

zg --install会自动完成四件事：写入zvec_grepMCP 配置、写入搜索引导规则、添加工具审批策略、启动本地服务。支持的 Agent 包括 Codex、Claude Code、Qwen Code、Qoder、Cursor、GitHub Copilot、VS Code 和 OpenCode，配置细节见 docs/01-agents.md。

设计亮点一：默认工具集只暴露一个工具

打开 src/mcp/tools.ts 可以看到，zvec-grep 把 MCP 工具分成两套工具集：

"默认只有一个工具"本身就是省 Token 的设计：

• 工具 schema 更短：MCP 的tools/list结果会占用 Agent 的上下文，工具越少，系统提示越精简；
• 决策更确定：Agent 不必在多个功能相近的工具间纠结，减少误调用与重复调用；
• 索引由 CLI 托管：建索引、看状态都在zg命令里完成，Agent 不需要反复调用状态类工具做 preflight 检查。

如需完整工具集，可用zg --server on --mcp-toolset full或环境变量ZVEC_GREP_MCP_TOOLSET=full切换（见 docs/03-mcp.md）。

设计亮点二：一次调用完成混合检索

zvec_grep_search的核心思想是"一次调用、多路召回"，它的输入参数（定义在 src/mcp/schemas.ts）按检索路由分组：

一个典型的"语义意图 + 词法锚点"融合调用：

{ "root": "/path/to/workspace", "query": "authentication flow and failure handling", "fts": ["AuthService", "ForbiddenError"], "fuse": true, "limit": 10 }

没有fuse时，各查询组分别返回并保留组元数据；设置fuse: true后所有组坍缩成一个重排序列表——这正是让 Agent"一次到位"的关键。

设计亮点三：面向 Agent 的紧凑响应

zvec_grep_search的返回值是为 Agent 上下文设计的纯文本，而不是 JSON 大对象：

freshness: fresh src/theme/use-theme.ts:12-36 matched: 16-18 source: 15 export function useTheme() { 16 const [theme, setTheme] = useState("light");

三段式结构带来三个省 Token 的效果（格式化逻辑见 src/cli/format/context.ts）：

1. 有界片段：默认short预览每个文件最多 10 行、单行截断到 160 字符，证据紧凑、噪音少；确需细节时才用preview: "full"；
2. freshness 直接内联：响应首行就给出freshness与后台刷新状态，索引过期时结果仍可用（served_from_current_index），Agent 无需额外调用状态工具；
3. 引导"够用即停"：MCP 说明中明确写入"把足够的返回内容当作已读证据，只在缺口处才打开具体文件"，直接减少了后续的 Read 调用。

内置路由规则：什么时候搜、什么时候停

比工具本身更精妙的是随 MCP 一起下发的引导规则（见 src/prompts/zvec-grep-guidance.ts 与 src/mcp/tools.ts 中的searchRoutingRules）。核心路由逻辑：

规则里还有几条硬性"止损"条款：证据足够就停止搜索、不重复相似查询、纯语义探测最多一次且无相关结果即停。这些约束从协议层面压制了 Agent 最常见的 Token 浪费行为——盲目扩大检索和反复确认。

基准数据：少调工具、少耗 Token 到底省多少？

官方用配对 A/B 实验（任务、模型、提示、环境全部固定，仅改变是否可用 zvec-grep）验证了上述设计，完整结果见 benchmarks/README.md。

左图（Coding，SWE-QA-Bench 20 任务）：输入 Token −47.3%、工具调用 −58.6%、耗时 −37.5%，而 LLM 评审得分 +1.50pp；右图（通用文本检索，BrowseComp-Plus 80 案例）：输入 Token −41.7%、工具调用 −37.3%，准确率持平。

真实仓库案例中，Pylint 任务输入 Token 从 1.38M 降到 299K（−82.7%）、工具调用从 54.7 次降到 9 次（−83.5%）——语义发现 + 排序词法证据让 Agent 不再依赖大范围盲目扫描。

三个省 Token 最佳实践

1. 语义意图进query，已知符号进fts，加fuse: true：一次调用替代"先 grep 猜关键词、再 Read 多个文件"的多轮试探；
2. 默认short预览：片段足够回答时不要升级preview: "full"，只在缺细节时补查具体文件行号；
3. 信任响应里的 freshness：索引稍旧（possibly_stale）且结果充分时直接使用，不做状态预检，把省下的调用留给真正有价值的问题。

更多端点安全（仅回环 + 可选 Bearer 认证）、远程 Embedding 授权等细节，可继续阅读 docs/03-mcp.md 与 docs/06-server.md。

【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grep