内容
# LongBook 验证器
**一个启用 MCP 的用于长文档 RAG 系统的评估和声明验证工具包。**
[](LICENSE)
[](https://doi.org/10.5281/zenodo.20513116)
[](https://tts.bedvibe.studio/bookproof/app/)
LongBook 验证器衡量检索方法和 AI 输出是否真正基于长叙事手稿——通过从文档中检索证据并评估覆盖率，以确定性和不依赖外部模型 API 的方式。
## 使用方式
| | 您将获得 | 适用于 |
|---|---|---|
| 🔌 **本地 MCP** | 一个用于 Claude Code / Codex 的本地 stdio MCP 服务器，用于长文档评估、检索、声明验证和报告工具。**仅限本地**（不托管或远程）。 → **[docs/MCP.md](docs/MCP.md)** | 在 AI 客户端中使用验证器 |
| 🌐 **在线试用 BookProof** | **在线托管的 Web 产品** - 在浏览器中上传文档和金色问题，无需安装。 → **[tts.bedvibe.studio/bookproof/app](https://tts.bedvibe.studio/bookproof/app/)** | 立即试用 |
| 💻 **本地运行** | 克隆并在自己的机器上运行 FastAPI Web 应用程序 + 评估引擎。 → **[docs/LOCAL_RUN.md](docs/LOCAL_RUN.md)** | 开发人员/研究人员检查或运行验证器 |
## 功能
- **检索评估** - 跨五种方法 - `naive_first_context`、`naive_last_context`、`flat_chunk_rag`、`chapter_summary_chain`、`hierarchical_book_rag` - 在书籍长度的文档上。
- **声明/答案验证** - 根据源文档使用证据术语覆盖率、答案术语覆盖率和检索上下文精度/召回率等指标评估 AI 输出（或一组声明/问题）。
- **确定性** 本地嵌入 (`hashing_numpy`) - 可重复，不下载模型，不调用 Claude/OpenAI/Gemini。
- 三种使用方式：**CLI/eval 管道**、**本地 FastAPI Web 应用程序**和**本地 stdio MCP 服务器**用于 AI 编码客户端。
## 存在原因
短答案正确性和证据基础可能存在差异：模型可以给出一个看似合理的答案，但文档实际上并不支持。LongBook 验证器分离这些信号，以便您可以审计输出和检索是否基于长手稿——对于手稿 QA 和可重复的长文档评估非常有用。
## 在线产品
一个托管的、公开版本的此评估运行为 **BookProof**：
➡️ **[BookProof - 在线试用](https://tts.bedvibe.studio/bookproof/app/)**
BookProof 是一个现有的、相关的公开产品。**无需在本地运行此存储库中的任何内容**。
## 架构
一个评估引擎，三个访问界面，以及在线产品：
- **研究/评估引擎** (`src/`) - 分块、确定性索引构建、检索、五种方法、指标和声明验证。
- **本地 FastAPI Web 应用程序** (`product_mvp/server_longbook_verifier.py`) - 在浏览器中上传文档和金色问题，并在本地进行评分。
- **本地 stdio MCP 服务器** (`product_mvp/mcp_longbook_server.py`) - 通过 stdio 在本地暴露引擎给 MCP 客户端（例如 Claude Code / Codex）。
- **BookProof 公共产品/API** - 一个部署的实例，提供一个速率限制的公共演示和一个单独的令牌门控验证 API（参见 [BookProof API](#bookproof-api)）。
参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 获取图表。
## 研究方法
基准报告 **证据术语覆盖率、答案术语覆盖率、检索上下文召回率和任务完成行为** 分别 - 因为短答案正确性和证据基础可能存在差异。论文中记录了两个实验 [`paper/`](paper/):
- **实验 A** - 一个试点单一书籍基准（~64k 字，40 个金色问题，5 种检索方法，5 个外部消费者 AI 系统，在免费层协议下）。
- **实验 B** - 对 240,767 字语料库（~320,220 个令牌，80 个金色问题，5 种检索方法）的扩展压力测试。
这些是 **试点加压力测试包**，*不是* 通用模型排名或最先进声明。完整的方法和结果在 [`paper/`](paper/) 中；研究包存档在 **DOI [10.5281/zenodo.20513116](https://doi.org/10.5281/zenodo.20513116)**。
## 快速开始
```powershell
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```
详情：[docs/LOCAL_RUN.md](docs/LOCAL_RUN.md)。
## 运行本地 Web 应用程序
```powershell
python -m uvicorn product_mvp.server_longbook_verifier:app --host 127.0.0.1 --port 8078
```
然后打开 **<http://127.0.0.1:8078/>** 并上传文档和金色问题。
## 使用本地 MCP 服务器
```powershell
python product_mvp\mcp_longbook_server.py
```
MCP 服务器在 **本地 stdio 上运行**；MCP 客户端将其作为子进程启动。它还需要 `mcp` 包：`python -m pip install mcp`。参见 [docs/MCP.md](docs/MCP.md)。
## MCP 客户端配置
通用 `mcpServers` 条目（将路径替换为克隆存储库的路径 - 参见 [`mcp_config.example.json`](mcp_config.example.json))：
```json
{
"mcpServers": {
"longbook-proof-local": {
"command": "python",
"args": ["EDIT_THIS_PATH/product_mvp/mcp_longbook_server.py"]
}
}
}
```
## MCP 工具
所有工具都是 **读取或允许列表，本地限定**:
| 工具 | 描述 |
|---|---|
| `longbook_status` | 只读项目摘要（允许的根目录、脚本、报告/运行计数、默认后端）。 |
| `list_books` | 列出项目书籍文件夹（或项目内的子路径）下的 `.txt` / `.md` / `.docx` 文件。 |
| `list_reports` | 列出类似报告的文件（`.md` / `.txt` / `.json` / `.jsonl` / `.csv`）。 |
| `read_report` | 读取带有截断的类似报告文件。 |
| `run_chunking` | 将书籍分块为 `.jsonl` (`src/chunk_book.py`)。 |
| `run_index_build` | 构建检索索引 (`src/build_index.py`，`hashing_numpy`)。 |
| `run_retrieve` | 从现有的本地索引返回排名的块 (`src/retrieve.py`)。 |
| `run_eval` | 在书籍 + 问题上运行检索评估方法 (`src/run_eval.py`)。 |
| `generate_report_tables` | 从运行文件夹构建摘要 CSV 表 (`src/report_tables.py`)。 |
## 存储库结构
```text
src/ 评估引擎（分块、索引、检索、方法、指标、声明检查）
product_mvp/ 本地 FastAPI Web 应用程序 + 本地 stdio MCP 服务器 + site/ 前端
paper/ 研究论文（方法、结果、局限性）+ CITATION.cff
docs/ LOCAL_RUN、MCP、ARCHITECTURE
scripts/ Windows 助手（run_web.bat、run_mcp.bat）
```
## 数据政策
版权保护的语料库、源手稿、私人评估数据和用户上传 **故意排除** 在此存储库之外。工具在您提供的文档上运行。
## 安全模型
在 `product_mvp/mcp_longbook_server.py` 中确认：MCP 服务器 **仅限本地 stdio 运行** 并调用 **允许列表** 的本地脚本。它使用 **无任意 shell 命令**（无 `shell=True`），强制执行 **严格的读写路径检查**（读取仅限于项目根目录；写入仅限于 `outputs/`、`reports/` 和 `product_mvp/runs/`），**拒绝** 包含 `.env` / `secret` / `key` / `token` / `password` 的路径，以 `stdin=DEVNULL` 运行子脚本，应用超时，并且 **不进行云或外部模型调用**。它 **不提供** shell 执行或远程访问。
## BookProof API
托管的 **[BookProof](https://tts.bedvibe.studio/bookproof/app/)** 产品公开：
- 一个 **公共、限速演示** 端点（上限文档大小、限速问题、每天每个 IP 一次运行，处理后删除输入），以及
- 一个单独的 **令牌门控验证 API** （通过 `X-BookProof-Token` 头部进行身份验证），具有可读的机器规范端点。
存储库中不包含令牌。
## 局限性
- 评估是 **基于词汇/检索和确定性** 的（`hashing_numpy`）；它不是一个语义嵌入或模型评估基准。
- 已发布的 结果是 **试点 + 压力测试**，而不是通用排名或 SOTA 声明。
- MCP 服务器期望 **本地项目文件** 并完全在您的机器上运行。
## 许可证
[MIT](LICENSE) © 2026 Panos Gkilis。联系方式：[GitHub 安全咨询](https://docs.github.com/en/code-security/security-advisories) 获取安全报告（参见 [SECURITY.md](SECURITY.md)）。
