ripsem

ripsem

实现这个功能的代码在哪里？

开始使用 · 用法 · 编码 Agent · 工作原理 · 故障排除

ripsem 是一款面向开发者和编码 Agent 的本地离线代码搜索工具。输入标识符、错误消息或对行为的普通描述，即可获取与之相关的函数和类型，并按相关性排序，同时显示名称和行号范围。

• 一条查询，支持各种提问方式。 对代码感知词元进行 BM25 排序，并结合本地嵌入模型计算向量相似度，合并为一个排名。包含标识符或错误消息中所有词项的代码块会排在前面。
• 答案就是声明。 每条命中都是一个完整函数或类型，带有名称，支持 17 种语言，因此阅读定义时不会与调用位置混淆。按名称搜索会定位到其声明，并显示对应行号和标签。
• 专为编码 Agent 打造。 使用 ripsem install claude-code、cursor、vscode 或 gemini，即可添加一个 MCP 服务，在 Agent 编辑代码时持续更新索引，并告知 Agent 何时使用它。
• 离线运行。 无需账号、API 密钥或服务。模型只需下载一次，然后在 CPU 上运行；索引则是仓库中的一个文件。

开始使用

1. 安装 ripsem：

   npm（任何平台）：

   npm install -g ripsem
   

   Cargo：

   cargo install --locked ripsem
   

   macOS 和 Linux，无需 npm 或 Rust：

   curl -fsSL https://raw.githubusercontent.com/Sadykhzadeh/ripsem/master/install.sh | sh
   

   Windows，无需 npm 或 Rust：

   irm https://raw.githubusercontent.com/Sadykhzadeh/ripsem/master/install.ps1 | iex
   

2. 在仓库中，向它提问：

   ripsem search "strip the auth header when redirecting to another host"
   

3. 使用 ripsem install claude-code、ripsem install cursor、ripsem install vscode 或 ripsem install gemini，让编码 Agent 执行同样的搜索（参见下文）。

在 Git 仓库中首次搜索，或在运行过 ripsem init 的目录中首次搜索时，会构建索引：它会下载模型（约 133 MB）一次，并为仓库生成嵌入。此后每次搜索都会为有变动的内容生成嵌入，因此结果始终不会指向已移动的代码。Windows 上若有 GPU，首次建立索引时会通过 DirectML 使用 GPU。

为什么不用 grep？

grep 回答的是“这个字符串出现在哪里”。如果你知道要找的字符串，这就是正确的问题。ripsem 适用于你知道代码的功能、却不知道它叫什么的情况：描述可以找到对应函数；标识符或错误消息也能找到精确匹配，因为词法检索会按字面内容识别它们。每条命中都是带名称的完整函数或类型，而非匹配行，因此读者或 Agent 无需打开文件，就能区分定义和调用位置。

安装

npm 和安装脚本会将最新 发行版中的预构建二进制文件放到你的 PATH 中，并先根据发行版的 SHA256SUMS 进行校验。脚本会将文件安装到 ~/.local/bin 和 %LOCALAPPDATA%\Programs\ripsem；可通过 RIPSEM_INSTALL_DIR 覆盖该路径。也可以手动解压发行版压缩包；在 Windows 上，请将 DirectML.dll 放在 ripsem.exe 旁边。

平台	运行环境
x86_64-unknown-linux-gnu	glibc 2.35、libstdc++ 12 和 OpenSSL 3 或更高版本：Ubuntu 22.04、Debian 12 及更高版本
aarch64-unknown-linux-gnu	64 位 Arm 上的 glibc 2.39、libstdc++ 14 和 OpenSSL 3 或更高版本：Ubuntu 24.04、Debian 13 及更高版本，例如 AWS Graviton；目前可通过安装脚本或压缩包安装，npm 暂不支持
aarch64-apple-darwin	Apple 芯片上的 macOS 13.4 或更高版本
x86_64-pc-windows-msvc	Windows 10 或更高版本，以及 Microsoft Visual C++ Redistributable

x86-64 版本中的嵌入运行时需要支持 AVX2 的 CPU（Intel Haswell、AMD Excavator 或更新型号）。二进制文件包含嵌入运行时和 tree-sitter；模型会在首次使用时下载。

cargo install 会从源代码构建，需要 Rust 1.92 或更高版本。构建会下载预构建的 ONNX Runtime，并且需要 C 和 C++ 编译器；在 Linux 上还需要 pkg-config 和 OpenSSL 头文件（Debian 和 Ubuntu 上为 build-essential pkg-config libssl-dev）。

