Semlith

为什么选择 Semlith

在大型代码库中工作的 Agent，要么读取过多内容，既缓慢又昂贵；要么猜测该打开哪个文件，而这通常会猜错。它真正需要的是能回答问题的少数代码片段。Semlith 会为你找到它们。

• 混合搜索。 每次查询都会同时使用向量索引（含义）和关键词索引（确切名称），再融合两者的排名。How does retry backoff work 和 EMBED_BATCH 都能找到正确的代码块。
• 基于同一轮扫描构建的代码图谱。 定义会成为节点，调用、导入和重新导出会成为边，并为每条边标注其支持程度。你可以询问某个函数被谁调用、修改后会影响什么，或两个符号如何关联。
• 始终保持最新。 文件保存时，监视器会重新生成其嵌入。无需构建步骤，也无需担心索引与工作树不同步。
• 专为本地使用而设计。 无需 API 密钥，查询时也不会联网，除非你使用 semlith cloud login 登录 Semlith Cloud——这是一项独立的托管服务。门户仅绑定到 127.0.0.1。只有模型权重和加速包需要下载，且每项下载都由摘要固定校验；--airgap 会在连接建立前拒绝所有出站请求。
• 专为 Agent 打造。 MCP 服务默认列出八个工具，总计十六个；运行 semlith setup 即可在 Agent 客户端中注册，并提供一份记录每次检索及其节省 token 数量的账本。
• 不止支持代码。 PDF、Office 文档、笔记本和 Markdown 都会作为文本读取，图片也能按其所展示的内容进行搜索。

安装

一条命令，无需 Rust 工具链。

macOS 和 Linux

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/semlith/semlith/main/install.sh | sh

Windows

irm https://raw.githubusercontent.com/semlith/semlith/main/install.ps1 | iex

安装程序会为你的机器选择对应版本，验证发行版 SHA256SUMS 上的 ed25519 签名，检查归档文件是否与其匹配，将其解压到 ~/.semlith/bin，然后运行 semlith setup。Setup 会将 Semlith 添加到你的 PATH，下载嵌入模型，为每个具有注册 CLI 的 Agent 客户端注册 Semlith，并将守护进程安装为登录服务。你可以随时再次运行 semlith setup 修复安装；--yes 会采用所有默认选项。

变量	作用
SEMLITH_VERSION	安装指定的发行版标签。
SEMLITH_HOME	安装到 ~/.semlith 以外的位置。
SEMLITH_NO_SERVICE=1	跳过登录服务。

你也可以运行 cargo install semlith，或从发行版页面获取归档文件。 semlith upgrade 会将二进制文件替换为最新发行版；Semlith 不会自行检查更新。

要求。 使用 64 位机器，运行 Apple silicon 上的 macOS、x86_64 或 aarch64 上的 Linux，或 x86_64 上的 Windows（Windows PowerShell 5.1 即可）。 Linux 归档文件会在二进制文件旁附带 libonnxruntime.so，只需要 glibc 2.34 或更高版本以及 libstdc++（GLIBCXX_3.4.22）。Debian 12、Ubuntu 22.04、RHEL 9 和 Amazon Linux 2023 均符合要求。不支持 Intel macOS，因为 ONNX Runtime 已不再为其提供发行版。

验证安装程序

安装程序会将二进制文件写入 ~/.semlith/bin（在 macOS 和 Linux 上权限为 700），并在 Linux 上将 libonnxruntime.so 写在其旁边。归档文件通过三项检查前，不会写入任何内容。SHA256SUMS 必须带有项目的 ed25519 签名，并使用 ssh-keygen -Y verify 验证（需要 OpenSSH 8.1 或更高版本；macOS、当前 Linux 发行版以及 Windows 10 及更高版本均已提供）。归档文件的 SHA-256 必须与之匹配。如果 gh 在你的 PATH 中，还会验证由此仓库的发行工作流签署的 GitHub 工件证明。签名缺失或错误都会导致安装停止；semlith upgrade 也会使用相同密钥校验发行版，该密钥内置于二进制文件中，并由 semlith --version 标明。curl 仅使用 https 和 TLS 1.2 或更高版本；脚本只有在完整下载后才会运行。 v0.40.0 之前的发行版均未签名，因此这些安装程序不会安装它们。

