verify-citations
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseVerify Citations
验证引用
The anti-hallucination gate for bibliographies. Takes a file, validates
every entry against live scholarly indexes (Crossref, DBLP, Semantic Scholar,
arXiv, DataCite), and produces a per-entry verdict: VERIFIED, MISMATCH,
UNRESOLVED (possible fabrication), or RETRACTED. One fabricated citation in a
submitted paper can end a review — or a reputation. Be rigorous here.
.bibResolving is necessary but not sufficient. An identifier that resolves only
proves the entry points at a real record — not that it is the right
instance of the named work, nor that an independently-added reference is even
on-topic. The gate therefore goes beyond resolution with two non-fabricating
heuristics: a canonical-instance check (when a title exists as both, say, a
conference paper and a later RFC/tech-report/preprint, surface the
alternatives with citation counts so you cite the artifact the field cites)
and an opt-in relevance gate (score an added reference's topical fit and
flag low-fit ones for human review). And when an authoritative index is
unreachable, the run reports PARTIAL-PASS, never a clean PASS, naming the
checks that did not run — so "could not check" is never mistaken for "checked
and clean".
文献目录的防幻觉校验工具。接收一个文件,通过实时学术索引(Crossref、DBLP、Semantic Scholar、arXiv、DataCite)验证每一条目,并为每条目生成判定结果:VERIFIED(已验证)、MISMATCH(不匹配)、UNRESOLVED(无法解析,可能为伪造)或RETRACTED(已撤回)。提交的论文中只要有一条伪造引用,就可能导致评审失败,甚至损害个人声誉。请务必严谨对待。
.bib解析成功是必要条件,但并非充分条件。标识符可解析仅能证明该条目指向某一真实记录,但无法证明它是对应作品的正确版本,也无法证明新增的参考文献与主题相关。因此,本工具在解析之外还采用了两种非伪造性启发式检查:标准版本校验(当同一标题同时存在会议论文、后续RFC/技术报告/预印本等版本时,展示不同版本及其引用量,以便引用该领域普遍认可的版本),以及可选的相关性校验(对新增参考文献的主题匹配度打分,标记匹配度低的条目供人工审核)。当权威索引无法访问时,工具会返回PARTIAL-PASS(部分通过),而非完全通过,并列出未执行的检查项——避免将“无法检查”误判为“检查通过且无问题”。
When to use
使用场景
- The user asks to verify, check, validate, or audit citations / references /
a bibliography / a file.
.bib - Any writing skill (,
draft-related-work,literature-review, ...) added or edited citations — run this gate before declaring that work done.write-rebuttal - Before / submission, camera-ready, or arXiv upload.
preflight-check - The user suspects AI-generated references ("are these real papers?").
- 用户要求验证、检查、校验或审核引用/参考文献/文献目录/.bib文件时
- 任何涉及编写引用的工具(、
draft-related-work、literature-review等)新增或编辑了引用——在完成该工具的工作前,需运行本校验工具write-rebuttal - 在(预提交检查)、提交、终稿或arXiv上传之前
preflight-check - 用户怀疑AI生成的参考文献(如“这些论文是真实存在的吗?”)
Inputs
输入项
- A file (path from the user, or find it:
.bibnext to the main*.bib, or the file named in.tex/\bibliography{...}).\addbibresource{...} - environment variable — a real email, sent in the User-Agent so API providers can contact instead of block. Ask the user for it if unset; never invent one.
CONTACT_EMAIL - Optional: for a dedicated Semantic Scholar rate allowance (the shared anonymous pool 429s under load; the script backs off and falls back to other providers automatically).
S2_API_KEY
- 一个文件(用户提供路径,或自动查找:主
.bib文件旁的.tex文件,或*.bib/\bibliography{...}中指定的文件)\addbibresource{...} - 环境变量——真实邮箱,会包含在User-Agent中,以便API提供商联系而非封禁。若未设置需向用户索要,切勿编造
CONTACT_EMAIL - 可选:,用于Semantic Scholar的专属调用额度(共享匿名池在负载过高时会返回429错误;脚本会自动退避并 fallback 到其他提供商)
S2_API_KEY
Process
处理流程
-
Run the checker. Deterministic work belongs to the script — do not verify entries by hand or from memory:bash
export CONTACT_EMAIL=user@university.edu # ask the user python3 scripts/check_bibtex.py path/to/refs.bib --json /tmp/citecheck.jsonUseful variants:- — parse + duplicate/static checks only (no network; use when the user has no connectivity or only wants structural checks).
--offline - — re-check a single entry after a fix (repeatable).
--key smith2024 - — halves request count for very large files; keep retraction checks ON for any final pre-submission run.
--no-retraction-check - — exit nonzero on warnings and on PARTIAL-PASS (CI gate mode: a gate run that could not reach an index has not run).
--strict - — bypass the 24 h response cache in
--refresh..cache/ - — turn on the relevance gate for independently-gathered additions: pass a plain-text thesis/abstract and the keys you have already confirmed are core; low-topical-fit entries get a
--thesis-file thesis.txt --core-key dean2008 --core-key vaswani2017flag for review. Use this when another skill (LOW_RELEVANCE,draft-related-work) added references and you need to tell good additions from off-topic ones.literature-review - — skip the extra same-title lookup that powers the
--no-canonical-instancewrong-artifact check (on by default).CANONICAL_INSTANCE - — abort (exit 1) the instant any index is unreachable, instead of degrading to PARTIAL-PASS.
--no-soft-fail - — run the bundled offline unit tests for the deterministic
--self-testcheck (no network, noENTRY_TYPE_MISMATCHneeded); exits 0 if they pass. Use this to confirm the script is intact after editing it..bib
Exit codes:clean,0problems found,2operational failure (bad file, no network, missing CONTACT_EMAIL — fix the cause, do not skip the gate). For a 50-entry file expect ~2–4 minutes: the script is rate-limited to at most 1 request/second per host by design. Do not parallelize it and do not work around its politeness limits.1 -
Triage every flag. Read references/triage-guide.md for what each flag means, known false positives (online-vs-print year off-by-one, venue aliasing, arXiv-vs-published versions, truncated author lists), and the exact fix for each. Severity at a glance:
Flag Severity Meaning UNRESOLVED / DOI_NOT_FOUND / ARXIV_NOT_FOUND ERROR Not found in any index — possible fabrication TITLE_MISMATCH / AUTHOR_MISMATCH / YEAR_MISMATCH ERROR Identifier points at a different paper, or metadata is wrong RETRACTED ERROR A retraction notice exists for this DOI DUPLICATE_KEY / DUPLICATE_DOI / DUPLICATE_TITLE ERROR Same paper or key twice MALFORMED_DOI / MALFORMED_ARXIV_ID ERROR Identifier cannot be valid POSSIBLE_ID_TYPO / MISSING_DOI / VENUE_MISMATCH / AUTHOR_LIST_DIFFERS / TITLE_PARTIAL_MATCH / NOT_IN_INDEXES / EXPRESSION_OF_CONCERN WARN Real paper, imperfect entry — fix or justify ENTRY_TYPE_MISMATCH WARN BibTeX type contradicts the resolved record (e.g. a journal article or monograph typed , a@inproceedingsnaming a journal/publisher, orbooktitlecarrying@inproceedings) — set the type from the canonicaljournal=fieldtypeCANONICAL_INSTANCE WARN Resolves, but a different artifact of the same work is what the field cites — pick the canonical instance LOW_RELEVANCE WARN Resolves, but scored low topical fit to the paper — confirm it is load-bearing, never auto-remove UNVERIFIABLE_TYPE / RESOLVED_VIA_SEARCH / HAS_CORRECTION / RELEVANCE_OK / CHECK_SKIPPED INFO Context for manual judgment -
Fix only from canonical records. Replace broken entries with BibTeX fetched from the authoritative source (DBLPendpoint or doi.org content negotiation — exact commands in references/triage-guide.md). Never retype metadata from memory; that is how hallucinations get laundered into "fixes". Provider details, what each index is authoritative for, and the venue-alias problem are in references/verification-sources.md.
.bib -
Escalate what cannot be fixed. For each UNRESOLVED entry, present the evidence to the user and ask: keep (with a manual source they vouch for), fix (they supply the real reference), or remove (also remove theand adjust surrounding text). Never decide silently, never delete silently, and never substitute a different paper that merely sounds similar.
\citeForandCANONICAL_INSTANCE(both WARN), see references/triage-guide.md and references/relevance-gate.md. These are copilot prompts, not autopilot actions: surface the alternative artifact / the low-fit score and let the user decide. The script's lexical relevance score is a deterministic proxy — if you have an embedding model available, compute abstract-embedding similarity yourself for a stronger signal before advising, as the relevance-gate reference explains. Never auto-swap an instance or auto-delete a low-fit reference.LOW_RELEVANCE -
Re-run until exit code 0 (or until remaining flags are explicitly accepted by the user). Re-check just the fixed entries with, then do one full final pass. If a run came back PARTIAL-PASS because an index was unreachable, that is not done — re-run the skipped checks once connectivity returns before declaring the gate clean.
--key -
Report. The script prints a canonical(verdict + raw counts — N verified, errors, warnings, K skipped — plus the WARN breakdown by flag) and writes the same string to the JSON as
VERDICT-LINE:. Copy that line verbatim into your summary and into any README or status line you write — do not recompose it from memory and do not round it off. Around it, add: the list of fixes applied (old → new), user decisions taken, flags the user accepted as-is, and any wrong-artifact / low-relevance items raised for the user's judgment. If this run gates another skill's output, pass the sameverdict_linethrough unchanged; never upgrade a PARTIAL-PASS to "passed", never collapse "PARTIAL-PASS, 11 WARN, 1 skipped" into "verified, 0 errors", and never promise acceptance or a clean review.verdict_line
-
运行校验器。确定性工作由脚本完成——切勿手动或凭记忆验证条目:bash
export CONTACT_EMAIL=user@university.edu # 向用户索要 python3 scripts/check_bibtex.py path/to/refs.bib --json /tmp/citecheck.json实用变体:- ——仅执行解析+重复/静态检查(无需网络;适用于用户无网络连接或仅需结构检查的场景)
--offline - ——修正后重新检查单个条目(可重复执行)
--key smith2024 - ——大幅减少大型文件的请求量;但在最终预提交运行时请保持撤回检查开启
--no-retraction-check - ——若出现警告或PARTIAL-PASS则返回非零退出码(CI校验模式:若无法访问索引,则校验未完成)
--strict - ——绕过
--refresh中24小时的响应缓存.cache/ - ——为独立收集的新增引用开启相关性校验:传入纯文本论文/摘要,以及已确认的核心引用键;主题匹配度低的条目会被标记为
--thesis-file thesis.txt --core-key dean2008 --core-key vaswani2017供审核。适用于其他工具(LOW_RELEVANCE、draft-related-work)新增了引用,需要区分有效新增和偏离主题的引用时literature-review - ——跳过用于
--no-canonical-instance(错误版本)检查的同名标题额外查找(默认开启)CANONICAL_INSTANCE - ——一旦任何索引无法访问则立即终止(退出码1),而非降级为PARTIAL-PASS
--no-soft-fail - ——运行内置的离线单元测试,用于确定性的
--self-test检查(无需网络和ENTRY_TYPE_MISMATCH文件);测试通过则返回0。用于确认脚本在编辑后仍完整可用.bib
退出码:表示无问题,0表示发现问题,2表示操作失败(文件错误、无网络、缺少CONTACT_EMAIL——需修复问题,切勿跳过校验)。对于包含50条目的文件,预计耗时约2-4分钟:脚本设计为每个主机最多每秒1次请求,以遵守速率限制。请勿并行运行或绕过该礼貌限制。1 -
分类处理所有标记。阅读references/triage-guide.md了解每个标记的含义、已知误报(线上与印刷版年份差1、出版地别名、arXiv与正式出版版本、作者列表截断)以及每个问题的具体修正方法。严重程度概览:
标记 严重程度 含义 UNRESOLVED / DOI_NOT_FOUND / ARXIV_NOT_FOUND 错误 在任何索引中均未找到——可能为伪造 TITLE_MISMATCH / AUTHOR_MISMATCH / YEAR_MISMATCH 错误 标识符指向另一篇论文,或元数据错误 RETRACTED 错误 该DOI存在撤回通知 DUPLICATE_KEY / DUPLICATE_DOI / DUPLICATE_TITLE 错误 同一论文或引用键重复出现 MALFORMED_DOI / MALFORMED_ARXIV_ID 错误 标识符格式无效 POSSIBLE_ID_TYPO / MISSING_DOI / VENUE_MISMATCH / AUTHOR_LIST_DIFFERS / TITLE_PARTIAL_MATCH / NOT_IN_INDEXES / EXPRESSION_OF_CONCERN 警告 论文真实存在,但条目存在瑕疵——需修正或说明理由 ENTRY_TYPE_MISMATCH 警告 BibTeX类型与解析记录不符(例如:将期刊文章或专著标记为 ,@inproceedings字段填写期刊/出版社名称,或booktitle包含@inproceedings字段)——需根据标准journal=字段设置类型typeCANONICAL_INSTANCE 警告 可解析,但该作品的另一版本才是领域内普遍引用的——需选择标准版本 LOW_RELEVANCE 警告 可解析,但与论文主题匹配度低——需确认其是否必要,切勿自动删除 UNVERIFIABLE_TYPE / RESOLVED_VIA_SEARCH / HAS_CORRECTION / RELEVANCE_OK / CHECK_SKIPPED 信息 供人工判断的上下文信息 -
仅基于标准记录修正。使用权威来源获取的BibTeX替换有问题的条目(DBLP的.bib端点或doi.org的内容协商——具体命令见references/triage-guide.md)。切勿凭记忆重新输入元数据;这正是幻觉被洗白为“修正”的方式。关于提供商详情、各索引的权威领域以及出版地别名问题,请参阅references/verification-sources.md。
-
无法修正的问题需提交用户决策。对于每个UNRESOLVED条目,向用户展示证据并询问:保留(需用户提供可靠的手动来源)、修正(用户提供真实参考文献)或删除(同时删除命令并调整上下文文本)。切勿静默决策、静默删除,也切勿替换为仅名称相似的其他论文。
\cite对于和CANONICAL_INSTANCE(均为警告),请参阅references/triage-guide.md和references/relevance-gate.md。这些是辅助提示,而非自动操作:需展示替代版本/低匹配度分数,由用户决策。脚本的词汇相关性分数是确定性代理——若有嵌入模型可用,可自行计算摘要嵌入相似度以获得更可靠的信号,再给出建议,具体见相关性校验的参考文档。切勿自动替换版本或自动删除低匹配度引用。LOW_RELEVANCE -
重新运行直至退出码为0(或直至剩余标记被用户明确接受)。使用仅重新检查已修正的条目,然后进行一次完整的最终检查。若因索引无法访问导致返回PARTIAL-PASS,则校验未完成——待网络恢复后重新运行未执行的检查,再确认校验通过。
--key -
生成报告。脚本会在标准输出中打印一条标准的(判定结果+原始统计数据——已验证数量、错误数量、警告数量、跳过数量——以及按标记分类的警告明细),并将同一字符串写入JSON文件的
VERDICT-LINE:字段。请将该行原文复制到你的总结、README或状态行中——切勿凭记忆重新编写或四舍五入。在该行周围补充:已应用的修正列表(旧→新)、用户做出的决策、用户接受的标记,以及提交给用户判断的错误版本/低相关性条目。若本次校验为其他工具的输出把关,请原样传递verdict_line;切勿将PARTIAL-PASS升级为“通过”,切勿将“PARTIAL-PASS,11条警告,1项跳过”简化为“已验证,0错误”,切勿承诺会被接受或获得干净的评审结果。verdict_line
Output
输出结果
- The script's per-entry report on stdout, ending with a canonical
you reproduce verbatim, and — with
VERDICT-LINE:— a machine-readable report (per-entry statuses and flags, resolved DOIs/URLs, the same--json, and averdict_linecount) the calling skill can act on.summary.warnings_by_flag - A corrected (edits applied from canonical records, with the user's approval) and a short human summary whose first line is the verbatim
.bib, followed by what changed and what remains open.VERDICT-LINE
- 脚本在标准输出中生成的条目级报告,结尾为需原样复制的标准;若使用
VERDICT-LINE:参数,还会生成机器可读的报告(条目级状态和标记、解析后的DOI/URL、相同的--json,以及verdict_line统计),供调用工具使用summary.warnings_by_flag - 修正后的文件(基于标准记录进行编辑,需获得用户批准),以及一份简短的人工总结,第一行为原文复制的
.bib,后续内容为变更点和未解决问题VERDICT-LINE:
Hard rules
硬性规则
- Never fabricate a citation, DOI, arXiv ID, or BibTeX field. If a reference cannot be verified, say so — an honest gap beats a confident fake.
- Never "fix" an unresolved entry by guessing which real paper was meant. Search, show candidates, let the user choose.
- Resolution is not endorsement. A resolving DOI/ID proves the record is
real, not that it is the right instance or topically relevant. Treat
and
CANONICAL_INSTANCEas copilot prompts: surface the evidence, never auto-swap the artifact or auto-remove the reference.LOW_RELEVANCE - Never invent a citation count, an alternative artifact, or a relevance score. Every alternative the canonical-instance check shows must be a record an index actually returned; every relevance number comes from the script or from an embedding model you actually ran — not from memory.
- A PARTIAL-PASS is not a PASS. If any authoritative index was unreachable, report PARTIAL-PASS, list the skipped checks, and re-run them before treating the bibliography as verified. Never let "could not check" read as "clean".
- The human summary must echo the machine verdict verbatim — never paraphrase it cleaner. Any prose summary, README, or status line you write must carry the script's exact verdict (PASS / PARTIAL-PASS / FAIL) plus the raw counts: N verified, M warnings (by flag), K skipped checks. Do not collapse "PARTIAL-PASS, 11 WARN, 1 skipped check" into "verified, 0 errors"; a clean-looking summary that diverges from the report it summarizes is itself a failure. An entry is only "verified" once an actual index round-trip confirmed it this session and reconciled its type/venue/DOI to the canonical (not reprint) record — never mark verified from a stale or skipped check, and never leave a "not yet trustworthy" banner on a file you call verified.
- A RETRACTED result must be surfaced to the user verbatim, with the retraction-notice DOI. Citing retracted work knowingly is sometimes legitimate (e.g., studying retractions) — that is the user's call, and the citation should then mark the retraction explicitly.
- Metadata only: this skill fetches and compares titles, authors, years, venues, DOIs. Do not store fetched abstracts or paper text in the repo.
- Retraction coverage is best-effort (Crossref/Retraction Watch data plus title markers); absence of a flag is not proof a paper stands. Say so when it matters.
- When using profiles to judge a VENUE_MISMATCH, treat the profile as a starting point — re-verify any venue fact you rely on against the live
venues/in the profile before telling the user their entry is wrong.cfp_url
- 切勿伪造引用、DOI、arXiv ID或BibTeX字段。若参考文献无法验证,请如实告知——诚实的空白比自信的伪造更可取
- 切勿通过猜测“修正”无法解析的条目。需进行搜索,展示候选结果,由用户选择
- 解析成功不代表认可。可解析的DOI/ID仅能证明记录真实存在,无法证明其是正确版本或与主题相关。将和
CANONICAL_INSTANCE视为辅助提示:展示证据,切勿自动替换版本或自动删除引用LOW_RELEVANCE - 切勿编造引用量、替代版本或相关性分数。标准版本检查展示的每个替代版本必须是索引实际返回的记录;每个相关性分数必须来自脚本或你实际运行的嵌入模型——而非记忆
- PARTIAL-PASS不等于通过。若任何权威索引无法访问,需报告PARTIAL-PASS,列出跳过的检查项,并在将文献目录标记为已验证前重新运行这些检查。切勿让“无法检查”被解读为“无问题”
- 人工总结必须与机器判定原文一致——切勿简化表述。你编写的任何文字总结、README或状态行必须包含脚本的准确判定结果(PASS/PARTIAL-PASS/FAIL)以及原始统计数据:已验证数量、警告数量(按标记分类)、跳过的检查数量。切勿将“PARTIAL-PASS,11条警告,1项跳过检查”简化为“已验证,0错误”;与报告内容不符的简洁总结本身就是失败。只有当本次会话中实际通过索引往返确认,并将其类型/出版地/DOI与标准(非重印)记录一致后,条目才可标记为“已验证”——切勿基于过期或跳过的检查标记已验证,也切勿在标记为已验证的文件上留下“尚未可信”的提示
- RETRACTED结果必须原样展示给用户,并附上撤回通知的DOI。明知故犯地引用已撤回的文献有时是合理的(例如:研究撤回案例)——这由用户决定,且引用需明确标记撤回信息
- 仅处理元数据:本工具仅获取和比较标题、作者、年份、出版地、DOI。请勿在仓库中存储获取的摘要或论文文本
- 撤回信息覆盖为尽力而为(Crossref/Retraction Watch数据加标题标记);无标记不代表论文有效。必要时需告知用户这一点
- 使用配置文件判断VENUE_MISMATCH时,需将配置文件作为起点——在告知用户其条目错误前,需根据配置文件中的实时
venues/重新验证你依赖的任何出版地信息cfp_url
Bundled resources
附带资源
- — the verifier. Run it; do not reimplement it.
scripts/check_bibtex.py - references/triage-guide.md — flag-by-flag
interpretation, false positives, exact remediation commands (includes
and the PARTIAL-PASS verdict).
CANONICAL_INSTANCE - references/relevance-gate.md — how the
relevance gate scores topical fit, the embedding-similarity upgrade you
should run when a model is available, and how to act on .
LOW_RELEVANCE - references/verification-sources.md — provider APIs, authority order, venue aliasing, retraction data, rate limits and licensing.
- ——校验器。请直接运行,切勿重新实现
scripts/check_bibtex.py - references/triage-guide.md ——逐条标记的解释、误报说明、具体修复命令(包含CANONICAL_INSTANCE和PARTIAL-PASS判定)
- references/relevance-gate.md ——相关性校验如何计算主题匹配度、当有模型可用时应运行的嵌入相似度升级方法,以及如何处理标记
LOW_RELEVANCE - references/verification-sources.md ——提供商API、权威顺序、出版地别名、撤回数据、速率限制和许可信息
Memory
记忆机制
This skill uses the shared convention in the user's paper
directory, following .
.paper-memory/paper-memory-convention.md- At start: read to skip re-flagging entries the user already resolved this cycle, and lead with any
.paper-memory/lessons.mdcitation habits recorded for this author (e.g. "tends to cite arXiv preprints that are now published; prefer the published record").recurring - At end: append durable findings in the shared format (via
- [YYYY-MM-DD] (verify-citations | <scope>) issue -> recommendation'sreflect-and-improve, which dedupes and dates). A pattern across the bibliography or across papers isreflect_log.py append; a single fixed entry isrecurring. Never record fabricated metadata in memory, only the pattern and the canonical fix.this-paper - Create on demand if absent and offer to add it to the project
.paper-memory/. It is local-only; never upload it or copy it into this repo..gitignore
本工具遵循用户论文目录中的共享约定,详见。
.paper-memory/paper-memory-convention.md- 启动时:读取,跳过重新标记用户本次周期内已解决的条目,并优先处理为该作者记录的
.paper-memory/lessons.md(重复出现的)引用习惯(例如:“倾向于引用已正式出版的arXiv预印本;优先选择正式出版记录”)recurring - 结束时:以共享格式追加持久化发现(通过
- [YYYY-MM-DD] (verify-citations | <scope>) issue -> recommendation的reflect-and-improve实现,会自动去重并添加日期)。若在文献目录或多篇论文中发现模式,则标记为reflect_log.py append;单个已修正的条目标记为recurring。切勿在记忆中存储伪造的元数据,仅记录模式和标准修正方法this-paper - 若不存在则按需创建,并建议用户将其添加到项目的
.paper-memory/中。该目录仅本地存储;切勿上传或复制到本仓库.gitignore