Bibverify

Bibverify

验证文献是否存在以及元数据是否一致，同时避免破坏性编辑。

中文 · 安装 · 快速开始 · MCP · 开发

Bibverify 是一款面向研究人员、编辑、自动化流程和 AI 助手的 BibTeX 元数据验证工具。它首先根据精确的 DOI、PMID、PMCID 或 arXiv 标识符进行查询，然后依据标题、作者、年份、出版物和页码等信息为候选结果评分。

Bibverify 会评估能否在所查询的来源中找到某条文献记录，以及其元数据是否一致。它无法证明研究结果真实、数据可信或出版物值得信赖。数据库中没有记录，并不意味着文献是伪造的。默认情况下，源 .bib 文件绝不会被覆盖。

亮点

• 优先根据 DOI、PMID、PMCID 和 arXiv ID 查询标识符。
• 支持 Crossref、OpenAlex、Semantic Scholar、PubMed、Europe PMC、CORE、DBLP、arXiv、bioRxiv 等来源。
• 基于标识符、标题、作者、年份、出版物和页码等多个信号进行可解释的匹配。如果 DOI 可以解析，但标题存在实质性差异，结果会标记为 identifier_conflict，而不会被标题搜索结果掩盖。
• 结构化的提供方结果会区分确实没有匹配项，以及限流、身份验证、网络、解析和提供方故障等情况。
• 非破坏性合并会保留提供方未返回的 abstract、keywords、file、note 和自定义字段；不会自动覆盖相互冲突的持久标识符。
• 共享连接池支持重试、指数退避，以及针对 429/5xx 响应的 Retry-After。
• 使用可过期的 SQLite 缓存保存成功的 GET 响应；失败结果绝不会缓存。
• 支持跨平台路径、编码、Unicode 文件名、UTF-8 BOM 和 CRLF。
• 支持 JSON 输出、稳定的退出代码、Python API，以及基于官方 SDK 构建的 MCP 服务。
• 采用原子方式写入输出，并提供逐字节保留内容的备份。

要求

• Windows、macOS 或 Linux
• 可访问已启用的元数据 API 的网络连接
• 使用 Python 发行版时需要 Python 3.11–3.14；npm、容器和原生软件包均包含其运行时

GitHub Actions 会在全部三种操作系统上，对所有四个受支持的 Python 版本进行测试。

安装

当前发布的版本为 v0.3.0。此分支为 v0.4.0 做准备；标记为 v0.4.0 的命令只有在其关联的 npm、GHCR 或 GitHub Release 构件发布后才能使用。

无需永久安装即可运行：

uvx bibverify --version

从 v0.4.0 开始，Node.js 用户可以使用零依赖的 npm 启动器。它会下载匹配的原生版本、验证 SHA256SUMS，并传递所有参数和退出代码：

npx --yes @hylouis233/bibverify --version
pnpm dlx @hylouis233/bibverify --version
bunx --bun @hylouis233/bibverify --version

如需在隔离的 Python 环境中使用持久 CLI，请使用 uv tool 或 pipx：

uv tool install bibverify

pipx install bibverify

在虚拟环境中，也可以直接使用常规 pip：

python -m pip install --upgrade bibverify

每个版本还会在 GitHub Releases 上提供经过冒烟测试的原生安装包。从 v0.4.0 开始，发布矩阵将涵盖 Windows x64，以及 x64 和 ARM64 的 macOS 与 glibc 2.28+ Linux。基于 musl 的 Linux 用户应使用 Python 包或容器映像。目前尚未原生发布 Windows ARM64 版本，因为 MCP 运行时依赖项目前不提供 Windows ARM64 wheel；npm 会在 Windows 11 仿真环境下自动使用经过测试的 x64 版本，你也可以改用 ARM64 容器。

同一版本还会发布多架构容器：

docker run --rm ghcr.io/hylouis233/bibverify:0.4.0 --version

包管理器清单根据最终发布的文件生成，而不是根据未经验证的构建输入生成。Homebrew、Scoop 和 WinGet 尚未上线目录条目：v0.4.0 会在 GitHub Release 中附上可直接提交的清单，之后仍需各外部目录完成入驻或审核。有关推出状态，请参阅分发渠道。

