citation-management 技能脚本全参考：三大文献库检索、元数据提取与 BibTeX 校验命令行实战指南-平芜编程栈

citation-management 技能脚本全参考：三大文献库检索、元数据提取与 BibTeX 校验命令行实战指南

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

导读

本指南以 citation-management 技能中随附的 8 个脚本为骨架，逐条讲解每一个命令行工具的用途、参数与使用示例：从 OpenAlex、PubMed、Google Scholar 三个学术库完成文献发现，到 DOI/PMID/arXiv ID/URL 元数据提取、BibTeX 格式化清洗、以及对照目标刊物规范与手稿正文的引用校验。读完本文，你将能直接用现成命令搭建一条「检索 → 提取 → 清洗 → 校验 → 输出」的端到端文献引用流水线，并为每条命令背后共享的 BibTeX 解析与引用键机制建立源码级认知。

图中展示了本技能从 DISCOVERY（OpenAlex / PubMed / Google Scholar 检索）→ METADATA（extract_metadata.py 提取 + WebSearch 补全）→ OUTPUTS（references.bib 生成、重复合并、validate_citations 校验、最终输出 report.json 与论文正文）的完整链路，与本篇参考文档讨论的每个脚本一一对应。

脚本全景：8 个文件的分工与协作

技能随附的 scripts/ 目录共含 8 个文件，其中 7 个是可独立执行的命令行工具：

脚本	职责	所处阶段
`search_openalex.py`	免 API Key 检索 OpenAlex（约 2.5 亿篇全学科文献）	发现
`search_pubmed.py`	通过 E-utilities 检索 PubMed	发现
`search_google_scholar.py`	借助`scholarly`库检索 Google Scholar	发现
`extract_metadata.py`	由标识符（DOI/PMID/arXiv/URL）提取完整元数据	提取
`doi_to_bibtex.py`	DOI 一键转 BibTeX	提取
`validate_citations.py`	校验准确性、完整性、刊物引用量与手稿引用一致性	校验
`format_bibtex.py`	格式化、排序、去重、修复并统一引用键	清洗

_common.py不是命令行工具，而是上面每个脚本共同依赖的标准库模块：它承载了 brace-aware（感知花括号深度）的 BibTeX 解析器、条目渲染器、页码范围归一化器，以及统一引用键（citation-key）方案——正是这一点让来自不同数据库（OpenAlex、CrossRef、PubMed、Google Scholar）的条目彼此可比，从而在format_bibtex.py与validate_citations.py中实现跨来源去重。模块内已实现 parse_bibtex / parse_bibtex_file / render_entry / format_pages / sanitize_key / citation_key / protect_title 等全部核心函数。

一、文献发现：三个检索脚本

1.`search_openalex.py`— 免 Key 的全学科检索

面向 OpenAlex 的 REST API 客户端，无需任何 API Key。从源码可见其实现细节：

游标分页：API 地址固定为https://api.openalex.org/works，每页最多取min(200, max_results)条，通过meta.next_cursor逐页推进；
年份过滤：--year-start/--year-end分别转换为from_publication_date:{year}-01-01与to_publication_date:{year}-12-31的整年窗口；
类型过滤：--type直接拼接为type:{work_type}；
排序：--sort-by citations时按cited_by_count:desc排序；
摘要重建：OpenAlex 以倒排索引存储摘要，客户端按索引位置还原词序拼回正文；
开放获取标记：每条记录带is_open_access字段；
宽松限速：翻页间sleep(0.1)秒。

功能要点：免 Key REST API + 游标分页；年份区间与文献类型过滤；按相关度或被引量排序；由倒排索引重建摘要；开放获取状态标记；可导出 JSON 或 BibTeX。

用法示例：

# 基本检索 python scripts/search_openalex.py "quantum computing" # 指定窗口内被引量最高的文献 python scripts/search_openalex.py "quantum computing" \ --year-start 2020 \ --year-end 2024 \ --limit 100 \ --sort-by citations \ --output quantum_papers.json # 仅要综述，直接出 BibTeX python scripts/search_openalex.py "CRISPR gene editing" \ --type review \ --limit 50 \ --format bibtex \ --output crispr_reviews.bib

参数速查：query（位置参数，自由文本查询词）、--limit（最大结果数，默认 50）、--year-start/--year-end（含边界年份）、--type（work 类型，如article、review、preprint）、--sort-by（relevance或citations）、--format（json或bibtex，默认 json）、-o/--output（写文件，缺省打到 stdout）、--email。

