起因

🔍作为开发者,你是否经历过这样的崩溃时刻:

💭 “那个处理支付的配置文件叫啥来着?在哪个目录?”
💭 “项目里肯定有处理图片上传的代码,但我不记得文件名了…”
💭 “新来的同事问我:'认证逻辑在哪?'我竟然答不上来…”

grep 和 find 要求你记住精确的关键词,IDE 搜索只能匹配字面文本,而我想要的是:

“用人话描述需求,AI 帮我找到相关文件”

于是我做了 Vexor 这个工具。

它能做什么?

先看效果,不用记文件名,用自然语言搜索:

# 传统方式:需要猜文件名
grep -r "auth" ./src | grep "config"

# Vexor:直接说需求
vexor search "用户认证配置"

搜索结果按语义相关度排序,不是简单的关键词匹配:

是的,它甚至能搜到 Markdown 文档里的相关章节!

核心亮点

🧠 语义理解,而非关键词匹配

使用向量嵌入技术理解文件内容的语义:

• 搜 “API 配置” 能找到 config_loader.py
• 搜 “数据库连接” 能找到 db_settings.json
• 搜 “部署文档” 能定位到 Markdown 的对应章节

⚡ 智能分块索引

不同类型文件用不同策略:

• Python/JS/TS: 按函数、类边界分块
• Markdown: 按标题层级索引
• 配置文件: 全文索引

🔌 灵活的模型选择

• 支持 OpenAI、Gemini 等云端模型
• 支持完全离线的本地模型(无需联网!)
• 可自定义 API 端点和代理

🤖 为 AI Agent 设计

专门优化了与 Claude、Codex 等 AI 编程助手的集成,让 AI 也能用语义搜索自主查找代码。

一个真实场景

前几天接手一个 2 年前的老项目,需要找支付回调处理逻辑:

# 我不记得文件名,只知道功能
vexor search "支付宝回调处理"

# 结果:
# src/payment/alipay_webhook.py  (0.945)
# src/services/payment_handler.py (0.892)

找到了! 如果用传统搜索,我可能要:

1. 在项目里 grep “alipay”
2. 再 grep “callback”
3. 然后一个个打开看…

Vexor 一步到位。

技术实现简述

简单说,Vexor 做了这几件事:

1. 文件解析: 根据类型智能分块(代码按 AST,文档按结构)
2. 向量化: 将每个分块转为高维向量
3. 索引构建: 增量式缓存,只重建变更部分
4. 语义检索: 用余弦相似度找最相关的文件

技术栈:

• 向量模型: OpenAI/Gemini/本地 E5 模型
• 代码解析: Python AST / Tree-sitter
• 缓存策略: 基于文件修改时间的增量更新

为什么你可能需要它?

✅ 大型项目维护 - 快速定位功能模块
✅ 代码交接 - 新人快速熟悉项目结构
✅ 文档检索 - Markdown 文档按语义查找章节
✅ AI Agent 增强 - 让 AI 助手也能智能搜索
✅ 跨项目搜索 - 在多个仓库间查找相似实现

开发状态

目前 v0.15.0 版本,功能已经比较完善:

• ✅ 核心语义搜索
• ✅ 多种索引模式
• ✅ 本地离线模型
• ✅ AI Agent 插件
• ✅ 独立二进制发行(无需 Python 环境)

下一步计划:

• 向量数据库支持(处理超大项目)
• VSCode / JetBrains 插件
• Web UI 界面

邀请体验

如果你:

• 👨‍💻 维护多个项目,经常"想不起文件名"
• 🔍 厌倦了 grep 的精确匹配限制
• 🤖 在用 AI 编程助手,想增强它的能力
• 🧪 对向量搜索技术感兴趣

欢迎试用并给个 Star ⭐

👉 GitHub: https://github.com/scarletkc/vexor
👉 PyPI: https://pypi.org/project/vexor/

安装超简单:

pip install vexor

反馈与贡献

这是我的第一个开源向量搜索工具,还有很多可以改进的地方:

• 🐛 遇到 Bug? 欢迎提 Issue
• 💡 有想法? 欢迎 Discussion
• 🔧 想贡献代码? 欢迎 Pull Request

或者,直接在命令行反馈:

vexor feedback  # 一键跳转反馈页面

---

如果这个工具能帮到你,请给个 Star ⭐ 支持一下!

你的 Star 是我持续开发的动力 💪

📌 项目地址: https://github.com/scarletkc/vexor
📦 截止发稿时的当前版本: v0.15.0
📄 许可证: MIT