---
title: "W07 工具说明：文献核验接口"
---

# 文献核验接口

## 项目介绍

**它是什么。**Crossref、Semantic Scholar、OpenAlex、arXiv 这几个公开学术数据库提供免费的 HTTP 接口（HTTP 接口：程序通过网址发请求、拿回结构化数据的通道），智能体按 DOI 或题名去查，就能判断一条参考文献是否存在、元数据对不对、能不能读到摘要或全文。它们解决的问题是“智能体写的参考文献可能是编的”。这些是在线服务，不是可安装的软件，没有版本号：

| 服务 | 提供方与性质 | 开始服务 | 国内网络 |
| --- | --- | --- | --- |
| Crossref | 非营利会员组织，出版商在这里登记 DOI；REST API 免费 | 2000 年成立 | 能连 |
| Semantic Scholar | 艾伦人工智能研究所（Ai2）的学术搜索引擎；大多数接口免 Key | 2015 年 | 能连 |
| OpenAlex | 非营利组织 OurResearch 运营的开放学术目录，数据以 CC0 发布；2026 年起按用量计费 | 2022 年 1 月 | 能连 |
| arXiv | 康奈尔大学运营的预印本库 | 1991 年 | 能连 |
| Unpaywall | OurResearch 运营，查开放全文链接 | — | 连不上，不用 |

“开始服务”一栏来自公开资料。

社区对照 paper-search-mcp：GitHub 组织 openags 开发，MIT 许可；PyPI 首个版本 0.1.0 发布于 2025-04-06，最新 0.1.4（2026-07-02）；GitHub 约 2,860 星（2026-10 核查）。

接入方式：**HTTP 接口**（任何能发网络请求的智能体都能直接调）。本课通过 **Skill**（一份写给智能体的说明书，告诉它某类任务按什么步骤做）把查询步骤和判定规则交给智能体；paper-search-mcp 是 **MCP**（把外部能力包装成工具、供智能体调用的标准接口）方式的对照。

**核心能力：**

- 判断一个 DOI 是否存在；
- 取回题名、作者、年份、期刊、卷期页码，对照清单核验；
- 按题名＋作者找回正确 DOI，分清工作论文版和期刊发表版；
- 读摘要，查合法的开放全文链接。

**在同类工具里的位置：**Google Scholar 没有官方 API，国内网络也连不上 Google；知网、万方面向中文文献，没有免费公开接口。这几个库免费、可编程访问，适合让智能体批量核对英文文献。中文文献查不到不等于假，要另行核对。

**国内网络：**Crossref、Semantic Scholar、OpenAlex、arXiv、NBER 都能连；查开放全文的 Unpaywall 在国内网络下连不上，不要用。开放全文改看 OpenAlex 和 Semantic Scholar 返回的链接。

## 官方链接表

核查日期：2026-10。这些是在线服务，没有版本号，下表“当前限额”以官方页面为准。

| 接口 | 官网 | API 文档 | 要不要 key／邮箱 | 当前限额（官方） |
| --- | --- | --- | --- | --- |
| Crossref | https://www.crossref.org | https://api.crossref.org （Swagger）；使用建议 https://www.crossref.org/documentation/retrieve-metadata/rest-api/tips-for-using-the-crossref-rest-api/ | 不要 key；建议带 `mailto=邮箱` 进入 polite 池 | 公共池单条记录 5 次/秒、并发 1；polite 池 10 次/秒、并发 3；返回列表的检索请求另有更低上限（官方社区公告：公共 1 次/秒、polite 3 次/秒） |
| Semantic Scholar | https://www.semanticscholar.org/product/api | https://api.semanticscholar.org/api-docs/ | 大多数接口免 key；key 免费申请（邮件发放） | 免 key 用户**共用**每秒 1000 次的总池，高峰期会被进一步限流；个人 key 起步 1 次/秒 |
| OpenAlex | https://openalex.org | https://developers.openalex.org ；计费 https://developers.openalex.org/access/example-costs | 可不带 key；个人免费 key 在 https://openalex.org/settings/api-key 申请 | 2026 年起按用量计费：**匿名请求按 IP 共用每天 0.10 美元**，个人免费 key 每天 1 美元（UTC 零点重置）。按 DOI 取单条免费；列表＋过滤每千次 0.10 美元；检索每千次 1 美元。速率：无 key 10 次/秒，免费 key 30 次/秒 |
| Unpaywall（**国内网络连不上**，不用） | https://unpaywall.org | https://unpaywall.org/products/api | 不要 key；每个请求必须带 `email=` 参数 | — |
| arXiv | https://arxiv.org | https://info.arxiv.org/help/api/ ；使用条款 https://info.arxiv.org/help/api/tou.html | 不要 key | 每 3 秒不超过 1 次请求，同一时间只开一个连接；限额针对你控制的全部机器合计 |

