内容
# 开放书架
[简体中文](README.zh-CN.md) · [Codex 插件](#codex-插件) · [Claude Code 插件](#claude-code-插件) · [快速入门](docs/getting-started.md) · [概念](docs/concepts.md) · [搜索与证据](docs/search-and-evidence.md) · [工具参考](docs/tool-reference.md)
开放书架是一款本地优先的 MCP 服务器，用于从本地文件夹构建可搜索的知识库。它将文本层 PDF 索引到 DuckDB，面向代理提供基于证据的检索工具，并将基于语料库的答案与需要额外推理的答案分开。
开放书架适用于研究论文、教科书、技术文档和本地文档库。默认情况下，它不需要云向量数据库，不会上传源文件，并将生成的 DuckDB 文件、PDF 缓存和渲染的页面图像保留在仓库之外。
## 为什么选择开放书架
许多 RAG 工具模糊了“检索相关文本”和“语料库支持此答案”的界限。开放书架明确了这一界限：
- 从本地文件构建可重用的 DuckDB 知识库。
- 默认使用可解释的 DuckDB 支持的 BM25 文本检索。
- 保留页面块、技术结果块和源页面证据。
- 区分封闭语料库和开放研究语料库边界。
- 将结果标记为 `supported`、`related_only` 或 `not_found`。
- 通过共享 `.duckdb` 文件直接共享知识库。
## 功能
| 功能 | 描述 |
|---|---|
| 本地摄入 | 将可搜索的 PDF 索引到 DuckDB。 |
| 多个数据库 | 使用 `db_name` 管理隔离的知识库。 |
| 现有数据库注册 | 使用 `create_db_from_exist` 注册现有的开放书架 DuckDB 文件。 |
| 文本检索 | 默认 `mode: "text"` 使用 BM25 文本搜索。 |
| 证据标签 | 返回 `supported`、`related_only` 或 `not_found`。 |
| 语料库边界 | 使用配置文件区分封闭语料库和开放研究语料库行为。 |
| 源检查 | 获取块、页面文本和渲染的页面图像。 |
| 技术索引 | 让用户在摄入后决定是否构建定理、引理、定义和命题导向的索引。 |
## 快速入门
```bash
npm install
npm run openshelf-mcp
```
将服务器添加到 Codex MCP 配置中：
```toml
[mcp_servers.openshelf]
command = "npm"
args = ["--prefix", "/path/to/OpenShelf", "run", "--silent", "openshelf-mcp"]
```
添加可搜索的 PDF：
```bash
npm run create-document -- '{"pdf_path":"<path-to-book.pdf>","title":"Book Title","authors":["Author"],"tags":["book"]}'
```
参见 [快速入门](docs/getting-started.md) 以获取完整流程。
## Codex 插件
该仓库也是一个 Codex 插件根目录。它包含：
```text
.codex-plugin/plugin.json 插件清单
.mcp.json 开放书架 MCP 服务器配置
skills/openshelf/ 使用开放书架的代理指导
.agents/plugins/ 本地市场配置
```
本地安装：
```bash
codex plugin marketplace add /path/to/OpenShelf
codex plugin add openshelf@openshelf-local
```
安装后启动一个新的 Codex 线程，以便 Codex 加载开放书架 MCP 工具。
在插件模式下，开放书架默认情况下将知识库数据存储在 `~/.openshelf/data` 下，而不是 Codex 插件缓存中。现有的 `.duckdb` 文件可以使用 `create_db_from_exist` 注册到该目录中。
## Claude Code 插件
该仓库还支持 Claude Code 插件布局：
```text
.claude-plugin/plugin.json Claude Code 插件清单
.claude-plugin/marketplace.json Claude Code 本地市场
.mcp.json 由 Claude Code 加载的开放书架 MCP 服务器
```
本地安装：
```bash
claude plugin marketplace add /path/to/OpenShelf
claude plugin install openshelf@openshelf-local
```
安装后重启 Claude Code 或启动新会话。Claude Code 导入名为 `openshelf` 的 MCP 服务器。插件数据默认存储在 Claude 的 `${CLAUDE_PLUGIN_DATA}/data` 下；现有的 `.duckdb` 文件可以使用 `create_db_from_exist` 注册。
## 推荐工作流程
开放书架设计用于具有 MCP 工具的 LLM 代理，而不是用户手动执行每个检索步骤。典型流程是：
1. 用户命名一个知识库，并用自然语言提出一个问题，例如“使用 `research_corpus` 来回答这个问题。”
2. 代理根据问题选择 `search`、`search_terms` 或 `search_technical_results`。
3. 如果结果是 `supported`，代理直接从引用的证据中回答。
4. 如果结果是 `related_only` 或 `not_found`，代理解释语料库证据不足，并询问用户是否允许进一步推理。
5. 如果用户允许进一步推理，并且语料库是封闭的，代理使用 `check_reasonable` 来审计推理是否超出语料库边界。如果语料库是开放研究，代理可以继续，但必须标记知识库的内容和独立推理的内容。
6. 如果需要定理、定义或命题级别的检索，代理可以建议在已经摄入的文档上调用 `build_technical_index` 以生成技术结果块。
## PDF 要求
默认情况下，开放书架只接受可以直接提取文本的 PDF。LaTeX 生成的论文和嵌入文本的电子书通常有效。扫描的 PDF、仅包含图像的 PDF 和文本无法复制和粘贴的 PDF 被拒绝。
默认设置：
```text
ocr: "never"
require_searchable: true
```
必须显式启用 OCR 以处理扫描文档。它依赖于本地的 Tesseract，对于公式、表格和复杂布局可能不可靠。
参见 [快速入门：PDF 要求](docs/getting-started.md#pdf-requirements)。
## 核心工具
| 工具 | 目的 |
|---|---|
| `create_db` | 创建一个命名的 DuckDB 知识库，可选地摄入 PDF。 |
| `create_db_from_exist` | 注册一个现有的开放书架 DuckDB 文件，而不复制或重新摄入它。 |
| `list_db` | 列出可用的数据库和配置文件。 |
| `create_document` | 添加一个可搜索的 PDF，默认拒绝仅包含图像的 PDF。 |
| `search` | 搜索块并返回可回答性元数据。 |
| `search_terms` | 用于技术或领域问题的两阶段检索。 |
| `build_technical_index` | 构建定理、引理、定义和相关技术结果索引。 |
| `search_technical_results` | 搜索结构化的技术结果。 |
| `get_chunk` / `get_page_text` / `get_page_image` | 检查块、页面文本和渲染的页面。 |
参见 [工具参考](docs/tool-reference.md) 以获取完整的模式。
## 文档
| 页面 | 内容 |
|---|---|
| [快速入门](docs/getting-started.md) | 安装、MCP 设置、摄入、烟雾测试和 PDF 要求。 |
| [概念](docs/concepts.md) | 知识库、DuckDB 文件、封闭/开放配置文件、页面块和技术结果块。 |
| [搜索和证据](docs/search-and-evidence.md) | BM25、搜索模式、可回答性和技术结果索引。 |
| [工具参考](docs/tool-reference.md) | MCP 工具输入和输出模式。 |
| [开发](docs/development.md) | 本地数据、测试和 Git 忽略策略。 |
## 开发
```bash
npm run typecheck
npm run test:unit
```
运行时数据保持本地，并被 Git 忽略：
```text
data/index/ DuckDB 数据库和目录
data/pdfs/ 可选的 PDF 暂存区
data/rendered/ 渲染的页面缓存
data/test_outputs/ 测试输出
```
下一篇：[快速入门](docs/getting-started.md)
