Vexor 语义代码搜索
按意图而非精确文本查找文件——在大型仓库中快速定位某个功能在哪里实现、加载或定义。
技能本身仅做本地文件检索，无破坏性默认行为；文档明确项目配置拒绝 api_key 等敏感字段（.vexor/config. 白名单），有测试锁定该行为，数据流较透明。扣分项：安装文档引导设置 API key 并写入全局配置，密钥处理与回滚说明不完整；发布者为未验证的第三方。
仓库含真实 CI（pytest + ruff）和覆盖 CLI 关键路径（porcelain 契约、JSON 输出、内容截断、无效配置报错）的测试套件，可支持超过静态上限 10 分。扣分项：测试多为 mock 后端的单测，端到端语义检索路径仅有 DummyBackend 覆盖，真实嵌入/索引行为、失败反馈质量未经验证执行。
触发场景清晰（中型/大型仓库中按意图定位文件），模式选择、非适用范围与故障排查写得较好，名称与描述匹配。扣分项：默认依赖远程嵌入服务（openai/gemini 等），中国大陆可达性存疑；本地模型方案需从 HuggingFace 下载，环境适配证据不足；对查询质量的边界（何种查询语义检索效果差）未披露。
SKILL.md 结构清晰、渐进披露合理（安装细节放 references/），MIT 许可明确，有维护者、发布流程和 changelog 约定（release notes 流程）。扣分项：技能文件本身无版本号/变更记录，随 pip 包捆绑分发使技能版本与 CLI 版本耦合但不透明；部分功能（MCP、collections）需跳转外部文档。
核心任务（按意图找文件）路径完整，--content/--format 直接返回源码可减少后续读文件，命令示例具体可用，README 有社区收录佐证。扣分项：静态审阅无法验证检索结果的真实质量与准确性；首个查询需索引、需配置嵌入提供方，冷启动成本对轻量用户偏高。
有可审计的主材料：CI 工作流、测试代码、配置白名单测试、第三方社区收录（阮一峰周刊等）。扣分项：无独立执行复现，语义质量类主张（相似度排序效果）仅有演示视频与示例输出，第三方佐证为收录而非技术验证。
- 默认远程嵌入提供方（openai/gemini 等）在中国大陆可能不可达，建议预先配置本地模型（vexor[local]）或确认网络可达性
- 使用远程提供方需设置 API key 并写入全局配置，注意密钥保管与权限最小化
- 静态审阅未执行任何命令，检索质量、索引耗时与失败反馈均为文档主张，未经独立验证
- 技能通过 pip 包捆绑分发，技能内容版本与 CLI 版本耦合，升级时注意核对变更
这个 Skill 能做什么，适合哪些场景？
Vexor 是一个面向文件和代码的语义搜索引擎，通过可复用的向量索引，让你按“文件做什么”来查找，而无需记住文件名或路径。它提供 CLI、Python API 和 MCP 服务器三种形态，支持可配置的 embedding 与重排序提供商，也能完全离线使用本地模型。仓库自带一个面向 AI 编码助手的 Agent Skill（vexor-cli），教 Claude Code、Codex 等具备 shell 能力的代理用完整 CLI 进行语义文件发现。项目采用 MIT 许可，Python 3.10+，可经 pip 安装或直接下载独立二进制。
将仓库文件按所选模式（name/head/brief/code/outline/full 等）分块并生成向量索引，缓存于内存或 .vexor/ 目录；接收自然语言查询，返回按相似度排序的文件路径、行号和片段预览，--content 或 --format 可直接输出匹配的源码文本。首次搜索会自动建索引，也可用 vexor index 显式预热。支持 gitignore 规则、.vexorignore、扩展名过滤、排除模式等，配置通过 ~/.vexor/config.（全局）和项目内 .vexor/config.（受限字段）管理。
- 开发者在大中型仓库中忘记某功能的位置，想用一句描述（如“JWT 校验在哪里”）直接找到实现文件。
- Claude Code / Codex 用户希望代理自主探索陌生代码库，用 vexor search 替代逐目录浏览。
- 文档作者想在 docs 目录中按标题结构检索相关章节（--mode outline）。
- 需要可脚本化输出的工程师，用 --format porcelain 或 porcelain-z 把结果接入 shell 管道。
- 无法联网的团队，配置本地 embedding 模型实现完全离线的语义搜索。
- 已在用 MCP 客户端（Cursor、Windsurf、Zed 等）的用户，通过 vexor mcp 把语义搜索作为原生工具接入。
这个 Skill 有哪些优点和局限？
- 按意图查找文件，省去 grep 和目录遍历。
- 一次安装，三种使用形态：CLI、Python API、MCP 服务器，覆盖人和 AI 代理两类用户。
- 多种索引模式可按场景选最快或最高召回，含代码感知分块。
- 支持完全离线（本地 embedding 模型）和项目级配置隔离。
- --rerank hybrid 可修复精确名称搜索的弱结果问题。
- 需要配置 embedding 提供商与 API 密钥（或本地模型），有初始设置成本。
- 首次搜索需建索引，可能耗时约一分钟；长符号被分块时内容行范围可能与结果行号不一致。
- 仓库索引缓存写盘，文件频繁变动的仓库可能出现 stale_line_range 需重建索引。
- 独立效果未附基准测试数据；与 grep 等传统工具的定量对比缺失。
如何安装这个 Skill？
1) 安装 vexor：pip install vexor（也支持 pipx、uv），或从 GitHub Releases 下载无需 Python 的独立二进制。2) 运行 vexor init 完成引导配置（设置提供商与 API 密钥，也可用 VEXOR_API_KEY 等环境变量）。3) 如需在 Claude Code 中安装 Agent Skill：vexor install --skills claude（Codex 用 vexor install --skills codex）。技能源文件位于仓库 plugins/vexor/skills/vexor-cli/SKILL.md。
如何使用这个 Skill？
技能的核心是指示代理优先用 vexor 做基于意图的文件发现。典型命令：vexor "api client config"（默认搜索当前目录）；vexor search "config loader" --path . --mode code --ext .py（代码模式）；vexor search "user authentication flow" --path docs --mode outline --ext .md --format porcelain。加 --content 可在结果中直接读取匹配源码，省去后续读文件。精确标识符搜索效果弱时，运行 vexor config --rerank hybrid 融合词法与语义匹配。配置问题用 vexor doctor 或 vexor config --show 排查。
这个 Skill 与同类方案有什么区别？
README 明确将 Agent Skill 与 MCP 服务器定位为同一核心能力的两种接入方式（技能驱动完整 CLI，MCP 暴露为原生工具），建议每个代理二选一。源材料未与其他具体搜索工具做对比。