ARIS OpenAlex 学术搜索技能实战指南：开源引文图谱、机构归属与资助信息的深度检索

• AI 技能/插件
• AI 评测
• 科研
• 人工智能
• MCP 服务
• dsh-plugin

本篇技术指南以 ARIS 项目中的/openalex技能为核心，系统讲解如何利用 OpenAlex 这一开放学术图谱完成超越 arXiv 与 Semantic Scholar 的综合学术检索——涵盖开源引文数据、机构归属、资助来源（NSF/NIH 等）与全学科元数据。读者将掌握/openalex的完整调用语法、全部参数覆盖规则、底层抓取脚本openalex_fetch.py的实现原理与容错机制，以及它在/research-lit多源聚合文献综述中的接入方式，最终能够在自己的研究流程中直接复用这套可复制的检索方案。

一、技能定位：ARIS 文献检索矩阵中的开源学术图谱

在 ARIS 的文献检索体系中，/openalex是专门面向OpenAlex API的学术检索技能，其设计目标是提供一个"开源的学术图谱"数据源。根据 skills/openalex/SKILL.md 中的定位表，ARIS 将不同来源按各自优势做了明确分工：

/openalex的独特价值在四个维度：开源引文数据（无需 API Key 即可使用完整开放引文图谱）、机构归属（作者所在机构与合作关系）、资助信息（NSF、NIH 等资助来源）、综合元数据（主题、关键词、摘要、开放获取状态），以及跨数据库覆盖（索引了来自多个来源的 2.5 亿+ 学术作品）。从源码结构看，这套技能的核心由两部分组成：作为"说明书"的 SKILL.md，以及作为"执行引擎"的 tools/openalex_fetch.py 抓取脚本。

二、环境准备：依赖、API Key 与联调验证

1. 安装依赖

/openalex需要 Python 3.7+ 环境并安装requests库（这也是其底层抓取脚本 tools/openalex_fetch.py 的唯一第三方依赖）：

pip install requests

需要注意的是，requests在脚本中被显式视为可选依赖：当导入失败时，脚本不会直接崩溃，而是向 stderr 打印安装提示并以退出码 2 结束——这个退出码专门用于向调用方技能发出"跳过此来源"的信号，区别于运行时错误使用的退出码 1（见 tools/openalex_fetch.py）。对应的测试 tests/test_openalex_fetch.py 也因此在 CI 环境中通过pytest.importorskip("requests")跳过本模块，避免因缺包导致测试失败。

2. 配置 API Key（可选但推荐）

OpenAlex 基础使用不需要 API Key，但配置后可显著提升速率限制。在项目根目录创建.claude/.env：

# 从模板复制 cp .claude/.env.example .claude/.env # 编辑并添加你的密钥 # .claude/.env OPENALEX_API_KEY=your-key-here OPENALEX_EMAIL=your-email@example.com

Claude Code 会自动将.claude/.env加载为环境变量。两个配置项在底层脚本中的作用（tools/openalex_fetch.py）：

• OPENALEX_API_KEY：作为api_key查询参数附加到每次请求，换取更高速率限制（免费档每日 10,000 次列表调用、1,000 次搜索调用）；
• OPENALEX_EMAIL：设置User-Agent: mailto:<email>请求头以加入Polite Pool（礼貌池），获得更快的响应速度，无需注册。

3. 验证安装

安装完成后，可以先用最小查询验证环境是否就绪：

python3 "$OPENALEX_FETCHER" search "machine learning" --max 3

其中$OPENALEX_FETCHER需要通过下文第三步的规范解析链（canonical chain）解析为openalex_fetch.py的实际路径。

三、调用语法：参数解析与覆盖规则

1. 参数体系

/openalex的调用格式为/openalex "搜索主题"，支持通过追加参数覆盖默认行为（见 skills/openalex/SKILL.md）：

• query（必填）：研究主题
• max：覆盖默认MAX_RESULTS = 10
• year：发表年份过滤，如2023-、2020-2023
• type：作品类型过滤（article、preprint、book、book-chapter、dataset、dissertation）
• open-access：仅返回开放获取论文
• min-citations：最低引用数阈值
• sort：排序方式（relevance、citations、date）

2. 覆盖规则速查

