literature-search-openalex

OpenAlex 技能

前置条件

1. uv：阅读 uv 技能并按照其中的设置说明，确保已安装 uv 且其位于 PATH 中。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/literature_search_openalex_LICENSE.txt，则 (1) 显著提醒用户查看 https://help.openalex.org/ 上的条款，并始终检查此技能检索到的论文的许可证是否有任何限制，然后 (2) 创建该文件，记录通知文本和时间戳。
3. .env 文件：确保 .env 文件存在于主目录中。如果不存在，请创建一个。
4. OPENALEX_API_KEY（可选但推荐）：此技能无需密钥也能运行，但不带密钥的请求会共享每个 IP 地址每天 $0.10 的预算。免费密钥有自己的每日 $1 预算和更高的速率限制，并且是从 content.openalex.org 下载全文（download-pdf）的必要条件。添加 mailto（以前称为“polite pool”）不再提高限制。你可以在 OpenAlex.org → 账户设置中获取免费密钥。每当检查或请求此密钥时，都必须使用 credentials 技能中的安全凭据流程；如果未设置密钥，不得因此阻止无密钥运行。

核心规则

1. 列出来源。 使用此技能时，确保在输出中提及这一点，并列出用于生成输出的所有论文 URL。
2. 先解析，再筛选。 绝不要按名称筛选。始终先用 resolve 将名称解析为 ID，然后在 --filter 中使用该 ID。
3. 仅使用 CLI。 绝不要通过 curl/urllib 调用 API。CLI 会处理重试和速率限制。
4. 禁止编造。 绝不要编造 OpenAlex ID 或 DOI。使用 resolve/get 查找。准确报告空结果。
5. API 密钥。 如果命令返回 401、因速率限制或每日预算耗尽而返回 429，或者你需要进行大量查询，则必须使用 credentials 技能中的安全凭据流程，检查并请求 OPENALEX_API_KEY，以帮助用户将其添加到 .env 文件中。免费密钥无法解决 429 Plan upgrade required 错误。
6. 控制输出规模。 概览查询始终使用 --select 和 --per-page 5–10。将 filter 输出通过管道写入文件（> results.json），然后用 jq 精简后再读入上下文。

速率限制

• 不带密钥： 10 req/s；每个 IP 地址每天 $0.10 的预算，由该 IP 的所有无密钥请求共享。
• 使用免费密钥： 30 req/s；每天 $1 的预算。
• 年度计划： 50 req/s。

操作	费用
单条 get	免费
filter	$0.0001
--search / resolve	$0.001
download-pdf	$0.01

CLI 参考

uv run scripts/openalex_cli.py [--api-key KEY] <command> [flags]

实体类型（所有命令共用）：works、authors、sources、 institutions、topics、domains、fields、subfields、sdgs、countries、 continents、languages、keywords、publishers、funders、work-types、 source-types、institution-types、licenses

命令

resolve <entity> <query> — 名称 → ID 候选项。返回 id、 display_name、hint。使用 --per-page N 获取更多候选项。

get <entity> <id> — 获取单个实体的完整元数据。接受短 ID （W2741809807）、完整 URL 或 DOI URL。使用 --select 限制字段。

filter <entity> — 搜索/筛选实体。主要标志如下：

• --search <query>：全文搜索（成本是 --filter 的 10 倍）
• --filter <expr>：筛选表达式。使用 , 表示 AND，使用 | 表示 OR。
• --sort <field:dir>：对结果排序（例如，cited_by_count:desc）
• --select <fields>：限制输出中返回的字段。
• --group-by <field>：按指定字段聚合结果。
• --per-page <N>：每页结果数（默认 25，最多 100）。
• --page <N>：指定要获取的页码。
• --sample <N>：随机抽取最多 10,000 条结果。
• --seed <N>：设置可复现抽样的种子。

download-pdf <work-id> <output-path> — 下载 PDF （content.openalex.org 需要 OPENALEX_API_KEY；如果未通过身份验证或主 服务器失败，则会回退到作品元数据中的备用 pdf_url 位置）。务必运行 download-pdf 并确认下载的 PDF 非空且未损坏；如果缺少 OPENALEX_API_KEY， 还要参阅 credentials 技能，帮助用户添加该密钥。

rate-limit — 检查当前速率限制和每日额度状态（未设置密钥时报告共享的每 IP 限制；设置 OPENALEX_API_KEY 时报告密钥专属限制；如果未设置 OPENALEX_API_KEY，还要参阅 credentials 技能，帮助用户添加该密钥）。

搜索提示

• 如果 resolve 未返回匹配项，请尝试其他拼写或缩写。
• 如果 --search 返回 0 条结果，请尝试更宽泛的词语（最多重试 3 次）。
• 如果 resolve 返回多个候选项，请向用户展示 display_name 和 hint， 以便手动选择。

实体参考

请查阅 references/，了解各实体有效的筛选、排序和分组字段：

• 作品 — 作者 — 来源
• 机构 — 主题 — 分类体系
• 地理与语言 — 出版商与资助方
• 类型值

对于此处未涵盖的内容，或 API 的行为与本技能描述不同时，请查阅官方文档索引： https://help.openalex.org/llms.txt。

常见工作流

# Author's works (resolve → filter)
uv run scripts/openalex_cli.py resolve authors "Geoffrey Hinton"
uv run scripts/openalex_cli.py filter works \
  --filter "authorships.author.id:A5108093963" \
  --sort "cited_by_count:desc" --per-page 10 > papers.json
cat papers.json | jq '[.results[] | {id, title: .display_name, year: .publication_year, citations: .cited_by_count}]'

# DOI lookup
uv run scripts/openalex_cli.py get works "https://doi.org/10.1038/s41586-021-03819-2"

# Bulk DOI lookup (up to 100)
uv run scripts/openalex_cli.py filter works \
  --filter "doi:10.1234/a|10.1234/b|10.1234/c" --per-page 100 > results.json

# Institutional impact by year
uv run scripts/openalex_cli.py resolve institutions "MIT"
uv run scripts/openalex_cli.py filter works \
  --filter "authorships.institutions.id:I63966007" \
  --group-by "publication_year" > mit_by_year.json

# Random sample
uv run scripts/openalex_cli.py filter works \
  --filter "publication_year:2023,is_oa:true" \
  --sample 100 --seed 42 > results.json

错误处理

CLI 已会通过退避机制重试 429 错误，但 Plan upgrade required 错误除外；此类错误会立即失败并给出说明。不要盲目重试这两种错误；错误输出中的 Server body 可用于区分它们。

代码	含义	操作
401	未经授权	你必须使用 credentials 技能中的安全凭据流程，帮助用户将 API 密钥添加到 .env
404	未找到	验证 ID；先尝试 resolve
429	正文显示 Plan upgrade required	付费方案功能（例如，受方案限制的筛选器）。不要重试；免费密钥无济于事。移除筛选器或告知用户；参见 https://openalex.org/pricing
429	正文显示速率限制或额度耗尽	没有密钥：你必须使用 credentials 技能中的安全凭据流程，帮助用户将 API 密钥添加到 .env。有密钥：等待后重试（速率限制），或告知用户每日额度已用完

已知受方案限制的筛选器：from_created_date、from_updated_date、 to_updated_date。

响应为空时，绝不要捏造结果——请如实报告，并建议尝试其他搜索词。