快速开始

将 DOI 转换为 BibTeX

bibverify doi 10.1038/nature12373 --key example2013

如需机器可读的响应：

bibverify doi 10.1038/nature12373 --json

验证 .bib 文件

创建一个基础配置：

bibverify config init

将 references.bib 放在配置文件旁边，然后运行：

bibverify check --config config.json

你可以通过命令行覆盖输入和输出路径：

bibverify check references.bib --config config.json --output-dir bibverify-output

检查结果，但不写入任何文件：

bibverify check references.bib --dry-run --json

查看报告后，显式应用高置信度字段更新。Bibverify 会先创建逐字节备份：

bibverify check references.bib --apply

PowerShell 示例：

py -m bibverify check '.\Bibliography\references.bib' --output-dir '.\Verification results'

为保持兼容，仍可使用 v0.2 形式，但新脚本应使用子命令：

bibverify config.json
bibverify --doi 10.1038/nature12373 --key example2013

配置

最简配置如下：

{
  "language": "EN",
  "bib_file": "references.bib",
  "encoding": "auto",
  "output_dir": "bibverify-output",
  "user_info": {
    "email": "[email protected]",
    "app_name": "Bibverify"
  }
}

所有常用选项请参阅 config_template.json。

路径行为特意设计得可预测：

• 相对的 bib_file 和 output_dir 值以 config.json 所在目录为基准解析，而不是以 shell 当前目录为基准。
• 如果省略 output_dir，输出将写入输入文献库所在目录。
• encoding: "auto" 会依次尝试 UTF-8 with BOM、UTF-8 和 GB18030。它不会回退到 Latin-1，也不会将未知字节静默转换为乱码。

API 密钥和电子邮件

密钥可以存储在本地配置中，但使用环境变量更安全，也更不容易意外提交：

环境变量	用途
BIBVERIFY_EMAIL	Crossref 礼貌池和联系信息
BIBVERIFY_OPENALEX_API_KEY	OpenAlex
BIBVERIFY_SEMANTIC_SCHOLAR_API_KEY	Semantic Scholar
BIBVERIFY_PUBMED_API_KEY	PubMed/NCBI
BIBVERIFY_CORE_API_KEY	CORE

PowerShell：

$env:BIBVERIFY_EMAIL = '[email protected]'
$env:BIBVERIFY_OPENALEX_API_KEY = '...'
bibverify check --config config.json

Bash 或 Zsh：

export BIBVERIFY_EMAIL='[email protected]'
export BIBVERIFY_OPENALEX_API_KEY='...'
bibverify check --config config.json

查询和匹配设置

{
  "query_settings": {
    "delay_between_requests": 0.5,
    "timeout": 10,
    "connect_timeout": 3.05,
    "read_timeout": 20,
    "max_retries": 3,
    "backoff_factor": 0.5,
    "stop_on_first_match": true,
    "match_threshold": 0.86,
    "ambiguous_threshold": 0.68,
    "auto_update_threshold": 0.92,
    "cache_enabled": true,
    "cache_ttl_hours": 168,
    "cache_path": ".bibverify-cache.sqlite3"
  }
}

connect_timeout 和 read_timeout 分别限制连接建立和响应读取时间；同时仍保留兼容字段 timeout。match_threshold 控制自动接受候选项的阈值，ambiguous_threshold 控制哪些合理候选项需要人工审核，auto_update_threshold 则是更改字段时的额外门槛。数值越高，判断越保守。相对缓存路径以配置目录为基准解析。

bioRxiv 官方的 details 路由不支持任意标题搜索。因此，Bibverify 只会针对精确的 10.1101/... DOI 调用 bioRxiv；仅按标题搜索则交由支持此功能的服务商处理，例如 Crossref 和 Europe PMC。

CLI 参考

