故障排查
排查安装、索引、检索、本地服务、Agent 连接和远程 Embedding 问题。
先运行三项检查：
zg --version
zg --status
zg --help找不到 zg 命令
通过 npm 安装时需要 Node.js 14.14 或更新版本；zg 本身是原生可执行文件：
node --version
npm install -g @zvec/zvec-grep --allow-scripts=@zvec/zvec-grep
zg --version如果 npm 安装成功但仍找不到 zg，请将 npm 的全局二进制目录加入 shell 的 PATH。
如果 npm 跳过了包的安装脚本，请允许执行这些脚本，再运行 npm rebuild -g @zvec/zvec-grep --allow-scripts=@zvec/zvec-grep --foreground-scripts 生成原生可执行文件。
索引不存在或已过期
在预期的工作区根目录中运行：
zg --status --check-ready
zg --index
zg "release checklist" --refresh wait更换 Embedding 模型或状态提示索引不兼容时，使用 --rebuild。索引不兼容时请重新指定所需模型和扫描规则，已有数据不会原地迁移。
检索结果为空或质量较弱
- 已知文本、标识符、路径或正则时使用
--rg。 - 已知关键词但需要排序时使用
--fts。 - 措辞或位置未知时使用默认混合查询。
- 使用
-g、-t或-T限制大型工作区。 - 确认内容已被索引，并且模型适合该内容。
zg "authentication flow" --debug --trace
zg --index --debug参见检索指南、支持的内容和 Embedding 模型。
显式 Server 模式未就绪
本节仅适用于 --mode server 或 HTTP MCP 连接。默认 stdio Agent 接入会自动管理服务。
zg --server status --check-ready
zg --server on
zg --server status --check-ready需要查看前台日志时运行 zg --server run。生命周期、CLI 连接模式、监听地址和鉴权方式参见本地 Server。
Agent 无法使用 Zvec-Grep
zg --install --target codex --yes重启 Agent 或新建会话。精确标识符和文件名可能会正确地使用 Agent 原生 grep，而不是 Zvec-Grep。参见接入 AI Agent。
远程 Embedding 被拒绝
检查或授予独立的工作区授权：
zg --auth status
zg --auth grant --capability embedding --scope workspace --embedding qwen/text-embedding-v4单次命令可以使用 --allow-remote；内容不能离开本机时，请选择本地模型。
安全重置
zg --index --rebuild --embedding local/potion-code-16m-v2
zg --index --drop删除操作不可恢复
--drop 会删除工作区索引，但不会删除源码文件。在重新构建索引前，索引检索将不可用。
反馈问题时，请提供版本、操作系统、失败命令、相关的 zg --status 和脱敏后的诊断信息，并移除凭据、私有路径和敏感片段。