运行前查看安装程序：

curl --proto '=https' --tlsv1.2 -fsSLO https://github.com/semlith/semlith/releases/latest/download/install.sh
less install.sh
gh attestation verify install.sh --repo semlith/semlith
sh install.sh

在 Windows 上，运行 irm https://github.com/semlith/semlith/releases/latest/download/install.ps1 -OutFile install.ps1，查看文件，然后运行 powershell -ExecutionPolicy Bypass -File install.ps1。

手动验证归档文件：

echo 'semlith-release ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICMTHiHMzeSHzzc+8UDZHUzJcvb6XGUBb+TJdFes91xm' > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I semlith-release -n file -s SHA256SUMS.sig < SHA256SUMS
grep "  semlith-<tag>-<target>.tar.gz$" SHA256SUMS | shasum -a 256 -c
gh attestation verify semlith-<tag>-<target>.tar.gz --repo semlith/semlith

快速开始

cd ~/src/ripgrep
semlith index .                                   # one store, and the model (~52 MB) downloads once
semlith search "where is a file detected as binary"
semlith neighbors search_parallel                 # callers and callees
semlith start                                     # the daemon and the portal

$ semlith search "where is a file detected as binary" -k 1
1. 0.083 vf  GUIDE.md:735-746
   binary files:

   1. The default mode is to attempt to remove binary files from a search
      completely. ...

$ semlith neighbors search_parallel
callers (2)
  main via defines (extracted)  crates/core/main.rs:44  · call at line 166
  run via calls (resolved)  crates/core/main.rs:78  · call at line 90
callees (25)
  matcher via calls (resolved)  crates/core/flags/hiargs.rs:379  · called at crates/core/main.rs:177
  search_worker via calls (resolved)  crates/core/flags/hiargs.rs:705  · called at crates/core/main.rs:176
  ...

每个命中项都是一个 path:start-end 定位符，可交给编辑器或 Agent；vf 表示向量列表和关键词列表都找到了它。文档的回答方式相同。

## 在 Agent 中使用

semlith setup     # registers each agent client that has a registration CLI
semlith doctor    # checks each client can actually reach it, and says how to fix it if not

semlith setup 会在每个已安装且提供注册 CLI 的客户端中，以用户级别注册 MCP 服务；12 个文档列出的客户端中有 6 个符合条件。其余 6 个需要配置文件，semlith setup --register-all 会为你写入该文件，而 semlith doctor 会检查每个客户端。每个配置段都会针对 tests/clients.rs 中的二进制文件运行，docs/clients.md 列出了所有客户端及其 HTTP 传输配置。Setup 还会安装 Semlith Agent Skill、一个引导钩子（当 Agent 即将使用 grep 时，建议调用 Semlith），以及一个只读研究 Agent。

semlith mcp 通过 stdio 提供 MCP 服务，守护进程则通过 HTTP 在 /mcp 提供相同的工具，并由 Agent 密钥保护（semlith key show）。默认列出 8 个工具，因为每个工具定义都会在每次请求中消耗令牌；设置 SEMLITH_MCP_TOOLS=all 可列出全部 16 个工具。

工具	解答的问题
semlith_search	答案在哪里？返回路径、代码片段、所属符号以及查找方式。
semlith_brief	一次调用即可获取一个问题所需的全部信息，包括代码片段、文本以及一层调用方和被调用方，并受令牌预算限制。
semlith_read	读取一个代码片段或一个符号，不包含周边内容。
semlith_symbol	这个符号定义在哪里？history: true 可显示它过去的定义。
semlith_neighbors	哪些内容会调用它？它又会调用哪些内容？
semlith_impact	所有能到达它的内容，以及涉及的文件。
semlith_files	索引了哪些文件？
semlith_stats	每个存储库中保存了什么？
semlith_path、semlith_trace	两个符号如何连接？以调用链或证据的形式呈现。
semlith_pattern	对一种语言应用 tree-sitter 结构模式。
semlith_index、semlith_add、semlith_forget	在对话中更改存储库。
semlith_report	从账本、索引和图中生成五种报告之一。
semlith_languages	lang 接受的语言名称。

