Skip to content

README.md

Latest commit

 

History

History
239 lines (170 loc) · 9.91 KB

README.md

File metadata and controls

239 lines (170 loc) · 9.91 KB

Bib-Check-Pro

简介

Bib-Check-Pro 是 Bib-Check 的增强版，面向科研/工程工作流的 BibTeX 引用真实性校验与联网矫正工具。

为什么要做这个工具？

AI 自动生成文献列表已经成为常态，但结果往往不靠谱——DOI 是编造的、作者和标题张冠李戴、venue 写错。如果让 AI 直接修改，它可能越改越错，还会消耗大量 token。

更好的方案：让 AI 调用专门的校验工具。

Bib-Check-Pro 的设计思路是：

  • 机器校验 比 AI 猜 更可靠——Crossref、OpenAlex、Semantic Scholar、arXiv、DataCite 等真实数据源说了算
  • 程序自动修复 比 AI 重写 更省 token——高置信修复直接应用，低置信项人工确认
  • 结构化报告 比 AI 闲聊 更高效——Markdown 分级报告 + 验证链接，人工复核有据可依
  • 智能 venue 匹配——支持缩写/全称互认（如 NeurIPS↔Advances in Neural Information Processing Systems），避免格式差异导致的误报

⚠️ 重要提醒：不要完全信任本工具

Bib-Check-Pro 是辅助校验工具，不是绝对权威：

  • 有 DOI 的文献：DOI 验证准确率接近 100%，但元数据（标题/作者）匹配依赖于在线数据库，可能因网络不稳定而失败
  • 无 DOI 的文献（如很多 CS 会议论文、预印本、书籍）：检测能力有限，可能误报或漏报
  • arXiv 预印本：若仅有 arXiv DOI（10.48550/arxiv.xxxx）而无 eprint 字段，部分数据源（如 S2）可能间歇性返回空结果，建议同时保留 eprint = {xxxx.xxxxx} 以走稳定的 arXiv API 路径
  • 国内无梯子环境：部分数据源（Semantic Scholar、Google Scholar）不可达，检测范围受限
  • 网络不稳定时：会标注 CANNOT_VERIFY，提示人工复核

正确的工作流：

  1. AI 生成初稿 → 2. Bib-Check-Pro 自动筛查 → 3. 人工审阅 --mode review → 4. 确认无误后提交

不要把工具的输出直接当真理，最终判断权在你。

默认只检查，不修改文件；显式开启 --mode fix 才会生成修复版 bib 与变更日志。核心能力：

  • 静态检查：解析错误、重复 citekey、必填字段缺失、年份/DOI/URL 格式、pages 规范化等。
  • 联网一致性：Crossref/OpenAlex/Semantic Scholar + arXiv/DBLP/CITATION.cff，标题/作者/年份/venue 对齐，DOI 找不到/不匹配报警，低置信匹配进入人工核对。venue 比较使用模糊匹配 + 别名表，支持缩写/全称互认（如 NeurIPS / LNCS↔ECCV / arXiv 变体），并自动跳过 @book 条目的 publisher-vs-title 比较。
  • Auto-fix（可选）：高置信补 DOI/作者/标题/年份/venue/pages；arXiv DOI 归一化；pages 规范化。
  • Blog-aware（可选）：识别研究博客/项目页（OpenAI/Anthropic/Transformer Circuits 等），抓取网页元数据/官方 BibTeX，补全 title/author/date/url/howpublished/note。

安装

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

快速开始

# 仅检查（自动查找当前目录的 .bib 文件）
python -m bibcheck

# 指定文件检查
python -m bibcheck sample.bib

# 自动修复高置信错误
python -m bibcheck sample.bib --mode fix

# 交互式逐条确认
python -m bibcheck sample.bib --mode review

