CORE API 接入指南：用 scientific-agent-skills 的 paper-lookup 技能解锁开放获取全文检索

CORE API 接入指南：用 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

CORE 是全球最大的开放获取研究论文聚合平台之一，本指南以 skills/paper-lookup/references/core.md 为核心，系统讲解 CORE API v3 的接入认证、Token 计费模型、查询语言、全部分页与全文下载端点，并结合仓库内 paper-lookup 技能的源码脚本与测试用例，给出可直接运行、可追溯、可审计的完整检索方案。读完本文，你将掌握在 CORE 上完成"查元数据 → 搜全文 → 取 PDF → 翻页到万级结果"全链路的能力，并理解如何与 PubMed、Unpaywall 等其余十个文献数据库协同，输出带完整溯源信息的检索报告。

CORE 与 paper-lookup：全文检索在技能中的定位

CORE 聚合了全球 15,000+ 个开放获取仓库的研究成果，为37M+ 篇文章提供全文，并为368M+ 篇论文提供元数据。在整个 paper-lookup 技能（SKILL.md）覆盖的 11 个学术文献 API 中，CORE 是"全文检索"这条主线的核心选择：

• 任意学科领域全文获取（Full text (any field)）时，CORE 是首选数据库；
• 生物医学文献的全文补充（Also consider列中与 PMC、Europe PMC 并列）；
• 开放获取 PDF 兜底（与 Unpaywall、PMC 互补）。

技能的选择指南给出的路由逻辑是：先用正确的数据库找到论文，再用 CORE 等全文库把内容取回来。例如"找到 CRISPR 相关论文并拿到 PDF"这类复合需求，就要求先在 PubMed、OpenAlex 等库中检索候选，再按 DOI 到 CORE 解析开放获取全文——这正是 CORE 在整个技能中的价值所在。

接入准备：Base URL、认证与 API Key

Base URL 与一个必须记住的坑

CORE API v3 的统一入口为：

https://api.core.ac.uk/v3

重要提示：GET 搜索路径要求末尾斜杠。例如/v3/search/works/是合法的，而/v3/search/works（无斜杠）会失败。这是 CORE 区别于大多数 REST API 的显著特性，也是接入时最常见的第一个报错来源。

两种认证方式

CORE 支持两种等价的身份传递方式：

在 paper-lookup 技能中，这两种方式都有对应的实战约束。技能要求通过curl发起调用，且必须使用请求头方式传递 CORE 密钥：

curl -s -H "Authorization: Bearer $CORE_API_KEY" \ "https://api.core.ac.uk/v3/search/works/?q=CRISPR&limit=10"

密钥本身通过环境变量CORE_API_KEY注入。按 SKILL.md 的约定，若环境变量不存在且工作目录存在.env，只读取NCBI_API_KEY、S2_API_KEY、CORE_API_KEY、OPENALEX_API_KEY这四个变量，绝不整文件加载——.env中通常还混有与文献检索无关的其他机密。

无认证时的能力边界

未认证状态下，基础的元数据查询仍然可用，但全文不可获取：请求全文会返回Not available for public API users。因此任何以"拿全文/下载 PDF"为目标的调用，都必须先完成 CORE 账号注册（在 CORE 官方 API 服务页面申请）并配置CORE_API_KEY。

速率限制与 Token 计费模型

CORE 不是按请求数而是按Token计费。不同用户类型的额度如下：

单次操作的成本差异明显：

• 简单查询（simple queries）消耗 1 Token：一次普通搜索、一次按 ID 取记录都属此类；
• 下载与 scroll 分页消耗 3–5 Token：全文下载、TEI 获取以及超过 10,000 条结果的滚动翻页成本显著更高。

这直接决定了技能层的工作方式。paper-lookup 在 paginate.py 中把单次检索的默认上限定为1,000 条记录 / 50 次调用（DEFAULT_MAX_RECORDS = 1000、DEFAULT_MAX_CALLS = 50），其设计意图正是"先计数、再分页、量入为出"：对 CORE 这类按 Token 计费的服务，超预算的连续翻页代价是真实且可量化的。技能还明确指出，对真正的大批量需求，应改用 CORE 官方提供的快照/转储（snapshot/dump），而不是用实时 API 慢慢翻——这既是成本考虑，也是稳定性考虑。

核心端点详解

1. 搜索 works：全库文献检索

最常用的检索端点为工作（works）集合：

GET /v3/search/works/?q={query}&limit={n}&offset={n}

实际示例：

https://api.core.ac.uk/v3/search/works/?q=CRISPR+gene+therapy&limit=10

对于查询表达式较复杂的场景，CORE 提供POST 替代形式，把参数放进 JSON body：

POST /v3/search/works Content-Type: application/json {"q": "machine learning", "limit": 10, "offset": 0}

