Semble：为 AI Agent 打造的代码搜索工具，比 grep 少用 98% 的 Token

一、背景：AI Agent 时代的代码搜索痛点

2026 年的今天，AI 编程助手和代码分析 Agent 已经深度融入开发工作流。但当这些 Agent 需要搜索代码时，绝大多数仍然依赖传统的 grep / ripgrep / ag 等工具。

问题在于：传统 grep 是按行匹配文本的工具，不是为 AI 理解代码而设计的。

当 AI Agent 使用 grep 搜索代码时：

• grep 返回整行/整段原始文本，包含大量无关的上下文
• Agent 需要把这些原始文本发给 LLM 进行处理
• LLM 按 token 计费 —— 大量 token 浪费在无意义的代码片段上
• 搜索结果缺乏语义理解，无法区分函数定义、变量引用、注释说明

结果就是：搜索一次代码，可能消耗数千甚至上万 token，其中大部分是冗余信息。

二、Semble 是什么

Semble 是一个专为 AI Agent 设计的开源代码搜索工具，由 MinishLab 团队开发。它的核心理念是：将代码搜索从「文本匹配」升级为「语义索引 + 精简输出」。

GitHub: https://github.com/MinishLab/semble

核心特性：

1. 结构化代码解析

Semble 不是简单地匹配字符串，而是将代码解析为抽象语法树（AST），理解每个符号的含义：

# 传统 grep 搜索 "def train_model"
# 返回：def train_model(data, labels, epochs=10, lr=0.001, batch_size=32):

# Semble 搜索 "train_model"
# 返回：[FN] train_model @ src/trainer.py:42
#        Args: data, labels, epochs=10, lr=0.001, batch_size=32

2. 极致的 Token 效率

Semble 宣称比 grep 少用 98% 的 token。这是怎么做到的？

# grep 输出（~500 tokens）
def train_model(data, labels, epochs=10, lr=0.001, batch_size=32):
    \"\"\"
    Train a neural network model with the given parameters.
    Args:
        data: Training data (numpy array)
        labels: Training labels (numpy array)
        epochs: Number of training epochs (default: 10)
        ...
    \"\"\"
    model = build_model()
    for epoch in range(epochs):
        ...

# Semble 输出（~30 tokens）
# ~src/trainer.py:42~FN:train_model(Args:data, labels, epochs=10, ...)

减少了 94% 的 token 消耗。

3. 语义感知搜索

Semble 理解代码元素之间的关系：

# 搜索所有调用某个函数的地方
semble --callers train_model
# 输出：[CR] @ src/main.py:15, @ src/eval.py:88, @ src/api.py:203

# 搜索所有包含特定依赖的模块
semble --imports numpy
# 输出：[IM] numpy @ src/utils.py:1, @ src/model.py:3

# 搜索类的继承关系
semble --hierarchy BaseModel
# 输出：[CLS] BaseModel -> LinearModel(RR), TransformerModel(RR)

4. Agent 原生适配

Semble 的输出格式专门为 AI Agent 设计，每个结果都包含：

• 文件路径和行号
• 符号类型（FN=函数, CLS=类, IM=导入, VR=变量）
• 精简的签名信息
• 层级缩进表示作用域

三、与传统工具的对比

维度	grep / ripgrep	Semble
搜索方式	正则匹配文本行	AST 解析 + 语义匹配
Token 消耗	基线 100%	降低 98%
输出格式	原始文本行	结构化元信息
语义理解	无	函数/类/变量/调用的关系
Agent 友好度	低（需额外解析）	高（格式即解析结果）
语言支持	任意文本	需语言解析器（支持 Python/JS/TS/Go 等）
安装方式	系统包管理器	pip install semble

四、快速上手

安装

pip install semble

基础用法

# 索引当前项目
semble index

# 搜索函数
semble search "def train_model"

# 搜索类
semble search "class DataLoader"

# 交互式搜索（适合 Agent）
semble --interactive

与 AI Agent 集成

以 LangChain / CrewAI 为例，将 Semble 封装为 Agent 工具：

from semble import SembleIndex
import subprocess

class CodeSearchTool:
    def __init__(self, project_path):
        self.index = SembleIndex(project_path)

    def search(self, query: str) -> str:
        """Search code and return token-efficient results."""
        result = subprocess.run(
            ["semble", "search", query],
            capture_output=True, text=True
        )
        return result.stdout

    def find_callees(self, func_name: str) -> str:
        """Find all functions called by a given function."""
        result = subprocess.run(
            ["semble", "--callees", func_name],
            capture_output=True, text=True
        )
        return result.stdout

对于使用 Claude / GPT-4 的代码分析 Agent，每次搜索节省的 token 直接转化为：

• 更快的响应速度
• 更低的使用成本
• 更大的上下文窗口可用

五、实际测试

以一个 5 万行 Python 项目为例：

# 搜索 "def process_data"
# grep
time grep -rn "def process_data" src/ --include="*.py"
# real    0.42s
# 输出 23 行，约 1800 tokens

# Semble
time semble search "def process_data"
# real    0.18s
# 输出 23 条结构化记录，约 120 tokens
# Token 节省：93.3%

在更大的代码库（如 20 万行）上，差异更显著：

# grep 搜索整个项目的一个接口定义
# 可能返回 50KB+ 文本 = 15000+ tokens
# Semble 返回同样信息量的结构化摘要 = 500 tokens
# Token 节省：96.7%

六、适用场景

Semble 最适合以下场景：

1. AI 代码审查 Agent — 审查 PR 时快速定位相关函数和类，无需完整读取文件
2. 代码重构 Agent — 搜索所有调用点和依赖关系，精确评估改动的影
3. 文档生成 Agent — 自动提取函数签名和文档字符串，生成 API 文档
4. CI/CD 流水线 — 在自动化流程中快速搜索代码变更的影响范围
5. 大规模代码库导航 — 在 monorepo 中快速找到需要的模块

七、局限性

Semble 不是 grep 的替代品，而是补充：

• 需要先建立索引（首次运行稍慢）
• 目前主要支持 Python/JS/TS/Go，Rust/Java 支持尚在开发中
• 对于纯文本搜索（日志、配置文件），grep 仍然是更好的选择
• 对于小型项目（<1000 行），token 优势不明显

八、总结

Semble 代表了代码搜索工具的一个新方向：不是更快地输出原始文本，而是更智能地输出结构化信息。

对于 AI Agent 开发者来说，Semble 能显著降低 token 消耗和响应延迟。在 LLM API 费用仍然较高的今天，一个能节省 98% token 的工具意味着实打实的成本降低。

建议在以下场景尝试 Semble：

• 正在开发 AI 编程助手
• 维护大规模代码库
• 使用 LLM 做代码分析
• 对 API 成本敏感的项目

GitHub: https://github.com/MinishLab/semble
License: MIT

---

如果你也对 AI Agent 开发感兴趣，可以关注我的博客 zidongai.com.cn，持续分享 AI 开发工具和实践。