bioRxiv 预印本 API 实战指南：日期区间浏览、DOI 查询与防跳页分页（scientific-agent-skills paper-lookup 技能深度解析）

bioRxiv 预印本 API 实战指南日期区间浏览、DOI 查询与防跳页分页scientific-agent-skills paper-lookup 技能深度解析【免费下载链接】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导读bioRxiv 是全球最大的生物学预印本服务器其开放 API 为论文检索、版本追踪与发表状态核查提供了官方数据源。本文以 skills/paper-lookup/references/biorxiv.md 为核心结合仓库内 paper-lookup 技能的源码与测试paginate.py、test_scripts.py系统讲解 bioRxiv API 的四个关键端点、响应结构、分页陷阱与速率限制并给出可直接运行的 curl 与脚本化调用方案。读完本文你将掌握如何用日期区间浏览预印本、按 DOI 精确定位稿件、链接预印本与正式发表版本以及如何规避HTTP 200 掩盖数据丢失的经典分页陷阱。一、API 概览功能边界与定位bioRxiv 的 API 用于获取预印本元数据包括标题、作者、摘要、DOI 与发表状态。它在 paper-lookup 技能中服务于生物学预印本按日期或 DOI 检索这类意图。最重要的功能边界bioRxiv API不提供关键词搜索仅支持日期区间浏览和 DOI 精确查询。这是所有调用者必须最先记住的事实——需要按主题搜索 bioRxiv 预印本时应改用 Semantic Scholar、OpenAlex 或 CORE尤其是 Europe PMC它会索引 bioRxiv 和 medRxiv 并支持直接检索。在 SKILL.md 的数据库选择指南中bioRxiv 被明确列为按日期或 DOI 浏览的首选库同时建议与 Europe PMC 搭配完成关键词检索先用 Europe PMC 的SRC:PPR AND PUBLISHER:bioRxiv语法定位主题相关预印本再回到 bioRxiv API 获取预印本专属元数据如已发表版本链接。基本信息项目值Base URLhttps://api.biorxiv.org认证无需任何认证完全公开速率限制官方无文档化限制但应保持合理的请求频率响应格式json默认或xml二、核心端点详解bioRxiv API 提供四组关键端点覆盖预印本的浏览、定位、发表状态追踪与出版方检索。1. 按日期区间浏览Content Detail这是检索预印本列表的主入口GET /details/biorxiv/{interval}/{cursor}/{format}路径参数参数取值说明intervalYYYY-MM-DD/YYYY-MM-DD日期区间含两端。建议将区间收窄到 1-3 天避免请求超时N整数最近 N 篇预印本Nd整数 d最近 N 天内的预印本cursor整数默认0绝对记录偏移量。/details/每页返回 30 条因此步长必须为 30详见分页章节formatjson默认、xml响应格式可选查询参数?categoryneuroscience按学科分类过滤分类名中的空格用下划线如synthetic-biology。示例https://api.biorxiv.org/details/biorxiv/2024-01-01/2024-01-31/0 https://api.biorxiv.org/details/biorxiv/5 https://api.biorxiv.org/details/biorxiv/10d https://api.biorxiv.org/details/biorxiv/2024-01-01/2024-01-31?categoryneuroscience2. 按 DOI 精确查询Content Detail通过预印本 DOI 精确获取单篇元数据GET /details/biorxiv/{doi}/na/{format}其中na是固定的占位符。示例https://api.biorxiv.org/details/biorxiv/10.1101/2024.01.16.575895/na/json3. 已发表文章链接Published Article Links将预印本与其正式发表版本关联起来GET /pubs/biorxiv/{interval}/{cursor} GET /pubs/biorxiv/{doi}/na该端点同时接受预印本 DOI 与正式发表 DOI可用于回答这篇预印本最终发表在哪个期刊以及哪些预印本已经正式发表。4. 出版方过滤Publisher Filter按 DOI 前缀查找由特定出版方发布的 bioRxiv 论文GET /publisher/{prefix}/{interval}/{cursor}示例https://api.biorxiv.org/publisher/10.15252/2024-01-01/2024-06-01/0⚠️ 已知陷阱2026-07-27 实测该端点对许多有效出版方前缀会返回{messages:[{status:no articles found}],collection:[]}且伴随HTTP 200——包括上面示例中的 EMBO 前缀。这意味着空collection与确实无匹配无法区分。因此不要将该端点的空结果当作某出版方未发布过 bioRxiv 预印本的证据应视为不确定要回答出版方 X 发布了哪些 bioRxiv 预印本优先使用/pubs/端点并按published_journal分组或改用 Crossref 的filterprefix:10.15252查询。三、响应格式与字段语义/details/的 JSON 响应由messages查询状态与collection预印本数组两部分组成{ messages: [{ status: ok, category: all, interval: 2024-01-01:2024-01-03, funder: all, cursor: 0, count: 30, count_new_papers: 232, total: 360 }], collection: [{ title: Paper title..., authors: Surname, A.; Surname, B., author_corresponding: Full Name, author_corresponding_institution: Institution, doi: 10.1101/2024.01.16.575895, date: 2024-01-20, version: 1, type: new results, license: cc_no, category: cancer biology, jatsxml: https://www.biorxiv.org/content/early/.../source.xml, abstract: Full abstract text..., published: 10.1158/2159-8290.CD-24-0187, server: bioRxiv }] }关键字段语义published若尚未正式发表则为NA已发表则为正式版本 DOI可用于跳转到期刊文章type预印本类型取值包括new results、confirmatory results、contradictory resultsauthors以Surname, A.; Surname, B.格式给出的作者字符串version预印本版本号同一 DOI 可能存在多个版本记录jatsxml全文 JATS XML 的源文件地址。messages块结构并不统一——核对前务必先检查计数类字段只存在于区间查询的响应中。仓库文档在 2026-07-27 实测确认了这一点请求messages[0]包含的字段/details/biorxiv/2024-01-01/2024-01-03/0status、category、interval、funder、cursor、count、count_new_papers、total/details/biorxiv/{doi}/na/json仅status、category——无计数/details/biorxiv/5最近 N 篇仅status、category——无计数/pubs/biorxiv/{interval}/{cursor}status、interval、cursor、count、total因此技能工作流中先计数再对账的步骤在 DOI 查询与最近 N 篇查询上无总可对——此时应改用len(collection)作为检索量并在溯源信息中明确说明该端点不暴露总数。对应到仓库实现paginate.py 中的_rxiv_parse只在total为可解析数字时才设置预期总量否则将expected保留为Nonetests/paper-lookup/test_scripts.py 的test_biorxiv_endpoint_without_counts_reports_no_total正是验证了DOI 查询缺少数计数时不会虚构总数。_common.py中的Reconciliation类也将端点无总数作为已记录状态而非失败expected_total_note字段避免把无总可对误报成数据缺失。total与count_new_papers统计的是不同的东西以2024-01-01:2024-01-03区间为例实测total为360而count_new_papers为232total统计区间内每一个版本记录同一预印本的多版本各算一条count_new_papers统计首次发布的去重预印本数量。分页走到total再按 DOI 去重后数量会接近count_new_papers而非total。因此必须与正确的指标对账并在报告中说明你用的是哪一个。paginate.py 的解析逻辑会在响应含count_new_papers时自动附加一条说明 note提示用户total计的是版本而count_new_papers计的是去重首发的预印本。四、分页最容易静默丢数据的环节分页大小因端点而异2026-07-27 实测确认且这种差异是静默的端点每页记录数cursor步长/details/{server}/{interval}/{cursor}3030/pubs/{server}/{interval}/{cursor}100100cursor是绝对记录偏移量而不是页码。更隐蔽的是步长错误的值也会被正常接受cursor100的/details/查询会返回第 100-129 条记录并伴随HTTP 200。这意味着如果按 100 的步长遍历/details/每 100 条中的第 30-99 条会被悄悄跳过而整个过程看起来完全正常。正确的遍历方式是按响应中实际报告的count作为步长并在cursor count total或collection返回空时停止。源码级验证paginate.py 的_rxiv_parse完整实现了上述规则step取自响应的count字段int(reported)而不是硬编码常量若count与实际返回的记录数不一致会追加一条response reported count{step} but returned {len(records)} records的 note 并以实际返回数为步长next_state int(state) step当next_state total时返回None结束遍历status非ok如no articles found时直接返回空结果并附加server status: ... (HTTP 200 with an empty collection)提示。测试套件 test_scripts.py 对每个关键分支都有覆盖test_biorxiv_steps_by_the_reported_count_not_100L386-L394验证按报告的count30步进明确注释按 100 步进会跳过第 30-99 条test_biorxiv_pubs_steps_by_100L396-L401/pubs/则按 100 步进test_biorxiv_stops_when_the_next_offset_reaches_totalL403-L408偏移量到达总量时结束test_biorxiv_reports_the_count_mismatch_it_falls_back_fromL410-L417count与实返回数不一致时如实上报test_biorxiv_no_articles_found_is_surfacedL419-L426HTTP 200 空 collection 时读取status判断test_biorxiv_url_selects_details_or_pubsL437-L440pubs:前缀路由到/pubs/端点。用内置脚本规避陷阱仓库的 scripts/paginate.py 已为 bioRxiv 实现了上述安全遍历无需手写解析# 按日期区间遍历 bioRxiv 预印本自动按 30 步进并核对总数 python3 scripts/paginate.py --api biorxiv --query 2024-01-01/2024-01-03 # 遍历 /pubs/已发表版本链接端点 python3 scripts/paginate.py --api biorxiv --query pubs:2024-01-01/2024-01-03 # 只打印第一个请求 URL不实际发请求最廉价的方式验证查询格式 python3 scripts/paginate.py --api biorxiv --query 2024-01-01/2024-01-03 --dry-run # 查看每个 API 的查询格式说明 python3 scripts/paginate.py --list-apis脚本关键参数参数默认值说明--page-size100请求页大小bioRxiv 会被响应自身的count修正--max-records1000超过该记录数即停止并将结果标记为部分--max-calls50超过该请求数即停止-o/--outputstdout结果写入 JSON 文件--dry-run—只打印首个 URL-v/--verbose—逐页打印 URL 到 stderr退出码语义脚本用非零退出码标记上游 API 当作成功返回的失败。对 bioRxiv 遍历而言退出码4表示遍历自行结束但数量不足预期总量——有记录丢失必须在得出任何结论前明确报告。而因--max-records/--max-calls上限停止不属于失败退出码为0但会在 stderr 输出 note 要求将结果报告为部分结果。_common.py中的Reconciliation类区分了complete计数一致、stopped_at_limit调用方设界诚实但不完整与短缩记录丢失绝不静默三种结局测试test_bound_is_explained_not_a_failure与test_unexplained_shortfall_is_not_oktest_scripts.py验证了这一区分。五、速率限制与请求规范无文档化速率限制无需认证——但仍应保持合理频率脚本内置delay1.0秒见 paginate.py 的APIS注册表即对 bioRxiv/medRxiv 宿主串行请求每请求间隔 1 秒不要在同一限流宿主上并行请求跨不同开放 API 并行时也要控制在少量请求在途参考 SKILL.md 的请求指南遇到 HTTP 429/503 时短暂等待后重试一次URL 编码curl 中用--data-urlencode配合--get安全传参避免未转义的用户字符串直接拼进 URL。值得注意的是medRxiv 的 API 实际也经由api.biorxiv.org提供见_rxiv_url实现与test_medrxiv_never_uses_the_api_medrxiv_host测试test_scripts.py同一套分页逻辑对两者均适用。六、学科分类列表Categories按日期区间浏览时可用?category参数按分类过滤下划线代替空格。完整分类列表animal-behavior-and-cognition、biochemistry、bioengineering、bioinformatics、biophysics、cancer-biology、cell-biology、clinical-trials、developmental-biology、ecology、epidemiology、evolutionary-biology、genetics、genomics、immunology、microbiology、molecular-biology、neuroscience、paleontology、pathology、pharmacology-and-toxicology、physiology、plant-biology、scientific-communication-and-education、synthetic-biology、systems-biology、zoology七、实战工作流与最佳实践场景 1按主题找生物学期刊预印本bioRxiv 无关键词搜索正确路径是先到 Europe PMCcurl -s --get https://www.ebi.ac.uk/europepmc/webservices/rest/search \ --data-urlencode query(SRC:PPR AND PUBLISHER:bioRxiv AND organoid) \ --data-urlencode formatjsonpageSize10resultTypelite取回结果中的10.1101/...DOI 后再用 bioRxiv API 获取预印本专属元数据如已发表版本链接published字段curl -s https://api.biorxiv.org/details/biorxiv/10.1101/2024.01.16.575895/na/json场景 2追踪预印本的正式发表状态用/pubs/biorxiv/{doi}/na一次查询即可获知预印本是否已正式发表及其 DOI做批量追踪时用/pubs/biorxiv/{interval}/{cursor}按区间遍历并按响应中的count步进100 条/页。场景 3产出可审计的结果按照 SKILL.md 的输出格式结果应先给答案、再给溯源记录查询的端点、参数、标识符与访问日期使人类或其他 Agent 可以完整复现调用对穷举式检索明确报告预期总量 vs 实际检索量、抓取的页数、应用过的本地过滤以及该端点无总数或分页提前停止等警告。绝不能把数据库返回空静默当作该论文不存在。八、延伸阅读技能总览与数据库选择指南skills/paper-lookup/SKILL.md本文配套的分页实现skills/paper-lookup/scripts/paginate.py公共辅助模块脱敏、对账、输入防护skills/paper-lookup/scripts/_common.py离线测试套件全部 fixture 为 2026-07-27 真实响应裁剪tests/paper-lookup/test_scripts.py配套参考文档同属 paper-lookup 技能medrxiv.md、europepmc.md、arxiv.md结语bioRxiv API 结构简单、无需认证但无关键词搜索分页大小因端点而异HTTP 200 掩盖空结果与跳页这三重特性决定了它是一把用起来容易、用对不易的检索工具。把分页步长交给响应自身报告的count、把空结果与总数缺失当作需要明确上报的状态并善用仓库中已验证的 paginate.py就能让每次预印本检索都可复现、可审计、可信任。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考