bibverify check [BIB_FILE] [--config PATH] [--output-dir DIR] [--format txt|json|jsonl|csv] [--dry-run|--apply] [--json]
bibverify doi DOI [--key KEY] [--config PATH] [--json]
bibverify config init [--output PATH] [--force]
bibverify doctor [--config PATH] [--json]
bibverify providers list [--json]
bibverify cache clear [--config PATH]
bibverify benchmark [--dataset PATH]
bibverify mcp [--config PATH] [--workspace-root DIR] [--transport stdio|streamable-http]
bibverify agent init [--target generic|codex|claude|cursor] [--output PATH]
bibverify skill export [--target ...]

退出代码：

代码	含义
0	验证已完成，元数据一致
1	运行时错误，保留用于未分类的命令失败
2	存在元数据差异或高置信度更新
3	存在需要审核的模糊、未找到或标识符冲突条目
4	服务商不可用，验证未完成
5	输入文件、配置或条目无效

使用 --json 时，stdout 仅包含 JSON。诊断信息会输出到 stderr，因此命令可安全用于 CI 和脚本。

输出文件

对于名为 references.bib 的输入，Bibverify 可能会创建：

• bibverify_report_<timestamp>.<format>：完整的状态、候选项、服务商错误、置信度和字段来源信息，格式为 txt、json、jsonl 或 csv。
• references_backup_<timestamp>.bib：源文件的逐字节副本。
• references_updated_<timestamp>.bib：经过非破坏性合并后的完整参考文献；无更改时不会生成。
• references_review_<timestamp>.bib：存在模糊、未找到、来源不可用、标识符冲突或无效的条目；无需审核时不会生成。

只有所有条目都已完成验证，报告级别的 complete 值才为 true。即使其他来源找到了候选项，只要有服务商遭遇速率限制或无法访问，该值就会为 false。每条 field_diffs 记录都包含原始值／建议值、来源、置信度、规范化等价性、操作和原因。

可通过 output_settings 分别禁用各项输出。--dry-run 会覆盖这些设置，不执行任何写入。默认命令只会写入建议；只有在创建备份后，--apply 才会更改源文件。

服务商排序

静态优先级只是起点：

1. 存在 DOI 时会提升 Crossref 的优先级，并优先使用其精确端点。若可解析的 DOI 对应的标题存在显著差异，则状态会变为 identifier_conflict。
2. 存在 PMID、PMCID 或生物医学领域提示时，会提升 PubMed 和 Europe PMC 的优先级。
3. 存在 arXiv 标识符时，会提升 arXiv 的优先级。
4. 存在计算机科学会议提示时，会提升 DBLP 的优先级。

目前，Unpaywall 被视为开放获取信息补充来源，而非主要书目元数据服务商。服务商状态包括 matched、no_match、ambiguous、rate_limited、auth_error、network_error、parse_error、provider_error 和 skipped。

MCP 和 AI 助手

Bibverify 使用官方 MCP Python SDK，并支持本地 stdio 和 Streamable HTTP 传输方式。

启动 stdio 服务：

bibverify mcp --config config.json --workspace-root .

MCP 客户端配置：

{
  "mcpServers": {
    "bibverify": {
      "command": "bibverify",
      "args": ["mcp", "--config", "config.json"]
    }
  }
}

面向 Node 的 MCP 客户端可以直接使用 npm 启动器：

{
  "mcpServers": {
    "bibverify": {
      "command": "npx",
      "args": ["--yes", "@hylouis233/bibverify", "mcp"]
    }
  }
}

容器化的 stdio MCP 会将当前目录设为唯一可写工作区：

docker run --rm -i -v "$PWD:/workspace" ghcr.io/hylouis233/bibverify:0.4.0 \
  mcp --workspace-root /workspace

启动 Streamable HTTP：

bibverify mcp --transport streamable-http --config config.json

默认情况下，MCP 会将配置目录视为工作区根目录。它会拒绝读取该根目录之外的配置或 .bib 文件，并阻止在该目录之外写入报告、缓存或更新内容。只有在启动服务时明确设置 --workspace-root，才能扩大访问范围。官方 MCP SDK 负责处理协议协商、架构、结构化结果、进度和取消操作。

可用工具：

• doi_to_bibtex
• rank_lookup_sources
• explain_update_diff
• verify_bib_file

