# https://github.com/ydf0509/nbrag 项目说明书

生成时间：2026-06-21 19:52:18 UTC

## 目录

- [项目概览与系统架构](#page-overview)
- [数据接入、切片与索引管线](#page-ingestion)
- [检索能力与 MCP 工具集](#page-retrieval-mcp)
- [配置、部署与扩展](#page-config-deploy)

<a id='page-overview'></a>

## 项目概览与系统架构

### 相关页面

相关主题：[数据接入、切片与索引管线](#page-ingestion), [检索能力与 MCP 工具集](#page-retrieval-mcp), [配置、部署与扩展](#page-config-deploy)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ydf0509/nbrag/blob/main/README.md)
- [README.zh-CN.md](https://github.com/ydf0509/nbrag/blob/main/README.zh-CN.md)
- [nbrag/skills/readme.md](https://github.com/ydf0509/nbrag/blob/main/nbrag/skills/readme.md)
</details>

# 项目概览与系统架构

## 一、项目定位与适用场景

`nbrag` 是一个发布在 PyPI 的 Python 包，用于在本地构建文本知识库，并通过 **MCP（Model Context Protocol）服务器** 把该知识库的能力暴露给任意兼容 MCP 的客户端。资料来源：[README.md:1-9]()

该项目的核心价值在于让用户完全掌控自己的语料：当需要让大模型基于内部文档、规范、手册、笔记、本地项目文档或 Python 源码进行回答时，可借助 `nbrag` 在本地完成向量化、检索与原文回溯，而无需把数据外送到托管型 RAG 服务。资料来源：[README.md:11-19]()

适用场景包括：

- 索引**私有或本地**的文本（外部服务不可见）
- 基于自有文件构建**领域知识库**
- 让 MCP 客户端同时检索**向量化分块**与**原始存储文本**
- 将存储保留在**本机**上

需要注意：`nbrag` 是 **text-first** 的。源材料若是 PDF、Word、图片、扫描件或网页，应先转换为 `.md`、`.txt`、`.html` 再摄入，以获得最佳效果。资料来源：[README.md:21-25]()

## 二、整体架构与数据流

`nbrag` 由"摄入端"与"服务端"两段组成。摄入端以 `batch_ingest()` 与 `set_collection_profile()` 写入 ChromaDB 与本地索引；服务端通过 `python -m nbrag` 启动 MCP 进程，向 MCP 客户端暴露检索类工具。资料来源：[README.md:75-83](), [README.md:95-102]()

```mermaid
flowchart LR
    A[本地文本文件<br/>.md / .txt / .html] --> B[batch_ingest<br/>分块 + Embedding]
    B --> C[(ChromaDB<br/>+ 本地索引)]
    C --> D[set_collection_profile<br/>人类可读元数据]
    D --> E[python -m nbrag<br/>MCP Server]
    E -->|stdio 或 streamable-http| F[MCP Client<br/>IDE / Agent]
    F -->|工具调用| E
    E -->|检索结果 + 原文| F
```

## 三、配置体系

`nbrag` 的配置按以下优先级生效：**CLI 参数 > 环境变量 > YAML 配置 > 默认值**。资料来源：[README.md:115-119]()

主要环境变量如下表所示：

| 变量 | 必填 | 默认值 | 用途 |
|---|:---:|---|---|
| `NBRAG_API_KEY` | 是 | — | Embedding / Rerank 服务的 API Key |
| `NBRAG_BASE_URL` | 否 | `https://api.siliconflow.cn/v1` | OpenAI 兼容 API 的 Base URL |
| `NBRAG_EMBEDDING_MODEL` | 否 | `BAAI/bge-m3` | 向量模型 |
| `NBRAG_RERANK_MODEL` | 否 | `BAAI/bge-reranker-v2-m3` | Rerank 模型 |
| `NBRAG_DB_PATH` | 否 | `<project>/rag_db` | ChromaDB 与本地索引路径 |
| `NBRAG_RAW_FILES_PATH` | 否 | `<db_path>/raw_files` | 原始文件快照存储路径 |
| `NBRAG_CHUNK_SIZE` | 否 | `1000` | 分块大小 |
| `NBRAG_CHUNK_OVERLAP` | 否 | `150` | 分块重叠 |

资料来源：[README.md:121-137]()。YAML 配置文件会自动按 `./nbrag_config.yaml`、`./nbrag_config.yml`、`~/.config/nbrag/config.yaml`、`~/.config/nbrag/config.yml` 的顺序查找。资料来源：[README.md:139-157]()

MCP 服务支持两种传输模式：

- **stdio**：一客户端对应一服务进程，适合单 IDE 窗口使用
- **streamable-http**：通过 `--port` 指定端口，多客户端可共享同一本地服务进程

资料来源：[README.md:89-93](), [README.md:95-102]()

## 四、MCP 工具能力矩阵

服务端启动后会暴露一组以检索为核心的 MCP 工具。可按能力维度整理如下：

| 能力 | 代表性工具 | 作用范围 |
|---|---|---|
| 搜索 | `nbrag_search`、`nbrag_search_and_fetch` | 对已摄入集合做语义与混合检索 |
| 搜索探查 | `nbrag_search_only_bm25`、`nbrag_search_only_vector` | 单独观察词法或向量行为 |
| 精确文本定位 | `nbrag_grep` | 在存储的原始文本上逐行匹配 |
| 原始文本读取 | `nbrag_get_raw_file`、`nbrag_get_file_chunks` | 读取原始文件或分块视图 |
| 上下文扩展 | `nbrag_get_adjacent_chunks`、`nbrag_get_chunks_by_lines`、`nbrag_find_files` | 围绕命中扩展上下文、解析具体文件路径 |
| 清单与路由 | `nbrag_stats`、`nbrag_list` | 发现集合、浏览已导入文档 |

资料来源：[README.md:119-125]()

## 五、与传统（naive）RAG 的差异

传统 RAG 通常是"一次性 retrieve top-k → 拼进 prompt"的固定管线；而 `nbrag` 提供了两点本质差异：

1. **知识库由用户自行准备并掌控**：通过 `batch_ingest()` 显式摄入本地文本，配合 `set_collection_profile()` 补充 `display_name`、`description`、`aliases`、`tags` 等人类可读元数据，使 collection 既有稳定的机器标识（slug-like 的 `collection_name`），又具备良好的可发现性。资料来源：[README.md:75-83](), [README.md:85-87]()
2. **检索通过 MCP 工具暴露**：客户端可以在多次调用间进行**搜索 → 精化 → 检视原文 → 拉取更多上下文**的迭代流程，而不是单次取 top-k 后即终止。资料来源：[README.md:125-131]()

此外，`nbrag` 在仓库内还附带了 `nbrag/skills/` 目录，可被第三方工具的 skills 扫描器识别，复制到目标项目下即可被自动加载。资料来源：[nbrag/skills/readme.md:1-1]()

项目以 **MIT 协议**开源。资料来源：[README.md:191-191]()

## See Also

- 快速开始与安装：[README.md:27-31]()
- 摄入与集合描述 API：[README.md:75-87]()
- 传输模式与客户端配置：[README.md:89-113]()

---

<a id='page-ingestion'></a>

## 数据接入、切片与索引管线

### 相关页面

相关主题：[项目概览与系统架构](#page-overview), [检索能力与 MCP 工具集](#page-retrieval-mcp)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [nbrag/ingest.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/ingest.py)
- [nbrag/chunker.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/chunker.py)
- [nbrag/embeddings.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/embeddings.py)
- [nbrag/bm25_index.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/bm25_index.py)
- [nbrag/symbol_index.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/symbol_index.py)
- [nbrag/storage.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/storage.py)
- [README.md](https://github.com/ydf0509/nbrag/blob/main/README.md)
</details>

# 数据接入、切片与索引管线

## 概览与设计目标

`nbrag` 的数据接入管线负责把本地文本文件（`.md`、`.txt`、`.html`、以及 Python 源码）转化为可被 MCP 客户端检索的混合索引。整个管线以 [nbrag/ingest.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/ingest.py) 中的 `batch_ingest()` 为统一入口，按顺序完成「扫描 → 原始文件快照 → 切片 → embedding → 多索引落地」的流程（资料来源：[nbrag/ingest.py:1-120]()）。区别于一次性的 naive RAG，`nbrag` 把每一步都暴露为可配置、可重建的阶段，因此同一个 collection 可以在不停服的情况下被反复重建。

## 主入口：`batch_ingest()`

`batch_ingest()` 是整条管线的总入口，参数语义如下（资料来源：[README.md:60-90]()）：

| 参数 | 作用 |
|---|---|
| `paths` | 待扫描的文件夹或文件列表 |
| `collection_name` | ChromaDB 中机器可读的 collection 标识 |
| `file_extensions` | 限定被摄入的文件类型 |
| `delete_first` | 是否在摄入前清空同名 collection |
| `verbose` | 是否输出进度日志 |

该函数会委托 [nbrag/storage.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/storage.py) 创建底层 ChromaDB 客户端与本地索引目录，并依次触发后续阶段。

## 切片与原始文件快照

切片由 [nbrag/chunker.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/chunker.py) 负责，默认配置为 `chunk_size=1000`、`chunk_overlap=150`，可通过环境变量 `NBRAG_CHUNK_SIZE` 与 `NBRAG_CHUNK_OVERLAP` 覆盖（资料来源：[README.md:120-130]()）。为了让 MCP 工具在命中后能定位到原始上下文，[nbrag/ingest.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/ingest.py) 在切片前会先把整份文件以原文形式写入 `NBRAG_RAW_FILES_PATH`（默认位于 `NBRAG_DB_PATH/raw_files` 之下，资料来源：[README.md:115-120]()），供 `nbrag_get_raw_file`、`nbrag_get_file_chunks` 等检索后回溯使用。

## Embedding 与向量索引

向量侧的 embedding 由 [nbrag/embeddings.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/embeddings.py) 调用 OpenAI 兼容接口完成，默认 `base_url` 指向 SiliconFlow、默认模型为 `BAAI/bge-m3`（资料来源：[README.md:105-115]()）。切片得到的文本块经 embedding 后写入 ChromaDB 集合，配合 `BAAI/bge-reranker-v2-m3` 重新排序模型支撑 `nbrag_search` 与 `nbrag_search_and_fetch` 工具。

## BM25 与符号索引

为了支持精确文本检索与 Python 源码场景，管线并行维护两套辅助索引：

- [nbrag/bm25_index.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/bm25_index.py) 构建词法索引，驱动 `nbrag_search_only_bm25`、`nbrag_search_only_vector` 与 `nbrag_grep`（资料来源：[README.md:160-185]()）；
- [nbrag/symbol_index.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/symbol_index.py) 抽取 Python 模块、类、函数等符号，配合 `set_collection_profile()` 的 `aliases/tags` 元数据，帮助客户端在代码类问题上快速收敛目标范围。

```mermaid
flowchart LR
    A[paths / file_extensions] --> B[raw_files 快照]
    B --> C[chunker 切片]
    C --> D[embeddings 向量]
    C --> E[bm25_index 词法]
    C --> F[symbol_index 符号]
    D --> G[(ChromaDB)]
    E --> G
    F --> G
    G --> H[MCP 检索工具]
```

## 常见失败模式

- 摄入 PDF/扫描件时未先转 `.md/.txt/.html`，切片质量会显著下降（资料来源：[README.md:30-35]()）。
- 调整切片或 embedding 参数时若忘记 `delete_first=True`，新参数不会生效。
- API key 未设置时 embedding 阶段会直接报错，需要先 export `NBRAG_API_KEY`。

## See Also

- 配置参考与 CLI 参数：[README.md](https://github.com/ydf0509/nbrag/blob/main/README.md)
- MCP 工具能力总览：README "MCP capabilities overview" 一节
- 集合元数据描述函数 `set_collection_profile()`：见 README "Why `set_collection_profile()` matters" 一节

---

<a id='page-retrieval-mcp'></a>

## 检索能力与 MCP 工具集

### 相关页面

相关主题：[项目概览与系统架构](#page-overview), [数据接入、切片与索引管线](#page-ingestion), [配置、部署与扩展](#page-config-deploy)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [nbrag/mcp_tools.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/mcp_tools.py)
- [nbrag/retrieval.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/retrieval.py)
- [nbrag/server.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/server.py)
- [nbrag/loggers.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/loggers.py)
- [nbrag/defaults.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/defaults.py)
- [README.md](https://github.com/ydf0509/nbrag/blob/main/README.md)
- [nbrag/skills/readme.md](https://github.com/ydf0509/nbrag/blob/main/nbrag/skills/readme.md)
</details>

# 检索能力与 MCP 工具集

`nbrag` 是一个面向本地文本知识库构建与 MCP（Model Context Protocol）检索的服务端包。其核心价值在于：把"由用户自己控制的知识库"通过一组 MCP 工具暴露给兼容 MCP 的客户端，使大模型客户端能够语义检索、混合检索、回查原文并按需展开上下文，而不是一次性塞入 top-k 片段。资料来源：[README.md]()。

## 1. 设计定位：与朴素 RAG 的区别

朴素 RAG 通常是固定的一次性流程：检索 top-k 个文本片段并直接拼入 prompt。`nbrag` 在两点上不同：

- **由用户准备并控制知识库**：通过 `batch_ingest()` 与 `set_collection_profile()` 显式建立与描述 collection。
- **检索通过 MCP 工具暴露**：客户端可搜索、细化、查阅原文，并按需获取更多上下文。

资料来源：[README.md]()

## 2. MCP 工具能力分类

`nbrag` 在服务启动后暴露一组面向检索的 MCP 工具。按能力归类如下：

| 能力 | 代表性工具 | 覆盖范围 |
|---|---|---|
| 检索 | `nbrag_search`、`nbrag_search_and_fetch` | 在已入库 collection 上进行语义/混合检索 |
| 检索检视 | `nbrag_search_only_bm25`、`nbrag_search_only_vector` | 仅关键词或仅向量的单路行为检视 |
| 精确文本匹配 | `nbrag_grep` | 对存储的原文逐行匹配 |
| 原文读取 | `nbrag_get_raw_file`、`nbrag_get_file_chunks` | 读取已存储的原始文件或分块视图 |
| 上下文扩展与定位 | `nbrag_get_adjacent_chunks`、`nbrag_get_chunks_by_lines`、`nbrag_find_files` | 在命中点周围扩展上下文、解析精确文件路径 |
| 资源清点与路由 | `nbrag_stats`、`nbrag_list` | 发现 collection、浏览已导入文档 |

资料来源：[README.md]()

## 3. 关键运行时参数

检索与重排效果由以下环境变量驱动，配置优先级为：CLI 参数 > 环境变量 > YAML 配置 > 默认值。资料来源：[README.md]()

| 变量 | 必填 | 默认 | 说明 |
|---|:---:|---|---|
| `NBRAG_API_KEY` | 是 | — | Embedding / Rerank 服务的 API Key |
| `NBRAG_BASE_URL` | 否 | `https://api.siliconflow.cn/v1` | OpenAI 兼容 API 基址 |
| `NBRAG_EMBEDDING_MODEL` | 否 | `BAAI/bge-m3` | Embedding 模型 |
| `NBRAG_RERANK_MODEL` | 否 | `BAAI/bge-reranker-v2-m3` | Rerank 模型 |
| `NBRAG_DB_PATH` | 否 | `<project>/rag_db` | ChromaDB 与本地索引路径 |
| `NBRAG_RAW_FILES_PATH` | 否 | `<db_path>/raw_files` | 原始文件快照目录 |
| `NBRAG_CHUNK_SIZE` | 否 | `1000` | 切片长度 |
| `NBRAG_CHUNK_OVERLAP` | 否 | `150` | 切片重叠 |

> 说明：上述默认值是面向中文/英文混合文本的推荐起点；当切换模型或语料类型时，优先调整 `NBRAG_CHUNK_SIZE` 与 `NBRAG_CHUNK_OVERLAP`，再观察 `nbrag_search_and_fetch` 的命中率。

## 4. 传输模式与客户端接入

`nbrag` 同时支持两种 MCP 传输：

- **stdio**：单客户端独占一个服务进程，适合 IDE 单窗口直连。
  ```bash
  python -m nbrag
  ```
- **streamable-http**：多客户端/多窗口共享同一个本地服务进程，便于复用已建立的索引。
  ```bash
  python -m nbrag --transport streamable-http --port 9101
  ```

stdio 模式下，客户端配置需指向安装了 `nbrag` 的 Python 解释器：

```json
{
  "mcpServers": {
    "nbrag": {
      "command": "python",
      "args": ["-m", "nbrag"],
      "env": { "NBRAG_API_KEY": "sk-xxx" }
    }
  }
}
```

HTTP 模式下，先启动共享服务，再将客户端指向 `http://localhost:9101/mcp`。资料来源：[README.md]()

## 5. 常见失败模式与处理建议

- **检索不到预期片段**：先调用 `nbrag_list` 与 `nbrag_stats` 确认目标 collection 存在且文档已被导入；再分别尝试 `nbrag_search_only_bm25` 与 `nbrag_search_only_vector` 区分是语义还是词法失效。
- **命中片段上下文不足**：使用 `nbrag_get_adjacent_chunks` 或 `nbrag_get_chunks_by_lines` 在命中点附近扩展；如需回溯原文，调用 `nbrag_get_raw_file`。
- **客户端连接失败**：检查 `NBRAG_API_KEY` 是否在客户端环境注入；HTTP 模式下确认端口与 `url` 字段一致。

## 6. 与 skills 目录的关系

`nbrag/skills/readme.md` 要求用户将该目录复制到自身项目下、被第三方工具认可扫描的 skills 目录中。这意味着 `nbrag` 的检索行为不仅由 MCP 工具本身决定，还可由随包发布的 skills 描述来引导客户端更规范地使用工具。资料来源：[nbrag/skills/readme.md]()

## See Also

- [README.md](https://github.com/ydf0509/nbrag/blob/main/README.md) — 安装、配置、客户端接入
- [nbrag/mcp_tools.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/mcp_tools.py) — 工具实现
- [nbrag/retrieval.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/retrieval.py) — 检索与重排逻辑
- [nbrag/server.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/server.py) — MCP 服务端与传输注册
- [nbrag/defaults.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/defaults.py) — 默认模型与路径常量

---

<a id='page-config-deploy'></a>

## 配置、部署与扩展

### 相关页面

相关主题：[项目概览与系统架构](#page-overview), [数据接入、切片与索引管线](#page-ingestion), [检索能力与 MCP 工具集](#page-retrieval-mcp)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [nbrag/config.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/config.py)
- [nbrag/defaults.py](https://github.com/ydf0509/nbrag/blob/main/nbrag/defaults.py)
- [config.example.yaml](https://github.com/ydf0509/nbrag/blob/main/config.example.yaml)
- [scripts/start_http_rag_mcp.py](https://github.com/ydf0509/nbrag/blob/main/scripts/start_http_rag_mcp.py)
- [scripts/start_local_rag_mcp.py](https://github.com/ydf0509/nbrag/blob/main/scripts/start_local_rag_mcp.py)
- [scripts/run_all_ingest.py](https://github.com/ydf0509/nbrag/blob/main/scripts/run_all_ingest.py)
- [README.md](https://github.com/ydf0509/nbrag/blob/main/README.md)
- [nbrag/skills/readme.md](https://github.com/ydf0509/nbrag/blob/main/nbrag/skills/readme.md)
</details>

# 配置、部署与扩展

`nbrag` 是一个面向本地文本知识库的 PyPI 包，通过 MCP（Model Context Protocol）服务器把检索能力暴露给兼容的客户端。本文聚焦其**配置体系、部署方式与扩展点**三个面向，帮助使用者快速搭建稳定可复现的本地 RAG 服务。

## 配置体系

`nbrag` 的配置遵循清晰的优先级链，使得同一套代码可以在不同环境下复用，资料来源：[README.md:114-118]()。

```text
CLI 参数 > 环境变量 > YAML 配置文件 > 内置默认值
```

### 环境变量

`nbrag` 默认对接 SiliconFlow 兼容的 OpenAI 风格 embedding / rerank 端点，关键环境变量整理如下，资料来源：[README.md:120-130]()：

| 变量 | 是否必填 | 默认值 | 含义 |
|---|:---:|---|---|
| `NBRAG_API_KEY` | 是 | — | embedding / rerank 的 API Key |
| `NBRAG_BASE_URL` | 否 | `https://api.siliconflow.cn/v1` | OpenAI 兼容 API 根地址 |
| `NBRAG_EMBEDDING_MODEL` | 否 | `BAAI/bge-m3` | embedding 模型名 |
| `NBRAG_RERANK_MODEL` | 否 | `BAAI/bge-reranker-v2-m3` | rerank 模型名 |
| `NBRAG_DB_PATH` | 否 | `<project>/rag_db` | ChromaDB 与本地索引路径 |
| `NBRAG_RAW_FILES_PATH` | 否 | `<db_path>/raw_files` | 原始文件快照存储路径 |
| `NBRAG_CHUNK_SIZE` | 否 | `1000` | 切片大小 |
| `NBRAG_CHUNK_OVERLAP` | 否 | `150` | 切片重叠大小 |

### YAML 配置文件

YAML 是环境变量之外最常用的集中化配置方式。包在启动时会按下列顺序自动搜索，资料来源：[README.md:132-137]()：

1. `./nbrag_config.yaml`
2. `./nbrag_config.yml`
3. `~/.config/nbrag/config.yaml`
4. `~/.config/nbrag/config.yml`

配置示例，资料来源：[README.md:139-150]()：

```yaml
embedding:
  api_key: ${NBRAG_API_KEY}
  base_url: https://api.siliconflow.cn/v1
  model: BAAI/bge-m3

rerank:
  model: BAAI/bge-reranker-v2-m3

storage:
  db_path: ./rag_db

chunking:
  chunk_size: 1000
  chunk_overlap: 150
```

注意 `api_key` 字段支持 `${NBRAG_API_KEY}` 这种 shell 风格占位符，便于在不同部署环境复用同一份 YAML。`config.example.yaml` 提供了可复制的模板，建议在仓库中保留，资料来源：[config.example.yaml]()。

### 命令行参数

`python -m nbrag` 同时支持 CLI 参数覆盖，常见用法包括，资料来源：[README.md:152-159]()：

```bash
python -m nbrag --help
python -m nbrag --transport stdio
python -m nbrag --transport streamable-http --port 9101
python -m nbrag --api-key sk-xxx
python -m nbrag --db-path /data/rag
python -m nbrag --config ./nbrag_config.yaml
```

CLI 参数适合临时调试与 CI 中的一次性覆盖；长期运行的服务建议使用 YAML + 环境变量组合。

## 部署模式

`nbrag` 的 MCP 服务器支持两种传输模式，分别面向"一客户端一进程"和"多客户端共享进程"两种典型场景，资料来源：[README.md:70-82]()。

```mermaid
flowchart LR
    A[MCP 客户端] -->|stdio| B[nbrag 进程]
    C[MCP 客户端 1] -->|HTTP| D[共享 nbrag 服务 :9101]
    E[MCP 客户端 2] -->|HTTP| D
    F[IDE 窗口 N] -->|HTTP| D
```

### stdio 模式

适合本地单一客户端独占一个 `nbrag` 进程，资料来源：[README.md:72-74]()：

```bash
python -m nbrag
```

该模式由客户端直接拉起子进程，环境变量需要通过客户端配置中的 `env` 字段注入。

### HTTP 模式（streamable-http）

适合多个客户端或多个 IDE 窗口共享同一个本地服务进程，资料来源：[README.md:76-82]()：

```bash
python -m nbrag --transport streamable-http --port 9101
```

服务启动后，端点暴露在 `http://localhost:9101/mcp`。这种模式常配合 [`scripts/start_http_rag_mcp.py`](https://github.com/ydf0509/nbrag/blob/main/scripts/start_http_rag_mcp.py) 作为 systemd / 容器入口长期运行，而 [`scripts/start_local_rag_mcp.py`](https://github.com/ydf0509/nbrag/blob/main/scripts/start_local_rag_mcp.py) 则适合一次性调试。

### MCP 客户端连接

stdio 客户端配置示例（JSON），资料来源：[README.md:86-99]()：

```json
{
  "mcpServers": {
    "nbrag": {
      "command": "python",
      "args": ["-m", "nbrag"],
      "env": {
        "NBRAG_API_KEY": "sk-xxx"
      }
    }
  }
}
```

HTTP 客户端配置示例：

```json
{
  "mcpServers": {
    "nbrag": {
      "url": "http://localhost:9101/mcp"
    }
  }
}
```

如果客户端使用的解释器与 shell 不同，需要把 `python` 替换为绝对路径，例如 `python`、`/Users/me/.venv/bin/python` 等。

## 扩展与开发

### 技能（skills）扩展

`nbrag` 把面向 AI 的检索工作流封装为 skills，便于第三方工具自动发现与调用。`nbrag/skills/readme.md` 指出，使用方应将整个 skills 文件夹复制到自己项目下被第三方工具识别的 `skills` 目录中，资料来源：[nbrag/skills/readme.md:1-1]()。这种方式保持了主仓库与业务仓库的解耦：升级 `nbrag` 时只需同步该文件夹。

### 知识库增量与全量重建

[`scripts/run_all_ingest.py`](https://github.com/ydf0509/nbrag/blob/main/scripts/run_all_ingest.py) 是常见的批量入库脚本入口。README 明确建议：只有在调整切片参数或更换 embedding 模型时使用 `delete_first=True` 全量重建；支持增量入库时，应避免预先删除集合，否则会产生重复 embedding 费用，资料来源：[README.md:67-69]()。

### 开发模式安装

进行二次开发时使用可编辑安装，资料来源：[README.md:163-168]()：

```bash
git clone https://github.com/ydf0509/nbrag.git
cd nbrag
pip install -e ".[dev]"

python -m nbrag
python -m nbrag --transport streamable-http --port 9101
```

## 常见故障与最佳实践

- **API Key 未配置**：`NBRAG_API_KEY` 缺失会导致 embedding / rerank 调用失败，CLI 上传 `NBRAG_API_KEY` 是最快的临时修复手段。
- **多客户端争用 embedding 配额**：HTTP 模式下所有客户端共享同一 embedding Key，建议为不同业务分配独立的 `NBRAG_API_KEY` 或自部署兼容端点。
- **路径不一致**：`NBRAG_DB_PATH` 与 `NBRAG_RAW_FILES_PATH` 在 YAML 与 CLI 中需保持一致，否则会出现"能搜但拿不到原文"的现象。
- **解释器不匹配**：stdio 模式下客户端使用的 Python 环境若未安装 `nbrag`，应在 `args` 中显式指定绝对路径。

## See Also

- [快速上手与 MCP 工具能力概览](README.md)
- [`nbrag/config.py` 配置加载实现](nbrag/config.py)
- [`nbrag/defaults.py` 默认值定义](nbrag/defaults.py)
- [批量入库脚本入口](scripts/run_all_ingest.py)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：ydf0509/nbrag

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/ydf0509/nbrag | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/ydf0509/nbrag | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/ydf0509/nbrag | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/ydf0509/nbrag | no_demo; severity=medium

## 5. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/ydf0509/nbrag | issue_or_pr_quality=unknown

## 6. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/ydf0509/nbrag | release_recency=unknown

<!-- canonical_name: ydf0509/nbrag; human_manual_source: deepwiki_human_wiki -->