Shebe：给 coding agent 一个本地 BM25 代码搜索层
AI coding agent 找代码时，很多问题并不需要语义搜索。
如果你已经知道函数名、错误信息、API 名、配置键、日志片段，最有效的做法往往还是关键字检索。问题在于，普通 grep 很快，但输出是平铺的：一堆文件、一堆行号、一堆需要 agent 再读、再筛、再总结的上下文。对人来说还能扫过去；对 agent 来说，常常会变成几轮工具调用和一大段 token 消耗。
今天想记下的 shebe-oss/shebe，切的是这个很朴素的缝隙：给 coding agent 一个本地、快速、基于 BM25 的代码搜索层。它不是向量数据库，也不是代码理解平台，而是一个 Rust 写的 CLI 和 MCP server，让 agent 在本地仓库里拿到排序后的相关结果、引用候选、文件预览和分页读取能力。
按 GitHub repository page、README、Releases page、Tags page、commit history、LICENSE 和 GitHub 页面 metadata 在 2026-07-15 能核验的公开信息，shebe-oss/shebe 当前有 35 stars、3 forks。仓库主语言是 Rust，许可证是 Apache-2.0。仓库创建于 2025-12-28 03:51:24 UTC，最近公开 push 是 2026-07-13 17:52:06 UTC。默认分支 main 当前最新提交是 7166911，提交时间 2026-07-13 17:52:04 UTC。GitHub Releases 页当前最新版本是 v0.5.8，Tags 页也显示最新 tag 为 v0.5.8，日期是 2026-02-03。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | shebe-oss/shebe |
| 定位 | 面向 coding agent 的本地 BM25 代码搜索 CLI 和 MCP server |
| Stars | 35 |
| Forks | 3 |
| 主语言 | Rust |
| 许可证 | Apache-2.0 |
| 仓库创建时间 | 2025-12-28 03:51:24 UTC |
| 最近 push | 2026-07-13 17:52:06 UTC |
| 最新 main 提交 | 7166911，2026-07-13 17:52:04 UTC |
| Latest GitHub release | v0.5.8，2026-02-03 |
| 最新 tag | v0.5.8 |
| 核心入口 | brew tap shebe-oss/tap、brew install shebe、shebe index-repository、shebe search-code、shebe-mcp |
| 关键词 | BM25、local-first、MCP、code search、ranked results、Rust |
为什么不是再做一个向量搜索
Shebe README 的问题设定很明确：开发者的大量代码搜索价值来自精确词。你要找的可能就是 AuthorizationPolicy、SubstitutionFormatter、某个 error message、某个 config key。这个时候，让 agent 先把问题改写成 embedding query，再从语义相似度里猜答案，不一定比关键词模型更直接。
BM25 的优点是朴素、可解释、便宜。它知道 query term 在文档里出现在哪里，也会考虑词频和文档长度。对代码仓库来说，这种排序比纯 grep 更适合给 agent 使用：不是把所有匹配行一次性倒出来，而是先给一组相关性更高的候选，让 agent 读更少的上下文。
Shebe 的定位也没有试图吃掉所有工具。README 里把它放在 grep/ripgrep 和 Serena 这类结构工具之间：grep 适合精确正则和小仓库，Serena 适合 AST/LSP 级别的符号重构，而 Shebe 适合大仓库、多语言、需要排序结果和布尔查询的内容搜索。这个边界感比“万能 AI 搜索”更可信。
对 agent 友好的接口，而不是只给人看的 CLI
Shebe 提供两类入口。人可以直接用 CLI：
shebe index-repository ~/envoy envoy-v1
shebe search-code envoy-v1 "accesslog format"agent 则可以通过 MCP 使用它。README 里列出的能力包括 search_code、find_references、find_file、read_file、preview_chunk、list_dir、reindex_session 等，总数是 14 个 MCP tools。这里有一个很实际的设计点：结果不是只返回大段文件内容，而是控制在较小 token 范围内，并支持分页。
这对 coding agent 很重要。普通工具链里，agent 经常先用 grep 找到几十个文件，然后逐个 read file，最后再自己判断哪些真的相关。Shebe 把“排序候选”和“低 token 预览”提前放进工具层，等于减少 agent 在搜索结果上做机械筛选的时间。
README 给出的性能目标也很偏工程化：毫秒级查询、几千到上万文件每秒的索引速度、每次查询几百 token 级别的输出。这里我不会把 benchmark 当成所有项目上的保证，但这些指标说明作者关心的不是 demo，而是 agent 在真实代码库里跑工具时的成本。
本地优先，代价也很清楚
Shebe 的安装路径比较简单。macOS 和 Linux 可以用 Homebrew tap：
brew tap shebe-oss/tap
brew install shebeLinux x86_64 也有手动下载的 release 包。索引时需要先把仓库 clone 到本地，再用 index-repository 建 session。README 明确写了两个限制：必须先有本地 clone，不支持直接给远程 URL；BM25 不是语义相似度，所以 login 不会自然匹配到 authenticate。
我反而喜欢这种限制写得很直。它告诉你什么时候该用 Shebe，什么时候不该用。查已知符号、API、错误文本、配置项、跨语言关键字，它会很合适；如果你想问“哪里实现了用户身份校验这种概念”，那就应该补上语义搜索或结构工具。
本地优先也是它的价值之一。索引和查询都在本机完成，不需要把私有仓库送到云端。对很多团队来说，代码搜索不是能不能做的问题，而是数据能不能出边界的问题。Shebe 的取舍刚好让它适合先在私有仓库里小范围试验。
和 grep、Serena 的关系
Shebe 的 WHY_SHEBE 文档拿 Istio 和 Eigen 做了两个 refactoring 场景对比。它想证明的不是“grep 不好”，而是：当 agent 要把一批搜索结果变成修改计划时，原始 grep 输出需要很多人工式综合；LSP/AST 工具在某些语言或宏场景下又可能不完整；BM25 加引用类工具能在中间提供更容易消费的候选集。
这个判断值得保留一点警惕。benchmark 总是会选对自己有利的任务，代码库语言、query、符号形态都会影响结果。但它提出的问题是真实的：agent 的瓶颈往往不是工具运行慢，而是工具输出太散，导致后续读取和判断变贵。
所以我不会把 Shebe 看成 ripgrep 的替代品。对人类来说，rg 仍然是第一反应。Shebe 更像是给 agent 准备的 ranked search adapter：它把本来需要 agent 自己整理的 grep 结果，变成更结构化、更省 token 的工具响应。
适合什么场景
第一类场景，是大仓库里的已知词搜索。比如错误码、日志片段、API 名、feature flag、配置 key、类型名。你知道要找什么，但不想让 agent 读太多无关匹配。
第二类场景，是多语言仓库。Shebe 不依赖某一种 LSP，README 强调 polyglot search。对 Go 加 YAML、TypeScript 加配置文件、Rust 加文档这类仓库，内容检索有时比纯符号工具更稳。
第三类场景，是你已经在用 MCP agent。Shebe 的价值不只是 CLI，而是能成为 Claude Code、Codex、其他 MCP client 的一个检索后端，让 agent 在修改前先查清引用和上下文。
第四类场景，是私有代码库。没有 SaaS account、没有云端索引，对安全边界敏感的团队更容易接受。
需要注意的地方
第一，项目还很小。35 stars、3 forks，虽然最近 main 分支在 2026-07-13 还有文档更新，但外部使用反馈仍然有限。采用时最好固定版本，先在非关键仓库测。
第二，BM25 不是语义理解。你需要让 agent 使用更好的 query，必要时加同义词、API 名、错误文本或具体类型名。README 也建议在真正需要语义相似度时搭配向量工具。
第三，它要求本地 clone 和索引 session。这比直接丢 GitHub URL 给云服务多一步，但换来的是本地控制和更低数据外流风险。
第四，最新 GitHub release v0.5.8 是 2026-02-03，而 main 分支在 2026-07-13 还有更新。使用时要区分 release 包和 main 分支文档状态，别默认 README 里的所有新说明都已经进入稳定 release。
总结
Shebe 有意思的地方，是它选择了一个不花哨但很实用的位置：不是让 agent “理解一切”，而是先把已知关键词搜索这件事做得更适合 agent 消费。
如果你的 coding agent 经常在大仓库里为了一个符号、一个错误字符串、一个 API 名来回 grep，再读一堆文件筛上下文，shebe-oss/shebe 值得试一下。它小、边界清楚、完全本地，适合作为 MCP 工具箱里那个“先把相关代码排好序”的基础层。