这与技能的通用建议一致：复杂检索用 POST + JSON body 更可控，也便于程序化生成查询。

2. CORE 查询语言：从关键词到精确表达式

q参数不是简单关键词，而是一套完整的查询语言，支持字段限定、布尔运算、范围与存在性判断：

可检索字段覆盖了一篇论文的完整描述面：

abstract, arxivId, authors, contributors, createdDate, dataProviders, depositedDate, documentType, doi, fullText, id, language, license, oai, title, yearPublished

值得注意的组合用法：_exists_:fullText可以把检索范围收敛到"确实有全文的论文"，配合CORE_API_KEY使用，正好发挥 CORE 相比纯元数据索引（如 Crossref）的核心差异——全文级检索。

3. 按 ID 获取 work 与 output

CORE 的 Work ID 是整数标识，直接用于单条记录获取：

GET /v3/works/{id}

例如GET /v3/works/267312。与之对应，outputs 集合也有独立端点：

GET /v3/outputs/{id}

区分这两个概念有助于理解 CORE 的数据模型：work 是论文的逻辑实体（含标题、作者、摘要、DOI 等元数据），output 是其对应的存储产出（含下载入口）。拿到 work 后，通常还需要再取一次 output 才能定位到可下载的文件。

4. 下载全文与 TEI XML

全文下载端点返回二进制 PDF：

GET /v3/outputs/{id}/download

该端点要求认证（Bearer Header 或api_key查询参数），未认证会得到Not available for public API users。

需要结构化文本时，可用 TEI（Text Encoding Initiative）XML 格式：

GET /v3/works/tei/{id}

TEI XML 是开放获取全文交换的常用结构格式，适合交给下游解析器做章节抽取。技能的输出规范（见 SKILL.md）特别提醒：大体积全文（PMC、Europe PMC、CORE）应保存到本地文件并报告路径，而不是把整段文本灌回对话上下文——这与 CORE 全文动辄数百 KB 到数 MB 的体量是匹配的。

5. 搜索 outputs 与 DOI 检索

outputs 集合同样支持全文检索：

GET /v3/search/outputs/?q={query}&limit={n}&offset={n}

最实用的用法是按 DOI 精确定位：

q=doi:10.1038/nature12373

由于 DOI 是全球通用的文献标识符，这条查询是把 CORE 接入多库工作流的关键粘合点：在 PubMed/OpenAlex 中找到候选论文后，用其 DOI 到 CORE 检索输出并下载全文。

响应格式

搜索响应

CORE 的搜索响应结构统一，顶层字段直接服务于分页与计数：

{ "totalHits": 2281337, "limit": 10, "offset": 0, "scrollId": null, "results": [...] }

totalHits可用于"先计数再决定是否穷举"，这与技能的可复现检索纪律一致：API 暴露总数时先取总数，再据此决定分页策略与预算。

work 对象核心字段

单条 work 的典型结构：

{ "id": 8848131, "title": "Attention Is All You Need", "authors": [{"name": "Ashish Vaswani"}, ...], "abstract": "The dominant sequence...", "doi": "10.48550/arXiv.1706.03762", "arxivId": "1706.03762", "yearPublished": 2017, "downloadUrl": "https://core.ac.uk/download/...", "fullText": "Full text content (when authenticated)...", "language": {"code": "en", "name": "English"}, "documentType": "research", "citationCount": 145678, "dataProviders": [{"name": "arXiv"}], "links": [{"type": "download", "url": "..."}] }

要点：fullText字段仅在认证后返回；downloadUrl与links提供了可直接下载的入口。对下游来说，id是回查的稳定主键，doi、arxivId是与外部库交叉引用的桥梁，citationCount可用于排序候选文献。

分页：offset 与 scroll 的选择

CORE 提供两级分页能力：

• 标准分页：offset+limit。limit最大 100，标准分页最深支持到10,000 条结果。适合绝大多数检索场景——技能的建议是"针对性查询第一页通常就够"。
• Scroll 分页：设置scroll=true。响应中会返回scrollId，将其带入后续请求即可在 10,000 条之外继续翻页。代价是每次 scroll 请求消耗更多 Token（3–5 Token）。

两者的取舍很清晰：标准分页便宜但浅，scroll 贵但深。在预算约束下（参考 paginate.py 的默认上限），穷举式检索应先看totalHits评估规模，规模超限就应改走官方快照，而不是无节制地 scroll。

错误处理与"200 即成功"陷阱

CORE 在高负载下可能返回部分分片失败（partial shard failure）消息，这类错误是瞬态的，短暂等待后重试即可。

