pp-openalex

Openalex — Printing Press CLI

前置条件：安装 CLI

此技能使用 openalex-pp-cli 二进制文件。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，默认将二进制文件安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install openalex --cli-only
   

2. 验证：openalex-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/other/openalex/cmd/openalex-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功前，请勿继续使用此技能中的命令。

不要使用此 CLI 的情况

对于需要创建、更新、删除、发布、评论、点赞、邀请、订购、发送消息、预订、购买或更改远程状态的请求，请勿启用此 CLI。此打印版 CLI 仅提供用于检查、导出、同步和分析的只读命令。

独特功能

这些功能在此 API 的其他工具中均不可用。

研究图谱检索

• works list — 使用精简 JSON、字段选择、筛选、排序和实时 API 回退功能搜索学术作品。
• authors list — 搜索作者并检索规范的 OpenAlex 作者记录，用于引文和合作者研究。
• institutions list — 搜索机构并获取国家/类型元数据，用于隶属关系和生态系统分析。
• sources list — 搜索期刊、知识库和出版场所，并获取精简的、面向 Agent 的输出。
• topics list — 探索 OpenAlex 主题，用于发现研究领域和后续筛选。

命令参考

authors — 学术作品的创作者

• openalex-pp-cli authors get — 按 OpenAlex ID 或 ORCID 检索单个作者。
• openalex-pp-cli authors list — 获取作者列表，可选择筛选、搜索、排序和分页。

autocomplete — 对任意实体类型进行快速联想搜索

• openalex-pp-cli autocomplete — 快速联想搜索，最多返回 10 条结果。适用于搜索即输入界面。

awards — 研究资助和资金奖项

• openalex-pp-cli awards get — 按 OpenAlex ID 检索单个奖项。
• openalex-pp-cli awards list — 获取研究资助和资金奖项列表。

changefiles — 管理变更文件

• openalex-pp-cli changefiles get — 获取指定日期变更文件的详细信息，包括发生变更的实体类型、记录数量和下载...
• openalex-pp-cli changefiles list — 列出所有可用的变更文件日期。每个日期都有可下载的文件，其中包含每条实体记录...

concepts — 研究领域的旧版分类体系（已弃用——请改用 Topics）

• openalex-pp-cli concepts get — **已弃用：**请改用 Topics。按 OpenAlex ID 检索单个概念。
• openalex-pp-cli concepts list — **已弃用：**请改用 Topics。获取旧版分类体系中的概念列表。

continents — 地理洲（共 7 个）

• openalex-pp-cli continents get — 按 Wikidata Q-ID 检索单个洲。
• openalex-pp-cli continents list — 获取洲列表（共 7 个）。

countries — 用于按地理位置筛选研究的国家

• openalex-pp-cli countries get-country — 按 ISO 3166-1 alpha-2 代码检索单个国家。
• openalex-pp-cli countries list — 获取国家列表。可用于按作者隶属机构所在国家筛选作品。

domains — 主题层级中的顶级类别（共 4 个）

• openalex-pp-cli domains get — 按 ID（1-4）检索单个领域。
• openalex-pp-cli domains list — 获取领域列表（顶层主题类别）。领域仅有 4 个：生命科学、社会科学……

fields — 主题层级中的第二级类别（共 26 个）

• openalex-pp-cli fields get — 按 ID 检索单个领域类别。
• openalex-pp-cli fields list — 获取领域类别列表（第二级主题类别）。26 个领域类别分布在 4 个领域中。

funders — 为研究提供资助的组织

• openalex-pp-cli funders get — 按 OpenAlex ID 或 Crossref Funder ID 检索单个资助方。
• openalex-pp-cli funders list — 获取资助方列表，并可选择筛选、搜索、排序和分页。

institution-types — 机构类型（教育、医疗保健、公司等）

• openalex-pp-cli institution-types — 获取机构类型列表（教育、医疗保健、公司等）。

institutions — 大学、研究组织及其他所属机构

• openalex-pp-cli institutions get — 按 OpenAlex ID 或 ROR 检索单个机构。
• openalex-pp-cli institutions list — 获取机构列表，并可选择筛选、搜索、排序和分页。

keywords — 从作品主题中识别出的短语

• openalex-pp-cli keywords get — 按 OpenAlex ID 检索单个关键词。
• openalex-pp-cli keywords list — 获取关键词列表，并可选择筛选、搜索、排序和分页。

languages — 学术作品使用的语言

• openalex-pp-cli languages get — 按 ISO 639-1 代码检索单种语言。
• openalex-pp-cli languages list — 获取学术作品中使用的语言列表。

licenses — 开放获取许可证（CC BY、CC BY-SA 等）

• openalex-pp-cli licenses — 获取开放获取许可证列表（CC BY、CC BY-SA 等）。

publishers — 出版学术作品的公司和组织

• openalex-pp-cli publishers get — 按 OpenAlex ID 检索单个出版商。
• openalex-pp-cli publishers list — 获取出版商列表，并可选择筛选、搜索、排序和分页。

rate-limit — 管理速率限制

• openalex-pp-cli rate-limit — 检查当前速率限制状态，包括使用情况和剩余额度。