设置环境变量OPENALEX_EMAIL（或传--email）即可加入 OpenAlex 的 polite pool——源码第 61 行显示该地址仅作为mailto查询参数发送给api.openalex.org，响应更快且可用性更稳定。在导出 BibTeX 时，OpenAlex 的 work 类型会通过TYPE_MAP映射为对应条目类型（如review→article、book-chapter→incollection、dissertation→phdthesis、preprint→misc），缺 DOI 时回退写入 OpenAlex ID 作为url。

2.`search_pubmed.py`— 生物医学权威检索（E-utilities）

面向 PubMed E-utilities API 的客户端，在生物与生命科学领域具有权威覆盖。支持复杂查询构造（MeSH 主题词、字段标签、布尔逻辑）、日期区间过滤、出版类型过滤，以及带完整元数据的批量抓取，可导出 JSON 或 BibTeX。结合 pubmed_search.md 可进一步学习 E-utilities 高级检索语法。

用法示例：

# 简单关键词检索 python scripts/search_pubmed.py "CRISPR gene editing" # 带过滤条件的复杂查询（MeSH + 字段标签 + 布尔） python scripts/search_pubmed.py \ --query '"CRISPR-Cas Systems"[MeSH] AND "therapeutic"[Title/Abstract]' \ --date-start 2020-01-01 \ --date-end 2024-12-31 \ --publication-types "Clinical Trial,Review" \ --limit 200 \ --output crispr_therapeutic.json # 导出 BibTeX python scripts/search_pubmed.py "Alzheimer's disease" \ --limit 100 \ --format bibtex \ --output alzheimers.bib

参数速查：query（位置参数）或--query（完整检索式，注意两者二选一）、--limit、--date-start/--date-end（形如YYYY-MM-DD的精确日期边界，区别于 OpenAlex 的年份）、--publication-types（逗号分隔的出版类型列表，如Clinical Trial,Review）、--format（json/bibtex）、-o/--output。

PubMed 客户端同样支持可选身份标识：设置NCBI_EMAIL（NCBI 要求的调用者身份）与NCBI_API_KEY（提升 Entrez 限速额度），详见 SKILL.md 的环境变量表。从源码结构看，其元数据由 efetch 返回的 XML 逐字段解析，作者以Smith JA这种「姓在前、缩写在后」的形式进入后续 BibTeX 渲染。

3.`search_google_scholar.py`— 覆盖面最广，但仅作补充

Google Scholar没有官方 API，此脚本依赖第三方scholarly库抓取公开页面，因此是三个检索源中最脆弱的一个。技能官方定位是：OpenAlex 与 PubMed 应作为主要检索源，Google Scholar 只能作为补充。

从源码可见其自我保护机制：每条结果之间强制sleep(random.uniform(2, 5))秒做限速以降低被封概率；支持--use-proxy通过ProxyGenerator().FreeProxies()换用免费代理规避封禁；年份过滤在抓取后于客户端本地完成（因为页面无法按年查询）。

功能要点：自动化检索 + 限速；分页支持；年份区间过滤；JSON/BibTeX 导出；被引量信息。

用法示例：

# 基本检索 python scripts/search_google_scholar.py "quantum computing" # 带过滤的进阶检索 python scripts/search_google_scholar.py "quantum computing" \ --year-start 2020 \ --year-end 2024 \ --limit 100 \ --sort-by citations \ --output quantum_papers.json # 直接导出 BibTeX python scripts/search_google_scholar.py "machine learning" \ --limit 50 \ --format bibtex \ --output ml_papers.bib

参数速查：query、--limit（默认 50）、--year-start/--year-end、--sort-by（relevance或citations）、--use-proxy、--format、-o/--output。

使用前需先安装依赖：uv pip install scholarly。若未安装，脚本会给出警告并建议改用 PubMed。两点使用提示（来自源码注释与 SKILL.md）：其一，Scholar 记录通常没有 DOI、venue 为非结构化字符串，生成的 BibTeX 只能作为起点，必须再过一遍元数据补全（见本文第三部分）才能引用；其二，被引量只保留在 JSON 输出中而刻意不写入 .bib——因为引用数每周都在变，写进参考文献会让文件立刻过时。

二、元数据提取与快速转换