但 skill 层面的警示更深刻。paper-lookup 技能的核心信条是：这 11 个 API 都会用 HTTP 200 返回失败。虽然 CORE 的高负载错误形态与 PMC 的"无<body>的 eFetch"、arXiv 的Error条目、Europe PMC 的 200 body 内errCode不同，但同一个应对原则贯穿所有数据库：不要只看状态码，要校验响应体的形状。CORE 场景下的具体表现包括：

• 未认证请求全文时返回的Not available for public API users——这在语义上是一种"软失败"，容易被当成正常响应；
• 分页提前终止、总数与实取数不一致等，都可能在 HTTP 200 的掩盖下发生。

技能在 tests/paper-lookup/test_scripts.py 中固化了这套失败哲学，用非零退出码把"静默失败"变成"显式信号"：jats_to_text.py无<body>退出 2、arxiv_atom.py遇 Error 退出 3、paginate.py翻页不足退出 4。对 CORE 使用者而言，对应的纪律是：全文取不到时如实报告"该文在 CORE 无开放获取全文"，而不是用元数据冒充全文。

实战：在 paper-lookup 技能中组合使用 CORE

组合检索路径

把 CORE 放回 11 库的工作流里，典型组合如下：

完整的 CORE 调用链示例

一个"查元数据 → 找全文 → 下载"的完整链路：

# 1) 带认证的全文检索（注意 /works/ 末尾斜杠） curl -s -H "Authorization: Bearer $CORE_API_KEY" \ "https://api.core.ac.uk/v3/search/works/?q=_exists_:fullText AND title:%22AlphaFold%22&limit=10" # 2) 按 DOI 在 outputs 中定位 curl -s -H "Authorization: Bearer $CORE_API_KEY" \ "https://api.core.ac.uk/v3/search/outputs/?q=doi:10.1038/nature12373" # 3) 下载全文 PDF 到本地文件 curl -s -H "Authorization: Bearer $CORE_API_KEY" \ "https://api.core.ac.uk/v3/outputs/{id}/download" -o paper.pdf

注意第 1 条中 URL 需要--data-urlencode级别的转义：引号、斜杠、括号都要按 URL 编码规则处理。CORE 的Authorization请求头方式让密钥不进入 URL，从根源上避免了凭据泄露到日志与溯源输出中。

溯源与脱敏：让结果可重复

技能对可重复检索的要求是：回答的每个结论都要附上"端点 + 参数 + 访问日期 + 标识符"，让人类或其他 Agent 可以原样复现。这正是 core.md 里所有端点、参数表存在的意义——文档本身就是可追溯性的载体。

有一个细节直接关系到 CORE 的安全性：技能支持api_key查询参数认证，而一旦采用查询参数，你请求过的 URL 本身就是凭据。仓库中的 _common.py 专门实现了redact_url()，对api_key、apikey、key、email、mailto、tool等参数值统一替换为REDACTED占位符再写入溯源输出，且参数名保留以保证调用可复现。如果你手工记录 CORE 调用 URL，务必做同样的脱敏处理。相关行为已由 test_scripts.py 的RedactionTests固化验证。

输出规范：先给答案，再给证据

综合 CORE 与其他库的结果后，推荐按技能规定的结构输出：

## Retrieval Summary - Query: <用户需求> - Scope: targeted lookup | exhaustive retrieval - Databases queried: CORE (search works + download), PubMed (esearch) - Access date: <日期> ## Results ### CORE <论文：标题、作者、年份、DOI、全文可用性> ## Provenance - Endpoints & parameters: <可复现的端点与参数> - Count reconciliation: <totalHits 与实取数对比，翻页页数> - Warnings: <无全文、分页不完整、缺少密钥等>

对 CORE 返回的大体积全文，保存到本地文件并报告文件路径，而不是把数 MB 文本灌入响应——这既是输出规范，也是对 Token 与上下文资源的双重尊重。

小结：CORE 接入的关键清单

最后，把本指南压缩为一张可执行的核对清单：

1. Base URL使用https://api.core.ac.uk/v3，GET 搜索路径必须带末尾斜杠；
2. 认证优先用Authorization: Bearer $CORE_API_KEY请求头；全文与下载必须认证；
3. 预算简单查询 1 Token、下载与 scroll 3–5 Token，参照用户类型额度规划调用次数；
4. 查询语言善用字段限定、布尔与_exists_:fullText，把检索收敛到有全文的论文；
5. 分页10,000 条内用offset/limit，超出用scroll（带scrollId）并接受更高 Token 成本，批量需求走官方快照；
6. 失败识别高负载时部分分片失败属瞬态，稍候重试；同时警惕"未认证全文不可用"这类 200 软失败；
7. 可复现每次调用记录端点、参数、访问日期，URL 中含密钥参数时先脱敏再入溯源；
8. 组合按论文定位、OA 解析、全文获取的分工，把 CORE 与 PubMed、Unpaywall、Europe PMC 等库编排为完整链路。

【免费下载链接】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