检索指南
选择检索路径、缩小工作区范围并调整 Zvec-Grep 的结果。
Zvec-Grep 在同一个 zg <query> 命令下提供多条互补路径。先选择与你掌握的信息相匹配的方式，再缩小搜索空间，而不是直接增加结果数量。
选择检索路径
| 你的意图 | 命令 | 结果特点 |
|---|---|---|
| 按语义发现，或同时使用语义与关键词 | zg "认证流程" | 混合检索后的排序样本 |
| 按相关性排列已知关键词 | zg --fts "AuthService" | BM25 排序样本 |
| 只按概念相似度检索 | zg --vector "凭证在哪里校验" | 向量排序样本 |
| 找到所有文本或正则匹配 | zg --rg -n -F "AuthService" src | 默认穷举匹配 |
精确或穷举任务使用 --rg。措辞或位置未知，或者需要理解跨文件关系时，使用索引检索。
默认位置参数会联合词法与向量检索：
zg --preview detail "用户偏好在启动时从哪里恢复" --limit 5位置参数会合并为一个查询，即使分别加了引号也是如此。需要独立查询时，重复使用 --hybrid、--fts 或 --vector：
zg --hybrid "connection pool" --hybrid "socket timeout"问题中还包含精确线索时，可以将它们融合为一个排序计划：
zg --hybrid "authentication flow" --fts "ForbiddenError" --fuse --limit 10缩小工作区范围
zg "plugin lifecycle" -g "src/**" -g "!src/generated/**" -t ts| 参数 | 用途 |
|---|---|
-g、--glob、--iglob | 包含或排除路径 |
-t、--type、-T、--type-not | 过滤文件类型 |
--modified-after / --modified-before | 按修改时间筛选 |
控制结果与新鲜度
| 参数 | 效果 |
|---|---|
--limit <n> | 每个查询组的最大结果数 |
--preview none|short|full|detail | 控制源码预览；detail 还包含元数据、大纲与文件分组 |
--debug / --trace | 查询与单条命中的诊断信息 |
--refresh background|wait|off | 选择索引新鲜度策略 |
终端、管道和重定向输出都默认使用 --preview short。full 展示每个检索项的全部可用内容，不会额外读取整个文件。
索引结果会报告 fresh 或 possibly_stale。Server 模式默认使用 background，direct 模式默认使用 off，且不支持后台刷新。需要先将变更纳入索引再搜索时，使用 --refresh wait。
改善较弱的结果
- 使用
zg --status确认工作区根目录和索引状态。 - 限制到相关路径或文件类型。
- 通过
--fts增加一到两个明确线索。 - 已知目标文本时切换到
--rg。 - 检查支持的内容与所选 Embedding 模型。
运行 zg --help search 查看已安装版本的完整参数。结果仍然较弱时，请查看故障排查。