Agent Skill

PMID引用验证·参考文献核查·文献格式化|AI幻觉检测

参考文献验真与AI幻觉引用检测:批量核验PMID/DOI/arXiv引用、验证文献真伪与论文引用错配——AI幻觉引用最常见的形态就是「真PMID指向别的论文」。五态判定系统,自动解析引用上下文并交叉比对,不匹配时推荐正确PMID。撤稿检测全覆盖(注册库撤稿标注直标,封顶为部分匹配并提示人工复核)、arXiv 预印本核验、纯文本参考文献表直读(论文草稿的文献列表粘贴即逐条核验:行内PMID/DOI/arXiv精确路由;中文文献条目经 OpenAlex 标题检索判定,无编号ID也能核验;无编号的英文条目按 PubMed 标题检索并如实标注)、参考文献生成与格式化导出(GB/T 7714 数字与著者-年份、Vancouver、APA、AMA、Harvard、Chicago 共七种制式,先验证后排版,只排已验真的条目)、OpenAlex DOI兜底(DataCite/Zenodo 等非Crossref注册的DOI可判定)。四数据源(NCBI + Europe PMC自动兜底 + Crossref + OpenAlex)、NCBI API key提速、429退避、断路器;网络故障诚实标注「未判定」,绝不误报「不存在」。零依赖,纯本地运行。触发词:验证PMID、核查文献、引用验证、文献验证、验证DOI、撤稿检查、PMID检查、参考文献格式化、文献排版、中文文献验证、文献核对、引用核查、verify PMIDs、check citations、validate references、citation audit、batch verify references、AI幻觉检测、参考文献核查、BibTeX审计。 仅验证不生成:需要润色改写、翻译降重、或凭空生成参考文献时不要用本工具(它只核验真伪,拒绝编造任何引用)。 Trigger on:PMID验证/引用验证/参考文献核查/DOI验证/arXiv核验/AI幻觉检测/参考文献格式/引用格式/文献排版/中文文献核查/论文引用核查;citation verification/bibliography audit/citation formatting/reference formatting/Chinese reference check。

行业专业·SorSor·来自 skill_hub·skillhub.cn ↗
skillhub install @indiv-sorsor/pubmed-verifier
5 Stars·4.4万 综合热度·14,894 字文档·源站更新 2026-11-14

README 文档

14,894 字

PubMed 文献引用批量验证工具 v7.0.0

检测 AI 编造的虚假文献引用。不只检查 PMID 是否存在——还能判断 PMID 是否指向正确的论文。零依赖,纯本地运行。

触发词

用户请求中出现以下任一意图即触发本技能:验证PMID / 检查引用 / 核查文献 / 引用验证 / 文献验证 / 验证DOI / DOI核查 / 撤稿检查 / 参考文献格式化 / 文献排版 / 中文文献验证 / 批量核验参考文献;以及英文 verify PMIDs、 check citations、validate references、citation audit、AI hallucination detection、citation formatting。粘贴的参考文献列表、.bib/.ris 文件、 Word .docx 文档、PowerPoint .pptx 课件、导出的 .html 页面、claims CSV 都是直接输入。

三个速查映射:「帮我验证这几个 PMID 31018962、22213727」→ --pmids; 「这个 PMID 是不是这篇标题的论文」单条速查 → --pmids X --title "标题"(v7.0.0 一行式,无需 claims 文件); 「检查我论文的参考文献」+粘贴列表 → --parse-text(或直接管道 --stdin—— 粘贴列表本身就是输入,无需明确说出「验证」二字);「这篇撤稿了该引什么」→ 撤稿条目加 --suggest。

按模式触发(不只按关键词):①请求中出现引用标识符(PMID/DOI/arXiv ID) +「查/核/验」类语义即触发——即使没说「验证」("这几个 PMID 是真的吗?"); ②粘贴或附上参考文献表即触发,无论措辞("帮我看下参考文献")——列表本身就是 输入(--parse-text/--stdin);③不应单独触发:「帮我写论文/综述」(先调 研走 cite-holmes,成稿后文献表交本技能终审);④无验证意图的纯排版不单独触发 (--format-references 先验证后排版是设计内行为);⑤混合意图裁决("帮我 润色并核对文献"、"检查我综述里的引用是不是真的"):只要点名了验证/核对,文献表 归本技能优先处理(先对草稿/列表跑一遍),另一任务各自继续;只提写作/润色且无 列表时本技能不触发。

