vexor-cli

Vexor CLI 技能

目标

按意图（文件的用途）而非精确文本查找文件。

使用方法

• 优先使用 vexor 按意图查找文件。
• 如果缺少 vexor，请参阅 references/install-vexor.md。

命令

vexor "<QUERY>" [--path <ROOT>] [--mode <MODE>] [--ext .py,.md] [--exclude-pattern <PATTERN>] [--top 5] [--content] [--format rich|porcelain|porcelain-z|json]

常用标志

• --path/-p：根目录（默认：当前目录）
• --mode/-m：索引/搜索策略
• --ext/-e：限制文件扩展名（例如 .py,.md）
• --exclude-pattern：按 gitignore 风格的模式排除路径（可重复使用；.js → **/*.js）
• --top/-k：结果数量
• --include-hidden：包含点文件
• --no-respect-gitignore：包含被忽略的文件
• 即使使用 --no-respect-gitignore，也始终遵循项目规则 .vexorignore。
• --no-recursive：仅搜索顶层目录
• --format：rich（默认）、供脚本使用的 porcelain/porcelain-z，以及包含分块内容的完整输出 json
• --content：在表格下方打印每个匹配项的源文本，通常无需之后再读取文件
• --no-cache：仅在内存中操作，不读取/写入索引缓存
• vexor index --local：创建并使用项目本地的 .vexor/ 缓存存储

项目配置

• 最近的 .vexor/config.json 会自动应用于解析后的搜索或索引路径。
• 仅接受 rerank、auto_index、model、embedding_dimensions、 batch_size、embed_concurrency 和 extract_concurrency。
• batch_size 必须至少为 0；两个并发值都必须至少为 1。
• 不接受凭据和端点（api_key、base_url、remote_rerank）以及所有 其他字段。
• 优先级依次为全局配置、项目配置、环境变量覆盖，最后是 显式参数。
• vexor config --show 会标注每个字段的来源，vexor doctor 会列出 生效的覆盖项；修改配置的 vexor config 命令仍仅支持全局配置。

模式（选择满足需求的最轻量模式）

• auto：按文件类型选择（默认）
• name：仅按文件名搜索（最快）
• head：仅搜索前几行（快速）
• brief：关键词摘要（适用于 PRD）
• code：针对 .py/.js/.ts 的代码感知分块（代码库的最佳默认选项）
• outline：Markdown 标题/章节（最适合文档）
• full：对完整文件内容分块（最慢，召回率最高）

故障排查

• 使用弱结果搜索精确标识符（函数/类/常量名称）时：建议尝试一次 vexor config --rerank hybrid——它会结合精确词法匹配与语义搜索。
• 需要搜索被忽略或隐藏的文件：添加 --include-hidden 和/或 --no-respect-gitignore。
• 需要可供脚本处理的输出：使用 --format porcelain（TSV）或 --format porcelain-z（以 NUL 分隔）。
• 查看详细帮助：vexor search --help。
• 配置问题：vexor doctor 或 vexor config --show 会报告生效值及其来源。

示例

# Find CLI entrypoints / commands
vexor search "typer app commands" --top 5

# Search docs by headings/sections
vexor search "user authentication flow" --path docs --mode outline --ext .md --format porcelain

# Locate config loading/validation logic
vexor search "config loader" --path . --mode code --ext .py

# Exclude tests and JavaScript files
vexor search "config loader" --path . --exclude-pattern tests/** --exclude-pattern .js

# Read the matching code directly, without a follow-up file read
vexor search "where JWT claims are validated" --path . --mode code --content

提示

• 首次搜索会为文件建立索引（可能需要一分钟）。长期运行的 MCP 或 Python 客户端会话会复用映射后的向量、监视源文件变更，并跳过 部分快照扫描。监视器设置失败时会回退到扫描。单独的 CLI 调用仍会检查文件系统。必要时请使用更长的超时时间。
• 结果会返回相似度排序、精确文件位置、行号和匹配片段预览。
• 添加 --content（或 --format json），即可在同一次调用中获取匹配的源文本，无需单独读取这些文件。文本位于 content_start_line..content_end_line，如果某个较长符号被索引为多个分块，其起始位置可能晚于结果的 start_line。如果结果显示 stale_line_range，说明文件在索引后发生了更改——请重新运行 vexor index。每次响应的内容都有上限，因此排名较低的结果可能会显示 budget_exhausted。
• 将 --ext 与 --exclude-pattern 结合使用，以聚焦于文件子集（排除规则会在此基础上生效）。