sdgs — 联合国可持续发展目标（共 17 项）

• openalex-pp-cli sdgs get — 按 ID（1-17）检索单个可持续发展目标。
• openalex-pp-cli sdgs list — 获取联合国可持续发展目标列表。共有 17 项可持续发展目标。

source-types — 来源类型（期刊、知识库、会议等）

• openalex-pp-cli source-types — 获取来源类型列表（期刊、知识库、会议等）。

sources — 作品发布所在的期刊、知识库及其他平台

• openalex-pp-cli sources get — 按 OpenAlex ID 或 ISSN 检索单个来源。
• openalex-pp-cli sources list — 获取来源列表（期刊、知识库、会议），并可选择筛选、搜索、排序和分页。

subfields — 主题层级中的第三级类别（共 254 个）

• openalex-pp-cli subfields get — 按 ID 检索单个子领域类别。
• openalex-pp-cli subfields list — 获取子领域类别列表（第三级主题类别）。254 个子领域类别分布在 26 个领域类别中。

text — 管理文本

• openalex-pp-cli text — **已弃用：**此端点已弃用，不建议在新项目中使用。它将不会收到更新或……

topics — 自动分配给作品的研究主题

• openalex-pp-cli topics get — 按 OpenAlex ID 检索单个主题。
• openalex-pp-cli topics list — 获取主题列表，并可选择筛选、搜索、排序和分页。主题是研究领域……

work-types — 学术作品类型（文章、书籍、数据集等）

• openalex-pp-cli work-types — 获取作品类型列表（文章、书籍、数据集等）。 works — 期刊文章、书籍、数据集和论文等学术文献

• openalex-pp-cli works get — 按 OpenAlex ID 或外部 ID（DOI、PMID、PMCID、MAG ID）检索单篇文献。外部 ID 可以按以下方式传入……

• openalex-pp-cli works list — 获取学术文献列表，可选择筛选、搜索、排序和分页。文献包括期刊……

查找合适的命令

当你知道想做什么，但不知道该用哪个命令时，可以直接询问 CLI：

openalex-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示无法有把握地找到匹配项——请改用 --help 或缩小查询范围。

身份验证设置

通过环境变量设置 API 密钥：

export OPENALEX_API_KEY="<your-key>"

或者将其保存到 ~/.config/openalex-pp-cli/config.toml。

运行 openalex-pp-cli doctor 验证设置。

Agent 模式

将 --agent 添加到任意命令。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传递 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留一部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于输出冗长的 API，这对控制上下文大小至关重要：

  openalex-pp-cli authors list --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不会发送

• 适合离线使用 — 有本地 SQLite 存储时，同步/搜索命令可以使用该存储

• 非交互式 — 从不提示输入，所有输入都通过标志传入

• 只读 — 请勿使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、订购、发送或其他会更改数据的请求

响应封装

从本地存储或 API 读取数据的命令会将输出封装在来源信息中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 以确认数据来自实时 API 还是本地存储。只有当 stdout 指向终端时，才会将人类可读的 N results (live) 摘要输出到 stderr——通过管道接收的程序/Agent 会在 stdout 上获得纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有异常之处时，请记录下来：

openalex-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
openalex-pp-cli feedback --stdin < notes.txt
openalex-pp-cli feedback list --json --limit 10

条目会保存在本地 ~/.openalex-pp-cli/feedback.jsonl。除非设置了 OPENALEX_FEEDBACK_ENDPOINT，且传入了 --send 或设置了 OPENALEX_FEEDBACK_AUTO_SEND=true，否则不会发送 POST 请求。默认行为仅保存在本地。

记录让你感到意外的地方，而不是提交错误报告。简短、具体、单行描述：这才是能不断积累价值的部分。

输出传递

每条命令都接受 --deliver <sink>。除了 stdout（或替代 stdout）之外，输出还会发送到指定的接收目标，这样 Agent 无需手动通过管道传递，也能路由命令结果。支持三种接收目标：

接收目标	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到 URL（使用 --compact 时，内容类型为 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回结构化错误，说明支持的方案。Webhook 请求失败时会返回非零退出代码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置是已保存的一组标志值，可在多次调用中重复使用。如果定时运行的 Agent 每次都以相同配置调用同一命令，可以使用配置——这就是 HeyGen 的“Beacon”模式。

openalex-pp-cli profile save briefing --json
openalex-pp-cli --profile briefing authors list
openalex-pp-cli profile list --json
openalex-pp-cli profile show briefing
openalex-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便进行自省的 Agent 在运行时发现这些配置。

退出代码

代码	含义
0	成功
2	用法错误（参数不正确）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（请稍后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 openalex-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的前提条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并带上 --agent）

MCP 服务安装

从此 CLI 发布的公共库条目或预构建版本安装 MCP 二进制文件，然后注册：

claude mcp add openalex-pp-mcp -- openalex-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which openalex-pp-cli 如果未找到，则提供安装选项（参见此技能顶部的前提条件）。
2. 根据用户查询，从上文的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   openalex-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，则查看子命令帮助：openalex-pp-cli <command> --help。