NBER 一句带过：NBER 工作论文的 DOI 是 `10.3386/w编号`（例如 `10.3386/w23470`），Crossref 和 OpenAlex 都能查到。NBER 官网在国内网络下能打开；网站另有免 key 的 JSON 检索接口，但没有官方文档，用不了时改查 Crossref 或 OpenAlex。

OpenAlex 计费：匿名请求的返回里 `meta.notice` 写明“同一 IP 共用每天 0.10 美元”；用 `filter=title.search:...` 按题名查一次，返回里的 `meta.cost_usd` 是 0.001，也就是匿名额度约够 100 次题名查询。**学校机房或宿舍同一出口 IP 下所有人共用这 0.10 美元**，一个班同时跑很快就会 429（请求过多）。按 DOI 取单条不计费。

## 能做什么、不能做什么

能做：

- 判断一个 DOI 是否存在（Crossref、OpenAlex 返回 404 即“该 DOI 未注册”）。
- 取回权威元数据：题名、作者、年份、期刊、卷期页码，对照你清单里写的是否一致。
- 按题名＋作者找回正确 DOI，发现“工作论文版”和“期刊发表版”。
- 读摘要（Crossref 部分记录带摘要，Semantic Scholar 常有 `abstract`），查开放获取全文链接（Semantic Scholar 的 `openAccessPdf`、OpenAlex 的 `open_access.oa_url`）。

不能做：

- 不能替你判断“这篇文献是否支持你文中那句话”。接口只给元数据和摘要，原句核验要读摘要或全文，再由人判断。
- 查不到不等于假。中文期刊（知网、万方收录的大部分）、学位论文、政府报告、书的章节，常常不在这些库里或元数据不全。
- 不下载付费全文；OpenAlex、Semantic Scholar 只给合法开放的版本链接，常是工作论文版而不是期刊排版版。

适合本课的任务：核报告或论文的参考文献清单；让智能体写文献综述时附带自查；检查 AI 生成的 BibTeX。

## 两个 Skill 与一个 MCP 对照

| 名称 | 是什么 | 用来做什么 | 使用时注意 |
| --- | --- | --- | --- |
| academic-paper-search | 纯说明书型 Skill：一份 SKILL.md 写清“按什么信息查哪个库”的决策树和 curl 示例 | 按 DOI 取元数据、按题名检索、查开放全文，覆盖 arXiv、NBER、SSRN、Crossref、OpenAlex、Unpaywall、Semantic Scholar | Unpaywall 国内网络连不上，查开放全文一步改用 OpenAlex `open_access.oa_url` 与 Semantic Scholar `openAccessPdf`；SSRN 连不上时改用 Crossref 或 OpenAlex 查同一篇；文末限额表与上面的官方限额不同时，以上表为准；curl 管道写法在 Windows PowerShell 下要改 |
| bib-citation-validator | 带 Python 脚本的 Skill：解析 `.bib` 和 `.tex`，查本地 Zotero、Crossref（DOI 与题名）、OpenAlex（题名），按固定阈值给 PASS／WARN／FAIL | 批量核一整份 BibTeX，输出 `report.md`、`report.csv`、`report.json` | `--tex` 和 `--bib` 都是必填，没有 LaTeX 稿的同学用不了；默认 Zotero 路径是 `~/Zotero/zotero.sqlite`，没有 Zotero 也能跑（该项记为未找到）；依赖 `requests`、`rapidfuzz`；不查 Semantic Scholar，也不核验论断；部分网络异常会被脚本当成“没找到”，表现为 FAIL 或 UNCHECKED，FAIL 要人工复查 |
| paper-search-mcp（社区，https://github.com/openags/paper-search-mcp ，MIT） | MCP 服务器，把 20 多个来源（含 Crossref、OpenAlex、Semantic Scholar、Unpaywall）包成工具 | 跨库检索、按 DOI 查、开放全文下载 | Python ≥ 3.10，用 `uvx paper-search-mcp` 启动，包从 PyPI 下载，要指定清华镜像；Unpaywall 国内连不上，不配 `PAPER_SEARCH_MCP_UNPAYWALL_EMAIL`；20 多个来源里不少在境外，某个来源连不上就换 Crossref、OpenAlex；仓库带可选 Sci-Hub 回退，默认关闭，本课不启用 |

选择建议：本课用两个 Skill。它们把“查哪几个库、怎样判定”写成规则，你能读懂每一步；MCP 对照用于说明同一件事也可以做成工具，但工具内部逻辑你看不到，判定规则还得自己写进提示词。

## 安装与配置

前置依赖：

