用途
vexor-cli 用于按意图（文件做什么）而非精确文本进行文件发现。当你需要定位某个功能在何处实现、加载、定义或文档化，且仓库规模较大、手动浏览或普通 grep 太慢或结果模糊时，适合使用该技能。
主要能力
- 语义化文件发现：根据查询意图返回相似度排序的结果，包含精确文件位置、行号和匹配片段预览。
- 多种索引/搜索模式，可按成本选择：
- auto：按文件类型路由（默认）
- name：仅文件名（最快）
- head：仅文件首行（快）
- brief：关键词摘要（适合 PRD）
- code：面向 .py/.js/.ts 的代码感知分块（代码库最佳默认）
- outline：Markdown 标题/章节（适合文档）
- full：整文件内容分块（最慢，召回最高）
- 过滤与范围控制：可指定根目录、限制文件扩展名、按 gitignore 风格模式排除路径（可重复）、限制结果数量、包含隐藏文件、忽略 gitignore、仅顶层目录。
- 输出格式：rich（默认）或 porcelain/porcelain-z，便于脚本处理。
- 缓存控制：--no-cache 仅内存运行，不读写索引缓存。
使用方式
基本命令：
vexor "<QUERY>" [--path <ROOT>] [--mode <MODE>] [--ext .py,.md] [--exclude-pattern <PATTERN>] [--top 5] [--format rich|porcelain|porcelain-z]
常用标志：
- --path/-p：根目录（默认当前目录）
- --mode/-m：索引/搜索策略
- --ext/-e：限制文件扩展名（如 .py,.md）
- --exclude-pattern：按 gitignore 风格模式排除路径（可重复；.js → **/*.js）
- --top/-k：结果数量
- --include-hidden：包含点文件
- --no-respect-gitignore：包含被忽略文件
- --no-recursive：仅顶层目录
- --format：rich（默认）或 porcelain/porcelain-z 用于脚本
- --no-cache：仅内存，不读写索引缓存
示例：
# 查找 CLI 入口点/命令
vexor search "typer app commands" --top 5
# 按标题/章节搜索文档
vexor search "user authentication flow" --path docs --mode outline --ext .md --format porcelain
# 定位配置加载/校验逻辑
vexor search "config loader" --path . --mode code --ext .py
# 排除测试和 JavaScript 文件
vexor search "config loader" --path . --exclude-pattern tests/** --exclude-pattern .js
提示：首次搜索会建立索引（可能需要一分钟），后续搜索较快；必要时使用更长超时。可将 --ext 与 --exclude-pattern 组合以聚焦子集（排除规则叠加生效）。
适用场景
- 中大型仓库中按意图查找实现、加载、定义或文档位置。
- 需要语义发现而非精确文本匹配的代码库探索。
- 文档检索（outline 模式）与代码检索（code 模式）。
- 需要脚本化输出的自动化流程（porcelain/porcelain-z）。
限制与前置条件
- 仅当任务明确符合上述范围时使用该技能。
- 输出不能替代针对具体环境的验证、测试或专家审查。
- 若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。
- 支持材料可用性：本目录副本包含内联指引，但不包含以下支持路径，它们属于外部前置条件而非捆绑文件：
- <support-root>/references/install-vexor.md
- 在使用依赖这些路径的步骤前，需索取原始支持材料或已有安装；本目录未标识经验证的下载来源。应相对于该安装解析每个路径、检查其内容，并核实适用的许可证与执行前置条件。在所需文件存在前，不要运行命令或声称已遵循所引用的流程。不要伪造缺失脚本，也不要把同名无关文件视为等价。此处完整记录的独立步骤可在用户授权范围内进行；任何依赖步骤应报告为不可用。
- 若 vexor 缺失，需遵循 references/install-vexor.md（该文件未随本目录提供）。
- 配置问题可通过
vexor doctor或vexor config --show诊断 API、缓存与连通性（需用户自行设置）。 - 详细帮助：
vexor search --help。