4.`extract_metadata.py`— 通用元数据提取器

把各类论文标识符统一转换为完整元数据。支持的标识符类型与后端对应关系（从源码的identify_type/extract_from_*方法可确认）：DOI → CrossRef（首选）并回退 DataCite；PMID/PMCID → PubMed E-utilities；arXiv ID → arXiv API；URL → 先解析路径中的 DOI，若没有则读取出版商文章页里嵌入的citation_doimeta 标签还原 DOI，再交给 CrossRef。支持单条与批量处理、多种输出格式。

用法示例：

# 单个 DOI python scripts/extract_metadata.py --doi 10.1038/s41586-021-03819-2 # 单个 PMID python scripts/extract_metadata.py --pmid 34265844 # 单个 arXiv ID python scripts/extract_metadata.py --arxiv 2103.14030 # 从 URL 提取 python scripts/extract_metadata.py \ --url "https://www.nature.com/articles/s41586-021-03819-2" # 批量处理（输入文件每行一个标识符） python scripts/extract_metadata.py \ --input paper_ids.txt \ --output references.bib # 不同输出格式 python scripts/extract_metadata.py \ --doi 10.1038/nature12345 \ --format json # 或 bibtex, yaml

参数速查：--doi、--pmid、--arxiv、--url（四者给出其一即可）、-i/--input（每行一个标识符的输入文件）、-o/--output（缺省 stdout）、--format（bibtex或json，默认 bibtex）、--email（NCBI E-utilities 建议使用的身份标识）。注意：此处命令行选项仅支持bibtex/json两种格式，原文档注释中的yaml是「格式可扩展」的示意。

5.`doi_to_bibtex.py`— DOI 快速转换

面向「手头只有一个 DOI、想立刻拿到一条干净 BibTeX」的场景。内部走 CrossRef 查询；批量模式（convert_multiple，源码默认delay=0.5）在连续请求之间自带 0.5 秒间隔，兼顾礼貌限速。

功能要点：单 DOI 极速转换；批量处理；多输出格式；剪贴板支持。

用法示例：

# 单个 DOI python scripts/doi_to_bibtex.py 10.1038/s41586-021-03819-2 # 多个 DOI python scripts/doi_to_bibtex.py \ 10.1038/nature12345 \ 10.1126/science.abc1234 \ 10.1016/j.cell.2023.01.001 # 从文件读取（每行一个 DOI） python scripts/doi_to_bibtex.py --input dois.txt --output references.bib # 复制到剪贴板（macOS 用 pbcopy；Linux 可用 xclip） python scripts/doi_to_bibtex.py 10.1038/nature12345 | pbcopy

三、BibTeX 格式化与清洗

6.`format_bibtex.py`— 格式化、排序、去重、重排键

用于生成干净、一致的 BibTeX 文件。支持统一格式、按键/年份/作者排序、去重、语法校验与常见错误修复、强制统一引用键规范。fix_common_issues默认开启，可修复字段值中的常见问题。

源码中format_file的参数与 CLI 对应：--output（结果写往该文件）与--in-place（直接覆写输入文件）互斥；两者都缺省时结果打到 stdout，输入文件保持不动。--rekey用于把同一条文献的不同键重排成统一方案，因此在合并多来源结果时务必使用--rekey，让同一篇论文坍缩为同一条目——这正是配合后续validate_citations.py去重的前提。

用法示例：

# 基本格式化（结果到 stdout） python scripts/format_bibtex.py references.bib # 按年份排序（新的在前） python scripts/format_bibtex.py references.bib \ --sort year \ --descending \ --output sorted_refs.bib # 去除重复 python scripts/format_bibtex.py references.bib \ --deduplicate \ --output clean_refs.bib # 完整清理：重排键 + 去重 + 排序 python scripts/format_bibtex.py references.bib \ --rekey \ --deduplicate \ --sort year \ --output final_refs.bib

参数速查：file（位置参数，输入 .bib）、--output/--in-place（互斥写出方式）、--deduplicate、--rekey、--sort（按key/year/author等字段排序）、--descending、--no-fix-issues（关闭常见问题自动修复）。

共享基础：`_common.py`的四个关键机制

为什么去重能跨来源生效？答案在 _common.py：