• /openalex "topic" — max: 20— 最多返回 20 条结果
• /openalex "topic" — year: 2023-— 2023 年至今的论文
• /openalex "topic" — year: 2020-2023— 2020 至 2023 年的论文
• /openalex "topic" — type: article— 仅期刊文章
• /openalex "topic" — type: preprint— 仅预印本
• /openalex "topic" — open-access— 仅开放获取论文
• /openalex "topic" — min-citations: 50— 最低 50 次引用
• /openalex "topic" — sort: citations— 按引用数降序排序
• /openalex "topic" — sort: date— 按发表日期排序（最新优先）

3. 参数到 API 过滤器的映射

这些参数在底层被精确映射为 OpenAlex/works端点的过滤器（见 tools/openalex_fetch.py 的search_works方法）：

排序选项通过 CLI 层的sort_map映射为 API 格式（tools/openalex_fetch.py）。per_page会被限制为min(max_results, 200)，因为 OpenAlex API 单页上限为 200 条——这一行为有测试专门锁定（tests/test_openalex_fetch.py 验证了当请求max_results=250时实际发送的per_page=200）。过滤器以逗号拼接为单个filter参数，多个条件之间是 AND 关系。

四、辅助脚本解析：strict-safe 规范解析链与失败策略

/openalex与/semantic-scholar、/arxiv、/deepxiv、/exa-search一样，遵循 ARIS 的集成契约（skills/shared-references/integration-contract.md §2）中规定的四层解析链来定位辅助脚本。这一步的设计动机在契约文档中有明确记载：历史上曾因技能硬编码tools/research_wiki.py路径，导致用户项目在缺少该目录时静默失败，整个research-wiki/空了一周。规范解析链正是为此而生。

/openalex的解析块（skills/openalex/SKILL.md Step 2）按以下顺序尝试定位openalex_fetch.py：

1. .aris/tools/openalex_fetch.py——由install_aris.sh创建的符号链接（安装器会在~/.aris/repo写入一行绝对仓库路径的全局指针文件）；
2. tools/openalex_fetch.py——手动复制，或在 ARIS 仓库内直接运行；
3. $ARIS_REPO/tools/openalex_fetch.py——通过环境变量ARIS_REPO或从.aris/installed-skills.txt清单读取repo_root；
4. $HOME/.aris/repo指向的仓库路径——覆盖无项目清单的全局复制安装场景。

cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1 if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true fi if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true fi OPENALEX_FETCHER=".aris/tools/openalex_fetch.py" [ -f "$OPENALEX_FETCHER" ] || OPENALEX_FETCHER="tools/openalex_fetch.py" [ -f "$OPENALEX_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && OPENALEX_FETCHER="$ARIS_REPO/tools/openalex_fetch.py"; } [ -f "$OPENALEX_FETCHER" ] || { echo "ERROR: openalex_fetch.py not resolved at .aris/tools/, tools/, \$ARIS_REPO/tools/, or via ~/.aris/repo." >&2 echo " Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), export ARIS_REPO, or copy the helper to tools/." >&2 echo " Also ensure 'requests' is installed: pip install requests" >&2 exit 1 }

关键点在于，/openalex对该辅助脚本采用的是契约中的 Policy D1 变体（严格模式）：因为 OpenAlex 的检索必须依赖requestsSDK 与可选 API Key，抓取脚本封装了分页、节流与按来源的参数处理，所以没有文档化的内联回退方案（与/semantic-scholar保留的 inline Python 回退不同）。一旦解析失败，技能会以明确错误终止并给出修复指引，而不是静默跳过——这正是"承接失败必须显式可见"这一集成契约原则的体现。

五、核心用法：搜索、过滤与按 ID 取单篇

1. 基础搜索

python3 "$OPENALEX_FETCHER" search "QUERY" --max 10

2. 组合过滤器搜索

python3 "$OPENALEX_FETCHER" search "QUERY" --max 10 \ --year 2023- \ --type article \ --open-access \ --min-citations 20 \ --sort citations

3. 按 DOI 取单篇作品

python3 "$OPENALEX_FETCHER" work "10.1109/TWC.2024.1234567"

4. 按 OpenAlex ID 取单篇作品

python3 "$OPENALEX_FETCHER" work "W2741809807"