组合场景(参数可叠加,各司一职):投稿终验 --source 草稿 --quick; 粘贴即验 pbpaste | ... --stdin --suggest;知识库审计+证据包 --source 库 --report-bundle 目录;文献库往返 --bibliography refs.bib --export-bibtex out.bib;跨月差分 --source 库 --diff 旧audit.json;纯中文文献表 --parse-text refs-cn.txt。

何时必须用 --claims-file:普通扫描验证的是存在性+上下文可解析的元数据; 凡判定结果要用于决策(投稿前的 mismatch/partial),必须提供预期标题+作者 走 --claims-file 才有决定性五态判定。工具分工:cite-holmes 面向带机器 验证引用的深度调研,本技能是核验/格式化环节——需求混合时先调研、文献最终 审计交给本技能。

从 Python 调用

整个工具就是一个纯标准库模块,无需安装即可导入(完整参考: references/python_api.md):

import sys
sys.path.insert(0, "/path/to/pubmed-verifier/scripts")
import verify_pmids as vp

info = vp.fetch_summaries(["31018962"], batch_size=1)["31018962"]
cross = vp.cross_check_citation(
    {"claimed_title": "Classification criteria for autoinflammatory recurrent fevers",
     "claimed_year": "2019"},
    {"title": info["title"], "authors": info["authors"],
     "journal": info["journal"], "pubdate": info["pubdate"]})
print(cross["verdict"], round(cross["confidence"], 2))

凡是引用真实性重要的场景都可以调起:

  • 「验证/核对这些 PMID / 这份参考文献表」(投稿或发布前)
  • 审核 AI 生成内容中的引用(编造或错配的参考文献)
  • 抽查系统综述的文献目录
  • 「PMID 12345678 真的是这篇论文吗?」——存疑即验
  • 知识库中 PMID/DOI 引用的批量质检
  • 自动调用时机:用户提出"验证/核对/审计"引用、PMID、DOI、参考文献时即触发本技能——首轮无需任何参数;用户提供预期标题时加 --claims-file。

触发优先级与工具选择——用户明确要求「验证/核对/审计引用、文献、PMID、DOI」时优先调用本技能。cite-holmes 面向带机器验证引用的深度调研;当需求混合调研与核验时,先做调研、再用本工具做最终文献审计。

运行前必知

六条限制覆盖绝大多数意外——每条都有单参数规避动作:

限制规避
引用上下文解析是启发式(奇特排版可能切错)需要精确元数据用 --claims-file
无 ID 中文条目:行长 ≥12 字符即路由 OpenAlex 中文标题检索;判定要求注册标题逐字出现于条目原文(给了年份则须吻合;刊名非必要);短碎片与散文段停留「待确认」--parse-text(OpenAlex 中文检索腿)或提供 ID
网络故障如实报「未判定」,绝不静默报「不存在」先 --check-net,网络可达后重试
撤稿/DOI 状态以缓存时刻为准(30 天)投稿终验加 --no-cache
Office/HTML 输入只提取文本——扫描版 PDF 与图片没有可提取文本先导出为文本/HTML,或经 --claims-file 提供 ID
超大批量耗时且可能触发限速分批演算见 references/operations.md,按片验证

以下章节都是这六条的展开。

文档地图——要找的内容在哪个文件,无需翻找:

想看什么去哪
完整版本历史references/CHANGELOG.md(主文档只留近期要点)
全量 FAQ、场景实操与调优参数references/usage_guide.md
「场景 → 一条命令」旗标速查(全旗标按任务域分组)references/flags.md
大批量分批/代理配置/提速/CI 接入/stderr 标识契约references/operations.md
屏幕出现 [ERROR]/[WARN]、或结果与预期不符references/troubleshooting_ZH.md(一条报错一行对策;英文版 troubleshooting.md)
Python API 参考 / 可运行示例references/pythonapi.md / references/apiexamples.md
按任务找该读哪个文件references/INDEX.md

五态判定系统

