Vexor

---

Vexor 是一款语义搜索引擎，可为文件和代码构建可复用的索引。 它支持可配置的嵌入和重排序提供商，并通过 Python API、CLI 工具和 MCP 服务提供相同的核心功能。

Vexor 演示视频

精选推荐

Vexor 获得了社区认可并被多处推荐：

• 阮一峰的周刊（第 379 期） - 中国开发者社区中颇具影响力的技术通讯。
• Awesome Claude Skills - 为 AI Agent 精选的优质技能列表。
• Awesome MCP Servers - 精选的模型上下文协议服务列表。
• Awesome CLI Apps - 精选的命令行应用列表。

为什么选择 Vexor？

当你记得某个文件的用途，却忘了它的名称或位置时，Vexor 能即刻找到它——无需 grep 模式或遍历目录。

Vexor 专为人类和 AI 编码助手打造，可在自主 Agent 工作流中实现语义文件发现。

安装

从 releases 下载独立二进制文件（无需 Python），或：

pip install vexor  # also works with pipx, uv

快速入门

0. 引导式设置（推荐）

vexor init

如果不存在配置，向导也会在首次运行交互式操作命令前自动启动。 配置管理（vexor config）、MCP、帮助和版本命令会直接运行。

1. 搜索

vexor "api client config"  # defaults to search current directory
# or explicit path:
vexor search "api client config" --path ~/projects/demo --top 5
# in-memory search only:
vexor search "api client config" --no-cache 

Vexor 会在首次搜索时自动建立索引。输出示例：

Vexor semantic file search results
──────────────────────────────────
#   Similarity   File path                       Lines   Preview
1   0.923        ./src/config_loader.py          -       config loader entrypoint
2   0.871        ./src/utils/config_parse.py     -       parse config helpers
3   0.809        ./tests/test_config_loader.py   -       tests for config loader

2. 显式建立索引（可选）

vexor index  # indexes current directory
# or explicit path:
vexor index --path ~/projects/demo --mode code

适用于 CI 预热，或禁用 auto_index 时。

Python API

也可以直接在 Python 中导入并使用 Vexor：

from vexor import index, search

index(path=".", mode="head")
response = search("config loader", path=".", mode="name")

for hit in response.results:
    print(hit.path, hit.score)

配置解析方式与 CLI 相同，遵循全局和项目级配置。 有关运行时覆盖、缓存控制和单次调用选项，请参阅 docs/api/python.md。

AI Agent 技能

此代码库包含一项技能，供 AI Agent 高效使用 Vexor：

vexor install --skills claude  # Claude Code
vexor install --skills codex   # Codex

技能源文件：plugins/vexor/skills/vexor-cli

MCP 服务

说明

Agent Skill 和 MCP 服务提供相同的核心能力——每个 Agent 任选其一。 该技能教会具备 shell 操作能力的 Agent（Claude Code、Codex）使用完整 CLI，并假设 vexor 已安装在 PATH 上；MCP 服务将搜索功能作为原生工具公开，可用于任何 MCP 客户端（Cursor、Windsurf、Zed 等），并可通过 uvx 和环境变量在无需预先设置的情况下启动。

Vexor 内置了 MCP stdio 服务，因此任何支持 MCP 的 Agent 都能将语义文件搜索用作原生工具：

claude mcp add vexor -- vexor mcp   # Claude Code
codex mcp add vexor -- vexor mcp    # Codex

或者在任何 MCP 客户端中手动配置，也可以选择通过 env 提供 API 密钥 和任何配置覆盖项（无需运行 vexor init）：

{
  "mcpServers": {
    "vexor": {
      "command": "vexor",
      "args": ["mcp"],
      "env": {
        "VEXOR_API_KEY": "sk-...",
        "VEXOR_CONFIG_JSON": "{\"provider\": \"gemini\", \"rerank\": \"bm25\"}"
      }
    }
  }
}

该服务提供两个工具：vexor_search（语义文件搜索，返回匹配的源文本，因此 Agent 通常无需再读取文件）和 vexor_index（显式预热索引）。无需额外依赖。Vexor 已列入官方 MCP 注册表，名称为 io.github.scarletkc/vexor。工具架构、环境变量和客户端设置详情，请参阅 docs/mcp.md。

配置

vexor init                             # guided setup (recommended)
vexor config --set-api-key "YOUR_KEY"  # or env: VEXOR_API_KEY / OPENAI_API_KEY / ...
vexor config --set-provider openai     # default; also gemini/voyageai/custom/local
vexor config --rerank hybrid           # optional: fuse exact keyword + semantic ranking
vexor config --show                    # view effective settings and origins

全局配置位于 ~/.vexor/config.json；最近的 <project>/.vexor/config.json 可为该项目覆盖一组受限的行为字段。也可以通过 VEXOR_CONFIG_JSON 注入非机密字段（适用于 MCP 客户端和 CI），并且支持通过 本地嵌入模型完全离线使用。

完整参考请参阅 docs/configuration.md：项目配置字段及优先级、所有配置命令、API 密钥和环境变量、重排策略（混合 / BM25 / FlashRank / 远程）、远程与本地提供方、嵌入维度，以及离线本地模型设置。

CLI 参考

日常使用只需 vexor "query"、vexor search 和 vexor index（参见快速入门）。完整命令表、常用标志、索引模式（--mode auto/name/head/brief/full/code/outline）、.vexorignore 文件、项目本地索引（vexor index --local）、缓存行为和 porcelain 输出格式，均记录在 docs/cli.md 中。

文档

• 配置 — 提供方、API 密钥、重排、嵌入维度、本地模型
• CLI 参考 — 命令、标志、索引模式、缓存行为
• MCP 服务 — 客户端设置、环境变量、工具架构
• Python API — 编程式用法
• 集合 API — 由数据库支持的文本记录和筛选搜索

参与贡献

欢迎贡献、提交问题和 PR！提交消息和 PR 标题遵循 Conventional Commits 规范（例如 feat(mcp): add stdio server）。如果觉得有帮助，请点个 Star。

Star 历史

许可证

MIT