osgrep

减少 Token 消耗，节省时间。专为你的 AI Agent 设计的语义搜索引擎。

一款像 grep 一样好用的自然语言搜索工具。快速、本地化，且专为 AI 编码 Agent 构建。

语义化： 查找概念（例如“事务是在哪里创建的？”），而不仅仅是匹配字符串。
调用图追踪（Call Graph Tracing）： 使用 trace 映射依赖关系，查看谁调用了谁。
角色检测： 区分 ORCHESTRATION（高层逻辑）和 DEFINITION（类型/类）。
本地与私有： 通过 onnxruntime-node 实现 100% 本地 Embedding。
自动隔离： 每个代码仓库都会自动拥有独立的索引。
Agent 友好： 提供包含符号、角色和调用图的原生输出。

快速入门

安装
```
npm install -g osgrep
```
设置（推荐）
```
osgrep setup
```
预先下载 Embedding 模型（约 150MB）。如果跳过此步骤，模型将在首次使用时自动下载。
搜索
```
cd my-repo
osgrep "where do we handle authentication?"
```
首次搜索时会自动对仓库进行索引。 每个仓库都会自动隔离并拥有各自的索引。切换仓库时无需任何手动配置，直接使用即可。如果后台服务已启动（osgrep serve），搜索将通过热启动的守护进程进行；否则将回退到按需索引模式。
追踪（调用图）
```
osgrep trace "function_name"
```

查看谁调用了该函数（上游依赖）以及它调用了什么（下游依赖）。非常适合进行影响分析和理解代码流。

要查找代码库中的符号，请使用：

osgrep symbols

在我们的公开基准测试中，osgrep 可以节省约 20% 的 LLM Token，并提升 30% 的检索速度。

Claude Code 插件

运行 osgrep install-claude-code
打开 Claude Code (claude) 并询问有关代码库的问题。
强烈建议在使用插件前先对代码库进行索引。
插件的钩子（hooks）会在后台自动启动 osgrep serve，并在会话结束时自动关闭。Claude 将自动使用 osgrep 进行语义搜索，你也可以主动引导它使用。

Opencode 插件

运行 osgrep install-opencode
打开 OC (opencode) 并询问有关代码库的问题。
强烈建议在使用插件前先对代码库进行索引。
插件的钩子（hooks）会在后台自动启动 osgrep serve，并在会话结束时自动关闭。OC 将自动使用 osgrep 进行语义搜索，你也可以主动引导它使用。

命令

`osgrep search`

默认命令。使用语义含义搜索当前目录。

osgrep "how is the database connection pooled?"

选项：

标志	描述	默认值
`-m`	返回结果的总数上限。	`25`
`--per-file`	每个文件显示的最大匹配数。	`1`
`-c`, `--content`	显示完整块内容而非代码片段。	`false`
`--scores`	显示每个结果的相关性分数 (0-1)。	`false`
`--min-score`	过滤掉低于此分数阈值的结果。	`0`
`--compact`	仅显示文件路径（类似于 `grep -l`）。	`false`
`-s`, `--sync`	搜索前强制重新索引已更改的文件。	`false`
`-r`, `--reset`	重置索引并从头开始重新索引。	`false`

示例：

# 常规概念搜索
osgrep "API rate limiting logic"

# 深入分析（显示每个文件更多的匹配项）
osgrep "error handling" --per-file 5

# 仅列出文件路径
osgrep "user validation" --compact

# 显示相关性分数并过滤低置信度结果
osgrep "authentication" --scores --min-score 0.5

`osgrep index`

手动对仓库进行索引。如果你想预热缓存，或者在编辑器之外进行了大量修改，这个命令非常有用。

遵循 .gitignore 和 .osgrepignore（详见配置部分）。
智能索引： 仅 Embedding 代码和配置文件。跳过二进制文件、锁文件和压缩资源。
并发限制： 使用固定的线程池以保持系统的响应速度。
语义分块： 使用 TreeSitter 语法处理支持的语言（TypeScript, JavaScript, Python, Go, Rust, C/C++, Java, C#, Ruby, PHP, JSON, YAML, Kotlin, Swift, Dart）。