zvec-grep Server模式深度解析auto、server、direct三种执行模式如何选择【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grepzvec-grep简称 zg是一个本地优先的代码与文本统一检索工具把 ripgrep、BM25 与向量检索整合到同一个入口服务于终端里的人和 AI Agent。它的索引类命令都支持--mode auto|server|direct三种执行模式——选对模式直接决定你的搜索是即用即走还是常驻共享。三种执行模式一表看懂三种模式调用的是同一套检索引擎区别只在于进程生命周期与协调方式不影响搜索结果本身见 架构文档模式适用场景行为auto默认几乎所有终端使用有现成 Server 就走 Server没有就直接在当前进程执行不会擅自拉起后台服务server脚本强依赖守护进程、共享状态、后台刷新强制要求 Server不可用则报错direct一次性任务、CI 流水线、前台调试完全在当前进程中运行进程退出即结束 记住一句话auto是能搭车就搭车server是车必须在direct是我自己走。auto 模式为什么它是默认推荐auto是最省心的一档如果你已经跑着 Server比如 Agent 集成时由zg --install自动启动了命令会自动复用 Server享受共享的 Embedding 模型和后台索引刷新如果 Server 不存在它静默降级为 direct 执行不会阻塞你、也不会悄悄留下一个后台进程。路由逻辑非常直白核心实现在 src/client/mode-router.tsdirect直走当前进程server直走守护进程auto先探测 Server 是否就绪就绪走 Server、否则走 direct。server 模式谁应该常开守护进程满足以下任意一条就值得用server或让auto命中 ServerAgent 通过 MCP 接入Codex、Claude Code、Cursor 等 Agent 的检索请求都经由本地 Server默认端点http://127.0.0.1:7999/mcp仅监听回环地址跨会话反复搜索同一工作区被多次索引查询时模型只加载一次多请求共享后台刷新Server 会用文件监听持续保持索引新鲜并每小时做一次全量核对防止漂移运维契约需要明确的就绪/未就绪健康检查。常用生命周期命令详见 Server 与执行模式文档zg --server on # 启动后台守护进程 zg --server status --check-ready # 健康检查未就绪退出码非零适合写进脚本 zg --server off # 优雅停止 zg --server run # 前台运行方便看日志direct 模式一次一结CI 首选当命令是孤立的一次性操作、CI 任务不应留下守护进程、或者你希望失败与资源生命周期都绑定在单个进程里时选directzg --mode direct root-local index discovery它还适合需要立即生效环境变量如调整索引并发的场景因为不需要等后台服务重启。模式优先级与刷新策略差异模式配置的优先级从高到低命令行的--mode显式参数永远胜出环境变量ZVEC_GREP_MODE全局配置~/.zvec-grep/config.json中的client.mode默认auto。模式还会改变默认索引刷新策略这是很多新手容易忽略的一点策略server 模式direct 模式默认background先返回结果后台安排更新off不更新--refresh wait等待索引刷新完成当前进程内更新并等待--refresh off不更新直接搜不更新直接搜也就是说同样的--refresh background在 direct 模式下会提示警告并按off处理。如果你必须拿到此刻最新的文件状态请加--refresh wait。选对模式带来的实际收益Server 常驻 排序后的紧凑证据在真实 Agent 评测中体现为显著的资源节省。下图是 SWE-QA-Bench 与 BrowseComp-Plus 两组基准中Baseline 与接入 zvec-grep 后的对比灰色为 Baseline100彩色为 BaselinezgCoding 场景中接入 zvec-grep 后答案质量 1.50 pp而输入 Token −47.3%、工具调用 −58.6%通用文本检索中 Token 与耗时同样下降约 40%。这些节省很大程度上来自 Server 模式下的共享模型与新鲜索引减少了 Agent 的大范围扫描与重复调用。一页选型清单 只是终端随手一搜、不想维护后台进程 →auto默认即可给 AI Agent 配 MCP、长期频繁检索同一仓库 →serverzg --install通常已自动启动CI 任务、容器内一次性脚本、想前台看日志调试 →direct写健康检查脚本 →zg --server status --check-ready需要最新文件状态的精确搜索 → 追加--refresh wait补充一点精确文本搜索zg --rg走受管的 ripgrep无需索引、无需 Server在任何模式下都能本地直接运行。延伸阅读模式选择与 Server 生命周期完整说明docs/06-server.md全部 CLI 参数含--mode、--refreshdocs/02-cli.md系统整体架构与数据边界docs/05-architecture.md模式路由核心实现src/client/mode-router.ts【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grep创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
