这段时间持续看 AI coding agent 工具，会越来越明显地感觉到一个现实：

很多 token 并不是花在“推理”上，而是花在 agent 笨拙地读环境上。

它先 ls -R 一遍仓库，把一堆不该看的目录也带进来；然后 grep 一个词，匹配出几十处位置；接着又 cat 整个文件；最后构建一跑，几 MB 的 CI 或编译输出再糊进上下文。

如果你已经在高频使用 Codex、Claude Code 或 Cursor，这种浪费很快就会变成真实成本。

今天想记下的 johunsang/semble_rs，正好瞄准这条链路。它不是再做一个聊天壳，也不是要你起一整套服务，而是把 代码检索、代码树摘要、依赖影响分析、构建日志压缩 放进一个本地 Rust 二进制里，尽量让 agent 在真正展开源码前，先拿到更便宜的结构视图。

按 GitHub 仓库页、release 页、公开提交记录和 README 在 2026-07-01 能看到的公开信息，这个项目当前约有 136 stars、20 forks。仓库主语言是 Rust，代码许可证是 MIT。公开提交记录的起点是 2026-05-12，最近公开更新出现在 2026-06-02。最新 release 是 v0.9.1，发布时间为 2026-05-15。

项目概览

属性详情
仓库johunsang/semble_rs
定位面向 AI coding agent 的本地代码检索与上下文压缩 CLI
Stars136
Forks20
主语言Rust
公开提交起点2026-05-12
最近公开更新2026-06-02
最新版本v0.9.1
版本发布时间2026-05-15
代码许可证MIT
核心思路用更便宜的结构检索和日志摘要，减少 agent 盲读全文

它把“上下文预算”当成统一问题来处理

我觉得 semble_rs 最值得看的地方，不只是“又一个代码搜索工具”，而是它把几件原本分散的小痛点串成了同一个问题：

  • 仓库结构怎么先看轮廓；
  • 代码怎么先按语义找准块；
  • 变更前怎么先看依赖和影响面；
  • 构建和 CI 输出怎么先去噪。

README 对它的自我描述很直接：这是一个给 AI coding agent 用的 Rust 工具，用来替代一部分 grep、cat、read、ls，同时还能压缩 build 和 CI 输出。

这个判断挺准。

因为 agent 真正昂贵的地方，往往不是最后那次精读，而是前面这一连串粗暴探索：

  1. 先把目录树展开；
  2. 再全文搜索；
  3. 再打开整个文件；
  4. 再读一大段测试、构建或报错日志。

semble_rs 试图做的，就是把这些动作都换成更适合 agent 的窄输出。

tree、search、digest 三件套很实用

它最核心的几个入口分别是：

semble_rs tree ./my-project --symbols
semble_rs search "how is auth handled" ./my-project --outline
cargo build 2>&1 | semble_rs digest

这三类命令分别对应三种最常见的上下文浪费。

1. tree 解决的是“先别把整个仓库目录喊进来”

README 里讲得很清楚，真实项目里 ls -R 很容易把 .git/、target/、node_modules/ 之类的内容一起炸出来。对人都很吵，对 agent 更吵。

semble_rs tree 用同一套 gitignore-aware 索引来输出代码树，还可以：

  • 只看目录；
  • 限制深度；
  • 追加每个文件的顶层 symbol；
  • 按语言过滤。

README 自带的测量里，这个仓库自身的 tree 输出是 533 B，而 ls -R 是 398,101 B，自报可达 747× 的缩减。更大的 Python backend 场景里，也有几十倍量级的差距。

这类数字当然是项目作者自己的 benchmark，不该直接当成所有仓库的普遍结果，但方向是对的：

先把“目录地图”做薄，agent 才不至于在起步阶段就浪费上下文。

2. search 解决的是“别一上来就全文匹配 + 整文件展开”

semble_rs search 的核心思路不是只做关键词匹配，而是把几层机制叠在一起：

  • tree-sitter 分块；
  • BM25；
  • Model2Vec 静态 embedding；
  • RRF 融合；
  • 再加一层 code-aware rerank。

README 里还列了它的加权思路，比如：

  • symbol 样式的 query 会更偏 lexical；
  • 自然语言 query 会维持更平衡的混合检索；
  • 定义位置会被提升；
  • identifier stem、同文件命中、相邻 chunk、依赖关系也会参与排序；
  • test、legacy、.d.ts 之类容易制造噪声的区域会被降权。

我比较喜欢它输出层的设计，而不是只看检索算法本身。它提供了几种不同的输出模式：

  • --outline：先看结构签名；
  • --group：分目录看匹配；
  • --compact：精确看匹配行；
  • --json --strip：只有在真需要 chunk body 时再拿。

这套分层非常适合 agent。

因为很多时候你需要的不是“更强的搜索”，而是：

第一轮先拿便宜结果，第二轮再逐步展开。

它还提供了 find-related、plan、find-pattern。尤其 plan 这个命令挺有意思，当 agent 还不知道从哪里下手时，它会先跑一轮轻量搜索，然后建议下一步该用 --outline、--compact、deps 还是 impact。

这不保证它一定对，但至少是在把“探索顺序”也纳入工具设计。