brace-aware 解析器：普通正则\{([^}]*)\}会在第一个右花括号处截断——凡是含{AlphaFold}这类大写保护项的标题都会被截坏，写回后生成花括号不平衡、任何 BibTeX 引擎都读不了的.bib。parse_bibtex 按深度扫描花括号与引号、只在顶层切分逗号，@string/@comment/@preamble一律跳过；
统一渲染器：render_entry 按固定的FIELD_ORDER稳定排序并对齐字段值、丢弃空字段——四个来源产出的条目格式一致，才可互相比较；
页码范围归一化：format_pages 把所有583-589式连字符统一成 BibTeX 规范的 en-dash583--589，并把 PubMed 缩写区间1123-30展开为1123--130形式……实际上它按start[:len(start)-len(end)] + end补全为1123--1130，而不是留下无意义的1123--30；非区间值（如文章号e0123456）原样返回；
统一引用键方案：citation_key 生成<首位作者姓><年份><标题首实义词>，先做 ASCII 折叠（Müller→Muller）再剔除字母数字之外的所有字符；sanitize_key 保证O'Brien、Müller不会产出让 LaTeX 报错的键；protect_title 会对AlphaFold/CRISPR/DNA/mRNA/HIV等PROTECTED_TERMS表内的大写专业术语加花括号保护（且已幂等，重复运行不会嵌套加括号）。

安全提示（务必阅读）：被提取的元数据应视为不可信输入。作者、标题、期刊字符串原样来自「内容由出版商控制」的记录——一条含$(...)、反引号或引号的标题，一旦被拼进 shell 字符串就变成命令注入。跨进程传参时用subprocess参数列表而非 shell 字符串；若必须用 shell，请对每个替换值加单引号并把内嵌引号转义为'\''；任何引用键在进入文件路径前都应先用^[A-Za-z0-9]+$校验。

四、引用校验：`validate_citations.py`

发布前必须执行的最终关卡。从源码可确认其校验维度与实现：

DOI 验证：--check-dois时逐条核对。特别注意其实现细节——不直接 HEADdoi.org（多家出版商会因 bot 检查返回 403/405，让好 DOI 看起来失效），而是先查注册机构 CrossRef 的api.crossref.org/works/{doi}；CrossRef 返回 404 时再查 DataCite（因为 DataCite 注册数据集与大量预印本），都查不到才判死；
必填字段检查：按条目类型给出必填字段表（如article要求author/title/journal/year，book允许author OR editor，misc仅title/year）；
重复检测：同时检查重复 DOI（high）、重复引用键（high）与规范化后完全相同的标题（medium）；
格式校验：年份必须为 4 位数字、DOI 须匹配^10\.\d{4,}/\S+$、页码范围应为--而非单连字符、作者须以and分隔（出现;或&判错）；
刊物引用量标准检查：--venue对照预设阈值表（如 Nature 类 35–50、NeurIPS/ICML/CVPR 等 ML 会议 30–45、综合文献综述 40–65），可传nature、neurips、review等键名；注意这些阈值是编辑经验法则而非投稿硬性要求，所以低于阈值只报 warning，永不因「引用太少」而判条目错误；
手稿一致性检查（发表前强制项）：--manuscript指定论文正文（Markdown 或 LaTeX），脚本用正则同时识别\cite{...}/\citep{...}系列与 Pandoc 的@key/[@key1; @key2]语法（并已规避邮箱、@ 昵称等误报），然后对照 BibTeX 键集找出「正文引用但 bib 未定义」（unresolved，high）与「bib 定义但正文未引用」（unused，medium）两类问题。

退出码语义：存在 high 级错误（缺必填字段、非法年份、未解析引用、低于显式--min-count下限）时脚本以非零码退出——因此可作为 CI / 写作流水线的门禁。--min-count是唯一会升级为 error 的数量检查，因为它是调用者显式要求的硬性下限。

用法示例：

# 基本校验 python scripts/validate_citations.py references.bib # 对照刊物标准校验（如 Nature、NeurIPS、文献综述） python scripts/validate_citations.py references.bib --venue nature python scripts/validate_citations.py references.bib --venue neurips python scripts/validate_citations.py references.bib --venue review # 自定义最少引用数 python scripts/validate_citations.py references.bib --min-count 40 # 对照手稿正文检查（找出缺失或未用引用） python scripts/validate_citations.py references.bib --manuscript paper.md # 完整联合校验 python scripts/validate_citations.py references.bib \ --venue nature \ --manuscript paper.md \ --report validation_report.json \ --verbose

