Semble

uv tool upgrade semble   # upgrade
uv cache clean semble    # for MCP users (restart your MCP client after)

对于沙盒或脚本化环境，可使用 --agent，并可选用 --type，以跳过提示：

semble install --agent claude --type mcp subagent --yes

--agent 接受一个或多个 Agent ID（例如，claude、codex、pi）；--type 接受 mcp、instructions、subagent、skill 或 all（默认值为除 skill 之外的所有类型）；--yes 跳过确认提示（若要完全以非交互方式运行，必须指定 --agent）。

Semble 会读取 .gitignore 和 .sembleignore 文件来确定要索引的文件。这两个文件都使用标准 gitignore 语法，其模式会合并。.sembleignore 可让你添加 Semble 专用规则，而无需修改 .gitignore。规则会递归应用，因此子目录中的 .sembleignore 会对该目录树生效。

**排除文件：**按与 .gitignore 相同的方式添加模式：

# .sembleignore
generated/     # exclude generated dir
*.pb.go.       # exclude Go protobuf files

**包含默认扩展名之外的文件：**在扩展名模式前加上 !，即可强制包含 Semble 默认不会索引的文件：

# .sembleignore
!*.proto       # include Protobuf files
!*.cob         # include COBOL files

运行 semble file-types 可查看每种内容类型会索引哪些扩展名。未列出的扩展名（包括 .json 和 .csv 等数据文件）默认不会被索引，但可以像上面那样使用 ! 模式强制包含。

无论忽略文件中的设置如何，Semble 始终会跳过一组常见的非源代码目录（例如 node_modules/、.venv/、dist/、build/、__pycache__/ 等）。

semble savings 会显示 Semble 在所有搜索中节省的 Token 数量：

semble savings

  Semble Token Savings
  ════════════════════════════════════════════════════════════════════════

  Total saved:  ~714.2M tokens  (94%)
  Total calls:  14.3k
  Efficiency:  ███████████████████████░  94%

  By Period
  ────────────────────────────────────────────────────────────────────────
  Period             Calls           Saved  Ratio
  ────────────────────────────────────────────────────────────────────────
  Today                198    ~1.4M tokens  ███████████████████████░  95%
  Last 7 days        13.1k  ~707.2M tokens  ███████████████████████░  94%
  All time           14.3k  ~714.2M tokens  ███████████████████████░  94%

  By Call Type
  ────────────────────────────────────────────────────────────────────────
  #     Call type            Calls  Share
  ────────────────────────────────────────────────────────────────────────
  1.    search               14.1k  ████████████████    99%
  2.    find_related           205  █░░░░░░░░░░░░░░░     1%
  ════════════════════════════════════════════════════════════════════════

节省量按以下方式计算：对于每次调用，Semble 会记录包含已返回片段的唯一文件的字符总数，以及返回的片段的字符数。估算节省的 Token 数为 (文件字符数 − 片段字符数) / 4（每个 Token 按 4 个字符计算）。这是一个保守估算：基准是完整读取匹配到的文件，这也是编码 Agent 探索不熟悉的代码时常用的方式。

默认情况下，Semble 的节省统计数据和任何已保存的索引都存储在操作系统的缓存目录中（macOS 上为 ~/Library/Caches/semble/，Linux 上为 ~/.cache/semble/，Windows 上为 %LOCALAPPDATA%\semble\Cache\）。若要更改此位置，可以设置环境变量 SEMBLE_CACHE_LOCATION，指定目标缓存目录的完整路径，例如 ~/my-folder/my-caches/semble。

Semble 也可以作为 Python 库使用，以便通过编程方式访问，适用于构建自定义工具或将搜索直接集成到你自己的代码中。

from semble import ContentType, SembleIndex

# Index a local directory (code only, the default)
index = SembleIndex.from_path("./my-project")

# Index docs and prose (markdown, rst, etc.)
index = SembleIndex.from_path("./my-project", content=ContentType.DOCS)

# Index everything (code, docs, and config)
index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS, ContentType.CONFIG])

# Index code and docs together
index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS])

# Index a remote git repository
index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# Merge indexes from several repos into one (chunk paths are prefixed with the repo name)
index = SembleIndex.merge([("./service-a", SembleIndex.from_path("./service-a")), ("./service-b", SembleIndex.from_path("./service-b"))])

# Search the index with a natural-language or code query
results = index.search("save model to disk", top_k=3)

# Find code similar to a specific result
related = index.find_related(results[0], top_k=3)

# Each result exposes the matched chunk
result = results[0]
result.chunk.file_path   # "model2vec/model.py"
result.chunk.start_line  # 127
result.chunk.end_line    # 150
result.chunk.content     # "def save_pretrained(self, path: PathLike, ..."

当需要为大量文件建立索引时，CLI 和 MCP 服务会使用 4 个工作进程进行分块处理（SEMBLE_INDEX_WORKERS 用于设置进程数，0 表示禁用）。在 Python API 中，默认不启用此功能。要启用它，请设置 SEMBLE_INDEX_WORKERS，并在 if __name__ == "__main__": 代码块中调用 Semble，因为每个工作进程都会重新导入你的脚本。

• 自适应加权。 类似符号的查询（Foo::bar、_private、getUserById）会获得更高的词法权重，而自然语言查询则在语义和词法检索器之间保持平衡。
• 定义加权。 定义所查询符号（class、def、func 等）的片段，排名会高于仅引用该符号的片段。
• 标识符词干。 查询词元会被提取词干，并与片段中的标识符词干匹配，从而额外提高包含这些词干的片段的权重。例如，查询 parse config 会提高包含 parseConfig、ConfigParser 或 config_parser 的片段的排名。
• 文件关联性。 当同一文件中的多个片段与查询匹配时，该文件会获得加权，因此顶层结果反映的是文件整体相关性，而不是某个脱离上下文的片段。
• 噪声惩罚。 测试文件、compat//legacy/ 兼容层、示例代码和 .d.ts 声明存根的排名会降低，从而让规范实现优先显示。