onecite

@article{LeCun2015Deep,
  doi = "10.1038/nature14539",
  title = "Deep learning",
  author = "LeCun, Yann and Bengio, Yoshua and Hinton, Geoffrey",
  journal = "Nature",
  year = 2015,
  volume = 521,
  number = 7553,
  pages = "436-444",
  publisher = "Springer Science and Business Media LLC",
  url = "https://doi.org/10.1038/nature14539",
  type = "journal-article",
  abstract = "Deep learning allows computational models that are composed of multiple processing layers to learn representations of data with multiple levels of abstraction...",
}
@inproceedings{Vaswani2017Attention,
  arxiv = "1706.03762",
  title = "Attention Is All You Need",
  author = "Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N. and Kaiser, Lukasz and Polosukhin, Illia",
  year = 2017,
  booktitle = "Advances in Neural Information Processing Systems (NeurIPS)",
  url = "https://arxiv.org/abs/1706.03762",
}
# ... and 5 more entries ...

onecite process "10.1038/nature14539"
onecite suggest "Attention is all you need, Vaswani et al., NIPS 2017"
echo "10.1038/nature14539" | onecite process -

在 Python 脚本中直接使用 OneCite。

from onecite import process_references

result = process_references(
    input_content="10.1038/nature14539",
    input_type="txt",
    template_name="journal_article_full",
    output_format="bibtex",
)

print('\n\n'.join(result['results']))

OneCite 提供了命令行界面，包含以下命令和选项：

onecite process

用于通过 OneCite 流水线处理参考文献的主命令。

用法：

onecite process <input_file> [OPTIONS]

参数：

• input_file - 输入文件路径、表示标准输入的 -，或强标识符／参考文献字符串

选项：

示例：

# Process a text file
onecite process references.txt -o results.bib

# Process a BibTeX file with auto-detection
onecite process references.bib

# Use stdin
echo "10.1038/nature14539" | onecite process -

# Process a direct string (DOI)
onecite process "10.1038/nature14539"

# Process with custom template
onecite process references.txt --template conference_paper

# Quiet mode for scripts
onecite process references.txt -o results.bib --quiet

# Automation-friendly JSON with unresolved-entry exit-code handling
onecite process references.txt --json --fail-on-unresolved

# Streaming NDJSON for automation
onecite process references.txt --ndjson

# CSL-JSON item output (a development fixture verifies Pandoc 3.10 consumption)
onecite process references.txt --output-format csl-json -o references.json

开发验证证实，Pandoc 3.10 能够使用代表性输出条目。此版本未单独验证 Quarto、独立 citeproc 和参考文献管理器导入工作流。

报告字段。 除了 results 和 failed_entries，处理报告还包含两个审计信号：

• warnings — 针对已解析条目的非阻断性审核警告。最重要的是 text_metadata_mismatch：已解析 DOI 周围的输入文本似乎描述了另一篇作品（典型的标题与 DOI 幻觉配对）。该 DOI 仍是已解析的标识符，条目也会解析成功，但系统会将其标记为待审核，而不是悄然作为干净输出发出。
• duplicates — 同一作品在批次中出现了多次（裸 DOI、PMID、格式化引文）。该作品只会输出一次；重复项会连同输出条目的引文键一起报告。

失败条目包含原始输入摘录（raw_text）和 reason 代码 — doi_not_found（在已实现的回退流程之后仍未返回注册记录）、no_strong_identifier（文本存在歧义；请使用 onecite suggest）、source_error（该路由上出现了来源／身份解析失败）等。这些代码便于区分重要情况，但并非完整的提供方调用轨迹：目前，某些 PMID、ISBN 和 DataCite 请求错误会与查询未命中归为同一未解析原因。

onecite suggest

搜索候选匹配项，不生成 BibTeX，也不返回验证 passed 状态。

onecite suggest "Attention is all you need, Vaswani et al., NIPS 2017" --json

候选项供审核使用，并非已通过来源核实的引文。 每条建议都会在 sources 列表中披露所查询学术索引的健康状况。如果某个来源受到速率限制或发生错误，建议状态会变为 candidates_found_incomplete / no_candidates_incomplete——正确的匹配项可能完全不在列表中，因此不得将候选列表视为完整列表。年份与查询中引用的年份相矛盾的候选项会受到惩罚，并标记为 year_conflict。若要将审核通过的候选项转换为已通过来源核实的 BibTeX，请通过 onecite process "<doi>" 解析其 DOI。