它把构建和 CI 日志当成一等公民，这点很少见

很多项目只盯着代码检索，但 semble_rs 另一个很有辨识度的点，是 digest。

gh run view <id> --log-failed | semble_rs digest
pnpm install 2>&1 | semble_rs digest
pytest 2>&1 | semble_rs digest

README 的设计目标很明确：

  • 错误、file:line:col、traceback、panic stack、failed step body 要保留；
  • 进度条、重复信息、安装噪音尽量折叠。

它内置识别的格式不算少，覆盖 cargo、pnpm/npm/yarn/bun、tsc、pytest、go test、gradle、ruff、mypy、clang/gcc/cmake/make/swiftc、GitHub Actions 等。

如果你已经让 agent 参与调试，这个能力会很实用。

因为很多时候 agent 不是真的“不会看日志”，而是：

  • 日志太长；
  • 失败信号占比太低；
  • 上下文里混进太多无关进度信息。

README 里最夸张的一组 benchmark 是把一个真实的 GitHub Actions 失败日志从 3.3 MB 压到 35 KB，自报 -98.9%。这个数字同样应该当作项目自测参考，而不是普遍承诺，但它至少说明作者很明确地把 CI output compression 当成 agent 工作流的一部分，而不是附带功能。

deps 和 impact 很适合改代码前的“先看牵连面”

另一个我比较在意的点，是它没有停在“找到代码”。

semble_rs deps src/auth.rs ./my-project --tree
semble_rs impact src/auth.rs ./my-project --tree

这两个命令分别看：

  • 这个文件依赖了什么；
  • 哪些地方会受它影响。

而且 v0.9.1 还把 deps/impact --tree 做成了 ASCII dependency tree，可直接在终端里看，不依赖外部图形界面。

这件事对 agent 特别重要。

因为改代码前真正需要的，不只是“目标文件在哪”，而是：

  • 这是不是共享模块；
  • 改这里会不会牵到上游或下游；
  • 有没有隐蔽的 call-chain 或 import chain。

如果这一步仍靠人工拼 grep、IDE 引用跳转和零散 shell 命令，agent 很容易改到一半才发现影响面判断过晚。

“单一二进制、无 daemon、无 API key” 是它的重要性格

README 多次强调：

  • 一个二进制；
  • 不需要 daemon；
  • 不需要 API key；
  • 不需要 GPU；
  • 默认模型是 minishlab/potion-code-16M，首次运行会从 HuggingFace 下载大约 60 MB。

这点看起来普通，其实很关键。

很多面向 agent 的检索工具，一旦往更重的方向走，就会开始要求：

  • 长驻进程；
  • 单独索引服务；
  • 远端 API；
  • 额外的基础设施和权限管理。

semble_rs 的取向更克制。它更像一个：

尽量留在本地 shell 和一次性命令语义里的上下文前处理层。

对个人开发者和小团队来说，这种形态通常更容易真正进入日常工作流。

它也很诚实地暴露了边界

README 里有几个点让我觉得比较可信。

第一，它没有把 benchmark 写成神话。比如 100-query benchmark 里，项目自报：

  • Recall@1 为 70%；
  • Recall@5 为 90%；
  • Korean query 的 R@1 只有 10%。

也就是说，它并没有把自己包装成“任意语言、任意仓库、任意 query 都能稳定命中第一条”的万能检索器。

第二，它承认自己的工作方式依赖 chunking、静态 embedding、rerank 和依赖图这些 heuristics。plan 也被明确写成 guardrail，而不是 oracle。

第三，find-pattern 这种结构化查询还需要额外安装 ast-grep。这说明它不是试图把所有能力无脑塞进一个巨大黑箱，而是愿意在合适地方借外部工具。

这些边界反而是好事。因为对 AI agent 工具来说，最危险的不是能力少，而是把不确定性包装成确定性。

它适合谁

我觉得 semble_rs 特别适合这些场景：

  • 你已经在高频使用 Codex、Claude Code、Cursor 一类 coding agent；
  • 你想减少 grep + cat + ls -R + 满屏日志 这种上下文浪费；
  • 你更偏好本地 CLI，而不是再维护一个服务化检索系统；
  • 你希望在修改前先看依赖和影响面；
  • 你经常把 build、test、CI 输出喂给 agent，但又受不了噪音。

如果你只是偶尔手动搜一个函数名，IDE 本身也许已经够用；但如果你在认真经营 agent 工作流，这类“先压缩上下文再交给模型”的工具会越来越有价值。

小结

johunsang/semble_rs 值得看的地方，不只是它把语义代码搜索搬到了 Rust。

它真正抓住的是一个更现实的问题：

  • agent 不是只缺“更聪明的模型”；
  • 很多时候更缺的是“更便宜、更干净、更有层次的输入表面”。

tree 让仓库地图别一开始就膨胀，search 让代码定位别总靠全文乱扫，deps 和 impact 让修改前的牵连关系更清楚，digest 则把最容易失控的构建和 CI 输出压回可读范围。

如果你已经开始在真实项目里长期和 coding agent 协作，semble_rs 这种工具处理的就不是边缘问题，而是每天都会反复撞到的问题：

怎样先把上下文喂对，再谈让 agent 做对。