带标签的发行版是稳定版本，npm、Cargo 和安装脚本都会安装最新版本。master 包含下一发行版的更改，列在 CHANGELOG.md 的 Unreleased 部分。

从检出代码构建最新发行版：

git clone https://github.com/Sadykhzadeh/ripsem
cd ripsem
git checkout "$(git describe --tags --abbrev=0)"
cargo install --locked --path .

省略 git checkout 会构建 master。

默认启用的 fastembed 功能会引入本地嵌入运行时。使用 --no-default-features 构建时，ripsem 会运行轻量级哈希后端，该后端按词匹配而非按含义匹配，测试套件使用的正是这一后端。

默认也启用的 treesitter 功能会按函数和类型边界对代码分块，而非使用固定行数窗口，并根据每个块所属的声明为其命名。结果类似于 src/auth/session.rs:40-72 fn Session::refresh，调用方无需打开文件即可区分定义和调用位置。对于无法放入单个块的函数，每个片段都会带上其名称。该功能支持 Rust、Python、JavaScript、TypeScript、Go、Java、C、C++、C#、Ruby、PHP、Scala、Kotlin、Bash、HTML、CSS 和 JSON；其他文件会按行数窗口切分。

hnsw 功能会为超过 500 000 个块的索引添加近似最近邻图。它只会改变向量分支收集候选项的方式；无论索引大小如何，词法分支和合并过程都保持不变。

Shell 补全

ripsem completions bash > ~/.local/share/bash-completion/completions/ripsem
ripsem completions zsh > ~/.zfunc/_ripsem
ripsem completions fish > ~/.config/fish/completions/ripsem.fish
ripsem completions powershell >> $PROFILE

用法

ripsem init                       # write .ripsem/config.toml
ripsem index                      # build the index (incremental on re-runs)
ripsem search "where is auth set up?"   # updates the index first
ripsem status                     # index size, counts, model, drift from the tree
ripsem status --json              # the same as JSON (schema ripsem/status/v1)
ripsem watch                      # keep the index in sync as files change

和 git 一样，除 init 外的所有命令都可以从任意子目录运行：它会使用最近的、包含 .ripsem 目录的父目录。--path <dir> 可以覆盖此设置。

索引不会纳入 git：.ripsem/.gitignore 会将其列出，因此 git status 只会显示 config.toml（可以提交）和该 .gitignore。如果文件不存在，ripsem 会创建它，且绝不会更改已有文件。

status 还会报告索引与文件之间的偏差程度。命中结果会带有文件建立索引时的 行范围，因此 tree: out of date: 3 changed, 1 new 会告诉你结果可能不再指向正确的行。偏差使用增量索引采用的同一内容哈希来衡量，因此计数恰好等于重建索引时会处理的内容。JSON 中会将其作为 index.drift （added/modified/removed）提供。

结果按合并后的排名顺序，以 path:start-end 的形式输出，并附带声明名称和代码片段。前三个命中结果会附带最多 40 行代码，因此无需打开文件即可阅读答案。覆盖相同行的记录（声明和其上方的文档，或相邻窗口）只会返回一次，因此 -k 5 表示五个不同的位置。显示的数值范围为 0 到 1：表示命中的含义超出此仓库中无关文本的程度，或查询词在文本中逐字出现的比例，取两者中较高的值。这个数值在排名列表中不会递增，因此设置阈值会保留排名靠前的结果。每个索引都会通过匹配与代码无关的查询来衡量自身的噪声基线，因此数值尺度会随仓库和模型而变化。

查询词无需加引号：ripsem search where is auth set up 与 ripsem search "where is auth set up" 的查询相同。

• -k <N> 设置结果数量（默认值为 10）。
• --json 将命中结果以 JSON 数组形式输出。每项包含 path、start_line、 end_line、score、kind 和 symbol（例如 fn 和 Session::refresh；如果命中位置不属于任何声明，则两者均为 null），以及 snippet。使用 --count-by-file 时，每项包含一个 path 和对应的 count。
• --in <subdir> 将结果限制在某个子目录中。相对路径从当前目录开始，与 shell 中的行为相同：在 src 中，--in auth 表示 src/auth，--in . 表示 src。也可以使用指向仓库内部的绝对路径。
• --context <N> 设置每个命中结果输出的代码片段行数（在终端中为 3 行， 输出到其他程序时为整个代码片段；0 表示只输出位置）。
• --min-score <SCORE> 仅保留匹配度较高的结果，适用于人类可读输出和 JSON 输出。
• --count-by-file 按文件输出命中数量，而不是输出命中结果。