- 接口本身不用安装。智能体要能发网络请求：Windows 11 自带 `curl.exe`（在 PowerShell 里要写 `curl.exe`，单写 `curl` 会调用 PowerShell 的 `Invoke-WebRequest` 别名）；或装 Python 3.11 并 `python -m pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple`。Python 安装包从国内镜像下载（npmmirror https://registry.npmmirror.com/-/binary/python/ 或华为云 https://repo.huaweicloud.com/python/ ），步骤见 [Python 读写 Excel](https://ai.lingnan.top/materials/2026-autumn/w07/tool-09-python-excel) 的 Python 安装部分。
- 用 bib-citation-validator 还要装 `rapidfuzz`，同样加清华镜像（连不上换阿里云 https://mirrors.aliyun.com/pypi/simple/ ）。
- 用 paper-search-mcp 还要装 uv（一个 Python 包管理器）。官方安装说明见 https://docs.astral.sh/uv/getting-started/installation ，安装脚本会从 GitHub release 下载，GitHub 在国内访问慢、不稳定；国内网络下建议用 `python -m pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple`。

### 1. 首选：交给智能体装

**Claude Code 端，安装两个 Skill（项目作用域）**。把课程提供的两个 Skill 文件夹放到电脑上某处后，复制下面这段给 Claude Code：

```txt
请帮我把文献核验用的两个 Skill 装到当前项目里，并配好运行环境。

要装的东西：
1. academic-paper-search 文件夹（我放在：<填你的路径>）
2. bib-citation-validator 文件夹（我放在：<填你的路径>）

要求：
- 两个文件夹都复制到当前项目的 .claude/skills/ 下，不要放到全局目录。
- 检查电脑上有没有 Python 3.10 以上版本；有的话用它安装 requests 和 rapidfuzz 两个包，命令用 python -m pip install requests rapidfuzz -i https://pypi.tuna.tsinghua.edu.cn/simple（清华镜像连不上换 https://mirrors.aliyun.com/pypi/simple/ ，不要用 pypi.org 官方源）。不要做其他全局改动；如果需要装 Python 本身，先停下来问我。
- 打开 bib-citation-validator/scripts/api_client.py，如果里面写死了某个邮箱，改成读取环境变量 CROSSREF_MAILTO，读不到就不带邮箱。把改了哪几行告诉我。
- 打开 academic-paper-search/SKILL.md，把文末的限额表改成：Crossref 公共池 5 次/秒、polite 池 10 次/秒；OpenAlex 匿名每 IP 每天 0.10 美元、个人免费 key 每天 1 美元；Semantic Scholar 免 key 共用池、可能 429；arXiv 每 3 秒 1 次。再把查开放全文的步骤从 Unpaywall 改成 OpenAlex 的 open_access.oa_url 和 Semantic Scholar 的 openAccessPdf，注明 Unpaywall 在国内网络连不上。
- Windows 下所有 curl 命令写成 curl.exe，URL 用英文双引号包起来。
- 装完自查：
  a) 用 curl.exe 请求 https://api.crossref.org/works/10.1257/aer.20171330 ，确认返回的 title 是 Measuring and Bounding Experimenter Demand；
  b) 请求 https://api.crossref.org/works/10.1257/aer.20231999 ，确认返回 404；
  c) 运行 python bib-citation-validator/scripts/validate_refs.py --help 能看到帮助。
- 需要我填邮箱、申请 key、或者要从网上下载安装包时，停下来问我。
```

它装的过程中会请求的权限：

