findscripter Vexor 向量 CLI：语义文件搜索工具配置
采编自 sickn33/antigravity-awesome-skills（MIT）的 vexor 技能，结合上游 scarletkc/vexor（MIT）实际命令适配重写。
Vexor 是一个向量驱动的语义文件搜索引擎 CLI：对文件/代码计算嵌入、建立可复用索引，用自然语言按「含义」检索，并能把搜索能力作为 skill 装进 Claude Code / Codex。
何时使用
- 想用自然语言（而非精确关键词/正则）在一个目录或代码库里找「讲了某件事」的文件或代码片段。
- 要给 Claude Code 或 Codex 智能体接入语义文件发现能力（自主工作流里定位相关文件）。
- 需要为代码库建立一次构建、多次复用的向量索引，避免每次全量扫描。
不该用（负边界）：
- 纯字面/正则匹配——直接用
grep/ripgrep，无需嵌入开销。 - 没有可用的嵌入能力时：既没有远程提供方的 API Key，又没装本地模型。此时先完成配置或改用关键词搜索。
- 桌面 App：上游标注「experimental，未积极维护」，生产场景只用 CLI。
步骤 / 指令
- 安装：
pip install vexor（亦支持 pipx / uv；或从 GitHub releases 下载独立二进制）。本地嵌入模型需pip install "vexor[local]"（GPU 用vexor[local-cuda]）。 - 配置嵌入提供方与 Key（远程任选其一，OpenAI 为默认）：
vexor config --set-provider openai|gemini|voyageai|custom|localvexor config --set-model text-embedding-3-smallvexor config --set-api-key "YOUR_KEY"（或用环境变量OPENAI_API_KEY/GOOGLE_GENAI_API_KEY/VOYAGE_API_KEY）- 或一步到位：
vexor init（交互式向导）。配置存~/.vexor/config.json，索引缓存在~/.vexor/。
- 建索引（可选，搜索会按需自动建）：
vexor index --path PATH --mode MODE。--mode控制粒度：auto（默认，按文件类型智能路由：Py/JS/TS 走 AST 的code、Markdown 走outline、其余按大小）、或显式name|head|brief|full|code|outline。 - 语义搜索：
vexor search "QUERY" --path PATH --top K（简写vexor QUERY）。首次搜索会自动建索引。结果含相似度分数与文件预览。 - （推荐）配置重排提升精度：可选
bm25/flashrank/remote重排器对 Top 结果重排序；FlashRank 需pip install "vexor[flashrank]"。 - 接入智能体：
vexor install --skills claude（Claude Code）或vexor install --skills codex（Codex）。 - 排障：
vexor doctor自检；vexor config --show查看配置；vexor update [--upgrade]升级。
常用 flag：--path（目标目录，默认当前）、--top K/-k（结果数，默认 5）、--ext .py,.md（按扩展名过滤）、--include-hidden（含隐藏文件）、--no-cache（仅内存搜索不落盘）、--format porcelain（TSV 输出，便于脚本解析）。
示例
# 1. 一次性配置（OpenAI 默认提供方）
vexor config --set-provider openai
vexor config --set-api-key "sk-..."
# 2. 在 src 目录按语义找“处理用户登录鉴权的代码”，取前 8 条，只看 py/ts
vexor search "user login authentication flow" --path ./src --top 8 --ext .py,.ts
# 3. 手动用 code 模式给整个仓库建可复用索引
vexor index --path . --mode code
# 4. 脚本里消费结果（TSV）
vexor "where is rate limiting configured" --format porcelain
# 5. 离线：用本地多语言模型 + GPU
vexor local --setup --model intfloat/multilingual-e5-small
vexor local --cuda
# 6. 把语义搜索装进 Claude Code
vexor install --skills claude
注意事项
- 必须先有嵌入能力：远程提供方需配 API Key，否则搜索失败；离线场景务必先
vexor local --setup。 - 索引缓存键由 path + mode + 过滤 flag 共同决定：换
--mode或--ext会触发重建；清理用vexor config --clear-index-all，本地模型在~/.vexor/models（vexor local --clean-up清理）。 - 成本与隐私：远程提供方会把文件内容片段发往第三方做 embedding；敏感代码库优先用本地模型（
localprovider）。 - 重排是可选但强烈建议：上游建议预先配置 Reranker 以提升准确率，尤其结果噪声多时。
- 桌面 App 不稳定且未维护，自动化一律走 CLI。
互见
- related：
ai-native-cli-design—— vexor 体现了 agent 友好 CLI（--format porcelain机读输出）的设计取向。 - combines_with：知识检索 / RAG 类技能 —— 语义文件搜索可作为 RAG 流水线的本地检索层。
- combines_with：Claude Code / Codex skill 接入 ——
vexor install --skills让智能体在自主工作流中直接定位相关文件。