内容
<!-- ---
!-- Timestamp: 2026-01-16 19:15:51
!-- Author: ywatanabe
!-- File: /home/ywatanabe/proj/crossref-local/README.md
!-- --- -->
# CrossRef 本地版
<p align="center">
<a href="https://scitex.ai">
<img src="docs/scitex-logo-blue-cropped.png" alt="SciTeX" width="400">
</a>
</p>
<p align="center"><b>本地 CrossRef 数据库，包含 1.67 亿+ 学术作品，全文本搜索和影响因子计算</b></p>
## 演示
<p align="center">
<img src="examples/readme_figure.png" alt="CrossRef 本地版演示" width="800"/>
</p>
```bash
# 在本地搜索 1.67 亿篇论文 - 无 API 速率限制，约 22 毫秒全文查询
crossref-local search "癫痫发作预测"
# 解析 DOI 获取完整记录（标题，摘要，引用，期刊影响因子）
crossref-local search-by-doi 10.1038/nature11247
# 通过 MCP / Claude 代码驱动
crossref-local mcp serve
```
图像是针对本地数据库的实时捕获；下面的 `<details>` 块包含 6 分 55 秒的 MCP 驱动演示视频。
## 架构
```
┌──────────────────────────┐ ┌──────────────────────────┐
│ CrossRef 公共数据转储 │ │ JCR / OpenAlex 影响因子表 │
│ （~100 GB 压缩） │ │ │
└──────────────┬───────────┘ └──────────────┬───────────┘
│ dois2sqlite │
▼ ▼
┌─────────────────┐ ┌──────────────┐
│ crossref.db │ ◀── joins ──▶ │ 影响因子 │
│ （SQLite + FTS5） │ │ 表 │
└────────┬────────┘ └──────────────┘
│
▼
┌──────────────────────────────────┐
│ crossref-local — Python / CLI / MCP │
│ search · search-by-doi · cache │
│ stats · check-citations · relay │
└──────────────────────────────────┘
```
数据库完全存储在磁盘上；`crossref-local` 是 SQLite + FTS5 + 小型影响因子表的薄封装。在查询期间没有网络调用；`make fts-build-screen` / `citations-build-screen` 下的重建脚本是状态的唯一生产者。
[](https://badge.fury.io/py/crossref-local)
[](https://crossref-local.readthedocs.io/en/latest/)
[](https://github.com/ywatanabe1989/crossref-local/actions/workflows/test.yml)
[](https://codecov.io/gh/ywatanabe1989/crossref-local)
[](https://www.python.org/downloads/)
[](LICENSE)
<details>
<summary><strong>MCP 演示视频</strong></summary>
<p align="center">
<a href="https://scitex.ai/media/videos/crossref-local-v0.3.1-demo.mp4">
<img src="examples/04_mcp_demo_out/crossref-local-v0.3.1-demo-thumbnail_6m55s.png" alt="演示视频缩略图" width="600"/>
</a>
</p>
`癫痫发作预测` 文献综述的 MCP 服务器集成与 Claude 代码演示：
- 1.67 亿篇论文的全文搜索（22 毫秒响应）
📄 [完整演示文档](examples/demo_mcp.org) | 📊 [生成的图表](examples/04_mcp_demo_out/)
</details>
<details>
<summary><strong>为什么选择 CrossRef 本地版？</strong></summary>
**为 LLM 时代而构建** - 适用于 AI 研究助手的功能：
| 功能 | 益处 |
|---------|---------|
| 📝 **摘要** | 用于语义理解的全文 |
| 📊 **影响因子** | 按期刊质量过滤 |
| 🔗 **引用** | 优先考虑有影响力的论文 |
| ⚡ **速度** | 毫秒级搜索 1.67 亿记录，无速率限制 |
完美适用于：RAG 系统，研究助手，文献综述自动化。
</details>
<details>
<summary><strong>安装</strong></summary>
```bash
pip install crossref-local
```
从源码：
```bash
git clone https://github.com/ywatanabe1989/crossref-local
cd crossref-local && make install
```
数据库设置（1.5 TB，约 2 周构建）：
```bash
# 1. 下载 CrossRef 数据（~100GB 压缩）
aria2c "https://academictorrents.com/details/..."
# 2. 构建 SQLite 数据库（~天）
pip install dois2sqlite
dois2sqlite build /path/to/crossref-data ./data/crossref.db
# 3. 构建 FTS5 索引（~60 小时）和引用表（~天）
make fts-build-screen
make citations-build-screen
```
</details>
<details>
<summary><strong>Python API</strong></summary>
```python
from crossref_local import search, get, count
# 全文搜索（22 毫秒搜索 541 个匹配项，跨 1.67 亿记录）
results = search("海马电激波")
for work in results:
print(f"{work.title} ({work.year})")
# 通过 DOI 获取
work = get("10.1126/science.aax0758")
print(work.citation())
# 计数匹配项
n = count("机器学习") # 477,922 个匹配项
```
异步 API：
```python
from crossref_local import aio
async def main():
counts = await aio.count_many(["CRISPR", "神经网络", "气候"])
results = await aio.search("机器学习")
```
</details>
<details>
<summary><strong>CLI</strong></summary>
```bash
crossref-local search "CRISPR 基因编辑" -n 5
crossref-local search-by-doi 10.1038/nature12373
crossref-local status # 配置和数据库统计
```
带摘要（`-a` 标志）：
```
$ crossref-local search "RS-1 增强 CRISPR" -n 1 -a
找到 4 个匹配项，耗时 128.4 毫秒
1. RS-1 增强 CRISPR/Cas9- 和 TALEN- 介导的敲入效率（2016）
DOI：10.1038/ncomms10548
期刊：Nature Communications
摘要：锌指核酸酶，转录激活因子样效应核酸酶和 CRISPR/Cas9 正在成为基因编辑的主要工具...
```
</details>
<details>
<summary><strong>HTTP API</strong></summary>
启动 FastAPI 服务器：
```bash
crossref-local relay --host 0.0.0.0 --port 31291
```
端点：
```bash
# 搜索作品（FTS5）
curl "http://localhost:31291/works?q=CRISPR&limit=10"
# 通过 DOI 获取
curl "http://localhost:31291/works/10.1038/nature12373"
# 批量 DOI 查询
curl -X POST "http://localhost:31291/works/batch" \
-H "Content-Type: application/json" \
-d '{"dois": ["10.1038/nature12373", "10.1126/science.aax0758"]}'
# 引用端点
curl "http://localhost:31291/citations/10.1038/nature12373/citing"
curl "http://localhost:31291/citations/10.1038/nature12373/cited"
curl "http://localhost:31291/citations/10.1038/nature12373/count"
# 集合端点
curl "http://localhost:31291/collections"
curl -X POST "http://localhost:31291/collections" \
-H "Content-Type: application/json" \
-d '{"name": "my_papers", "query": "CRISPR", "limit": 100}'
curl "http://localhost:31291/collections/my_papers/download?format=bibtex"
# 数据库信息
curl "http://localhost:31291/info"
```
HTTP 模式（连接到正在运行的服务器）：
```bash
# 在本地机器上（如果服务器是远程的）
ssh -L 31291:127.0.0.1:31291 your-server
# Python 客户端
from crossref_local import configure_http
configure_http("http://localhost:31291")
# 或通过 CLI
crossref-local --http search "CRISPR"
```
</details>
<details>
<summary><strong>MCP 服务器</strong></summary>
作为 MCP（模型上下文协议）服务器运行：
```bash
crossref-local mcp start
```
本地 MCP 客户端配置：
```json
{
"mcpServers": {
"crossref-local": {
"command": "crossref-local",
"args": ["mcp", "start"],
"env": {
"CROSSREF_LOCAL_DB": "/path/to/crossref.db"
}
}
}
}
```
通过 HTTP 进行远程 MCP：
```bash
# 在服务器上：启动持久的 MCP 服务器
crossref-local mcp start -t http --host 0.0.0.0 --port 8082
```
```json
{
"mcpServers": {
"crossref-remote": {
"url": "http://your-server:8082/mcp"
}
}
}
```
诊断设置：
```bash
crossref-local mcp doctor # 检查依赖项和数据库
crossref-local mcp list-tools # 显示可用的 MCP 工具
crossref-local mcp installation # 显示客户端配置示例
```
查看 [docs/remote-deployment.md](docs/remote-deployment.md) 以获取 systemd 和 Docker 设置。
可用工具：
- `search` - 跨 1.67 亿+ 篇论文的全文搜索
- `search_by_doi` - 通过 DOI 获取论文
- `enrich_dois` - 为 DOI 添加引用计数和参考文献
- `status` - 数据库统计信息
- `cache_*` - 论文集合管理
</details>
<details>
<summary><strong>影响因子</strong></summary>
```python
from crossref_local.impact_factor import ImpactFactorCalculator
with ImpactFactorCalculator() as calc:
result = calc.calculate_impact_factor("Nature", target_year=2023)
print(f"影响因子：{result['impact_factor']:.3f}") # 54.067
```
| 期刊 | 2023 年影响因子 |
|---------|---------|
| Nature | 54.07 |
| Science | 46.17 |
| Cell | 54.01 |
| PLOS ONE | 3.37 |
</details>
<details>
<summary><strong>引用网络</strong></summary>
```python
from crossref_local import get_citing, get_cited, CitationNetwork
citing = get_citing("10.1038/nature12373") # 1539 篇论文
cited = get_cited("10.1038/nature12373")
# 构建可视化（类似 Connected Papers）
network = CitationNetwork("10.1038/nature12373", depth=2)
network.save_html("citation_network.html") # 需要：pip install crossref-local[viz]
```
</details>
<details>
<summary><strong>性能</strong></summary>
| 查询 | 匹配项 | 时间 |
|-------|---------|------|
| `海马电激波` | 541 | 22 毫秒 |
| `机器学习` | 477,922 | 113 毫秒 |
| `CRISPR 基因编辑` | 12,170 | 257 毫秒 |
通过 FTS5 在毫秒内搜索 1.67 亿记录。
</details>
<details>
<summary><strong>相关项目</strong></summary>
**[openalex-local](https://github.com/ywatanabe1989/openalex-local)** - 具有 OpenAlex 数据的姊妹项目：
| 功能 | crossref-local | openalex-local |
|---------|----------------|----------------|
| 作品 | 1.67 亿 | 2.84 亿 |
| 摘要 | ~21% | ~45-60% |
| 更新频率 | 实时 | 每月 |
| DOI 权限 | ✓ （源） | 使用 CrossRef |
| 引用 | 原始参考文献 | 链接作品 |
| 概念/主题 | ❌ | ✓ |
| 作者 ID | ❌ | ✓ |
| 最适合 | DOI 查询，原始引用解析，权威元数据 | 语义搜索，引用分析，主题发现 |
**何时使用 CrossRef**：实时 DOI 更新，原始引用解析，权威元数据。
**何时使用 OpenAlex**：语义搜索，引用分析，主题发现。
</details>
## 安装
```bash
pip install crossref-local # 核心
pip install crossref-local[mcp] # + MCP 服务器
```
从源码：
```bash
git clone https://github.com/ywatanabe1989/crossref-local
cd crossref-local && make install
```
## 4 接口
<details open>
<summary><strong>Python API</strong></summary>
```python
from crossref_local import search, get, count
# 全文搜索（22 毫秒搜索 541 个匹配项，跨 1.67 亿记录）
results = search("海马电激波")
for work in results:
print(f"{work.title} ({work.year})")
# 通过 DOI 获取
work = get("10.1126/science.aax0758")
print(work.citation())
# 计数匹配项
n = count("机器学习") # 477,922 个匹配项
```
</details>
<details>
<summary><strong>CLI</strong></summary>
```bash
crossref-local search "CRISPR 基因编辑" -n 5
crossref-local search-by-doi 10.1038/nature12373
crossref-local status # 配置和数据库统计
```
</details>
<details>
<summary><strong>HTTP API</strong></summary>
查看上面的 [HTTP API 部分](#http-api) 以获取所有端点。
</details>
<details>
<summary><strong>MCP 服务器</strong></summary>
查看上面的 [MCP 服务器部分](#mcp-server) 以获取配置。
</details>
## SciTeX 组成部分
`crossref-local` 是 [**SciTeX**](https://scitex.ai) 的组成部分。
> 研究的四大自由
>
> 0. 在任何地方运行研究的自由 - 您的机器，按照您的条件。
> 1. 研究每个步骤的工作原理的自由 - 从原始数据到最终手稿。
> 2. 分发工作流的自由，而不仅仅是论文。
> 3. 修改任何模块并与社区分享改进的自由。
>
> AGPL-3.0 - 因为我们相信研究基础设施应该拥有与其运行的软件相同的自由。
---
<p align="center">
<a href="https://scitex.ai" target="_blank"><img src="docs/scitex-icon-navy-inverted.png" alt="SciTeX" width="40"/></a>
</p>