底层实现中，get_work方法（tools/openalex_fetch.py）对不同的 ID 格式做了路由：以10.开头的按 DOI 处理（请求/works/doi:<id>），以W开头的按 OpenAlex 作品 ID 处理（请求/works/<id>）。两种模式都支持--json标志输出结构化 JSON，便于下游流水线消费。

5. JSON 输出模式

CLI 支持--json标志（search与work子命令通用），会以json.dumps(..., indent=2)输出完整的结构化结果，这是/research-lit等聚合技能集成时的推荐形态。

六、结果解析：返回字段全解与摘要重建原理

openalex_fetch.py会将 OpenAlex 原始作品对象解析为扁平化结构（_parse_work方法，tools/openalex_fetch.py），字段如下：

• title：论文标题
• authors：作者名列表
• publication_year：发表年份
• venue：期刊/会议名称
• venue_type：来源类型（journal、repository、conference 等）
• cited_by_count：引用数
• is_oa：开放获取布尔值
• oa_status：开放获取类型（gold、green、bronze、hybrid、closed）
• oa_url：直接 PDF 链接（若可用）
• doi：DOI 标识符
• openalex_id：OpenAlex 作品 ID
• abstract：完整摘要文本
• topics：前 3 个研究主题
• keywords：前 5 个关键词
• type：作品类型（article、preprint 等）

值得深入讲解的是摘要重建这一实现细节：OpenAlex API 返回的摘要采用倒排索引格式（abstract_inverted_index），即{单词: [位置列表]}的映射。_reconstruct_abstract方法（tools/openalex_fetch.py）先展开所有(位置, 单词)元组，按位置排序后再拼接成完整摘要文本。测试 tests/test_openalex_fetch.py 用一个包含重复单词的构造样例验证了排序逻辑：{"models": [1], "are": [2], "useful": [0, 3]}正确重建为"useful models are useful"。

同样值得注意的健壮性处理包括：对primary_location/source使用or {}防御显式 null（OpenAlex 对部分作品会返回显式 null 而非缺键）；对缺失 author 的条目填充"Unknown"；doi去除https://doi.org/前缀归一化；CLI 展示层将摘要截断为前 200 字符、作者列表超过 3 人时以et al.省略。这些行为均有对应测试锁定（如 tests/test_openalex_fetch.py 验证了缺失位置信息时的字段归一化）。

七、结果呈现与后续动作

1. 结构化表格

技能要求将结果以结构化表格呈现（skills/openalex/SKILL.md Step 5）：

| # | Title | Venue | Year | Citations | OA | Summary | |---|-------|-------|------|-----------|----|---------| | 1 | ... | IEEE TWC | 2024 | 156 | ✓ | ... | | 2 | ... | NeurIPS | 2023 | 89 | ✓ | ... |

对每篇论文还需展示：

• DOI：规范标识符
• OpenAlex ID：用于交叉引用
• 开放获取：状态（gold/green/bronze/hybrid/closed）与 PDF 链接
• 主题：主要研究主题
• 摘要：前 200 字符或全文

2. 推荐后续动作

呈现结果后，技能建议向用户提供后续操作选项：

/semantic-scholar "DOI:..." — 获取 S2 引用上下文与相关论文 /arxiv "arXiv:XXXX.XXXXX" — 若可用则获取 arXiv 预印本 /research-lit "topic" — sources: openalex, semantic-scholar — 组合多源综述 /novelty-check "idea" — 对照文献验证新颖性

八、与 Semantic Scholar / arXiv 的对比选型

何时优先选 OpenAlex 而非 S2：需要机构归属数据、需要资助信息、想要完全开放的引文图谱、需要综合的主题/关键词元数据、或者研究领域不限于计算机科学（OpenAlex 覆盖全学科）。

何时优先选 S2 而非 OpenAlex：需要实时引用数（S2 更新更快）、需要"高影响力引用"指标、需要论文推荐、或者以 CS/AI 为核心研究领域（S2 的 CS 覆盖更优）。

九、规则要点与故障处理

• OpenAlex 完全开放：基础使用无需 API Key，但推荐配置以获得更高速率限制；
• 无 Key 时速率非常受限（约每天 $0.01 量级），免费 Key 可获得每日 10,000 次列表调用、1,000 次搜索调用；
• Polite Pool：设置OPENALEX_EMAIL环境变量可获得更快响应；
• 跨源交叉引用：OpenAlex 索引了 arXiv、PubMed、Crossref 等来源的论文，可用 DOI/arXiv ID 做交叉引用与去重。