参数速查：file（位置参数，待校验 .bib）、--venue（nature/science/cell/neurips/icml/iclr/cvpr/acl/review/medical等标准键）、--min-count、--manuscript、--check-dois（慢，需联网打 CrossRef）、--report（JSON 报告输出路径）、--verbose。--report会生成结构化 JSON（含total_entries、valid_entries、errors、warnings、duplicates、manuscript_results等字段），供下游程序解析。

五、把七个命令串成一条流水线

引用管理遵循五阶段方法论（完整版见 core_workflow.md），把上面的脚本按序衔接即得典型端到端流程：

# Phase 1 文献发现：至少覆盖两个库，避免单一来源偏差 python scripts/search_openalex.py "CRISPR gene editing" --limit 50 --output results.json python scripts/search_pubmed.py "CRISPR gene editing" --limit 50 --output pm_results.json # Phase 2 元数据提取：DOI / PMID 等标识符统一成 BibTeX python scripts/doi_to_bibtex.py 10.1038/s41586-021-03819-2 python scripts/extract_metadata.py --input identifiers.txt --output citations.bib # Phase 2.5 元数据补全（强制）：缺失 volume/pages/doi 用网络检索补齐，确实找不到就记录 note 字段 python scripts/search_openalex.py "<exact title>" --limit 1 # 最省事的补全入口 # Phase 3 BibTeX 清洗：多来源合并必须 --rekey --deduplicate python scripts/format_bibtex.py citations.bib --output clean.bib --rekey --deduplicate # Phase 4 引用校验：必做项 + 对照正文 python scripts/validate_citations.py clean.bib --report report.json --check-dois python scripts/validate_citations.py clean.bib --manuscript paper.md # Phase 5 写作工作流集成：search → extract → format → validate → cite

安装依赖与网络前提：本技能需 Python 3.9+ 与requests，安装uv pip install requests即可驱动 OpenAlex/PubMed/CrossRef/arXiv 检索；仅当使用search_google_scholar.py时才需额外uv pip install scholarly。BibTeX 解析、渲染、去重与校验均基于标准库_common.py，因此format_bibtex.py与validate_citations.py不依赖任何第三方包。运行时需可访问api.openalex.org、api.crossref.org、eutils.ncbi.nlm.nih.gov、export.arxiv.org、api.datacite.org。全程无需任何 API Key，可选的三个环境变量分别只发给各自所属服务：NCBI_API_KEY、NCBI_EMAIL仅发往eutils.ncbi.nlm.nih.gov，OPENALEX_EMAIL仅发往api.openalex.org，脚本不会把环境变量合并外发。

六、常见误区与配套资源

结合 SKILL.md 的 Common Pitfalls，脚本层最容易踩的坑包括：只用单一数据库导致引用列表偏置（解法：至少搜 OpenAlex + PubMed，再用--rekey --deduplicate合并）；盲目采信提取结果（解法：与原始来源抽查核对）；含损坏 DOI 就提交（解法：发布前跑validate_citations.py --check-dois）；引用键与格式混杂（解法：统一走format_bibtex.py）；同文异键的重复条目（解法：校验器的重复检测）；@article缺 volume/pages/DOI 就跳过（解法：Phase 2.5 补全后再进入格式化，绝不让缺这三个字段的条目过关）；以及手工逐条敲 BibTeX（解法：一律用脚本从元数据源提取）。

同主题深入阅读（引用键全部指向本技能内文档）：

core_workflow.md：五阶段全流程与端到端序列
search_strategies.md：三库查询构造与检索算子
google_scholar_search.md / pubmed_search.md：检索语法详解
metadata_extraction.md / bibtex_formatting.md / citation_validation.md：分主题细节
best_practices.md：检索、提取、BibTeX 质量与校验最佳实践
example_workflows.md：四个端到端实战范例
样例数据与清单：assets/bibtex_template.bib、assets/citation_checklist.md

该技能还可与仓库中的 literature-review（系统化检索与综合）、scientific-writing（LaTeX 手稿引用）、venue-templates（不同刊物引用风格）等技能协同，构成完整科研写作链路；具体集成方式见 SKILL.md 的 Integration with Other Skills 一节。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

citation-management 技能脚本全参考：三大文献库检索、元数据提取与 BibTeX 校验命令行实战指南