模型

ripsem model list                 # show available models
ripsem model set bge-base-en-v1.5
ripsem index                      # rebuilds the index for the new model

模型	维度	磁盘占用	备注
bge-small-en-v1.5	384	~133 MB	默认
all-MiniLM-L6-v2	384	~90 MB	体积最小，嵌入速度最快
bge-base-en-v1.5	768	~436 MB	更大的英文模型
multilingual-e5-small	384	~470 MB	适用于其他语言的查询和注释
nomic-embed-text-v1.5	768	~550 MB	更大的英文模型，建立索引时最占内存

模型只会在首次使用时下载，之后所有操作都可离线进行。

与编码 Agent 搭配使用

ripsem install claude-code        # .mcp.json and a note in CLAUDE.md
ripsem install cursor             # .cursor/mcp.json and a rule in .cursor/rules
ripsem install vscode             # .vscode/mcp.json and .github/copilot-instructions.md
ripsem install gemini             # .gemini/settings.json and a note in GEMINI.md

install 会注册服务、写入 .ripsem/config.toml，并添加一条简短说明，告诉 Agent 搜索前先使用 search。在该目录中重启 Agent 后，它就可以直接调用 search。

服务会将同一条说明作为 MCP 指令发送。Claude Code 只有在模型查找 MCP 工具时才会加载工具描述，因此模型会从 CLAUDE.md 中的指令和说明了解到 search 的存在，以及何时使用它。

ripsem mcp 通过 stdio 使用 MCP，并提供一个 search 工具：必需参数为 query，还可以指定 path 以限定搜索范围、指定 limit（默认值为 5，最多为 50）以及 min_score。参数不符合架构要求时，会返回一条说明预期内容的工具错误，以便 Agent 修正调用。在包含 .ripsem 目录的目录中，服务会自行保持索引最新：首次启动时建立索引，并在 Agent 修改代码后重新嵌入代码。提前运行一次 ripsem index，即可在首次搜索前准备好索引。

其他 MCP 客户端也可以在各自的配置中添加相同的条目：

{
  "mcpServers": {
    "ripsem": { "command": "ripsem", "args": ["mcp"] }
  }
}

如果尚未安装 ripsem，客户端可以通过 npm 使用 "command": "npx", "args": ["-y", "ripsem", "mcp"] 启动它。

服务会从启动目录查找索引。若要将它指向其他位置的代码仓库，请在 args 中添加 "--path", "/path/to/repo"；install cursor 和 install vscode 会写入 "--path", "${workspaceFolder}"，由编辑器将其展开为项目路径。VS Code 将服务列在 servers 下，而不是 mcpServers 下。共享工作区根目录的客户端（例如从主目录启动服务的客户端）应将服务指向项目本身；--path 会覆盖工作区根目录。

配置

.ripsem/config.toml：

backend = "fastembed"
model = "bge-small-en-v1.5"
chunk_lines = 40
chunk_overlap = 8
max_chunk_lines = 50
max_file_kb = 1024
skip_generated = true
exclude = []

chunk_lines 和 chunk_overlap 用于设置纯文本文件以及没有解析器的语言所使用的行窗口大小。max_chunk_lines 限制单个语义分块的大小；较大的函数会被拆分。更改这三个设置中的任意一项后，下次运行 ripsem index 时都会重新对每个文件进行分块和嵌入。大于 max_file_kb 的文件会被跳过。exclude 接受 gitignore 风格的 glob 模式，并在 .gitignore 和可选的 .ripsemignore 之外生效。backend = "hash" 会匹配词语而非含义；未启用 fastembed 功能的构建版本会默认使用它。ripsem 不识别的键会作为错误报告。

skip_generated 会排除已提交但由机器生成的文件：锁文件、go.sum、*.min.js、*.min.css 和源映射文件。.gitignore 不会排除这些文件，因为它们是有意提交的，而且单个锁文件可能比所有手写内容加起来还大。将其设为 false 即可照常为这些文件建立索引。

工作原理

