# @dreb/semantic-search 中文文档

规范地址：https://npmcn.com/package/%40dreb/semantic-search/

版本：2\.83\.0
npm 元数据更新时间：2026-11-12T20:59:11.520Z
中文译文更新时间：2026-11-12T22:37:08.567Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dreb/semantic-search
原文对照：https://npmcn.com/package/%40dreb/semantic-search/?lang=original
项目主页：https://github.com/aebrer/dreb#readme
源码仓库：https://github.com/aebrer/dreb

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：728 kB，91 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^26\.13\.0
- 运行依赖：12 个
- 首次发布：2026-04-09T14:26:36.947Z
- 最新版本发布：2026-11-12T20:59:11.156Z
- 近 30 天下载量：3768（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：159（近 12 个月 159 个）

## 中文简介

具有嵌入式排名和MCP服务器的语义编码库搜索引擎

## 安装

```sh
npm install @dreb/semantic-search
```

也可以使用：`pnpm add @dreb/semantic-search`、`yarn add @dreb/semantic-search`、`bun add @dreb/semantic-search`

## README

# @dreb/语义搜索

有嵌入式排名和MCP服务器的语义编码库搜索引擎. 利用树套进行AST-感知分块和变压器嵌入模型提取和索引编码([全米-米尼LM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2)),然后通过POEM对结果进行6-信号聚变排序.

## 所需资源

-   **节点.js 26 LTS** (单位:千美元)`^26.13.0`)——使用内置 `node:sqlite` 模块

## 安装

```bash
npm install @dreb/semantic-search
```

## 克劳德代码插件

包船作为克洛德代码插件. 添加 dreb 市场并安装 :

```
/plugin marketplace add aebrer/dreb
/plugin install semantic-search@dreb
```

或来自CLI的会外:

```bash
claude plugin marketplace add aebrer/dreb
claude plugin install semantic-search@dreb
```

或者,在没有插件系统的情况下直接注册 MCP 服务器:

```bash
claude mcp add --transport stdio semantic-search -- npx @dreb/semantic-search semantic-search-mcp
```

对于本地开发的克隆回波:

```bash
claude --plugin-dir ./packages/semantic-search
```

## MCP 服务器

包裹会暴露一个 `search` 工具在“示范背景协议”(stdio transport)之上。 该工具接受:

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `query` | 对 | 自然语言、标识符或路径查询 |
| `searchDir` | 对 | 索引和搜索目录——每个独特的值都获得自己的独立索引 |
| `restrictToDir` | 没有 | 过滤结果到已建索引中此路径下的文件( 不影响索引编制) |
| `limit` | 没有 | 返回的最大结果( 默认: 20) |
| `rebuild` | 没有 | 强制重建干净的索引( 默认: 假) |

单独启动服务器 :

```bash
npx @dreb/semantic-search semantic-search-mcp
```

## 排名如何运作

6个独立信号使用 **邮政** (Pareto-Optimal 嵌入式建模)每个查询类型变化的权重:

| 信号 | 说明 |
| --- | --- |
| **BM25型导弹** | 通过 FTS5 全文搜索进行关键字匹配 |
| **余弦相近性** | 使用全MiniLM-L6-v2嵌入基于语义的相似性 |
| **路径匹配** | 查询文件路径中的术语 |
| **符号匹配** | 查询匹配函数、类或类型名称的术语 |
| **导入图** | 接近导入/ 依赖图中高分文件 |
| **Git 惯性** | 最近修改的文件排名更高 |

查询自动分类为 _标识符_, (中文(简体) ), _自然语言_,或 _路径_ 查询,每个类型应用不同的POEM列加权. POEM在所有信号维面上构建出一个Pareto前方并基于支配地位深度分配等级——不需要手动重心调制. 见 [平面嵌入式建模](https://iopscience.iop.org/article/10.1088/2632-2153/ab891b) 为理论基础.

## 图书馆 API

```typescript
import { SearchEngine } from "@dreb/semantic-search";

const engine = new SearchEngine("/path/to/project", {
  indexDir: "/custom/index/path",         // default: <projectRoot>/.search-index
  globalMemoryDir: "~/.dreb/memory",      // additional directory to index
  modelCacheDir: "~/.cache/models",       // default: ~/.cache/semantic-search/models
  visibleDirs: (root) => [`${root}/.special`], // extra dirs (bypasses .gitignore)
});

// First call builds the index (10-60s); subsequent calls are fast
const results = await engine.search("where is auth handled", {
  limit: 20,
  pathFilter: "src/",
  onProgress: (phase, current, total) => console.log(`${phase}: ${current}/${total}`),
});

const stats = engine.getStats();    // { files, chunks } | null
await engine.resetIndex();          // delete index, next search rebuilds
await engine.close();               // dispose resources
SearchEngine.isAvailable();         // check for node:sqlite
```

## 何为索引

-   **代码** ——树保姆AST块(功能,类,方法,界面等). TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, GDScript. 星洲网.
-   **文本** - Markdown(按标题)、YAML/TOML(按键)、JSON、简写(按段落)。 还索引了戈多特场景(`.tscn`资源(`.tres`)和项目(`.godot`)文件为平正文本.
-   **额外目录** 通过 `globalMemoryDir` 或者说 `visibleDirs`,即使被扫描.

索引存储于 `.search-index/search.db` 项目根( 添加 `.search-index/` 改为 `.gitignore`) (中文(简体) ).

## 许可证

麻省理工学院

## 常见问题

### @dreb/semantic-search 是什么？

具有嵌入式排名和MCP服务器的语义编码库搜索引擎

### 如何安装 @dreb/semantic-search？

在项目目录运行 npm install @dreb/semantic-search，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 semantic-search-mcp，可以用 npx semantic-search-mcp 直接运行。

### @dreb/semantic-search 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dreb/semantic-search 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dreb/semantic-search 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^26\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dreb/semantic-search 可以商用吗？

@dreb/semantic-search 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dreb/semantic-search 的下载量有多少？

根据 npm 官方下载统计，@dreb/semantic-search 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,768 次，日均约 126 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dreb/semantic-search 还在维护吗？

最新版本 2\.83\.0 发布于 2026/11/13（今天）；至今共发布 159 个版本，其中过去 12 个月发布了 159 个；首次发布于 2026/04/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。