openalex

OpenAlex 学术搜索

搜索查询：$ARGUMENTS

角色与定位

此技能使用 OpenAlex 作为全面开放的学术图谱来源：

技能	来源	适用场景
/arxiv	arXiv API	最新预印本、前沿的未经过同行评审的研究
/semantic-scholar	Semantic Scholar API	已发表的会议和期刊论文（IEEE、ACM、Springer），含引用次数
/openalex	OpenAlex API	开放引用图谱、机构隶属关系、资助数据、全面的元数据
/deepxiv	DeepXiv CLI	分层阅读：搜索、摘要、章节概览、章节阅读
/exa-search	Exa API	广泛的网络搜索：博客、文档、新闻、公司、研究论文
/gemini-search	Gemini MCP / CLI	AI 驱动的广泛文献发现

以下情况适合使用 OpenAlex：

• 开放引用数据——完全开放的引用图谱（基本使用无需 API 密钥）
• 机构隶属关系——作者所属机构及合作关系
• 资助信息——NSF、NIH 及其他资助来源
• 全面的元数据——主题、关键词、摘要、开放获取状态
• 跨数据库覆盖范围——索引多个来源的 2.5 亿多篇成果

常量

• MAX_RESULTS = 10——默认结果数量。可通过 — max: 20 覆盖。
• DEFAULT_SORT = relevance——按相关性排序。可通过 — sort: citations 或 — sort: date 覆盖。
• OPENALEX_FETCHER——规范名称为 openalex_fetch.py，按 shared-references/integration-contract.md §2 进行解析 （Policy D1——独立的 /openalex 没有已记录的内联回退方式， 因此无法解析辅助程序时会以明确错误终止）。

覆盖选项（追加到参数中）：

• /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——按发表日期排序（最新优先）

设置

前提条件

1. 安装带有 requests 库的 Python 3.7+：

   pip install requests
   

2. 可选：API 密钥——在项目根目录中创建 .claude/.env：

   # Copy from template
   cp .claude/.env.example .claude/.env
   
   # Edit and add your keys
   # .claude/.env
   OPENALEX_API_KEY=your-key-here
   [email protected]
   

   Claude Code 会自动将 .claude/.env 加载为环境变量。

3. 获取 API 密钥（可选，但建议获取）：

   • OpenAlex API 密钥：从 openalex.org 获取免费套餐，每天 $1（10,000 次列表调用、1,000 次搜索调用）
   • 礼貌池使用的电子邮件：可加快响应速度（无需注册）

验证设置

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

（先通过规范链解析 $OPENALEX_FETCHER——见下文第 2 步。）

工作流

第 1 步：解析参数

解析 $ARGUMENTS，提取：

• query：研究主题（必填）
• max：覆盖 MAX_RESULTS
• year：发表年份筛选条件（例如 2023-、2020-2023）
• type：成果类型筛选条件（article、preprint、book、book-chapter、dataset、dissertation）
• open-access：仅包含开放获取论文
• min-citations：引用次数下限
• sort：排序方式（relevance、citations、date）

第 2 步：定位脚本

通过规范的严格安全链解析 $OPENALEX_FETCHER（见 shared-references/integration-contract.md §2）。 Policy D1：OpenAlex 没有原生内联回退方式 （检索需要 requests SDK 和可选的 API 密钥—— 抓取器脚本封装了分页、限流和按来源配置的参数）， 因此无法解析辅助程序时会终止并提供明确的解决方法。

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
}

步骤 3：执行搜索

基本搜索：

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

使用筛选条件：

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

通过 DOI 获取特定作品：

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

通过 OpenAlex ID 获取特定作品：

python3 "$OPENALEX_FETCHER" work "W2741809807"

步骤 4：解析结果

脚本会返回结构化 JSON，其中包含：

• title：论文标题
• authors：作者姓名列表
• publication_year：发表年份
• venue：期刊／会议名称
• venue_type：出版场所类型（期刊、知识库、会议等）
• 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：作品类型（文章、预印本等）

步骤 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 个字符或完整文本

步骤 6：提供后续选项

展示结果后，建议：

/semantic-scholar "DOI:..."     — get S2 citation context and related papers
/arxiv "arXiv:XXXX.XXXXX"      — fetch arXiv preprint if available
/research-lit "topic" — sources: openalex, semantic-scholar  — combined multi-source review
/novelty-check "idea"          — verify novelty against literature

关键规则

• OpenAlex 完全开放——基本使用无需 API 密钥，但建议使用密钥以获得更高的速率限制
• 全面的元数据——OpenAlex 提供的元数据比大多数来源更丰富（机构、资助、主题）
• 引用数据开放——与 Semantic Scholar 不同，所有引用数据都可免费获取
• 速率限制：不使用 API 密钥时，限制非常严格（约为 $0.01/天）。使用免费 API 密钥时：每天 10,000 次列表调用、1,000 次搜索调用。
• 礼貌池：设置 OPENALEX_EMAIL 环境变量以加快响应速度
• 与其他来源交叉引用：OpenAlex 收录了来自 arXiv、PubMed、Crossref 等来源的论文——使用 DOI/arXiv ID 进行交叉引用
• 如果无法访问 OpenAlex API 或受到速率限制，建议改用 /semantic-scholar、/arxiv 或 /research-lit "topic" — sources: web。

OpenAlex 与其他来源的比较

特性	OpenAlex	Semantic Scholar	arXiv
覆盖范围	2.5 亿+ 作品	2 亿+ 论文	240 万+ 预印本
引用数据	完全开放	部分开放	无
机构	✓ 完整隶属关系	✓ 有限	✗
资助	✓ NSF、NIH 等	✗	✗
开放获取	✓ 完整 OA 状态	✓ PDF 链接	✓ 所有论文
API 密钥	可选（免费）	可选（免费）	无需
速率限制	每天 1,000 次搜索（免费密钥）	未知	每 3 秒 1 次请求
摘要	✓ 完整文本	✓ TLDR	✓ 完整文本
最适用场景	全面元数据、机构、资助	引用次数、出版场所信息	最新预印本

优先使用 OpenAlex 而非 S2 的情况：

• 需要机构隶属关系数据
• 需要资助信息
• 希望使用完全开放的引用图谱
• 需要全面的主题／关键词元数据
• 研究计算机科学以外的领域（OpenAlex 覆盖所有学科）

优先使用 S2 而非 OpenAlex 的情况：

• 需要实时引用次数（S2 更新更快）
• 需要“高影响力引用”指标
• 需要论文推荐
• 研究侧重计算机科学／AI（S2 对计算机科学的覆盖更好）