# 使用预设场景
python -m bibcheck sample.bib --profile strict    # 投稿前严格检查
python -m bibcheck sample.bib --profile quick     # 只扫前 20 条
python -m bibcheck sample.bib --profile ci        # CI 静默模式
python -m bibcheck sample.bib --profile draft     # 写作草稿（默认）

# 静默模式（只显示 ERROR + 一行汇总）
python -m bibcheck sample.bib --quiet

# 仅输出 Markdown 报告（不打印终端汇总）
python -m bibcheck sample.bib --output-format md

常用参数

运行模式

  • --mode check 仅检查（默认）
  • --mode fix 自动修复高置信错误（生成 .fixed.bib）
  • --mode review 交互式逐条确认（y 接受 / n 跳过 / q 退出）

预设场景

  • --profile strict 投稿前严格检查（更低阈值，启用 DBLP）
  • --profile quick 快速扫前 20 条（高阈值，关闭 DBLP/CFF）
  • --profile ci CI 静默模式（无进度条，仅终端输出）
  • --profile draft 写作草稿（合理默认值）

输出控制

  • --quiet / -q 只显示 ERROR + 一行汇总
  • --output-format terminal|md|all 输出格式，默认 all
  • --outdir bibcheck-out 报告输出目录（默认 bibcheck-out）
  • --progress auto|always|never 进度条策略

网络与数据源

  • --offline 离线模式
  • --sources crossref,openalex,s2 数据源
  • --enable-arxiv / --disable-arxiv
  • --enable-dblp 启用 DBLP（仅 CS 条目）
  • --enable-citation-cff / --disable-citation-cff
  • --high-conf / --mid-conf 置信度门控（默认 0.8/0.6）
  • --user-agent 自定义 UA
  • --max-entries N 只检查前 N 条

修复选项

  • --dry-run 仅预览变更
  • --inplace 覆盖原文件（先备份 .bak）
  • --aggressive 中置信修复也应用
  • --fixed-bib / --changes-log / --fix-summary 自定义输出路径
  • --latex-apostrophe 将作者名中的 ’ 转为 {\\textquoteright}

退出码：若存在 ERROR 则返回 1，否则 0，便于 CI。

配置文件

在项目根目录创建 .bibcheck.toml，日常即可零参数运行：

outdir = "bibcheck-reports"
sources = "crossref,openalex,s2"
enable_arxiv = true
enable_dblp = false
high_conf = 0.75
user_agent = "bibcheck/0.1 (+https://my-lab.edu/contact)"

也支持 pyproject.toml 的 [tool.bibcheck] 段。

配置文件优先级：文件配置 < --profile 预设 < CLI 参数（后者覆盖前者）。

输出

  • bibcheck-out/report.md：Markdown 复核报告
    • 🔴 疑似 AI 编造 / 🟠 张冠李戴 / 🟡 其他错误 / 🟢 警告 / 🛠 可自动修复项 / 🔗 验证链接汇总
  • 终端汇总：总数、OK/WARNING/ERROR、按错误类型计数、ERROR citekey 列表
  • --mode fix / --mode review 额外输出：
    • bibcheck-out/<name>.fixed.bib（或原文件，若 --inplace）
    • bibcheck-out/changes.jsonl 变更日志
    • bibcheck-out/fix_summary.md 修复汇总

支持的主要错误类型

  • 静态：PARSE_ERROR、DUPLICATE_CITEKEY、MISSING_REQUIRED_FIELDS、BAD_YEAR、BAD_DOI_FORMAT、BAD_URL_FORMAT、SUSPICIOUS_METADATA
  • 联网：DOI_NOT_FOUND、TITLE_MISMATCH、YEAR_MISMATCH、AUTHOR_MISMATCH、VENUE_MISMATCH（使用模糊匹配，容忍缩写/全称差异和 arXiv 变体）、CANDIDATE_FOUND_NO_DOI、NOT_FOUND_ONLINE
  • 新增：DOI_HALLUCINATED（AI 编造 DOI）、TITLE_SEVERELY_MISMATCHED（张冠李戴）、SUSPECTED_HALLUCINATION（疑似 AI 幻觉）、NOT_FOUND_ON_ARXIV、CITATION_CFF_MISSING、AMBIGUOUS_MATCH、LOW_CONFIDENCE_CANDIDATE
  • Blog-aware：WEB_CITATION_NEEDS_URLDATE、WEB_TITLE_MISMATCH、WEB_AUTHOR_MISMATCH、WEB_DATE_MISMATCH、WEB_CITATION_HAS_FAKE_DOI、WEB_BIBTEX_AVAILABLE

