Semble 怎么给 Agent 省代码搜索 Token：grep 对照与接入清单
Agent 用 grep 搜代码会把整文件读进上下文，Semble 按 README 宣称可少约 99% token。本文对照 grep 烧 token 的原因、成本场景表与接入 checklist。
semble 怎么给 agent 省代码搜索 token——核心做法是：用本地语义检索只返回相关代码块，而不是让 Agent 先 grep 再整文件 read。根据 Semble 官方 README 的 benchmark，在同等召回水平下，相对 grep+read 平均约少 99% 的检索 token；97% 召回只需约 2k token，而 grep+read 要到 85% 召回往往需接近 100k 上下文。Semble 跑在 CPU 上，无需 API Key，可作为 MCP 工具、CLI 或独立 sub-agent 接入 Claude Code、Cursor、Codex 等。
Semble 是什么，为何能省 Token
Semble 是 MinishLab 开源的面向 Agent 的代码搜索库（MIT）。它用 tree-sitter 做代码感知分块，再用 Model2Vec 嵌入 + BM25 双路检索，RRF 融合后按定义位置、标识符词干、文件一致性等信号重排，毫秒级返回最相关片段。
与「搜关键词 → 打开匹配文件 → 整段读入上下文」的 grep 工作流不同，Semble 的 search 工具直接返回 file_path、行号区间和 snippet 文本。官方 savings 统计把「匹配文件总字符数 − 返回片段字符数」除以 4 估算节省 token——基准假设 Agent 会把 grep 命中的文件整份读入，这是多数 coding agent 探索陌生仓库时的常见路径。
接入形态有三种，可按团队习惯选一种或组合：
| 形态 | 适用场景 |
|---|---|
| MCP Server | Agent 原生调用 search / find_related |
| CLI + AGENTS.md | 脚本化、无 MCP 的 Agent |
| sub-agent | 把搜索委托给专用 semble-search 子代理 |
安装最快路径：uv tool install semble，再跑 semble install 自动检测已装 Agent 并写入 MCP 配置。索引首次构建后缓存到本地，文件变更时增量更新，平均仓库索引约 500 ms、单次查询约 1 ms（README 数据，CPU）。
为什么 grep 会烧掉 Agent 上下文
grep 本身输出的匹配行通常不长，但 Agent 拿到行号后几乎总会继续 read_file——因为单行匹配不足以理解函数边界、调用链和类型定义。一次探索往往连锁读多个大文件：
- 宽匹配：
grep -r "auth"命中测试、配置、文档、legacy 目录，Agent 为「不漏」会逐个打开。 - 整文件注入：500 行的
middleware.ts可能只有 20 行与问题相关，整文件仍占满上下文窗口。 - 多轮叠加：Agent 不擅长第一次就写准 grep 模式，常见路径是「grep → 读文件 → 发现不对 → 换关键词 → 再读」——每轮都把历史上下文带上。
- 长会话复利：同一 session 里前面读过的文件片段留在上下文，后续每次 request 都重复计费。
这和 Claude Code 配额烧太快 里「脏上下文 + 重复带入历史」是同一类成本：搜索阶段占的 token，往往比最终改代码还多。Semble 试图把「探索」压缩成「只拿需要的块」，从入口减少无效阅读。
grep vs Semble：成本场景对照表
下表按仓库规模 × 探索深度估算该用哪条路。数字侧重点是 Semble README 的 token efficiency benchmark（相对 grep+read）；场景判断供落地决策，不是精确计费公式。
| 场景 | 仓库规模 | grep 典型代价 | Semble 预期 | 建议 |
|---|---|---|---|---|
| 单文件已知路径 | 任意 | 低：直接 read 一行范围即可 | 过度：索引有固定成本 | 不用 Semble，精确 read |
| 熟悉模块内改 bug | 中小 | 中：1–2 次 grep + 局部 read | 低–中：语义 query 一次命中 | grep 够用；Semble 可选 |
| 陌生仓库找入口 | 中大型 | 高：多轮 grep + 整文件 read | 低：README 称 97% 召回 ~2k token | 优先 Semble |
| 跨语言/monorepo | 大 | 很高：路径分散、误匹配多 | 中–低：chunk 级返回 | 优先 Semble |
| CI/脚本一次性查 | 任意 | 低：stdout 不进 LLM | 低：CLI 输出可控 | 两者皆可，看是否过 LLM |
| 离线/air-gapped | 任意 | 无网络依赖 | 需首次拉 Hugging Face 模型 | 预缓存索引后再断网 |
一句话：当你不知道「该 grep 什么字符串」时，Semble 的 ROI 最高；当你已经知道文件和行号，硬上语义搜索反而多一步索引。
什么时候值得接入 Semble
值得上的信号：
- Agent session 里「搜索 + 读文件」占了大头 token，且任务本身是理解代码而非生成大量新代码。
- monorepo、多语言、生成代码/测试目录多，grep 误匹配导致 Agent 在无关文件里打转。
- 团队已用 MCP 扩展 Agent 能力，加 Semble MCP 的边际成本低（
semble install --agent claude --type mcp --yes可脚本化）。 - 需要
find_related：从已知位置扩散语义相似块，比手写 ripgrep 模式省脑力。
不必上的情况：
- 仓库很小（几十个文件），Agent 直接列目录 + read 更便宜。
- 只写全新业务代码、几乎不读既有实现。
- 环境不允许下载嵌入模型（首次需网络拉 potion-code-16M-v2）。
- 搜索需求是精确字面量（某个常量字符串、UUID），BM25+grep 往往更准，Semble 的语义优势不明显。
Semble 本地运行，不经过第三方 API，索引内容不出网——但若你同时接了抓取外部 URL 的 MCP，搜索省下的 token 可能被别的工具又烧回去；接 MCP 时建议对照 MCP ANSI 转义注入风险 收紧工具面，避免「省搜索、亏安全」。
Semble 接入 Checklist
按顺序勾选，适合第一次在生产仓库启用：
| 步骤 | 动作 | 验收 |
|---|---|---|
| 1 | 安装 uv + uv tool install semble |
semble --version 有输出 |
| 2 | 跑 semble install，选 MCP / instructions / sub-agent |
Agent 工具列表出现 search |
| 3 | 根目录添加 .sembleignore，排除 dist/、生成物、巨型 fixture |
索引体积与误匹配下降 |
| 4 | 在 AGENTS.md / CLAUDE.md 写清：先 Semble search，禁止未命中就整库 grep | Agent 首步行为可观测 |
| 5 | 用真实任务试 3 次：semble search "认证流程" . 对比手动 grep 的 token |
记录 semble savings 输出 |
| 6 | MCP 客户端重启（升级后 uv cache clean semble） |
工具调用不报版本冲突 |
| 7 | 大仓库首次索引放非峰值时段（若走按量计费 Agent） | 避免索引 + 推理叠峰 |
| 8 | 与 避免 AI Slop 式乱读乱改 的项目规则并用 | 搜索省 token，输出仍要约束质量 |
.sembleignore 语法同 .gitignore，可用 !*.proto 强制纳入默认跳过的扩展名。远程仓库支持 git URL，但 CI 里更建议缓存 ~/Library/Caches/semble/（macOS）或设置 SEMBLE_CACHE_LOCATION。
常见踩坑：Agent 仍习惯 grep——需要在规则里写死「探索阶段只允许 semble search，grep 仅用于已确认的字面量」；否则 savings 统计会好看，实际上下文没少。
常见问题
Semble 能完全替代 ripgrep 吗？
不能。精确字符串、正则、git blame 这类任务仍适合 ripgrep/IDE。Semble 补的是「不知道搜什么、但要找语义相关实现」的 Agent 探索阶段。
99% 省 token 是实测还是营销数字？
来自 Semble README 的 benchmarks 方法论：在 ~1,250 条查询、63 个仓库上对比 grep+read 的 token–recall 曲线。你的仓库若 Agent 本来就不会整文件 read，实际节省会低于 99%；若探索路径更「贪婪」，节省可能更高。以 semble savings 本地统计为准。
和 IDE 内置 @codebase 语义搜索有何不同？
IDE 索引通常服务补全和聊天，Agent CLI 未必能调用同一索引。Semble 的优势是Agent 原生 MCP/CLI、可脚本化、跨 Cursor/Claude Code/Codex，且 benchmark 公开。若你只用某一 IDE 且其 Agent 已能精准 @file，重复装 Semble 收益有限。
首次索引慢怎么办？
README 称平均仓库 ~500 ms。超大 monorepo 首次可能到数秒；索引缓存后增量更新。可把 node_modules 等确保被 .gitignore 排除，必要时 .sembleignore 再加一层。