sweet-search：给 AI agent 的本地代码搜索糖衣
AI coding agent 找代码时，经常会退回到一个很朴素的循环：先 grep，再读文件，再 grep，再读更多文件。
这个循环能工作，但不便宜。grep 返回的是字符串命中，不是答案；agent 还要自己判断哪些文件值得打开、哪些命中只是噪音、同一个函数的调用链是不是已经看完整。代码库越大，命名越不一致，这个过程越容易把上下文塞满。对人类来说，搜索只是定位动作；对 agent 来说，搜索结果的形状会直接影响后续推理成本。
今天想记下的 mrsladoje/sweet-search，就是围绕这个缝隙做的小工具。它把本地代码搜索包装成 agent 更容易消费的六类接口：search、grep、find、semantic、trace、read。README 里的说法很直白：不要只把原始 grep 输出交给 agent，而是返回已经排序、压缩、带预算意识的结果。它还提供可选 MCP server，以及面向 Claude Code、Codex、Gemini CLI、Cursor 的 agent prompt 注入，让 agent 在动手改代码前先养成更稳的搜索反射。
按 GitHub repository API、README、release API、tags API、commits API 和 languages API 在 2026-07-12 能核验的公开信息，mrsladoje/sweet-search 当前有 21 stars、0 forks。仓库主语言是 JavaScript，许可证是 Apache-2.0。仓库创建于 2026-02-06 18:14:57 UTC，最近 push 是 2026-07-08 22:16:31 UTC。默认分支 main 当前最新提交是 5d84770b，提交时间 2026-07-08 22:16:26 UTC。GitHub Releases 页标记的 latest release 是 v2.6.9，发布时间为 2026-07-03 10:18:00 UTC；Tags 页当前最新 tag 是 v2.6.17，日期为 2026-07-08。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | mrsladoje/sweet-search |
| 定位 | 面向 AI coding agent 的本地代码搜索与检索工具 |
| Stars | 21 |
| Forks | 0 |
| 主语言 | JavaScript |
| 许可证 | Apache-2.0 |
| 仓库创建时间 | 2026-02-06 18:14:57 UTC |
| 最近 push | 2026-07-08 22:16:31 UTC |
| 最新 main 提交 | 5d84770b，2026-07-08 22:16:26 UTC |
| Latest GitHub release | v2.6.9 |
| 最新 tag | v2.6.17 |
| 核心能力 | CLI、MCP server、hybrid retrieval、indexed grep、semantic search、trace/read 工具、agent prompt 注入 |
不是让 agent 更会 grep，而是减少它需要 grep 的次数
sweet-search 的安装路径很像一个普通 CLI：npm install -g sweet-search，进入仓库后执行 sweet-search init 和 sweet-search index，之后就可以直接问类似 “where do we validate JWT tokens?” 这种自然语言问题。默认用法不要求 API key，README 强调索引和模型都在本机运行。
它真正有意思的地方，不是“又做了一个代码搜索命令”，而是把输出面向 agent 重新设计了一遍。README 把六个工具拆得很清楚：search 做通用检索，grep 做更快的字符串命中，find 找文件，semantic 处理自然语言到代码，trace 看调用/关系，read 给出受控的文件阅读入口。对 agent 来说，这比一个巨大 grep 输出更容易接入，因为不同阶段可以用不同工具，而不是把所有问题都塞进 shell。
这种设计很贴近日常痛点。agent 改一个 bug 前，最需要的不是全仓库里所有包含 validate 的行，而是“最可能相关的几段代码，以及为什么它们相关”。如果搜索工具能按 token budget 返回结果，并且帮它区分关键词、语义和结构关系，agent 就少一些盲读文件的冲动。
hybrid retrieval 和本地索引是主线
sweet-search 的 README 明确写了 hybrid retrieval：BM25F lexical、dense semantic、structural graph signal 会在查询时融合，然后再 rerank。它也把 indexed grep 当作一等能力，而不是只做 embedding。对代码搜索来说这很关键，因为“语义相近”并不总是比精确符号更可靠。函数名、配置键、错误码、环境变量这类东西，很多时候就是要精确命中。
项目里同时有 JavaScript、Rust、Python、Shell 和 Objective-C 代码。GitHub languages API 显示主语言是 JavaScript，但仓库里还有 crates、native、mcp、packages、core 等目录，说明它不是纯前端脚本。README 提到本地 reranking、SIMD kernel、GPU accelerated indexing、Apple Metal、CUDA、CoreML Neural Engine 和 CPU fallback。这些实现细节不用全盘相信成性能承诺，但至少说明作者在把它当作搜索引擎做，而不是只拼一个向量库 demo。
另一个值得注意的点是增量索引。README 强调索引会跟随 working tree，包括未提交改动。对 agent workflow 这很重要，因为 agent 经常在一个还没提交的分支上连续修改多个文件。如果搜索只看上一次完整索引，agent 可能会读到旧结构；如果索引能跟上当前工作区，后续搜索就更接近实际状态。
agent prompt 注入有点激进，但方向对
sweet-search 不只是给一个命令，然后等用户自己教 agent 怎么用。init 会把 tool-routing prompt 注入 CLAUDE.md、AGENTS.md、GEMINI.md、Cursor rules 等位置，也能注册 session-start prewarm hook，并给 Claude Code 安装 /sweet-index skill。这个做法有点激进，因为它会改项目里的 agent 指令文件；但从工具目标看，这是合理的：如果 agent 没有明确搜索纪律，很快又会回到 grep 加乱读文件。
Tags 页最近几版也能看出作者在调 agent 行为。v2.6.17 的 tag message 重点是 P2 fix-surface agent guide、trace correctness 和 C++ graph coverage；v2.6.16 则在调 verdict-gated trust agent guide。这些不是普通用户会关心的 release headline，但对 AI coding workflow 反而有价值：项目把“agent 看到搜索结果后下一步该怎么做”也当成产品的一部分。
我会把这点视为 sweet-search 的特色，也视为采用时的 caveat。它不是一个完全中性的 grep 替代品，而是带有一套明确 workflow 假设的工具。你如果已经有自己的 AGENTS.md 规范，最好先在小仓库里试，确认注入内容不会和现有工作流冲突。
MCP 让它不只服务某一个编辑器
README 提到 sweet-search 可以提供 MCP server，同时默认也能作为 CLI 使用。这比只做某个编辑器插件更稳一点。CLI 适合 Codex、Claude Code 这类能跑 shell 的 agent；MCP 适合希望把搜索能力作为结构化工具暴露给客户端的环境；prompt 注入则处理“什么时候该用它”的策略问题。
我更看重这种分层：搜索引擎本身、本地索引、agent 调用接口、agent 行为提示，分别解决不同问题。很多 AI coding 辅助工具只做最后一层，写一堆提示词告诉模型“请先搜索”，但底层仍然只有 grep。sweet-search 至少尝试把底层检索也补上。
这种分层对团队也有实际意义。一个项目可以先只把 CLI 装给本地 agent 用；如果效果不错，再考虑把 MCP server 接到更统一的 agent 环境；如果不喜欢自动注入 prompt，也可以保留手动调用路径。小工具最怕一上来就要求整套迁移，sweet-search 的入口相对可拆。
适合什么场景
第一类场景，是你已经在用 AI coding agent，而且发现它经常为了找上下文浪费大量 grep/read 回合。sweet-search 的目标正是把这些回合压缩成更有结构的搜索结果。
第二类场景，是代码库有一定规模，传统 grep 命中太多，但又不想把源码交给外部 SaaS 代码搜索。sweet-search 的默认路径是本机索引、本机模型，对私有仓库试验更友好。
第三类场景，是你想让 agent 同时拥有关键词、语义和结构关系的检索入口。grep、semantic、trace 和 read 分开暴露，比只给一个自然语言搜索框更可控。
第四类场景，是你愿意折腾 agent prompt。sweet-search 的一部分价值来自它对搜索纪律的规定，如果你完全不希望工具改 AGENTS.md 或类似文件，就要小心使用 init 选项。
需要注意的地方
第一，项目很小。21 stars、0 forks，虽然提交和 tag 很活跃，但生态反馈还少。采用时应该固定版本，先在非关键仓库里做对照测试。
第二，release 状态有一点不直观。GitHub Releases 页的 latest release 是 v2.6.9，但 Tags 页已经到 v2.6.17。文章里我把两者分开写，就是因为自动化脚本、包版本和 GitHub release badge 可能看到不同的“最新”。
第三，本地模型和索引不是零成本。README 提到 CPU、GPU、CoreML 等路径，也提到模型下载和 cache footprint。对大仓库来说，第一次索引、后续增量维护、磁盘占用都要实测。
第四，prompt 注入要审查。它会影响 agent 的搜索策略，可能是优点，也可能和团队已有规范冲突。尤其是已经有严格 AGENTS.md 的项目，不能无脑 init。
小结
sweet-search 有意思的地方，是它没有把问题停在“给 agent 一个更快 grep”上，而是试图把代码搜索变成 agent loop 里更明确、更省 token、更可审计的一组动作。
如果你的 agent 经常在代码库里迷路，或者你想测试本地 semantic/code graph 检索能不能减少无效文件阅读，mrsladoje/sweet-search 值得放进试验清单。它还非常早期，但抓住了一个真实问题：AI agent 的代码能力，常常先受限于它能不能找到该读的代码。