典型工作流

推荐工作流（安全修复，避免张冠李戴）：

# 1. AI 生成初稿后，先检查
python -m bibcheck draft.bib --profile draft

# 2. 自动修复（安全模式：严重不匹配时会自动跳过，不覆盖）
python -m bibcheck draft.bib --mode fix

# 3. 查看哪些条目被跳过（需要人工判断），逐条审阅
python -m bibcheck draft.bib --mode review

# 4. 确认无误后覆盖原文件（先自动备份 .bak）
python -m bibcheck draft.bib --mode fix --inplace

--mode fix 的安全机制：

  • 若条目存在 DOI_HALLUCINATED（假 DOI）或 TITLE_SEVERELY_MISMATCHED（张冠李戴，标题相似度 < 40），自动修复对该条目完全跳过
  • 该条目在 .fixed.bib 中保持原样，终端输出 [人工介入] ... — 自动修复已跳过
  • 用户需通过 --mode review 人工判断：是 DOI 写错了，还是整条引用都是 AI 编造的

其他场景：

# 投稿前严格检查
python -m bibcheck references.bib --profile strict --mode review

# CI 流水线集成（仅终端输出，静默）
python -m bibcheck references.bib --profile ci

arXiv 预印本优先查 arXiv API，GitHub 软件条目优先读取 CITATION.cff，CS 论文可选 DBLP 兜底。

Venue 匹配说明

VENUE_MISMATCH 现在使用模糊匹配（rapidfuzz token_set_ratio），并维护了一张常见缩写-全称别名表：

  • 顶会缩写 ↔ 全称：NeurIPS、ICLR、CVPR、ICML、ECCV 等
  • 论文集系列 ↔ 会议：LNCS / Lecture Notes in Computer Science ↔ ECCV
  • arXiv 变体统一：arXiv.org、arXiv preprint、arXiv:xxxx.xxxxx 均视为同一 venue
  • 自动跳过 @book 类型的 venue 比较（避免 publisher 与书名被误判为 mismatch）

如果本地 venue 使用了未收录的缩写，匹配会回退到模糊度阈值（默认 < 50 才报 mismatch）。欢迎在 bibcheck/validators_online.py 的 _VENUE_ALIASES 中补充你领域的常用缩写。

开发与测试

pytest

测试中所有在线请求均使用 responses mock，无需真实联网。

示例

sample.bib 包含：

  • 正确 DOI 条目（ResNet）
  • 明显错误条目（年/DOI/URL/pages）
  • arXiv 需归一化/补 DOI
  • OpenAI 研究博客条目（blog-aware 测试）

示例命令：

# 仅检查（不传参数自动找当前目录 .bib）
python -m bibcheck

# 指定文件检查
python -m bibcheck sample.bib

# 快速扫描前 20 条
python -m bibcheck sample.bib --profile quick

# 自动修复高置信错误
python -m bibcheck sample.bib --mode fix

# 交互式逐条确认
python -m bibcheck sample.bib --mode review

# 投稿前严格检查 + 交互式审阅
python -m bibcheck sample.bib --profile strict --mode review

# CI 静默模式
python -m bibcheck sample.bib --profile ci

# 仅输出 Markdown 报告（不打印终端汇总）
python -m bibcheck sample.bib --output-format md