判定含义
✅ 正确PMID 存在,且与引用的论文匹配(标题+作者/期刊)
⚠️ 不匹配PMID 存在,但指向不同的论文(AI 幻觉最常见的情况!)
🔶 部分匹配部分元数据匹配(如作者+期刊匹配但标题不同)
❌ 无效PubMed 中不存在此 PMID
❓ 待确认缺少足够的引用元数据无法交叉比对;或数据源不可达(网络故障诚实标注,绝不误报为「不存在」)

为什么「存在性检查」不够:相当大一部分编造引用用的是真实存在的 PMID,只是指向同年份/同期刊/同领域的另一篇论文——我们自己的一次审计里,5 条「有效」PMID 就有 4 条属于此类。二元存在性检查对它们全部漏检。

快速开始

下面十条命令覆盖绝大多数运行;每个旗标在 references/flags.md 都有一行速查(场景 → 一条命令,按任务域分组),完整场景演练在 references/usage_guide.md。

# 投稿终验一条命令:新鲜注册库(--no-cache)+ Crossref DOI 交叉核验
# (--verify-doi)+ 正确 PMID 推荐(--suggest),无需记参数组合
python3 scripts/verify_pmids.py --source /path/to/draft --quick --output report.html

# 粘贴即验证:复制来的参考文献表直接管道进来,无需落盘
pbpaste | python3 scripts/verify_pmids.py --stdin --suggest

# 验证指定 PMID,或扫描整个项目目录(Word .docx、.pptx 课件、导出 .html
# 与 JATS .nxml/.xml 均直接可读)
python3 scripts/verify_pmids.py --pmids 31018962,22213727
python3 scripts/verify_pmids.py --source /path/to/project --output report.html

# 精确五态判定:提供期望元数据(CSV/JSON)
python3 scripts/verify_pmids.py --claims-file claims.csv --suggest --output report.html

# 核验纯文本参考文献表,再把通过的条目排版为可粘贴的参考文献表
python3 scripts/verify_pmids.py --parse-text references.txt --no-cache
python3 scripts/verify_pmids.py --parse-text references.txt --format-references refs_gbt.txt --citation-style gbt

# 投稿证据包:一条命令出全部工件
python3 scripts/verify_pmids.py --parse-text references.txt --report-bundle evidence_pack

# 健康检查:环境自检 + 四数据源+arXiv 网络预检(逐源探测直连与 HTTPS_PROXY 两路)
python3 scripts/verify_pmids.py --doctor
python3 scripts/verify_pmids.py --check-net

快速 FAQ

本节是纯 FAQ(问题 → 解答);深度版本在 references/usage_guide.md。十件不该做的事的速查表已集中到下一节「反模式」开头——一个事实一处陈述。

几百条 PMID 批量验证很慢,怎么提速? 纯元数据验证按 50 条/批、批间 0.4 秒(带 --ncbi-api-key 为 0.12 秒)查询;缓存后重跑约 5 秒。--verify-doi 每条引用多一次 Crossref 调用、--suggest 每条不匹配多一次搜索——大批量粗筛时先关掉,只对标记出的子集开。

什么时候必须用 --claims-file 而不是扫描? 上下文解析是启发式的(v3.3.0 已防护常见缩写,极端格式仍可能切错)。需要精确核验、或要在 claims 里提供 DOI(拼接检出需要 doi 字段)时,请用结构化 JSON/CSV。

引用正文是中文——scan 几乎解析不出? GB/T 7714 格式(……标题[J]. 刊名, 年… PMID: xxx)自 v3.9.0 起可解析——标题/刊名与拉丁注册库的比对跨语言跳过,判定基于年份/DOI 证据。无 PMID 标记的自由中文散文仍解析受限——请用 --claims-file 拿与语言无关的完整判定。

国内网络慢或不稳定? 先跑 python3 scripts/verifypmids.py --check-net 看四个文献数据源与 arXiv 预印本 API 当前是否可达——v5.6.0 起每个源探测两次(直连一次、走代理一次,各 5 秒),直连被墙但代理可达的源会显示为「可用」,并标注每源服务的验证路径与兜底源。 原生支持标准 HTTPSPROXY/HTTPPROXY 环境变量;可加大 --timeout;NCBI 不可达时 --meta-source europepmc 走 Europe PMC 兜底(每条 metasource 标注实际来源);缓存 30 天内复用。