1. 遍历。 按照 git 查看文件树的方式读取文件树：应用 .gitignore、全局 gitignore 和 .ripsemignore 的规则，并排除二进制文件、大于 max_file_kb 的文件以及机器生成的文件。
2. 切分。 tree-sitter 会在函数和类型的边界处切分每个文件，并以声明为每个代码块命名。文档注释或文档字符串会成为同一声明的第二条记录，因为作者描述代码时使用的词语，代码本身很少会用到。
3. 嵌入并分词。 每个代码块都会由本地模型生成一个向量，以 int8 格式存储；同时生成一组词项，其中标识符会完整保留，也会按 snake_case 和 camelCase 的边界拆分。每个代码块还会列出其中包含的声明及其行号。
4. 搜索。 查询会经过两条检索路径，并通过倒数排名融合合并排名。包含查询中所有有效词项的代码块会排在最前，这让标识符和错误消息的搜索结果更可靠。无论查询是以代码形式输入声明名称，还是用文字拼出声明名称，声明它的代码块都会排在仅使用它的代码块前面，并报告该声明。在此之后，代码的排名高于测试（除非查询要求搜索测试），也高于描述代码的说明文字。
5. 保持更新。 索引是单个文件 .ripsem/index.bin。重新运行时，只会读取内容已更改的文件，并且只会嵌入文本已更改的代码块；更换模型或代码块设置则会重建索引。 ripsem watch 会在文件更改时保持索引最新，MCP 服务也会在索引重建后自动加载，无需重启。

故障排除

文件始终不会出现在结果中。 ripsem index --dry-run 会列出索引纳入的所有文件。如果文件符合 .gitignore、.ripsemignore 或 exclude 的规则，属于二进制文件或大于 max_file_kb，或者被 skip_generated 判定为机器生成文件，就会被排除。

结果指向了错误的行。 文件在建立索引后发生了更改。ripsem search 会在搜索前更新索引，ripsem watch 或运行中的 MCP 服务也会保持索引最新；ripsem status 会显示索引偏离当前状态的程度。

搜索提示索引是用其他模型构建的。 配置指定的模型或后端与索引不一致。ripsem index 会根据配置重建索引。

Agent 不会调用 search。 服务会随 Agent 启动，因此请在运行 install 后，于代码库中重启 Agent。在 Claude Code 中，/mcp 会列出已连接的服务。

首次建立索引需要一些时间。 程序会下载一次模型并嵌入每个文件，同时显示已嵌入的代码块数量和预计剩余时间。之后每次运行都只会嵌入已更改的代码。在 Windows 上，包含 256 个或更多代码块的任务会通过 DirectML 在 GPU 上运行，速度约为 CPU 的四倍；RIPSEM_NO_GPU=1 可强制使用 CPU，例如显卡驱动出现异常时。模型缓存在 Linux 的 ~/.cache/ripsem、macOS 的 ~/Library/Caches/ripsem 和 Windows 的 %LOCALAPPDATA%\ripsem\cache 中；RIPSEM_MODEL_DIR 可指定其他缓存目录。

ripsem.exe 在 Windows 上无法启动。 缺少 VCRUNTIME140.dll 或 MSVCP140.dll 表示尚未安装 Microsoft Visual C++ Redistributable： 运行 winget install Microsoft.VCRedist.2015+.x64 即可安装。缺少 DirectML.dll 表示解压归档文件时没有将其保留在 ripsem.exe 旁边。

质量

排名通过一组标注问题进行基准测试，涵盖四个真实项目和四种语言（Rust、Python、Go 和 TypeScript），每个项目都固定在一个发布标签上。问题分为人们实际搜索时使用的四种形式：用自己的话描述、标识符、输出中看到的消息，以及记错的名称。合并后的排名必须优于任一单独的检索器，至少在 86% 的问题中将答案排在前五位，并且读取到答案所需的内容不能比答案所在的文件更多。第二项测试会搜索这些项目中声明过的所有名称：对于至少 95% 的名称，首个命中必须是对应的声明，且名称必须正确；声明所在行的任何命中都不得带有其他名称。

cargo test --release --test retrieval_quality -- --ignored --nocapture \
  fusion_beats_either_retriever_alone a_declared_name_leads_to_its_declaration

首次运行会将这四个项目克隆到 target/corpora 并下载模型。CONTRIBUTING.md 介绍了如何衡量排名变更的效果。

许可证

Apache-2.0