企业官网建设流程全解析

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 获取预印本专属元数据（如已发表版本链接）。

基本信息

二、核心端点详解

bioRxiv API 提供四组关键端点，覆盖预印本的浏览、定位、发表状态追踪与出版方检索。

1. 按日期区间浏览（Content Detail）

这是检索预印本列表的主入口：

GET /details/biorxiv/{interval}/{cursor}/{format}

路径参数：

可选查询参数：?category=neuroscience按学科分类过滤，分类名中的空格用下划线（如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?category=neuroscience

2. 按 DOI 精确查询（Content Detail）

通过预印本 DOI 精确获取单篇元数据：

GET /details/biorxiv/{doi}/na/{format}

其中na是固定的占位符。

示例：

https://api.biorxiv.org/details/biorxiv/10.1101/2024.01.16.575895/na/json

3. 已发表文章链接（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 的filter=prefix: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 results；
• authors：以Surname, A.; Surname, B.格式给出的作者字符串；
• version：预印本版本号，同一 DOI 可能存在多个版本记录；
• jatsxml：全文 JATS XML 的源文件地址。

messages块结构并不统一——核对前务必先检查

计数类字段只存在于区间查询的响应中。仓库文档在 2026-07-27 实测确认了这一点：

因此，技能工作流中"先计数再对账"的步骤在 DOI 查询与最近 N 篇查询上无总可对——此时应改用len(collection)作为检索量，并在溯源信息中明确说明"该端点不暴露总数"。

对应到仓库实现，paginate.py 中的_rxiv_parse只在total为可解析数字时才设置预期总量，否则将expected保留为None；tests/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为232：

• total统计区间内每一个版本记录（同一预印本的多版本各算一条）；
• count_new_papers统计首次发布的去重预印本数量。

分页走到total再按 DOI 去重后，数量会接近count_new_papers而非total。因此必须与正确的指标对账，并在报告中说明你用的是哪一个。paginate.py 的解析逻辑会在响应含count_new_papers时自动附加一条说明 note，提示用户total计的是版本而count_new_papers计的是去重首发的预印本。

四、分页：最容易静默丢数据的环节

分页大小因端点而异（2026-07-27 实测确认，且这种差异是"静默"的）：

cursor是绝对记录偏移量，而不是页码。更隐蔽的是，步长错误的值也会被正常接受：cursor=100的/details/查询会返回第 100-129 条记录，并伴随HTTP 200。这意味着如果按 100 的步长遍历/details/，每 100 条中的第 30-99 条会被悄悄跳过，而整个过程看起来完全正常。

正确的遍历方式是：按响应中实际报告的count作为步长，并在cursor + count >= total或collection返回空时停止。

源码级验证

paginate.py 的_rxiv_parse完整实现了上述规则：

1. step取自响应的count字段（int(reported)），而不是硬编码常量；
2. 若count与实际返回的记录数不一致，会追加一条"response reported count={step} but returned {len(records)} records"的 note 并以实际返回数为步长；
3. next_state = int(state) + step，当next_state >= total时返回None结束遍历；
4. status非ok（如no articles found）时直接返回空结果并附加"server status: ... (HTTP 200 with an empty collection)"提示。

测试套件 test_scripts.py 对每个关键分支都有覆盖：

• test_biorxiv_steps_by_the_reported_count_not_100（L386-L394）：验证按报告的count=30步进，明确注释"按 100 步进会跳过第 30-99 条"；
• test_biorxiv_pubs_steps_by_100（L396-L401）：/pubs/则按 100 步进；
• test_biorxiv_stops_when_the_next_offset_reaches_total（L403-L408）：偏移量到达总量时结束；
• test_biorxiv_reports_the_count_mismatch_it_falls_back_from（L410-L417）：count与实返回数不一致时如实上报；
• test_biorxiv_no_articles_found_is_surfaced（L419-L426）：HTTP 200 空 collection 时读取status判断；
• test_biorxiv_url_selects_details_or_pubs（L437-L440）：pubs:前缀路由到/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

脚本关键参数：

退出码语义：脚本用非零退出码标记"上游 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_ok（test_scripts.py）验证了这一区分。

五、速率限制与请求规范

• 无文档化速率限制，无需认证——但仍应保持合理频率；
• 脚本内置delay=1.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 PMC：

curl -s --get "https://www.ebi.ac.uk/europepmc/webservices/rest/search" \ --data-urlencode 'query=(SRC:"PPR" AND PUBLISHER:"bioRxiv" AND "organoid")' \ --data-urlencode 'format=json&pageSize=10&resultType=lite'

取回结果中的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