❓ 待确认 vs ❌ 无效 有什么区别? 待确认(退出码 2)=「源不可达,没验成」——稍后重试;无效(退出码 1)=「已核实不存在」。网络故障绝不会被报成「不存在」,也不写缓存。

网络抖动搞挂了半批引用——要全部重跑吗? 不用。unknown 不写缓存,直接重跑同一条命令就只会重新拉取失败的那些;且 v5.7.0 起运行内自带重试:--retries N(默认 1)在批末只对网络失败的取数补跑(2 秒冷却),恢复多少条会在统计里如实报告(retried_recovered)。

为什么我的引用封顶在 ⚠ partial? 判定阶梯在声称字段无法核验时封顶——最常见是 claims 缺 title(上表 #2),以及被撤稿论文(partial + 人工复核提示,设计如此)。

报告里 RETRACTED 是什么意思? 注册库自身把该论文的出版物类型标为 "Retracted Publication"(v2.7.0 起每条引用都查,无需 DOI、无需参数),和/或 Crossref 登记了撤稿记录。判定封顶为部分匹配并附人工复核提示——引用它会传播已被撤回的结论。撤稿声明本身不会被误标;处于 Expression of Concern(编辑关注声明,非撤稿)的论文也不标记。撤稿状态以缓存时刻为准——投稿前终验请加 --no-cache。

报了不匹配,但标题看起来挺像? 看 details 里哪个字段不符;阈值从严是有意的。用 --claims-file 提供完整引用信息可获得精确判定。

能直接审计 .bib / .ris 文件吗? 能——--bibliography refs.bib(BibTeX)与 --bibliography refs.ris(RIS/Zotero/EndNote/Mendeley)都按 PMID > DOI > arXiv 路由并交叉比对声称元数据;--lint-claims 可先离线体检。双向闭环:--export-bibtex 与 --export-ris 的输出修改后可直接喂回。

已验证的条目能进 Zotero 吗? 能——--export-csl library.json 导出 CSL JSON,Zotero「文件 > 导入」直接入库(Mendeley/Pandoc 支持同一文件);correct 条目按期刊文章导入,partial 条目附人工复核注记。

claims 文件好像丢了行 / 判定偏弱? 先离线体检:python3 scripts/verify_pmids.py --lint-claims claims.csv 会报出不可用行、ID 形状错误、未知列名(如把 title 拼成 titel)、缺标题与 DOI 前缀问题——零网络,有错误退出码 1。

DOI 能带声称元数据做完整判定吗? 能——v3.4.0 起只有 doi 的 claims 行(带 title,可选 authors/journal/year)与 PMID claims 走同一交叉比对:对登记元数据给出 correct / mismatch / partial。不带 claims 的 DOI 行保持「待确认」(仅存在性)。

arXiv 引用为什么从 correct 掉到了 partial? 你的 claims 行同时给了 arxiv_id 和 doi,而这个 DOI 与该 arXiv 条目登记的版本记录 DOI 不一致——要么笔误,要么是另一篇论文的 DOI。注册 DOI 就在 details 里;改正 claim 或去掉 doi 格即可。

输出长什么样

终端文本报告(判定汇总行,然后逐条证据):

Readiness: NOT SUBMISSION-READY — 1 invalid, 1 mismatched
Results: 1/3 correct, 1 mismatch, 1 invalid, 0 partial, 0 unknown
============================================================

✅ PMID 31018962 (claims) [correct]
   Actual: Classification criteria for autoinflammatory recurrent fevers
   Claimed: Classification criteria for autoinflammatory recurrent fevers
   Evidence: title ✓ · author ✓ · journal ✓ · year ✓

⚠️ PMID 34078778 (claims) [mismatch]
   Actual: Effect of CAD/CAM materials on the marginal fit of crowds
   Claimed: JIA pathogenesis and treatment
   → Suggest: PMID 34425842 - Juvenile idiopathic arthritis: from aetio...
   Evidence: title ✗ · author ✗ · journal ✗ · year —

❌ PMID 99999999 (cli) [invalid]
   Error: PMID not found in API response

--output report.json 携带同样的判定外加每条引用的完整证据链 (evidence.titlematch / authormatch / journalmatch / yearmatch、 fields 三态、metasource 标注应答的注册库、标题检索/OpenAlex 腿命中 时标注 resolvedby)与含投稿就绪判定的 stats 块。 --format-references 输出即用型文献表(形态见 references/CHANGELOG.md 的 v4.0.0 条目)。

实操场景

  • 「审稿人问我的引用是怎么核验的。」 —— 带 `--export-audit audit.json

--verify-doi` 跑一次审计:JSON 工作底稿含工具身份、版本、脱敏后的完整 调用命令与逐条证据链,审稿人或编辑可复放。随稿件一并提交即可。

  • 「查学位论文的参考文献。」 —— 把文献表复制进纯文本文件(每行一

条,或保留 [1] 编号),跑 --parse-text refs.txt:行内 PMID/DOI 精确 路由;英文条目走 PubMed 标题检索;中文条目走 OpenAlex 中文检索腿。 最后 --format-references refs_clean.txt --citation-style gbt 得到修正 且格式统一的文献表。

  • 「系统综述(PRISMA)文献库筛查。」 —— 全表核验一次并导出审计底

稿作基线;每次重投前跑 --diff audit.json:新撤稿、降级、新增以增量 报告呈现,只需复查变化的部分。

反模式——这些用法是错的

十件不该做的事——速查表;下方编号条目展开为什么错。(这些是使用错误,不是提问——问题形态的解答在上一节「快速 FAQ」。)

#不要应该
1把 --pmids 的存在性输出当「已验证」配 --claims-file 提供标题做真核验
2claims 不填 title务必带标题——没有它判定封顶 partial
3发表当天就信缓存结果投稿终验加 --no-cache
4把自动抽取 DOI 的「查无」读成「伪造」OpenAlex 二查后双库查无才升级;先经 doi.org / arxiv.org 人工复核
5把 CSV 单元格开头的 ' 当数据损坏那是公式注入防护符——导入后再去除
6把 READY 行当质量评分它只表示「已运行的检查都没发现问题」
7--source 和 --pmids 同时传传了 --pmids 时 --source 整个被忽略
8千条清单直接上 --verify-doi/--suggest先跑批量,再只对标记子集深验
9期待 CJK↔拉丁作者名比对跨语言名诚实跳过(author_check: skipped)
10合规场景不出审计底稿--export-audit 生成可复算工作底稿

每条:错误用法 → 为什么错 → 正确做法。

  1. 把 --pmids 的输出当成"已验证"——那只确认了存在性。

→ 错:"这 5 个 PMID 都存在,所以引用没问题。" → 对:存在性核对只是第一步;要核内容请配 --claims-file 提供标题(READY 行会显式标注)。

  1. claims 不填 title——只有作者/期刊/年份永远到不了 correct,最高只能 partial。→ 请务必提供标题。
  2. 发表当天就信缓存结果——新上线论文可能被更早的运行缓存成"查无",撤稿状态也以缓存时刻为准。→ 投稿终验加 --no-cache。
  3. 以为"查无"就一定是编造——Crossref 查无会先经 OpenAlex 二次核查(DataCite/Zenodo/中文注册库 DOI 在那里),「两个注册库都查无」才是新门槛;自动抽取的 DOI 双库查无仍只是疑似。被 arXiv 官方移除的论文同样查无。→ 先到 doi.org / arxiv.org 人工复核再下结论。
  4. 把 CSV 单元格开头的 ' 当数据错误——那是公式注入防护符,不是数据损坏。→ 导入后再去除。
  5. 把 READY 行当质量评分——它只表示"已运行的检查都没发现问题",不表示"这篇论文水平高"。

边界与声明(集中列出)

本工具不能做的事,集中在一处:

  • 拼接/失配信号只报告不一致,不裁判谁对——声称与登记库不符时,由人阅读证据行下结论。
  • 跨语言作者名跳过而非判负——CJK↔拉丁作者名不做比对(author_check: skipped),判定只依赖标题/期刊/年份。
  • 上下文解析是启发式的——v3.3.0 已防止常见缩写(U.S.、e.g.、vs.、St.、Vol.、No.)截断标题,但极端格式仍可能切错;需要精确元数据请用 --claims-file。
  • DataCite/仓储 DOI 不在 Crossref——OpenAlex 兜底覆盖(v4.1.0):

Crossref 报 404 会先经 OpenAlex 二次核查;仅当两个注册库都查无才适用 404 语义(--dois/claims=无效,自动提取=疑似)。经 OpenAlex 解析的条 目带 meta_source: openalex。

  • arXiv 官方移除的论文同样"查无"——invalid 判定的 details 里带此说明。
  • 撤稿状态以缓存时刻为准——投稿终验请加 --no-cache。
  • 单字母首字母缩写永不匹配——"Smith J" 对 "Smith John" 不计为不符。
  • unknown ≠ invalid——数据源不可达 = 退出码 2 + 待确认;网络故障绝不报"查无"、绝不写缓存。
  • arXiv 限速是刻意的——官方 API 要求调用间隔 ≥3 秒;大批量 arXiv 校验天然较慢(stderr 有进度与剩余时间估计)。登记了正式版 DOI 的条目会为挂接 PMID 额外发一次 Europe PMC 查询。
  • DOI claims 的比对基准——DOI 解析到 PubMed 记录用 PubMed 记录比对,否则用 Crossref 登记信息(Crossref 的作者字段较稀疏,作者层更常判「—」);DOI 行不带 title 停在「待确认」而非部分匹配;用户显式提供(--dois 或 claims)的 DOI 在 Crossref 查无计为无效。
  • 标题复核腿只确认、不指控(v4.8.0)——启发式单字段声称被降级为待确认后,会用 PubMed 标题检索复核:同一 PMID 得到印证则升级为「正确」(标注 inlinetitlesearch,弱于用户直供 ID 的证据);命中不同 PMID 的同名记录则给出「疑似错挂 PMID」信号,判定仍保持待确认;中文标题跳过此腿(走 OpenAlex 中文检索腿)。该腿绝不制造不匹配指控。
  • Word/HTML/PowerPoint 直接可读,PDF 不行(v4.8.0/v4.9.0)——.docx 段落/表格、.pptx 幻灯片+演讲者备注、.html 正文在内存中提取(script/style 忽略、链接 href 保留);损坏的结构化文件回落为原始字节读取并以 [NOTE] 明示(来自它的结果可能不完整)。扫描版 PDF/图片不是文本,请先导出为文本或 HTML;JATS/NLM .xml 文章(v6.0.0)同样内存提取。
  • 输入规模与并发(v5.1.0/v5.2.0)——--max-entries 护栏(默认 2000)统计去重后实际工作量并告警+给出分批建议;DOI 验证默认 4 并发;PMID 每批 50 条(有 API key 间隔更短);arXiv 官方限速 3 秒/次(1000 个 arXiv ID 至少 50 分钟);引用计数(citedbycount)仅 Europe PMC/OpenAlex 路径提供,NCBI 路如实缺省。--max-entries N 调阈值、0 关闭告警。
  • 参数优先级显式化(v5.1.0)——--pmids 与 --source 同传时 --pmids 生效,被忽略的一方会在 stderr 明确告示,绝不静默丢弃。
  • 撤稿原因(v5.3.0)——被撤条目带 retractionreason(注册库有摘要取摘要,否则取声明标题)与 retractionreason_doi(声明出处)。多数声明仅为「Retraction Note: 原题」形态——原题绝不冒充原因,此时如实引用声明本身供查证。
  • 判定阶梯单调性(v4.9.0)——扫描来源中「唯一缺口=作者未声称」的条目(标题匹配、期刊/年份未声称)判定为「正确」并标注 route: existencetitlematch——比纯存在性确认更强的证据不会判出更低的结果。凡作者/期刊/年份声称了但不同仍保持「部分匹配」(真疑点);--claims-file/CLI 显式输入永远走完整判定不升级。

claims.csv 参考格式

pmid,title,authors,journal,year,doi,arxiv_id
31018962,Candidate criteria for diagnosis of familial...,Gattorno,Ann Rheum Dis,2019,10.1136/annrheumdis-2019-215048,
,Attention Is All You Need,Vaswani,NeurIPS,2017,,1706.03762
  • 有 pmid 走 PubMed 管线;纯 arXiv 引用只填 arxiv_id(+title 可核验真伪);纯 DOI 引用只填 doi(v3.4.0 起走完整判定阶梯)。
  • PMID 行的 doi 列用于拼接检出;arxiv_id 列走 arXiv 官方 API。

国内使用指北(集中一页)

所有网络相关事项集中于此(各项同时在使用处就地说明):

  • 预检:--check-net 逐一探测四个注册库+arXiv——v5.6.0 起每源探测直连与代理两路(各 5 秒),给出可达性、该源服务的验证路径与兜底源建议;直连被墙但代理可达=可用。
  • 注册库选择:默认 --meta-source auto 已对 NCBI 失败批次自动重试 Europe PMC(免 key、一般可达);--meta-source europepmc 可强制。
  • 代理:标准 HTTPSPROXY/HTTPPROXY 环境变量对所有请求生效;自动化直连场景应 unset(残留死代理会把注册库伪装成不可达)。
  • 包体镜像:魔搭提供技能包下载(modelscope.cn/skills/Docsor/pubmed-verifier)——但验证运行时仍需访问学术注册库,镜像只消除安装摩擦。
  • 诚实失败:无论网络如何,失败一律判「待确认」(退出码 2),绝不误报「不存在」,且不写缓存。

最佳实践与调优

  • 大批量提速——申请 NCBI API key(https://ncbiinsights.ncbi.nlm.nih.gov/api-keys/ ):每批 50 条、间隔 0.12 秒(无 key 为 0.4 秒);缓存命中重跑只要几秒。
  • DOI 并行——--workers(默认 4,上限 8)作用于 Crossref 解析与 Europe PMC 挂接;arXiv 按官方礼仪保持串行(间隔 ≥3 秒)。
  • 两段式工作流——先跑仅元数据的批量核查(不带 --verify-doi 与 --suggest),再只对标记子集深验;每个深验标志每条引用多一次 API 调用。
  • 文献库闭环——--export-bibtex / --export-ris / --export-csl 输出已验证条目(CSL JSON 供 Zotero「文件 > 导入」直接入库);修改后用 --bibliography refs.bib / refs.ris 直接复验(PMID 会重新挂接完整记录)。
  • claims 优先于上下文解析——只要知道期望标题就用 --claims-file:它启用完整判定阶梯与 DOI/arXiv 配对检查。先用离线体检:python3 scripts/verify_pmids.py --lint-claims claims.csv 无网络即可报出 ID 形状错误、缺标题、未知列与重复键。
  • 网络不稳——调大 --timeout;原生支持 HTTPSPROXY/HTTPPROXY;NCBI 不可达自动切 Europe PMC 兜底(meta_source 显示实际应答方)。
  • 缓存策略——结果缓存 30 天、负条目 3 天;--cache-days 可调;投稿终验用 --no-cache。
  • 规模预期——仅元数据吞吐受 API 限制(带 key 约每 1000 条 1~2 分钟);DOI 解析每条多一次 Crossref 调用。一个刻意取舍:验证器是零依赖纯标准库——把 scripts/ 目录(入口文件+六个 pv_* 同级模块,v6.4.0 起分层)拷到任何有 Python 3.9+ 的机器即可运行,无需 pip/venv。

近期版本(完整历史见 references/CHANGELOG.md)

  • v7.0.0 —— --self-check 新增撤稿数据源健康探针(六条承诺:离线五条+在线一条,注册库不可达时诚实 SKIP);--title 单条 PMID 一行式声称(错标题报 mismatch,无需 claims 文件);python3 tests/run_tests.py 一条命令跑离线套件。
  • v6.9.0 —— 已验真文献表新增两种作者-年份制式:--citation-style harvard 与 chicago(制式总数 7;GB/T 著者-年份/Harvard/Chicago 均按首作者排序、不带编号)。
  • v6.8.0 —— 一个事实一处陈述:十件不该做的事速查表集中到「反模式」节开头,快速 FAQ 改为指针不再重复;README 特性按职能分组、快速开始精简——落地页与主文档不再互相复述(双语双向测试锁)。
  • v6.7.0 —— Files 表按包实况生成:每个反引号路径必须存在、包内每个随包示例/参考文件必须以全名出现(.json/_ZH 等短写曾把真实文件藏起来)、原生扩展名 .bib/.ris 明确标注「仅 GitHub 仓库与 zip」——双向测试锁对账;与 When-to-use 重复的 Use-cases 节删除。

安全与行为声明

  • 单次运行 CLI:扫描→验证→写报告→退出。无守护进程、无后台任务、运行时零下载零安装(纯标准库,零依赖)。
  • 网络访问仅限以下官方学术注册表,且全部 HTTPS:eutils.ncbi.nlm.nih.gov、www.ebi.ac.uk(Europe PMC)、api.crossref.org、api.openalex.org、export.arxiv.org——不访问任何其他主机;无遥测、无统计、无数据收集——出站载荷仅限你要求验证的 PMID/DOI/标题。
  • 你的文件与报告留在本机。写入仅限你指定的报告路径与 ~/.cache/pubmed-verifier/ 下的 SQLite 缓存(--no-cache 可禁用)。
  • 可选环境变量 NCBIAPIKEY / PUBMEDVERIFIERMAILTO 仅用于你自己的 API 请求认证/署名,绝不发往其他任何地方。
  • 无操作系统集成:无子进程、无系统服务、无权限变更、无计划任务。

工作原理

从输入提取声称元数据(上下文解析,启发式)→ 拉取注册库记录(批量/缓存/Europe PMC 兜底)→ 声称 vs 注册交叉比对(五态判定阶梯)→ 可选 Crossref DOI 核验含撤稿检测(--verify-doi)与正确 PMID 推荐(--suggest)。匹配阈值、DOI↔PMID 拼接规则与推荐机制详见 references/usage_guide.md;审计底稿(--export-audit)使每一步可复放。

性能

典型审计的纯元数据验证秒级完成;缓存重跑约 5 秒。深验旗标按条增加 API 调用——分批数学与提速清单见 references/operations.md。

与 cite-holmes 怎么选

  • pubmed-verifier(本工具)——轻量快速批量验证:手里有一批 PMID/DOI,要确认真实且引用正确。
  • cite-holmes——深度调研:对整篇文档的全部引用做多数据库交叉核查,输出置信度分级报告。

两者共享同一套五态判定哲学,可搭配使用。

适用场景

  • 系统性综述/荟萃分析文献验证
  • AI 生成内容的文献真实性审核
  • 论文投稿前引用自检
  • 医学知识库/教材引用质量控制
  • 药物警戒文献核查

相关工具

每个工具解决文献工作中的一个环节,按需取用。

  • cn-med-oa — 中文医学文献 OA 免费下载与引用元数据
  • cite-holmes — 深度调研,每条引用机器验证
  • paper-polisher-pro — 学术润色、术语核查与期刊预检
  • academic-figures — 一条命令出出版级科研配图
  • doc-holmes — 保持排版的 PDF 精准翻译(内测中)

常见顺序:找文献(cn-med-oa)→ 验引用(本工具或 cite-holmes)→ 学术润色(paper-polisher-pro)→ 配图(academic-figures)→ 翻译 PDF(doc-holmes)——按手头环节取用。

文件说明

文件用途
scripts/verify_pmids.py入口文件+编排(v7.0.0,纯标准库;旁边是六个 pv_*.py 同级模块)
references/usage_guide.md完整 FAQ、场景演练、调优手册、匹配机制
references/troubleshooting.md / references/troubleshooting_ZH.md报错速查——一条报错一行对策([ERROR]/[WARN] 原文→原因→修复)
references/flags.md旗标速查——场景到一条命令,全旗标分组
references/operations.md运维手册——分批数学、代理场景、提速清单、错误契约、CI 门
references/INDEX.md任务→文档路由表
references/python_api.mdPython 编程集成(稳定接口+示例)
references/api_examples.mdPubMed / Europe PMC / Crossref / arXiv API 说明
references/CHANGELOG.md完整版本历史
examples/README.txt各样例用途说明(每样例一条命令)
examples/claims.sample.csv / claims.sample.json--claims-file 参考格式(PMID / DOI-only / arXiv 三种行形态)
examples/refs.sample.txt / refs_list.sample.txt--parse-text 样例输入(行内 ID 路由+无 ID 标题条目)
examples/refs.sample.bib.txt / refs.sample.ris.txt--bibliography 示例文献库(格式按内容嗅探)
examples/refs.sample.bib / refs.sample.ris同一样例的原始扩展名版本(仅 GitHub 仓库与 zip 包)
tests/离线测试矩阵 + 真网验收脚本(仅仓库,不随包分发)

许可证

MIT-0 — 自由使用、修改和分发,无需署名。

同分类其他技能

查看全部 ›