直接运行 semlith mcp 会打开所有已注册的存储库，因此一个问题可以跨多个代码库查询。它支持 MCP 2026-07-28、2025-11-25、2025-06-18 和 2024-11-05，每个版本都由 tests/mcp.rs 中的会话验证。在官方 MCP 注册表中，它的名称为 mcp-name: io.github.semlith/semlith

门户

semlith start 会运行一个守护进程，由它管理所有存储。它持有每个存储的写锁、监视其文件夹、为你保存的内容重新生成嵌入，并在 http://127.0.0.1:7365 提供门户。包含会话令牌的 URL 只会打印一次，输出到 stdout。docs/portal.md 介绍了每个页面。

搜索。混合结果，并逐项注明找到结果的列表。	图谱。调用方、被调用方、影响范围和路径。
索引运行。实时显示各设备的速率，并可暂停和停止。	账本。记录每次检索以及节省的令牌。

它不在网络上。 守护进程仅绑定到 127.0.0.1，没有可更改此设置的标志。每个页面和 /api/ 路由都需要本次运行专属的会话令牌，该令牌通过 Semlith-Token 请求头发送；缺少令牌时，响应为 401。Agent 密钥只能访问 /mcp。响应会携带值为 'self' 的 Content-Security-Policy，不会发送 CORS 头，而且门户加载的每个字节都已编译进二进制文件。--airgap 会在连接建立前拒绝所有出站请求，包括下载未缓存的模型和工具包、运行 semlith upgrade、获取价格表、访问 Semlith Cloud 以及运行 semlith add。隐私页面会根据运行中的守护进程验证这些声明，完整说明见 docs/security.md。

工作原理