关于速率限制错误，底层脚本对 HTTP 429 有专门的处理路径（tools/openalex_fetch.py）：向 stderr 输出 "Rate limit exceeded. Consider using an API key or reducing request frequency." 后抛出 HTTPError；测试 tests/test_openalex_fetch.py 验证了这一行为。在/openalex技能层面，若 OpenAlex API 不可达或被限流，建议回退到/semantic-scholar、/arxiv或/research-lit "topic" — sources: web。

十、在/research-lit多源聚合中的集成方式

/openalex并非孤立使用——它还是/research-lit文献综述技能的九大可选数据源之一。根据 skills/research-lit/SKILL.md 的 Source Table，OpenAlex 源（优先级 9）的激活条件是$OPENALEX_FETCHER解析成功且Pythonrequests模块可导入；它属于显式 opt-in来源，不会包含在默认的all中，必须通过— sources: openalex或— sources: all, openalex显式启用。

接入代码段（skills/research-lit/SKILL.md OpenAlex search 部分）展示了与/openalex技能一致的解析链，并额外增加了requests预检：

# 预检：辅助脚本未解析或 requests 缺失时静默跳过 OpenAlex 源 if [ -z "$OPENALEX_FETCHER" ] || ! python3 -c "import requests" >/dev/null 2>&1; then echo "OpenAlex source not available (openalex_fetch.py unresolved or 'requests' module missing); skipping." >&2 else if python3 "$OPENALEX_FETCHER" search "QUERY" --max 10 \ --year "2022-" \ --type article \ --sort relevance; then echo "D2 contribution: openalex (helper invocation exit 0)" >&2 else echo "WARN: openalex_fetch.py invocation failed; D2 aggregate continues with remaining sources." >&2 fi fi

这一集成遵循集成契约 §2 的Policy D2（多源聚合）：每个来源的成功与否被记录为D2 contribution:日志行，即使单个来源失败，聚合流程也会继续使用其余已解析来源的结果；只有当所有请求来源都失败时，才在 D2 聚合收尾阶段报出空聚合错误。在去重策略上，/research-lit规定：当 OpenAlex 与 S2 命中同一篇论文时，优先用 S2 的引用数与期刊元数据（对 CS/AI 论文更准确），同时保留 OpenAlex 独有的机构归属与资助数据，合并为更丰富的记录；DOI 是跨源去重的第一优先级键。

十一、从源码到测试：质量保障闭环

/openalex的可靠性由三层保证：

1. 技能层（skills/openalex/SKILL.md）：明确定位、参数覆盖语法、工作流步骤与规则，任何 LLM 可直接按文执行；
2. 实现层（tools/openalex_fetch.py）：封装了端点调用、过滤器构造、摘要重建、ID 路由、429 处理与可选 Key 附加等全部业务逻辑；
3. 测试层（tests/test_openalex_fetch.py）：通过FakeResponse桩对象与monkeypatch离线验证关键行为——摘要倒排索引重建、缺失位置信息时的字段归一化、过滤器拼接与 per_page 上限、429 错误浮出、开放获取标志在解析与 CLI 两种输出形态下的保持（含参数化测试覆盖open_access为缺键/空对象/None 的多种形态）。

这三层叠加，使/openalex既能被人类与 Agent 快速理解调用，又能被确定性测试持续校验，符合 ARIS"技能散文可以描述集成，但无法保证集成；可验证的工件与脚本才能保证"的整体设计哲学。

结语

/openalex是 ARIS 文献检索矩阵中填补"开源学术图谱"空白的关键一环：它以零成本开放引文数据为底座，叠加机构归属、资助来源与跨学科元数据，配合规范解析链与显式失败策略保证了在任意安装形态下的可用性。无论你是需要验证一个想法的文献新颖性、追踪某篇论文的机构合作网络，还是为基金申请梳理资助背景，都可以将本文的参数表、命令模板与源码分析直接复制到自己的研究流程中——这也是 ARIS 一贯的设计取向：技能是方法论，取走即用，无框架绑定。

• AI 技能/插件
• AI 评测
• 科研
• 人工智能
• MCP 服务
• dsh-plugin