| 请求 | 处理 |
| --- | --- |
| 读写当前项目下的 `.claude/skills/` | 允许 |
| 运行 `python`、`pip install requests rapidfuzz` | 允许；看清包名只有这两个，地址是清华或阿里云镜像 |
| 运行 `curl.exe` 访问 api.crossref.org、api.openalex.org、api.semanticscholar.org、export.arxiv.org | 允许 |
| 修改 `api_client.py` | 允许，改完看它报告的行号 |
| 下载并安装 Python、改系统 PATH、写用户级 `~/.claude/` | 看清再点；装 Python 建议自己从国内镜像下载安装包（见 [Python 读写 Excel](https://ai.lingnan.top/materials/2026-autumn/w07/tool-09-python-excel)） |
| 访问上面四个接口域名和 PyPI 镜像以外的网站、要你输入密码 | 拒绝，问清原因 |

**Claude Code 端，MCP 对照（可选，用户作用域）**：

```txt
请帮我在 Claude Code 里添加社区的 paper-search-mcp 作为对照，只做配置，不要改别的。

- 仓库：https://github.com/openags/paper-search-mcp ，包名 paper-search-mcp
- 先检查 uv 是否已安装（运行 uv --version）。没装就停下来告诉我，我自己用 python -m pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple 装（官方安装脚本从 GitHub 下载，国内访问慢、不稳定，只作备选）。
- 用 claude mcp add 添加，作用域 user，启动命令是 uvx paper-search-mcp；加环境变量 UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple ，让 uvx 从清华镜像下载包。
- 不配置 Unpaywall（国内网络连不上），不要设 PAPER_SEARCH_MCP_UNPAYWALL_EMAIL。
- 不要启用任何 Sci-Hub 相关选项，不要配置付费来源的 key。
- 装完运行 claude mcp list，确认 paper-search 状态为 connected；再告诉我重开 Claude Code 后在 /mcp 里应看到什么。
```

**WorkBuddy 端**（用 WorkBuddy 的“技能”和“自定义连接器”两个入口）：

```txt
请帮我在 WorkBuddy 里配置文献核验。

1. 技能：把 academic-paper-search 和 bib-citation-validator 两个文件夹放进当前工作目录的 .workbuddy/skills/ 下（如果 WorkBuddy 要求从“技能 → 添加技能 → 上传”导入，就告诉我要点哪里，我自己点）。
2. 检查 Python 3.10 以上和 requests、rapidfuzz 是否可用，缺了先问我再装，装时加 -i https://pypi.tuna.tsinghua.edu.cn/simple 。
3. 装完用 curl.exe 请求 https://api.crossref.org/works/10.1257/aer.20171330 ，确认能拿到题名。
遇到需要填邮箱、key 或授权弹窗时停下来问我。
```

MCP 对照放 WorkBuddy 的“自定义连接器”：填 `command` 为 `uvx`（找不到就填 `uvx.exe` 的绝对路径，JSON 里反斜杠写成 `\\`），`args` 为 `["paper-search-mcp"]`，`env` 里填 `UV_DEFAULT_INDEX` 为清华镜像地址。不要混用 WSL 路径和 Windows 原生路径。

`UV_DEFAULT_INDEX` 是 uv 官方文档列出的环境变量，用来替换默认的 PyPI 地址。如果设了之后 uvx 启动仍然很慢、下载失败，就先不用 MCP 对照，用两个 Skill。

### 2. 要你亲手做的部分

- **邮箱**：Crossref 的 `mailto` 填自己的学校邮箱。智能体不该替你编邮箱。
- **OpenAlex 个人免费 key**（推荐）：到 https://openalex.org/signup 注册，在 Settings → API key 复制。OpenAlex 也允许智能体用你的邮箱代申请，但激活链接发到你的邮箱，要你本人点；不要让智能体用别人的邮箱。
- **Semantic Scholar key**（可选）：在 https://www.semanticscholar.org/product/api#api-key-form 申请，邮件发放。不申请也能用；免 key 共用池高峰期可能连续返回 429。
- **把 key 写进环境变量**（Windows PowerShell，写入当前用户，重开终端后生效）：

```powershell
setx OPENALEX_API_KEY "你的key"
setx S2_API_KEY "你的key"
setx CROSSREF_MAILTO "你的学校邮箱"
```

- **重启客户端**：设完环境变量，关掉 Claude Code 或 WorkBuddy 再打开，它才读得到。
- key 不进截图和共享文件：录屏前把终端里显示过 key 的窗口关掉；不要把 key 写进 `.bib`、`.md`、Skill 文件，也不要发到聊天群里；项目要上 GitHub 时，含 key 的 `.env` 加进 `.gitignore`。

### 3. 参考：手动命令

**Windows 11（PowerShell）**，按 DOI 查：

```powershell
# Crossref：元数据
curl.exe -s "https://api.crossref.org/works/10.1257/aer.20171330?mailto=you@mail2.sysu.edu.cn"

# Semantic Scholar：题名、年份、作者、摘要、开放全文
curl.exe -s "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1257/aer.20171330?fields=title,year,authors,venue,abstract,openAccessPdf,externalIds"

# OpenAlex：按 DOI 取单条（不计费）；有 key 时末尾加 &api_key=你的key
curl.exe -s "https://api.openalex.org/works/doi:10.1257/aer.20171330?select=id,doi,title,publication_year,authorships,open_access"

# arXiv：按编号
curl.exe -s "https://export.arxiv.org/api/query?id_list=1706.03762"
```

按题名＋作者查（URL 里的空格写成 `%20`，整个 URL 用双引号包住，否则 PowerShell 会把 `&` 当成命令分隔符）：

```powershell
# Crossref：题名放 query.bibliographic，作者放 query.author，只取前 3 条
curl.exe -s "https://api.crossref.org/works?query.bibliographic=Measuring%20and%20Bounding%20Experimenter%20Demand&query.author=de%20Quidt&rows=3&mailto=you@mail2.sysu.edu.cn"

# Semantic Scholar：按题名取最佳匹配
curl.exe -s "https://api.semanticscholar.org/graph/v1/paper/search/match?query=Measuring%20and%20Bounding%20Experimenter%20Demand&fields=title,year,authors,externalIds"

# OpenAlex：题名过滤（每次约 0.001 美元）
curl.exe -s "https://api.openalex.org/works?filter=title.search:measuring%20and%20bounding%20experimenter%20demand&per_page=3&select=id,doi,title,publication_year"

# arXiv：题名＋作者，两次请求之间隔 3 秒以上
curl.exe -s "https://export.arxiv.org/api/query?search_query=ti:%22attention%20is%20all%20you%20need%22+AND+au:vaswani&max_results=3"
```

查开放全文不用 Unpaywall（国内网络连不上）：看上面 OpenAlex 返回的 `open_access.oa_url` 和 Semantic Scholar 返回的 `openAccessPdf.url`。

**Python requests**（Windows 和 macOS 通用）：

```python
import time, requests

HEADERS = {"User-Agent": "course-check/0.1 (mailto:you@mail2.sysu.edu.cn)"}

def crossref_doi(doi):
    r = requests.get(f"https://api.crossref.org/works/{doi}", headers=HEADERS, timeout=20)
    if r.status_code == 404:
        return {"status": 404}
    r.raise_for_status()
    m = r.json()["message"]
    return {
        "status": 200,
        "title": m.get("title", [""])[0],
        "authors": [a.get("family") for a in m.get("author", [])],
        "year": m["issued"]["date-parts"][0][0],
        "journal": (m.get("container-title") or [""])[0],
        "has_abstract": "abstract" in m,
    }

def s2_doi(doi, retries=3):
    url = f"https://api.semanticscholar.org/graph/v1/paper/DOI:{doi}"
    params = {"fields": "title,year,authors,abstract,openAccessPdf"}
    for i in range(retries):
        r = requests.get(url, params=params, headers=HEADERS, timeout=20)
        if r.status_code != 429:
            return r.status_code, (r.json() if r.ok else r.text[:100])
        time.sleep(2 ** i * 5)  # 429：等 5、10、20 秒再试
    return 429, "多次限流，换 OpenAlex 或 Crossref"

for doi in ["10.1257/aer.20171330", "10.1257/aer.20231999"]:
    print(doi, crossref_doi(doi))
    time.sleep(1.5)
    print(doi, s2_doi(doi))
```

macOS 把 `curl.exe` 换成 `curl`，其余相同。

### 返回里看哪些字段

| 接口 | 看这些字段 | 注意 |
| --- | --- | --- |
| Crossref `/works/{doi}` | `message.title[0]`、`message.author[].family`／`given`、`message.issued.date-parts[0][0]`（年份）、`message.container-title[0]`（期刊）、`volume`、`issue`、`page`、`type`、`abstract`（JATS 格式，有的记录没有） | 404 正文是 `Resource not found.`；`issued` 是出版年，可能和工作论文年份差 1 年 |
| Crossref `/works?query...` | `message.items[].title`、`DOI`、`score` | 按得分排序，第一条不一定是期刊版（见下文教程） |
| Semantic Scholar | `title`、`year`、`authors[].name`、`venue`、`abstract`、`openAccessPdf.url`、`externalIds.DOI` | 字段要用 `fields=` 点名，不点名只返回 `paperId` 和 `title` |
| OpenAlex | `title`、`publication_year`、`authorships[].author.display_name`、`primary_location.source.display_name`、`open_access.oa_url`、`meta.cost_usd` | 返回的 `doi` 带 `https://doi.org/` 前缀；`meta.notice` 会提示额度 |
| arXiv | Atom XML 里的 `<entry><title>`、`<author><name>`、`<published>`、`<summary>`（摘要）、`<arxiv:doi>`（若已发表） | 返回 XML 不是 JSON；查不到时 `<entry>` 为空，不报 404 |

### 4. 怎样确认装好了

- `curl.exe -s -o NUL -w "%{http_code}" "https://api.crossref.org/works/10.1257/aer.20171330"` 输出 `200`；把 DOI 换成 `10.1257/aer.20231999` 输出 `404`。
- Claude Code 里输入 `/skills`（或问它“你现在有哪些 Skill”）能看到 academic-paper-search 和 bib-citation-validator。
- 装了 MCP 对照的：`claude mcp list` 显示 paper-search 为 connected，重开后 `/mcp` 里能看到它的工具列表。
- WorkBuddy：技能列表里出现两个技能；自定义连接器显示已连接。如果连接器一直连不上，先不用 MCP 对照，两个 Skill 照常可用。

## 核验四项与判定

每条参考文献核四项，前一项不过，后一项不用做：

| 项 | 怎样核 | 结论写法 |
| --- | --- | --- |
| 1. 是否存在 | 有 DOI：Crossref 或 OpenAlex 按 DOI 取，200 为存在。无 DOI：按题名＋第一作者在 Crossref、OpenAlex、Semantic Scholar 至少查两家 | 存在／DOI 未注册／多源未找到 |
| 2. 题名、作者、年份是否一致 | 对照返回的题名（忽略大小写和标点）、第一作者姓、年份（允许差 1 年，常见于工作论文与发表年）、期刊 | 一致／元数据有误（写出正确值） |
| 3. 能否读到摘要或全文 | Crossref `abstract`、Semantic Scholar `abstract`、arXiv `summary`；全文看 OpenAlex `open_access.oa_url`、Semantic Scholar `openAccessPdf` | 读到摘要／读到全文（注明版本）／都读不到 |
| 4. 是否支持原句 | 把你文中引用它的那句话和摘要或全文对照：数字、方向、范围是否吻合，有没有夸大 | 支持／部分支持（写出差在哪）／不支持／论断未核验 |

一个例子（据 Crossref 返回的摘要）：de Quidt、Haushofer、Roth（2018）在 11 个经典实验任务上估计实验者需求效应的界，平均约 0.13 个标准差，作者的结论是典型需求效应大概不大。若你文中写“该文在 11 个任务上估计需求效应的界约为 0.13 个标准差”，摘要支持；若写“该文证明实验者需求效应可以忽略、实验无需处理”，摘要不支持，原文提出的是一套界定和稳健性检验的方法。

### 回退顺序

1. **DOI 对不上**（404，或返回的题名和清单不符）：不要直接判假。先查 DOI 是否抄错（多一位、少一位、`l` 与 `1` 混淆），再用题名＋第一作者到 Crossref `query.bibliographic`＋`query.author` 查，再到 OpenAlex `title.search` 查。
2. **429（请求过多）**：停下来等，按 5、10、20 秒递增退避，最多 3 次；还不行就换源（Semantic Scholar → OpenAlex → Crossref）。OpenAlex 的 429 若是日额度用完，要等 UTC 零点（北京时间早上 8 点）或换用个人 key。
3. **超时或连接失败**：换源，不判定。Crossref、Semantic Scholar、OpenAlex、arXiv 在国内网络下都能连，偶发超时就换另一家；Unpaywall 连不上，不要再试它。
4. **全文读不到**：第 4 项标“论断未核验”，写明只核了元数据或只核了摘要，不写“已核实”。
5. **多源都查不到**：标“未找到，需人工核查”，不写“伪造”。查不到可能因为：中文文献（知网、万方的大部分期刊不在这些库）、学位论文、政府和机构报告、书和书的章节、非常新的论文。中文文献改到知网、万方或期刊官网人工查，或让智能体用浏览器工具（如 [agent-browser](https://ai.lingnan.top/materials/2026-autumn/w07/tool-05-agent-browser)）到知网查。

## 使用教程：核一份 5 条参考文献清单

任务：你写的一份报告里有 5 条参考文献，其中一部分是让智能体写的。逐条核验，产出一张核验表。

### 准备清单

在项目目录新建 `refs.md`，内容如下（第 2 条是本教程编的虚构文献，用来演示 404）：

```txt
1. de Quidt, J., Haushofer, J., & Roth, C. (2018). Measuring and Bounding Experimenter Demand. American Economic Review, 108(11), 3266–3302. https://doi.org/10.1257/aer.20171330
   文中引用句：该文在 11 个经典任务上估计实验者需求效应的界，平均约 0.13 个标准差。
2. Zhang, W., & Liu, H. (2023). Algorithmic Advice and Household Portfolio Choice. American Economic Review, 113(9), 2401–2440. https://doi.org/10.1257/aer.20231999
   文中引用句：算法投顾使家庭股票持有比例提高了 12%。
3. Bala, V., & Goyal, S. (2001). A Noncooperative Model of Network Formation. Econometrica, 68(5), 1181–1229.
   文中引用句：该文研究个人单方面决定建立连接时会形成哪些网络结构。
4. Vaswani, A., et al. (2017). Attention Is All You Need. arXiv:1706.03762.
   文中引用句：Transformer 结构不使用循环网络，完全基于注意力机制。
5. de Quidt, J., Haushofer, J., & Roth, C. (2017). Measuring and Bounding Experimenter Demand. NBER Working Paper No. 23470.
   文中引用句：实验者需求效应总体上很大，会推翻多数实验结论。
```

### 提示词

```txt
请用 academic-paper-search 技能逐条核验 refs.md 里的 5 条参考文献，结果写进 refs_check.md。

每条核四项：
1. 是否存在：有 DOI 先用 Crossref 按 DOI 查；没有 DOI 用题名加第一作者在 Crossref 和 OpenAlex 查；arXiv 编号用 arXiv 接口查。
2. 题名、作者、年份、期刊卷期是否和返回结果一致，不一致的写出正确值和来源。
3. 能否读到摘要或开放全文：查 Crossref 的 abstract、Semantic Scholar 的 abstract 和 openAccessPdf、OpenAlex 的 open_access.oa_url；读到全文时写明是投稿版还是期刊版。不要请求 api.unpaywall.org（国内网络连不上）。
4. 文中引用句是否被摘要或全文支持：支持、部分支持（说明差在哪）、不支持，或“论断未核验”（读不到摘要和全文时）。

规则：
- 每个结论后面附上你实际请求的 URL 和 HTTP 状态码。
- DOI 返回 404 时，先检查 DOI 写法，再用题名加作者查，查完再下结论。
- 遇到 429 等待后最多重试 3 次，然后换另一个库。
- 查不到写“未找到，需人工核查”，不要写“伪造”。
- Windows 下用 curl.exe 或 Python requests，两次 arXiv 请求间隔 3 秒以上。
- 最后给一张汇总表：序号、四项结果、建议怎么改。
```

### 预期看到的工具调用

- 若干次 `curl.exe` 或 `python` 调用，访问 `api.crossref.org/works/10.1257/aer.20171330`、`api.crossref.org/works/10.1257/aer.20231999`、`api.crossref.org/works?query.bibliographic=...`、`api.openalex.org/works?filter=title.search:...`、`api.openalex.org/works/doi:...`、`api.semanticscholar.org/graph/v1/paper/DOI:...`、`export.arxiv.org/api/query?id_list=1706.03762`。如果出现 `api.unpaywall.org`，说明它没按提示词做，这个请求在国内会超时。
- 可能出现 Semantic Scholar 429：免 key 共用池高峰期会连续返回 429，隔几秒重试也可能还是 429。智能体应等待后重试，或换 OpenAlex、Crossref。

### 预期结果

| 序号 | 存在 | 元数据 | 摘要／全文 | 原句 |
| --- | --- | --- | --- | --- |
| 1 | 存在（Crossref 200） | 一致：AER 第 108 卷第 11 期，3266–3302 页，2018 | Crossref 有摘要；开放全文看 OpenAlex `oa_url` 与 Semantic Scholar `openAccessPdf`，注意链接指向投稿版还是期刊版 | 支持 |
| 2 | Crossref 404，OpenAlex 404；按题名查无匹配 | — | — | 未找到，需人工核查（本例为教程虚构） |
| 3 | 存在，题名＋作者检索找到 DOI `10.1111/1468-0262.00155` | 年份有误：应为 2000 年（Econometrica 第 68 卷第 5 期，2000 年 9 月）；补上 DOI | 摘要需另查 | 待读摘要后判定 |
| 4 | 存在（arXiv 200） | 一致 | arXiv 摘要可读，全文开放 | 支持（摘要写明不用循环和卷积，只基于注意力） |
| 5 | 存在，DOI 为 `10.3386/w23470` | 一致，但已有期刊版（第 1 条），应合并为一条，引期刊版 | 同第 1 条 | 不支持：原文结论是需求效应大概不大 |

第 3 条和第 5 条展示了两类常见问题。用 Crossref 按题名＋作者查第 1 条时，排在前两位的是 SSRN 版（`10.2139/ssrn.2999695`）和 NBER 版（`10.3386/w23470`），期刊版不在前两位：按题名查回来的第一条不一定是期刊版，要对照期刊名和年份再选。

### 产出文件与验收

- 产出：`refs_check.md`（逐条结论＋请求 URL 与状态码＋汇总表）。
- 验收：
  - 第 2 条必须是“未找到”而不是“已核实”；如果智能体给出了这篇虚构论文的摘要或页码，说明它在编，结果作废。
  - 第 3 条要指出年份 2001 应为 2000。
  - 第 5 条要指出与第 1 条是同一研究的两个版本，且原句不被支持。
  - 每条结论都附了 URL 和状态码；随机挑一个 URL 自己用 `curl.exe` 或浏览器打开，结果一致。

有 LaTeX 稿和 `.bib` 的同学，可以再让智能体运行 bib-citation-validator 做一次批量核对：

```txt
请用 bib-citation-validator 技能核验 paper/main.tex 和 paper/refs.bib，输出到 check_report/。邮箱从环境变量 CROSSREF_MAILTO 读取。跑完把 report.md 里的 Critical flags 和 FAIL 条目列给我；FAIL 条目逐条再用 Crossref 按题名加作者手动查一次，确认不是网络错误造成的。
```

## 常见问题与排错

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| PowerShell 里 `curl` 弹出“是否运行脚本”或输出一堆对象属性 | `curl` 是 `Invoke-WebRequest` 的别名 | 写 `curl.exe` |
| URL 里有 `&`，PowerShell 报“不允许使用与号” | `&` 被当作命令运算符 | 整个 URL 用英文双引号包住 |
| 中文或空格题名查不到 | URL 未编码 | 空格写 `%20`，或改用 Python `requests` 的 `params=` 自动编码 |
| Semantic Scholar 一直 429 | 免 key 用户共用总池，高峰期限流 | 退避重试 3 次后换 OpenAlex 或 Crossref；需要常用就申请免费 key，请求头加 `x-api-key` |
| OpenAlex 返回 429，`meta` 提示额度 | 同一出口 IP（校园网、机房）共用每天 0.10 美元，被同学用完 | 用个人免费 key（每天 1 美元）；按 DOI 取单条不计费，能用 DOI 就用 DOI |
| OpenAlex 带 key 返回 403 `key_not_activated` | 还没点邮箱里的激活链接 | 去邮箱点链接；链接 7 天有效 |
| Crossref 返回 404 但论文确实存在 | DOI 抄错，或该文的 DOI 不是 Crossref 注册的（如部分 DataCite、中文 DOI） | 检查 DOI；用题名＋作者查；中文 DOI 到中国知网查，或去 https://doi.org 解析，doi.org 打不开就改用题名查 |
| 按题名查回来的第一条是 SSRN 或 NBER 版 | 同一研究有多个版本，排序按相关度 | 对照期刊名、年份选期刊版 |
| 返回成功但年份差 1 年 | 在线优先出版年和印刷年不同，或工作论文年份 | 以期刊版 `issued` 为准，差 1 年记为“需确认”而不是错误 |
| 请求 api.unpaywall.org 一直等、最后超时 | 国内网络连不上 Unpaywall | 不用 Unpaywall；开放全文看 OpenAlex `open_access.oa_url` 和 Semantic Scholar `openAccessPdf` |
| arXiv 返回很慢或 503 | 请求太密 | 每 3 秒最多 1 次，同时只开一个连接 |
| Semantic Scholar 连接超时 | 网络波动 | 换 Crossref、OpenAlex；不要因为超时判文献不存在 |
| uvx 启动 paper-search-mcp 很慢或下载失败 | uv 默认从 pypi.org 下载 | 设 `UV_DEFAULT_INDEX` 为清华镜像；不行就先不用 MCP 对照，用两个 Skill |
| bib-citation-validator 报大量 FAIL | 部分网络异常被脚本当成“没找到” | 检查网络后带 `--cache` 重跑；FAIL 条目手动复查 |
| bib-citation-validator 提示缺 `--tex` | 脚本要求 `.tex` 和 `.bib` 都有 | 没有 LaTeX 稿就用 academic-paper-search 逐条查 |
| 中文文献全部“未找到” | 这几个库很少收中文期刊 | 改用知网、万方或期刊官网人工查，标“需人工核查” |

## 费用、额度、隐私与安全

- 费用：这几个接口对本课这种用量都免费。OpenAlex 超出每日额度后可以付费充值，本课不需要，也不要绑定支付方式。
- 额度：OpenAlex 匿名额度按出口 IP 共用，全班集中使用时最先遇到问题；Semantic Scholar 免 key 共用池高峰期可能 429。
- 隐私：`mailto` 会让服务方知道是谁在请求，填自己的学校邮箱即可，不填别人的。查询的 DOI 和题名会被服务方记录，未发表论文的题名属于你的研究信息，介意的话少用题名检索。
- Key：OpenAlex 和 Semantic Scholar 的 key 放环境变量，不写进文件、不进截图、不发到聊天群。OpenAlex 个人 key 也是网站登录凭据，泄露后到 Settings → API key 轮换。
- 版权：arXiv 条款允许个人和研究用途读取论文，不允许把论文 PDF 存到自己服务器再对外提供；OpenAlex、Semantic Scholar 给出的开放版本按各自许可使用。paper-search-mcp 的 Sci-Hub 回退默认关闭，本课不启用。
- 封号风险：按限额请求不会被封。不要为了绕过限额换多台机器或多个 IP 并发请求，arXiv 和 Crossref 都写明会封禁这类行为。

## 与同类工具的一句对比

Google Scholar 覆盖面更广，但国内网络连不上，也没有官方 API，智能体抓取容易被验证码拦下；Zotero 自带“按 DOI 添加”能拿到同样的元数据，适合管理文献，不适合批量核验；本课的做法是用这几个公开接口加 Skill 里的判定规则，每一步都能看到请求和返回。

## 信息来源

| 内容 | 来源 | 类型 |
| --- | --- | --- |
| Crossref 限额与池 | https://www.crossref.org/documentation/retrieve-metadata/rest-api/access-and-authentication ；https://community.crossref.org/t/refining-rest-api-limits-for-improved-stability-and-reliability/16137 | 官方文档；官方社区公告 |
| Crossref 使用建议（`select`、`rows`、429 退避） | https://www.crossref.org/documentation/retrieve-metadata/rest-api/tips-for-using-the-crossref-rest-api/ （2025-10-24 更新） | 官方文档 |
| Semantic Scholar 免 key 共用池、key 起步 1 次/秒 | https://www.semanticscholar.org/product/api | 官方文档 |
| OpenAlex 计费、每日额度、速率、key 申请 | https://developers.openalex.org/how-to-use-the-api/rate-limits-and-authentication ；https://developers.openalex.org/access/pricing ；https://developers.openalex.org/access/example-costs | 官方文档 |
| Unpaywall 需 email | https://unpaywall.org/products/api | 官方页 |
| arXiv 每 3 秒 1 次、单连接、版权条款 | https://info.arxiv.org/help/api/tou.html | 官方文档 |
| paper-search-mcp 功能、环境变量、Sci-Hub 默认关闭 | https://github.com/openags/paper-search-mcp ；PyPI 版本 0.1.4 | 社区仓库 |
| uv 的 `UV_DEFAULT_INDEX` 环境变量 | https://docs.astral.sh/uv/reference/environment/ | 官方文档 |
| WorkBuddy 技能上传与自定义连接器 | https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market ；https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Connector | 官方文档 |
| Claude Code 添加 MCP 与 Skill 目录 | https://code.claude.com/docs/en/mcp | 官方文档 |