files ──chunk──> text ──embed──> vectors ──quantize──> index/*.tvim  (turbovec)
                  │
                  └──parse──> symbols, edges ─────────> store.db      (SQLite)

query ──embed──> vector ──search shards──┐
      ──keywords──> FTS5 ────────────────┴──fuse──> ranked spans ──> enclosing symbol

• 读取。 文件会按照人们实际看到的文本来读取。13 种格式各有专用读取器（PDF、Word、PowerPoint、Excel、笔记本等）。其他内容均按 UTF-8 读取，并切分为与行对齐、最长 800 个字符的片段。Markdown 片段会连同标题路径一起生成嵌入，代码片段则会连同其所属定义一起生成嵌入。
• 嵌入。 通过 ONNX Runtime 使用 granite-embedding-small-english-r2（int8，384 维，约 52 MB），并在每个存储中固定使用。守护进程还会在 Apple 芯片的 Neural Engine 和 GPU（Core ML、WebGPU 或 CUDA）上生成嵌入；每条处理通道都会在处理首批数据前，使用已知答案进行验证。图像通过 CLIP ViT-B/32 转换到第二个向量空间，并按图像所呈现的内容匹配，而非依靠 OCR。
• 存储。 index/ 保存 turbovec 分片，每个分片包含 65 536 个量化向量；store.db 保存片段文本、范围、符号、边、账本以及内容哈希，用于增量重新索引。保存内容时只会重写一个分片。
• 图谱。 46 种语言均包含边。每条边的类型为 extracted（由文件本身明确确定）、resolved（只有一个候选）、ambiguous（有多个候选，并注明数量）或 inferred（仅按名称匹配）。除非传入 --all-edges，否则 semlith path 不会跨越无法确切定位的名称。

完整说明见 docs/architecture.md。

命令

命令	作用
semlith index [PATHS...]	将路径编入存储；重新运行时仅嵌入发生变化的内容。--each 为每个路径分别创建存储，--projects <DIR> 为每个仓库创建一个存储。
semlith watch [PATHS...]	文件保存时重新嵌入。
semlith start	守护进程：让每个存储保持最新，并在 127.0.0.1:7365 提供门户和 /mcp。
semlith search <QUERY>	混合搜索。-k、--json、--path/--ext/--lang（可重复；以 ! 开头表示排除）、--prefer code|docs、--exact 用于搜索正则表达式所在行及其定义。
semlith brief <QUESTION>	在 --budget 个令牌（默认 4000）内，提供代码片段、其文本以及一跳范围内的调用方和被调用方。
semlith read <TARGET>	一个代码片段（src/store.rs:1041-1080）或一个符号。
semlith symbol、neighbors、impact、path、trace	图：定义、调用方和被调用方、影响范围、调用链、证据。
semlith pattern <QUERY> --lang L	tree-sitter 结构模式。
semlith stats、files、languages、models	查看存储包含的内容；files --tree 显示未编入索引的内容及原因。
semlith refused、scan	查看未编入索引的文件及原因；查看依据今天的规则会被拒绝、但已保留的文件。
semlith add <URL>	将一个 https URL 获取到存储中。不爬取、不使用凭据、不访问私有地址。
semlith forget、compact、drop	移除文件、回收失效字节而不重新嵌入、删除存储。
semlith adopt、trust	将存储移入存储主目录；允许一个位于其外部的存储。
semlith ledger、report、schedule、prices	检索历史记录、五种格式的报告、定时报告、价格表。
semlith mcp、hook、key	通过 stdio 使用 MCP、引导钩子、HTTP Agent 密钥。
semlith setup、doctor、upgrade	安装和修复、诊断各个客户端、替换二进制文件。
semlith accel	查看用于嵌入的设备：CPU（始终启用，可由 SEMLITH_CPU_CAP 限制）、Neural Engine、GPU，以及实验性的 CUDA、TensorRT、OpenVINO 和 llama.cpp 通道。
semlith cloud	连接到 Semlith Cloud，这是一项独立的托管服务。在运行 semlith cloud login 前，不会有任何内容访问网络。

semlith <command> --help 会说明每个标志。

存储位置。 每个存储位于 ~/.semlith/stores/<name>，并列于 ~/.semlith/registry.json 中，因此 semlith mcp 和 semlith start 无需任何标志 即可找到所有存储。命令会依次从 --store 或 SEMLITH_STORE、语料库旁的 .semlith、覆盖当前目录的已注册存储中选择存储；若都没有，则会创建一个。

会编入索引的内容。 给定路径下的所有内容，但不包括被 .gitignore 忽略的 文件和隐藏文件、二进制文件、超过 8 MiB 的文件、解压后超过 32 MiB 的 归档文件，以及生成目录或供应商目录。始终跳过 node_modules；若 target、 build、dist 和 vendor 位于其清单文件旁边，也会被跳过，除非设置了 SEMLITH_DEFAULT_IGNORES=0。凭据绝不会被编入索引，灰色地带由你决定。

检索账本

每次检索都会记录在其所属存储中，无论检索是通过 MCP、CLI 还是门户由 Agent 发起。每一行都保存查询、客户端、会话、命中结果以及读取的内容。 每一行都带有前一行的哈希，因此 semlith ledger --verify 可以发现被编辑或删除的行。账本数据保存在本地，默认开启，可通过 --no-ledger 或 SEMLITH_LEDGER=0 关闭。

它在本仓库上的节省情况。 对 src/ 的存储，针对本仓库的检索测试套件提出 全部 107 个问题并运行 semlith brief，然后运行 semlith ledger --verify。 每个得到回答的问题平均向 Agent 发送 3 982 个令牌，而完整读取这些答案提及的 4.1 个文件则需要 105 132 个令牌。按存储自身的分词器计算，覆盖率为 100 %，令牌用量减少了 26 倍。这是一个上限，因为同一个文件若被两个答案提及，就会被计算两次。

基准测试

针对 53 份公开文档提出 127 个问题后，一个配备 Grep、Glob 和 Read 的 Opus Agent 仅有 63 % 的概率找到相关段落，而它给出的 127 条最佳引文中，有 41 条在其所指的文档中根本不存在。它找到了文件名，却无法读取文件，于是编造了看似可信的内容。安装 Semlith 后，找到率升至 98 %，126 条引文中没有一条是编造的。在单仓库代码检索中，使用强模型时它没有帮助；无论是否使用 Semlith，Opus 的得分都是 92 %。

公开代码检索基准测试由 bench/scorecard/ 运行，于 2026 年 10 月在一台 M1 MacBook Air 上完成，并按实测结果发布，包括其他工具胜出的情况。所有表格、图表以及用于复现各项数据的命令，都在基准测试页面上。

基准测试	semlith	基线	实例数
SWE-bench Verified，正确文件进入前 10 名	76.8 %	47.0 %，先 grep 再读取	500
SWE-bench Lite，正确文件进入前 10 名	72.3 %	47.3 %，先 grep 再读取	300
SWE-bench Verified，找到首个正确文件所需的中位 token 数	224	15 491，先 grep 再读取	500
CodeRAG-Bench DS-1000，NDCG@10	0.260	0.158，BM25	513
Agent（Opus），每个正确答案的成本	$0.065	$0.072，仅 grep	50 × 3 次运行
文档（PDF、Office、EPUB 等），在 4k token 内找到段落	116/127	34/127，rga	127
Agent（Opus）检索上述文档时找到段落	124/127	80/127，仅 grep	127
真实会话中，发送的 token 数与读取的完整文件相比	少 75.2 倍		1,575 次检索

Semlith 并非在所有场景中都胜出。在包含 20 个实例的竞品样本中，Semble 的 hit@1 和 hit@10 略胜一筹；在 CodeRAG-Bench 的 RepoEval 上，BM25 优于 Semlith；而由于内置了 Grep，Opus 很少主动使用 Semlith。基准测试页面列出了这些结果以及 RepoBench-R。

数字

覆盖范围，从代码中读取。tests/readme.rs 会在其中任何一项与其来源不一致时导致构建失败。

可搜索并绘图的语言	46
边类型	6
带读取器的文档格式	13
图像类型	5
MCP 工具	16
CLI 命令	36
Agent 客户端，每个设置代码块都会在 tests/clients.rs 中针对二进制文件运行	12
预构建目标	4

在配备 4 个性能核心 + 4 个能效核心的 Apple 芯片笔记本电脑上测得，并附上可重现每项结果的命令。docs/performance.md 包含完整表格。

700 / 7 000 / 70 000 个块时的热搜索，峰值 RSS 低于 240 MB	16.2 / 37.9 / 159.1 ms	cargo test --release --test measure -- --ignored --nocapture
磁盘上的编辑变为可搜索，监视器正在运行	1.24 s	docs/performance.md
M1 Air 上的索引速度：神经网络引擎 / 通过 Core ML 使用 CPU 和 GPU	229.8 / 62.7 块/s，p10	docs/performance.md
运行 60 s 后的守护进程内存，七个存储已打开	465 MB	footprint -p <pid>
监视器空闲 60 s 的 CPU 使用时间	低于 1.0 s	同上
一个文件发生更改	重写 1 个分片	cargo test --release --test shards -- --ignored --nocapture
tools/list	2 633 字节，八个工具；向 Opus 请求添加 1 323 个 token	cargo test --release --test retrieval -- --ignored
检索，107 个问题中的 30 个封存问题	hit@1 24/30，hit@3 27/30，hit@8 29/30，零差异；标识符 11 个中有 11 个位于前三名	同上
单次搜索，不启用 / 启用重排序	8.2 ms / 132.2 ms，针对包含 300 个文件的存储	同上
回答一个问题，brief 对比先搜索后读取	1.00 次调用 vs 2.54 次，1 112 个 token vs 725 个	同上
调用边解析	62 % 已确定	同上
macOS arm64 二进制文件	125 435 312 字节（119.6 MiB）	ls -l target/release/semlith
Linux glibc 最低版本	GLIBC_2.34	objdump -T semlith runtime/libonnxruntime.so

峰值内存不会随语料库增大，因此无论索引多少内容，都应预留约 600 MB。查询延迟则会随语料库增大，因为向量扫描是线性的。

已知限制

• 每个存储仅允许一个写入者。当守护进程或 semlith watch 占用某个存储时，针对该存储运行第二个 semlith index 会退出并指出占用者。
• 首次索引速度受模型限制：在 M1 的神经网络引擎上约为 230 块/s，在 CPU 和 GPU 上为 63 块/s，仅用 CPU 时为 30 块/s。后续运行只会为更改的内容生成嵌入。在 macOS 上，仅用 CPU 的处理通道在登录服务中的运行速度约为终端速度的 60 %，这是因为 launchd 对 Agent 线程的调度方式所致。
• 在 Mac 上，除非运行 semlith accel on gpu-beside-ane，否则 GPU 不会与神经网络引擎同时生成嵌入。CUDA 仅在 Linux x86_64 上运行，Windows 上的 NVIDIA 显卡则通过 WebGPU 生成嵌入。
• macOS 上的新二进制文件会再次请求访问 Documents 等文件夹；在用户响应提示之前，位于这些文件夹中的存储会一直等待并显示 running。
• 大于 SEMLITH_INDEX_MEMORY 的存储会在每次查询时从磁盘读取分片，因此如果存储能放入内存，请提高预算。
• 默认模型仅支持英语，并在创建存储时固定。图像搜索不是 OCR。
• 搜索筛选器使用 SQLite GLOB（不支持正则表达式），而 --lang 根据扩展名进行映射，从不读取文件内容。多存储搜索会合并排名，而不是联合排名。默认不启用交叉编码器重排序（SEMLITH_RERANK=on），因为它会使搜索耗时增加约 16×，而在 k=1 时，77 个问题中仅多答对两个。
• 二进制文件未经 Apple 公证，也未通过 Authenticode 签名。每个版本都会附带由 ed25519 签名的 SHA256SUMS 和 GitHub 工件证明。没有 ARM64 Windows 或 Intel macOS 构建版本，并且 semlith upgrade 只会替换 ~/.semlith/bin 中的二进制文件。

文档

文档	内容
docs/portal.md	门户的每个页面和控件。
docs/clients.md	12 种 Agent 客户端的设置配置段以及 HTTP 传输。
docs/architecture.md	各部分如何协同运作，以及背后的原因。
docs/performance.md	每项测量数据及其对应的命令和日期。
docs/models.md	嵌入模型，以及如何选择模型。
docs/security.md	威胁模型和线路上传输的内容。
docs/compatibility.md	什么是契约，以及 0.x 版本的承诺。
CHANGELOG.md	各个版本中的变更。

贡献

欢迎贡献。CONTRIBUTING.md 介绍如何构建、CI 会运行哪些检查、哪些内容不在范围内；AGENTS.md 则为编码 Agent 提供相同的信息。所有人都应遵守行为准则。 要报告安全问题，请参阅 SECURITY.md，而不要提交 issue。

先前工作

Semlith 的向量索引基于 Ryan Codrai（MIT 许可）的 turbovec，它实现了 Amir Zandieh、Majid Daliri、Majid Hadian 和 Vahab Mirrokni 在论文 “TurboQuant：以接近最优失真率进行在线向量量化” 中提出的 TurboQuant。TurboQuant 与数据无关。它会随机旋转每个向量，并单独量化每个坐标，无需训练步骤。这正是每次保存文件后都要刷新的索引所需的特性。首个文件加入前无需收集任何数据，语料库增长时也无需重建；添加的向量即可用于搜索。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。

模型权重会在运行时根据各自的许可证下载。默认模型 ibm-granite/granite-embedding-small-english-r2 使用 Apache-2.0 许可证；CLIP ViT-B/32 模型对、WebGPU 插件（MIT 许可证）以及 CUDA 包获取的 NVIDIA 库也各有其许可证。请参阅 docs/models.md。