为 Codex、Claude、Cursor 或通用 MCP 客户端生成配置文件：

bibverify agent init --target codex --output .bibverify-agent --config config.json
bibverify doctor --config config.json

分发渠道

渠道	命令或制品	可用性
PyPI	python -m pip install bibverify	已发布
uv	uvx bibverify 或 uv tool install bibverify	已发布
pipx	pipx install bibverify	已发布
npm	npx --yes @hylouis233/bibverify	计划于 v0.4.0 发布；尚未发布
pnpm / Bun	pnpm dlx @hylouis233/bibverify / bunx --bun @hylouis233/bibverify	计划于 v0.4.0 发布；尚未发布
GHCR	docker pull ghcr.io/hylouis233/bibverify:0.4.0	计划于 v0.4.0 发布；尚未发布
原生程序	Windows x64；macOS 和 glibc 2.28+ Linux x64/ARM64	计划于 v0.4.0 发布；尚未发布
Homebrew	发布制品 bibverify.rb	计划于 v0.4.0 提交清单；目录尚未上线
Scoop	发布制品 bibverify.json	计划于 v0.4.0 提交清单；目录尚未上线
WinGet	发布制品 Hylouis233.Bibverify*.yaml	计划于 v0.4.0 提交清单；目录尚未上线
MCP Registry	io.github.Hylouis233/bibverify	已发布发现元数据；请通过上方某个软件包条目安装

npm 软件包是一个轻量启动器，并非另一套实现。无论通过 PyPI、npm、原生软件包还是容器分发，验证引擎都使用同一 Python 代码库。发布制品包含 SHA256SUMS；npm 会在执行前验证所选二进制文件，Homebrew、Scoop 和 WinGet 清单则会固定使用相同的发布哈希值。

Python API

from bibverify.checker import BibTeXChecker

checker = BibTeXChecker("config.json")
summary = checker.run()
print(summary["counts"])

在 0.3 发布系列期间，from bib_check import BibTeXChecker 仍保持兼容，但新代码应使用上方的软件包导入方式。

开发

git clone https://github.com/Hylouis233/bibverify.git
cd bibverify
python -m venv .venv

激活环境后：

python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check src tests tools bib_check.py
python -m ruff format --check src tests tools bib_check.py
python -m mypy
python -m build
python -m twine check dist/*
python -m bibverify benchmark --dataset benchmarks/cases.json
python -m pip_audit . --strict
(cd npm && npm ci && npm test && npm pack --dry-run)
docker build --tag bibverify:dev .

推送前，请运行 python tools/fix.py。该命令会对 CI 检查的路径执行 ruff format 和导入排序，然后运行 CI 的 ruff check 和 ruff format --check 命令；如果有任何需要手动修复的问题，命令会失败。pre-commit install 会将同一命令设置为提交钩子（参见 .pre-commit-config.yaml）。

CI 会在 Python 3.11–3.14 上测试 Windows、macOS 和 Linux，涵盖提供方测试夹具、黄金写入安全测试、代码检查、类型检查、覆盖率、离线基准测试、依赖项审计、Python 和 npm 软件包构建、容器冒烟测试以及 CycloneDX SBOM。GitHub Actions 均固定到提交 SHA，而 MCP Publisher 则固定版本并通过 SHA-256 验证。PyPI 和 npm 使用 Trusted Publishing 和来源证明，GHCR 则发布附带 SBOM 和构建来源证明的多架构镜像。

benchmarks/cases.json 是一组小型离线回归用例，涵盖短标题误报、DOI 冲突、预印本标题变体、Unicode/LaTeX 以及虚构的作者组合。它并非完整的科学评估，其分数也不能视为真实场景性能的上限。欢迎贡献范围更广、可再分发且由人工标注的用例。

引用

如果 Bibverify 对您的研究有所帮助，请引用：

@software{bibverify2025,
  title = {Bibverify: A Multi-Platform BibTeX Reference Verification Tool},
  author = {Hong Liu},
  year = {2025},
  url = {https://github.com/Hylouis233/bibverify},
  doi = {10.5281/zenodo.17338090}
}

许可证

MIT 许可证