用 OpenAlex 检索学术论文…

需要查询 OpenAlex 学术数据库（论文、作者、机构、主题、DOI、开放获取 PDF、引用量等）时，用 CLI 按「先解析 ID 再过滤」的流程安全检索。

适用场景

解决思路

1. 确认前置条件：阅读 uv 技能并按其 Setup 说明安装 uv 并加入 PATH。
2. 若工作区根目录不存在 .licenses/literature_search_openalex_LICENSE.txt，则显著提醒用户查看 https://developers.openalex.org/ 的条款，并提醒始终检查所检索论文的许可证限制，然后创建该文件记录提醒文本与时间戳。
3. 确保家目录存在 .env 文件，不存在则创建。
4. OPENALEX_API_KEY 可选但推荐：它启用 OpenAlex Premium API 以获得更高限流；无 key 时使用免费 polite pool。可在 OpenAlex.org → account settings 获取 key，并必须使用 credentials 技能中的安全凭据协议检查/请求该 key。
5. 输出中必须说明使用了本技能，并列出所有用于生成结果的论文 URL。
6. 绝不按名称直接过滤：必须先用 resolve 把名称解析为 ID，再在 --filter 中使用该 ID。
7. 只使用 CLI，绝不用 curl/urllib 直接调用 API，因为 CLI 会处理重试与限流。
8. 绝不编造 OpenAlex ID 或 DOI，必须用 resolve/get 查询；空结果要如实报告。
9. 若命令返回 401/429 或需要高并发查询，必须使用 credentials 技能中的安全凭据协议检查并请求 OPENALEX_API_KEY，帮助用户加入 .env。
10. 保持输出精简：概览查询始终使用 --select 和 --per-page 5–10；把 filter 输出重定向到文件（> results.json），再用 jq 精简后再读入上下文。
11. 了解限流：有 key 约 10 req/s、每天 $1 免费额度；无 key 额度非常有限、每天 $0.01。费用：单条 get 免费，filter $0.0001，--search/resolve $0.001，download-pdf $0.01。
12. 用 resolve <entity> <query> 做名称→ID 候选解析，返回 id、display_name、hint，可用 --per-page N 获取更多候选。
13. 用 get <entity> <id> 获取单个实体的完整元数据，接受短 ID（如 W2741809807）、完整 URL 或 DOI URL，可用 --select 限制字段。
14. 用 filter <entity> 搜索/过滤实体，关键参数：--search 全文搜索（成本是 --filter 的 10 倍）、--filter 过滤表达式（, 表示 AND，| 表示 OR）、--sort 排序（如 cited_by_count:desc）、--select 限制返回字段、--group-by 按字段聚合、--per-page 每页数量（默认 25，最大 100）、--page 页码、--sample 随机抽样（最多 10000 条）、--seed 可复现抽样的种子。
15. 用 download-pdf <work-id> <output-path> 下载 PDF（需要 API key），主地址失败时回退到其他 pdf_url；每次下载后都要验证 PDF 非空且未损坏。
16. 用 rate-limit 检查当前限流状态（需要 API key）。
17. 搜索技巧：resolve 无匹配时尝试其他拼写或缩写；--search 返回 0 结果时尝试更宽泛的词（最多重试 3 次）；resolve 返回多个候选时，把 display_name 和 hint 呈现给用户手动选择。
18. 查阅 references/ 了解各实体可用的 filter、sort、group-by 字段：works、authors、sources、institutions、topics、taxonomy、geo_and_language、publishers_funders、type_values。
19. 常见工作流示例：作者论文（先 resolve authors "Geoffrey Hinton"，再 filter works --filter "authorships.author.id:A5108093963" --sort "cited_by_count:desc" --per-page 10 > papers.json，再用 jq 提取 id/title/year/citations）；DOI 查询（get works "https://doi.org/10.1038/s41586-021-03819-2"）；批量 DOI 查询（最多 100 个，--filter "doi:10.1234/a|10.1234/b|10.1234/c" --per-page 100）；机构逐年影响力（resolve institutions "MIT"，再 filter works --filter "authorships.institutions.id:I63966007" --group-by "publication_year"）；随机抽样（--filter "publication_year:2023,is_oa:true" --sample 100 --seed 42）。
20. 错误处理：401 未授权时用 credentials 技能的安全凭据协议帮助用户把 API key 加入 .env；403 需要升级套餐时告知用户并参考 https://openalex.org/pricing；404 未找到时核实 ID，先试 resolve；429 限流时等待重试，并用安全凭据协议帮助用户把 API key 加入 .env。
21. 注意已知的仅限 Premium 的过滤器：from_updated_date、to_updated_date。
22. 空响应时绝不编造结果，要如实报告并建议其他搜索词。

适用边界 · 注意事项

• 没有安装 uv 或无法按 uv 技能完成 Setup 时。
• 用户不愿接受 OpenAlex 条款或不愿检查论文许可证限制时。
• 需要 from_updated_date/to_updated_date 等仅限 Premium 的过滤器但无相应套餐时。