Scan to join WeChat groupREADME
🚀 Shebe
Shebe是一款用于代码搜索的简单RAG服务，它借助快速的BM25全文搜索技术，为代码仓库提供支持，同时集成了适用于Claude Code的MCP工具。
🚀 快速开始
请参考 INSTALLATION.md。
✨ 主要特性
什么是Shebe？
Shebe提供代码的内容搜索功能，可通过关键词搜索在大型代码库中查找函数、API和代码模式。
主要特性如下：
- 查询延迟低至2ms
- 索引速度达2k - 12k文件/秒（0.5秒可索引6k个文件）
- 每次查询使用200 - 700个令牌
- 仅使用BM25算法，无需嵌入向量或GPU支持
- 全面支持UTF - 8编码（包括表情符号、中文、日文、韩文及特殊字符）
- 为Claude Code提供14种MCP工具（参考文档）
定位：通过内容搜索功能对结构化工具（Serena MCP）进行补充。
为何选择Shebe？
当开发者使用AI编码助手在大型代码库（6k + 文件）中重构符号时，通常面临着精度（基于LSP的工具）和效率（grep/ripgrep）之间的两难选择。Shebe试图消除这种权衡。
基准测试：在Istio（约6k个文件）中重构AuthorizationPolicy
| 方法 | 搜索次数 | 时间 | 令牌数 |
|----------|----------|------|--------|
| Shebe find_references | 1 | 2 - 3秒 | ~4,500 |
| Claude + Grep | 13 | 15 - 20秒 | ~12,000 |
| Claude + Serena MCP | 8 | 25 - 30秒 | ~18,000 |
Shebe通过单次调用返回带有置信度评分和模式分类的结果，实现了端到端时间快6 - 10倍，令牌使用量减少3 - 4倍。
详细的基准测试和工具比较请参考 WHY_SHEBE.md。
快速对比
| 能力 | Shebe | grep/ripgrep | Serena MCP | |------------|-------|--------------|------------| | 排序结果（BM25） | 是 | 否 | 否 | | 置信度评分 | 是 | 否 | 否 | | 支持非代码文件（YAML、md） | 是 | 是 | 否 | | 令牌效率 | 200 - 700 | 2,000 - 8,000 | 1,000 - 3,000 | | 速度（5k + 文件） | 2 - 32ms | 100 - 1000ms | 500 - 5000ms |
📦 安装指南
请参考 INSTALLATION.md 进行安装和设置。
💻 使用示例
常见任务
以下是完成特定目标的快速链接：
| 任务 | 工具 | 指南 |
|--------------------------|------------------------------------|------------------------------------------------------------------------|
| 安全重命名符号 | find_references | 参考文档 |
| 搜索多语言代码库 | search_code | 参考文档 |
| 探索陌生代码库 | index_repository + search_code | 快速入门 |
| 按模式查找文件 | find_file | 参考文档 |
| 查看带上下文的文件 | read_file 或 preview_chunk | 参考文档 |
| 更新陈旧索引 | reindex_session | 参考文档 |
工具选择指南
内容搜索（使用Shebe）
适用于通过关键词、模式和文本内容查找代码：
- "查找
authenticate的所有使用位置" - "查找限流的实现位置"
- "展示错误处理模式"
- "查找数据库连接配置"
结构化导航（使用Serena/LSP）
适用于精确的符号操作和类型信息查找：
- "转到
UserService的定义位置" - "查找
Handler特征的所有实现" - "在代码库中重命名
oldFunc为newFunc" - "展示此类的类型层次结构"
简单模式匹配（使用grep/ripgrep）
适用于在小型代码库中进行精确字符串匹配：
- "查找精确字符串
TODO:" - "统计
deprecated的出现次数" - "在少于1000个文件中进行一次性快速搜索"
外部信息搜索（使用网络搜索）
适用于查找文档和社区知识：
- "最新的React 19迁移指南"
- "特定错误的社区解决方案"
- "关于架构模式的博客文章"
Shebe + Serena 结合使用
可在不浪费令牌的情况下全面探索代码库：
1. Shebe: "查找authenticate的使用位置" -> 发现文件（2ms，300个令牌）
2. Serena: "转到定义位置" -> 导航到实现（精确）
3. Shebe: "查找相似模式" -> 发现相关代码（2ms，300个令牌）
📚 详细文档
入门指南
- INSTALLATION.md - 安装和设置指南
- 快速入门指南 - 为Claude Code提供5分钟设置指南
参考文档
- MCP工具参考文档 - 14种工具的完整API文档
- CONFIGURATION.md - 所有配置选项
- 性能基准测试 - 详细的性能数据
开发文档
- ARCHITECTURE.md - 开发者指南（代码修改位置和方法）
- CONTRIBUTING.md - 贡献指南
- CODE_OF_CONDUCT.md - 社区准则
- SECURITY.md - 安全策略和报告
🔧 技术细节
性能
在Istio（5,605个文件，以Go语言为主）和OpenEMR（6,364个文件，多语言PHP）上验证：
| 指标 | 结果 | |--------------------|--------------------------------------------------| | 查询延迟 | 2ms（所有查询类型一致） | | 索引（Istio） | 11,210文件/秒（5,605个文件用时0.5秒） | | 索引（OpenEMR） | 1,928文件/秒（6,364个文件用时3.3秒） | | 令牌使用量 | 210 - 650 令牌/查询 | | 多语言覆盖 | 单次查询支持 11种文件类型 |
详细的基准测试请参考 docs/Performance.md。
架构
仅支持MCP的设计
Shebe仅通过MCP协议访问，专为Claude Code集成而设计，无需HTTP服务器。
系统设计
+------------------+
| Claude Code |
+--------+---------+
| MCP (stdio)
+--------v---------+
| shebe-mcp |
| (14 tools) |
+--------+---------+
|
+--------v---------+
| Shared Storage |
| ~/.local/state/ |
| shebe/sessions/ |
+------------------+
开发者指南请参考 ARCHITECTURE.md。
故障排除
| 问题 | 原因 | 解决方案 |
|-------------------------------|----------------------------------|----------------------------------------------------|
| "Session not found" | 会话不存在或拼写错误 | 运行list_sessions查看可用会话 |
| "Schema version mismatch" | 会话来自旧版本的Shebe | 运行upgrade_session进行迁移 |
| 索引速度慢 | 磁盘I/O问题或文件过大 | 排除node_modules/、target/目录，检查磁盘 |
| 无搜索结果 | 会话为空或查询错误 | 使用get_session_info验证，检查查询语法 |
| read_file中出现"File not found" | 自索引以来文件已被删除 | 运行reindex_session进行更新 |
| 令牌使用量高 | 结果过多 | 减少k参数（默认值：10） |
详细的故障排除请参考 docs/guides/mcp-setup-guide.md。
📄 许可证
请参考 LICENSE。
🤝 贡献
我们欢迎贡献！详细的贡献指南请参考 CONTRIBUTING.md。
快速检查清单：
- 阅读 ARCHITECTURE.md 了解代码库指南
- 所有397个测试必须通过（
make test） - 无clippy警告（
make clippy） - 每行最大长度为120个字符
- 保持测试覆盖率超过85%（当前为86.76%）
- 每个功能分支提交一次
社区准则请参考 CODE_OF_CONDUCT.md。