可选的 Google Scholar 回退。 suggest 接受 --google-scholar（需要可选的 scholarly 软件包：pip install onecite[scholar]）。仅当 CrossRef 和 Semantic Scholar 均未返回结果时，才会将其用作尽力而为的回退。由于它会抓取没有公开 API 的服务，因此默认关闭，可能受到速率限制或被 CAPTCHA 拦截，也无法保证结果可复现——它仅用于 suggest（供人工审核的候选项），不会用于 process。

pip install onecite[scholar]
onecite suggest "some obscure title" --google-scholar

onecite --version

显示已安装的 OneCite 版本。

用法：

onecite --version

onecite version

显示版本信息的备用命令。

用法：

onecite version

onecite templates

列出随附的 BibTeX 回退模板及其所需字段。

用法：

onecite templates
onecite templates --json

onecite benchmark

运行一组小型、确定性的回归测试，涵盖 DOI 查询、arXiv 查询、PMID/PubMed 查询、GitHub 软件 URL、Zenodo/DataCite 数据集 DOI，以及有效和无效条目的混合批次。此命令专为 CI 和自动化工作流而设计，可提供机器可读的通过/失败检查；它并非全面的引文准确性基准测试。

用法：

onecite benchmark [OPTIONS]

选项：

示例：

onecite benchmark
onecite benchmark --json
onecite benchmark --live --json
onecite benchmark --cases my_cases.json --min-success-rate 1.0 --json
onecite benchmark --anti-hallucination
onecite benchmark --anti-hallucination --json

仓库基线记录存储在 benchmarks/leaderboard.json 中，复现说明见 benchmarks/README.md。

防幻觉评估

onecite benchmark --anti-hallucination 会运行带标签、完全离线的评估，以检验 OneCite 的核心安全属性。它会将真实的强标识符（A 类）解析为已通过来源核实的 BibTeX；对于存在歧义的纯文本参考文献（B 类）以及虚构的、不存在的 DOI（C 类——大模型可能会幻觉生成的类型），它会保持未解析，而不是输出错误引文；对于不匹配的配对（D 类——真实 DOI 与另一篇论文的标题关联，这是最常见的幻觉引文形式），它会附加 text_metadata_mismatch 警告，而不是悄然将其作为无误的来源核实结果输出。它会报告三项指标：

• 解析率——正确解析的 A 类输入所占比例；
• 非编造率——正确保持未解析（未编造）的 B/C 类输入所占比例。100% 表示 OneCite 未编造任何引文；
• 不匹配检测率——附带不匹配警告进行解析的 D 类输入所占比例。

管线崩溃会记录为 error，且在任何指标中都不会计为正确——干净地拒绝和管线故障是不同的结果。

数据集位于 src/onecite/benchmarks/anti_hallucination_cases.json，也可通过 Python 使用 onecite.run_anti_hallucination_eval() 运行此评估。

onecite doctor

检查自动化和 CI 的本地安装健康状况。doctor 命令会检查软件包是否可导入、内置模板、打包的基准测试资源、 仓库内的 OneCite Skill，以及离线基准测试回归检查。

用法：

onecite doctor
onecite doctor --json

JSON 输出是一个稳定的封装，包含 schema_version、tool、 command、status、environment、summary 和 checks 字段。

面向自动化工作流的 OneCite Skill

仓库包含一个本地技能包，位于 skills/onecite/SKILL.md。 它为自动化和贡献者工作流提供可重复的流程，用于 清理参考文献、运行基准测试和 doctor 检查，以及明确 报告未解决的条目。 该 Skill 位于仓库内，不会将自身安装到任何本地 工具记忆中。

输入类型自动检测

未指定 --input-type 时，OneCite 会自动检测输入类型：

• 以 .bib 结尾的文件会被视为 BibTeX 格式
• 其他所有文件和字符串都会被视为纯文本

可用模板

OneCite 支持多种适用于不同条目类型的模板预设：

• journal_article_full - 完整期刊文章条目（默认）
• conference_paper - 会议论文集论文
• book - 书籍条目
• thesis - 学位论文条目
• dataset - 数据集条目
• software - 软件/代码条目

退出代码

• 0 - 成功
• 1 - 发生错误（输入无效、处理失败等）
• 2 - 使用 --fail-on-unresolved 时存在一个或多个未解决的条目

对于 onecite benchmark 和 onecite doctor，退出代码 0 表示 配置的检查均已通过；退出代码 1 表示至少有一项检查失败。