内容
# 开放研究知识库
开放研究知识库是一个本地优先的MCP服务器，用于构建和查询PDF知识库。它将PDF索引到DuckDB中，提供基于证据的检索工具，并帮助代理将基于语料库的答案与独立推理分开。
## 功能特点
- 将可搜索的PDF文件摄入本地DuckDB知识库。
- 使用`db_name`管理多个命名的数据库。
- 使用保守的可信度标签搜索片段：`supported`、`related_only`和`not_found`。
- 检索源片段、页面文本和渲染的页面图像以进行引用检查。
- 使用`check_reasonable`审核独立推理与封闭语料库配置文件。
- 将PDF和生成的索引保留在本地；默认情况下，存储库数据目录被忽略。
## 快速入门
安装依赖项：
```bash
npm install
```
通过stdio运行MCP服务器：
```bash
npm run kb-mcp-ts
```
添加PDF：
```bash
npm run create-document -- '{"pdf_path":"<path-to-book.pdf>","title":"Book Title","authors":["Author"],"tags":["book"],"ocr":"auto"}'
```
使用任何可搜索的样本PDF运行可选的烟雾测试：
```bash
KB_MCP_SMOKE_PDF=<path-to-sample.pdf> npm run smoke:pdf
```
## Codex MCP设置
将服务器添加到您的Codex MCP配置中：
```toml
[mcp_servers.kb]
command = "npm"
args = ["--prefix", "/path/to/ResearchKB", "run", "--silent", "kb-mcp-ts"]
```
全新安装以默认数据库`default`启动，存储在`data/index/kb_default.duckdb`。如果您想创建其他数据库，如`research_corpus`或`textbook_corpus`，请使用`create_db`。
## 常见工作流程
1. 使用`create_document`或`ingest_pdf`添加PDF。
2. 使用`search`或`search_terms`搜索语料库。
3. 使用`get_chunk`、`get_page_text`或`get_page_image`检查源证据。
4. 仅当`answerability.status`为`supported`时，才从语料库中回答。
5. 如果证据薄弱或缺失，请明确标记独立推理，并在应使用封闭语料库配置文件约束答案时使用`check_reasonable`。
## 工具列表
| 工具 | 用途 |
|---|---|
| `create_db` | 创建一个命名的DuckDB知识库，可选地摄入PDF文件或目录。 |
| `list_db` | 列出可用的数据库及其配置文件。 |
| `set_active_db` | 设置会话默认数据库。 |
| `create_document` | 添加一个可搜索的PDF，适用于用户侧摄入，具有更严格的默认值。 |
| `ingest_pdf` | 将本地PDF摄入选定的数据库。 |
| `list_documents` | 列出索引文档，可选标题/路径/标签筛选器。 |
| `search` | 搜索片段并返回可信度元数据。 |
| `search_terms` | 技术/领域自然语言问题的两阶段搜索工作流程。 |
| `check_reasonable` | 检查独立推理是否在选定的语料库范围内。 |
| `build_technical_index` | 预览或构建提取的技术术语结果。 |
| `search_technical_results` | 搜索提取的技术术语结果和附近的定义。 |
| `get_chunk` | 获取一个片段，可选邻居和页面图像。 |
| `get_page_text` | 返回一个PDF页面的提取文本。 |
| `get_page_image` | 渲染或获取缓存的页面图像。 |
请参阅 [docs/tool-reference.md](docs/tool-reference.md) 获取完整的输入和输出模式。
## 证据策略
开放研究知识库故意保持保守。词汇匹配并不自动足以回答问题。
| 状态 | 含义 | 推荐代理行为 |
|---|---|---|
| `supported` | 找到直接的文本证据。 | 根据引用的证据回答。 |
| `related_only` | 找到弱相关材料，但不足以支持答案。 | 在独立推理之前报告限制。 |
| `not_found` | 未找到可用的证据。 | 在使用独立推理之前询问。 |
## 存储
运行时数据是本地的，Git会忽略：
```text
data/index/ DuckDB数据库和数据库目录
data/pdfs/ 可选的本地PDF暂存区
data/rendered/ 缓存的页面图像
data/test_outputs/
```
每个数据库都是一个单独的DuckDB文件，例如`data/index/kb_default.duckdb`。原始PDF在摄入过程中不会被复制到存储库中；它们的源路径存储在数据库元数据中。页面图像按需生成并缓存在`data/rendered`下。
在摄入前，请安装Poppler（`pdftotext`、`pdfinfo`、`pdftoppm`）。OCR是可选的，并在配置时使用本地Tesseract。
## 开发
```bash
npm run typecheck
npm run test:unit
```
存储库故意排除生成的PDF、图像、DuckDB文件、渲染的页面、日志、本地环境和`node_modules`。
