内容
# preprint-fulltext
获取 **全文** 的 bioRxiv / medRxiv / **arXiv** 预印本作为干净、结构化、嵌入式的数据 — 通过 CLI、Python 库或 MCP 服务器。
`preprint-fulltext` 将 DOI（或搜索）转换为结构化部分（摘要 / 引言 / 方法 / 结果 / 讨论）、单个 JSON/Markdown 文档或块状 JSONL/Parquet Corpus，以便进行嵌入和 RAG。openRxiv 文本和数据挖掘（TDM）合规性在结构上得到强制执行，而不是交给用户。
> **"嵌入准备" 意味着输出是干净的、按章节划分的、按 token 边界划分的块 — 准备好输入到您的嵌入模型中。计算嵌入是可选的最后一步，您自己完成；此工具不捆绑嵌入模型。**
---
## 为什么
预印本全文分散在不兼容的渠道中：欧洲 PMC 提供 JATS XML 用于开放获取子集，openRxiv S3 存储桶持有权威 `.meca` Corpus（请求者付费），OpenAlex 是一个仅限 n-gram 的全文搜索目录，bioRxiv/medRxiv 网站渲染 HTML。`preprint-fulltext` 将它们统一在一个规范的数据模型和 **一个共享的 JATS 解析器** 后，您可以获得相同的结构化输出，无论文档来自哪里。
## 适用人群
- **机器学习 / 自然语言处理研究人员**，用于在预印本文献上构建嵌入语料库或 RAG 系统。
- **生物信息学家和实验室**，需要论文的方法/结果作为干净的文本用于分析、提取或 LLM 流水线。
- **编码代理**（通过 MCP 服务器 / `SKILL.md`），需要拉取预印本的全文或在任务中搜索文献。
- 任何人想要 **从 DOI 获取一个预印本的章节**，而无需手动解析 JATS 或抓取 HTML。
## AI 驱动的科学全文
语言模型和代理在论文的 **方法 和 结果** 上推理远比仅在摘要上更可靠 — 大多数科学声明、协议、数量和注意事项都存在于正文中。`preprint-fulltext` 将 Claude、Codex 和其他代理作为干净的、按章节标记的、具有溯源和许可标签的文本，这是 **基于事实的科学推理 和 深入研究** 的基础：
- **文献深入研究** — 跨越多篇论文的全文，而不仅仅是摘要。
- **方法和协议提取** — 拉取确切的程序、参数和数据集。
- **声明验证** — 检查陈述的结果与实际结果部分。
- **可重复性和元分析** — 比较多个研究的方法和数据。
- **RAG 构建您自己的语料库** — 按章节划分的、按 token 边界划分的块，附带引用。
因为每个 `Section` / `Chunk` 都带有其 `类型`（方法 / 结果 / ...）、`来源` 和 `许可`，所以代理可以 **精确引用**（哪一节哪一版论文）并在其推理过程中 **保持许可**。全文是检索，而不是记忆：模型在其推理中依据原始来源，而不是回忆可能过时的总结。
## 功能
- **`get <id>`** — 获取一篇预印本的全文，作为结构化的 JSON 或 Markdown。bioRxiv / medRxiv 路由欧洲 PMC → S3（可选 HTML 备用）；**arXiv** id 路由到 arXiv 的 LaTeXML 全文（原生 HTML → ar5iv）。默认最新版本； `--version` 选择一个版本。
- **`search` / `discover`** — 关键词、标题、摘要或作者搜索欧洲 PMC、OpenAlex 和 **arXiv**；主题/类别/日期发现。
- **`ingest`** — 可恢复的、增量式的批量摄取来自 openRxiv S3 存储桶的块状语料库（JSONL 或 Parquet），附带侧边栏清单。
- **MCP 服务器** — 为编码代理提供与工具相同的功能。
- **内置合规性** — 出口门户将不可再分发作品降级为链接备份；未知许可被视为不可再分发（故障安全）。
## 安装
```bash
pip install preprint-fulltext # CLI + Python 库 + MCP 服务器
pip install "preprint-fulltext[parquet,openalex]" # + Parquet 输出，pyalex
```
**MCP 服务器内置** — 无需额外安装和第三方 MCP 框架。它是一个小型、自包含的 JSON-RPC 2.0 stdio 服务器，因此 `preprint-fulltext-mcp` 开箱即用，仅需核心依赖项。
设置欧洲 PMC / OpenAlex 礼貌池的联系邮箱（推荐），以及使用 OpenAlex 时所需的 OpenAlex API 密钥（自 2026-02-13 起必需）：
```bash
export CONTACT_EMAIL="you@example.org"
export OPENALEX_API_KEY="..." # 仅 OpenAlex 搜索/发现需要
```
## 快速入门（CLI）
```bash
# 获取一篇预印本的结构化全文（欧洲 PMC → S3 路由器）
preprint-fulltext get 10.1101/2024.01.15.575000 --markdown
# 接受 DOI、doi.org URL 或 bioRxiv/medRxiv 内容 URL
preprint-fulltext get https://www.biorxiv.org/content/10.64898/2026.06.13.731750v1.full --html --markdown
# 版本：DOI 默认解析为最新版本； --version 选择一个版本
preprint-fulltext get 10.64898/2026.01.29.702557 --version 1 --source html --markdown
# arXiv: id, arxiv.org URL 或 10.48550/arXiv.* DOI — 路由到 arXiv LaTeXML 全文
preprint-fulltext get arXiv:1706.03762 --markdown
preprint-fulltext get https://arxiv.org/abs/2401.10515 --markdown
# 搜索：关键词、标题或作者（添加 --source arxiv 以搜索 arXiv）
preprint-fulltext search "cortical interneurons" -n 20
preprint-fulltext search "Fezf2" --field title
preprint-fulltext search "Min Dai" --field author
preprint-fulltext search "diffusion model" --field title --source arxiv
# 按主题 + 日期窗口发现（OpenAlex）
preprint-fulltext discover --query "spatial transcriptomics" --since 2025-01 -n 100
# 来自 S3 的批量语料库（请求者付费；需要 AWS 凭证）
preprint-fulltext ingest corpus.jsonl --source s3 --server biorxiv --since 2025-06
# 通过欧洲 PMC 免费获取开放获取（CC）子集的语料库
preprint-fulltext ingest corpus.jsonl --source europepmc --query "long covid"
```
`get` 发出 `FullText` 文档（JSON）或 Markdown (`--markdown`)。`search` / `discover` 流式传输一个 `SearchHit` 每行（JSONL）。`ingest` 每行写入一个 `Chunk`，并附带一个 `<out>_manifest.jsonl` 审计/恢复侧边栏。
## 典型工作流
**1. 将一篇论文的方法/结果作为文本读取。**
```bash
preprint-fulltext get 10.64898/2026.01.29.702557 --markdown > paper.md
# -> # 标题 / ## 摘要 / ## 引言 / ## 方法 / ## 结果 / ## 讨论
```
**2. 在一个主题上构建一个嵌入准备的语料库（免费，无需 AWS）。**
```bash
# 通过欧洲 PMC 获取 CC/开放获取子集 — JSONL 每行一个块
preprint-fulltext ingest cortex.jsonl --source europepmc --query "cortical interneurons" -n 500
# cortex.jsonl -> {doi, version, chunk_id, section_kind, text, token_count, license, ...}
# cortex_manifest.jsonl -> 每行一个预印本（doi, version, license, n_chunks, status）
```
**3. 从 S3 构建一个月的完整语料库（请求者付费）。**
```bash
export AWS_PROFILE=... # 需要 AWS 凭证；~$0.09/GB
preprint-fulltext ingest 2025-06.jsonl --source s3 --server both --since 2025-06 --format parquet
# 可恢复：重新运行后跳过已完成的预印本（无重复）
```
**4. 按作者或标题查找论文，然后获取。**
```bash
preprint-fulltext search "Min Dai" --field author -n 20 > hits.jsonl
preprint-fulltext get "$(head -1 hits.jsonl | python -c 'import sys,json;print(json.load(sys.stdin)["doi"])')" --markdown
```
**5. 为编码代理提供文献访问** — 运行 `preprint-fulltext-mcp` 并指向它（参见 [`skills/preprint-fulltext/SKILL.md`](skills/preprint-fulltext/SKILL.md)）。
## Python
```python
from preprint_fulltext.pipeline.router import Router
result = Router().get_fulltext("10.1101/2024.01.15.575000")
if result.fulltext:
for section in result.fulltext.sections:
print(section.kind, section.title)
from preprint_fulltext.core.chunk import chunk_fulltext
chunks = chunk_fulltext(result.fulltext) # 嵌入准备的块记录
```
## MCP 服务器
```bash
preprint-fulltext-mcp # stdio MCP 服务器
```
`mcp-name: io.github.genecell/preprint-fulltext`
公开 `search_preprints`、`get_fulltext`、`get_metadata` 和 `resolve`。批量摄取 **不** 是 MCP 工具（它耗时长且产生请求者付费成本）。参见 [`skills/preprint-fulltext/SKILL.md`](skills/preprint-fulltext/SKILL.md) 以获取代理端用法。
## 数据源和路由
| 动词 | 默认源 | 注释 |
|-------------|-----------------------|---------------------------------------------------|
| `get` | 自动（欧洲 PMC → S3，或 arXiv） | bioRxiv/medRxiv：欧洲 PMC（CC/开放获取子集）→ S3（完整，需要 AWS 凭证）， `--html` 可选备用。 **arXiv id** → arXiv LaTeXML 全文（原生 HTML → ar5iv）。 |
| `search` | 欧洲 PMC | 真实的相关性排名； `--source openalex\|arxiv`。 |
| `discover` | OpenAlex | 250M+ 作品，开放获取位置，主题/日期； `--source arxiv`。 |
| `ingest` | S3（或欧洲 PMC） | S3 = 完整语料库；欧洲 PMC = 免费 CC 子集。arXiv 批量范围外（使用 arXiv 自己的 S3 LaTeX 存储桶）。 |
## 配置
通过环境变量（前缀 `PREPRINT_FULLTEXT_` 或以下名称）、`.env` 文件或 `preprint-fulltext.toml` 配置：
| 设置 | 默认值 | 目的 |
|---|---|---|
| `CONTACT_EMAIL` | – | 欧洲 PMC / OpenAlex 的礼貌池身份 |
| `OPENALEX_API_KEY` | – | OpenAlex 自 2026-02-13 以来必需 |
| `AWS_REGION` | `us-east-1` | 请求者付费 openRxiv 存储桶的区域 |
| `PREPRINT_FULLTEXT_CACHE_DIR` | `~/.cache/preprint-fulltext` | 内容寻址缓存 |
| `PREPRINT_FULLTEXT_CHUNK_TOKENS` | `512` | 每块最大 token 数 |
| `PREPRINT_FULLTEXT_CHUNK_OVERLAP` | `64` | 章节内的 token 重叠 |
## 合规性
语料库用于操作员自己的文本/数据挖掘，遵循 openRxiv TDM 条款。`preprint-fulltext` **不** 重新托管或重新分发预印本全文。每个 `FullText` / `Chunk` 都带有其许可；出口门户有两个模式：
- **分析** （默认）：您自己的挖掘的直通。
- **重新分发** (`--redistribution`)：许可允许重新分发的作品保持不变；所有其他作品降级为 **链接备份** （元数据 + URL，无正文）。未知/模糊许可被视为不可重新分发。
## 开发
```bash
pip install -e ".[dev]"
pytest # 离线套件（使用 respx 模拟 HTTP，使用 moto 模拟 S3）
ruff check preprint_fulltext/
```
实时测试是可选的（它们会调用真正的公共 API — 欧洲 PMC、arXiv 和 bioRxiv/medRxiv JSON API）：
```bash
PREPRINT_FULLTEXT_LIVE=1 CONTACT_EMAIL=you@example.org pytest -m live # EPMC / arXiv / medRxiv / 版本
PREPRINT_FULLTEXT_LIVE_S3=1 pytest -m live_s3 # 请求者付费 S3（小；需要 AWS 凭证）
```
相同的实时烟雾测试在 CI 中按需运行（操作 → **实时烟雾**）和每周，以捕获上游 API 偏移；默认 `test` 工作流保持完全离线。
代理文档（`AGENTS.md`、`llms.txt`、`.cursor/rules/…`、`.github/copilot-instructions.md`）从 `skills/preprint-fulltext/SKILL.md` 生成：
```bash
python scripts/build_agent_docs.py
```
## 联系方式
**Min Dai** — <dai@broadinstitute.org> ([Gord Fishell Lab](https://fishelllab.hms.harvard.edu)，哈佛医学院 / 布罗德研究所）。问题和拉取请求欢迎访问 <https://github.com/genecell/preprint-fulltext>。
## 许可证
BSD-3-Clause（参见 [`LICENSE`](LICENSE)）。这仅涵盖 **软件** — 检索的预印本内容仍在其作者选择的许可证下。
