aminer-academic-search

AMiner 开放平台学术数据查询

29 个 API + 6 个工作流。需要令牌：设置 AMINER_API_KEY 环境变量。

• 文档：https://open.aminer.cn/open/docs | 控制台：https://open.aminer.cn/open/board?tab=control

---

强制规则（重要）

1. 令牌安全：只检查 AMINER_API_KEY 是否存在；绝不在任何地方以纯文本形式暴露令牌。
2. 成本控制：优先采用最优的组合查询；绝不不加选择地检索全部详细信息。用户未指定数量时，默认提供前 10 条详细信息。
3. 免费优先：除非用户明确需要更深入的字段，否则优先使用免费 API；只有免费 API 无法满足需求时，才升级到付费 API。
4. 结果链接：输出中的每个实体后都必须附上可访问的 URL。
5. 消歧：学者存在歧义时 → 按 org/org_id 筛选或请用户确认。机构存在歧义时 → 使用 org_disambiguate_pro。论文存在歧义时 → 交叉核对 year + venue_name + first_author。
6. 费用报告：完成所有 API 调用后，始终向用户输出费用汇总，列出每个已调用的 API、单价、调用次数和总费用。格式示例：[Cost] ¥X.XX total, N API calls (api_a: ¥X.XX × N, api_b: Free × N)。
7. 高额费用确认（≥ ¥5）：执行预估总费用为 ¥5.00 或更高的工作流或调用链之前，先停止并征求用户确认。展示计划的调用链、每一步的预估费用和总费用。只有用户明确同意后才能继续。此规则适用于预定义工作流（例如，学者画像约 ¥6.00）和临时多步计划。
8. 实验数据意图边界：只有当用户明确要求实验级数据、Experiment JSON、方法、数据集或结构化实验结果时，才调用 experiment_search。绝不要将它用于常规论文搜索、摘要/引用查询、学者/机构/会议/专利请求、宽泛主题搜索或默认的论文深度分析工作流。

实体 URL 模板（必须使用）：

• 论文：https://www.aminer.cn/pub/{paper_id}
• 学者：https://www.aminer.cn/profile/{scholar_id}
• 专利：https://www.aminer.cn/patent/{patent_id}
• 期刊：https://www.aminer.cn/open/journal/detail/{journal_id}

---

令牌检查（必需）

任何 API 调用前，都要检查 AMINER_API_KEY 是否存在。绝不要以纯文本形式暴露令牌。

[ -z "${AMINER_API_KEY+x}" ] && echo "AMINER_API_KEY missing" || echo "AMINER_API_KEY exists"

• 如果 ${AMINER_API_KEY} 存在：继续。如果不存在：检查 --token 参数。如果两者都没有：停止，引导用户前往控制台生成令牌。
• 如果用户直接提供 AMINER_API_KEY（例如“我的令牌是 xxx”），则在当前会话中接受该令牌，但建议用户将其设置为环境变量以提高安全性。
• 默认请求头：Authorization: ${AMINER_API_KEY}、X-Platform（当前主机：claude-code / cursor / codex / openclaw；如果无法确定则为 unknown）、X-Skill-Name: aminer-academic-search、X-Skill-Version（此文件 frontmatter 中的 version）、Content-Type: application/json;charset=utf-8（POST）。始终发送 X-Platform 和两个 X-Skill-* 请求头。

---

调用规范

1. 参数名称和类型必须与 references/api-catalog.md 完全一致。
2. paper_info 仅支持批量查询：{"ids": [...]}。paper_detail 仅支持单篇论文查询：一个 id。绝不要混用。
3. 需要多条详细信息时，先使用低成本 API 筛选，再获取少量结果的详细信息。
4. 根据查询形式选择 API，而非习惯性选择。 请参阅“论文搜索 API 选择指南”。短语查询使用免费的 paper_search；批量查询使用带 size 参数的 paper_search_pro。在为 paper_qa_search_pro 花费 ¥0.30 之前，必须能指出四种原因之一——句子、范围筛选、布尔排除或精确优先；如果无法指出，就改用低成本 API。绝不要向 paper_search_pro 发送句子：它会返回 0 条结果，但仍会计费。

---

论文搜索 API 选择指南

当用户说“搜索论文”时，不要猜测其意图。请查看两个可直接观察的事实：查询字符串是短语还是句子，以及需要多少条结果。

API	接受的输入	仅此 API 能做到的事	硬性限制	费用
paper_search	短语	免费	仅限 title 字段；size ≤ 20；不支持筛选和排序	免费
paper_search_pro	短语，可指定字段（title/keyword/abstract/author/org/venue）	每页 100 条 + 硬排序（order=year|n_citation）；批量搜索最便宜	传入句子会返回 0 条，但仍会收费	¥0.01
paper_qa_search	短语或句子	加权嵌套 AND/OR（topic_high/middle/low）、sci_flag、offset 最多可到 10000	不支持年份/引用数范围筛选和布尔排除	¥0.05
paper_qa_search_pro	句子、口语化问题或中文问题	语义解析 + 年份/引用数范围 + all/any/exclude 布尔条件 + sort 模式；检索质量最佳	每页固定 10 条；每多取一页需再支付 ¥0.30	¥0.30
paper_list_by_keywords	多个关键词	批量主题检索	—	¥0.10
paper_detail_by_condition	年份 + venue	直接返回详情	—	¥0.20

两条决策规则

1. 查询是不是句子（包含谓语或疑问词）？是 → 只有 paper_qa_search_pro / paper_qa_search 能解析；另外两个会返回 0 条，而 paper_search_pro 仍会就这 0 条结果收费。否 → 从免费的 paper_search 开始，只有结果不够时才升级。
2. **是否需要超过 10 条结果？**是 → 不要使用 paper_qa_search_pro；使用 paper_search_pro 并设置 size（≤100）。

**费用差距——务必牢记。**获取 100 条结果：paper_search_pro 设置 size=100，调用一次只需 ¥0.01；paper_qa_search_pro 则需要翻 10 页，共 ¥3.00。相差 300 倍。

支付 ¥0.30 的硬性规则

调用 paper_qa_search_pro 之前，你必须至少能指出以下一种理由。如果无法指出，就改用 paper_search_pro。

1. 句子——查询是自然语言句子或问题，因此按字面匹配的端点会返回 0 条。
2. 范围筛选——需要使用 year_from/year_to 或 min_citations/max_citations。其他端点只能列出指定年份，无法表达范围。
3. 布尔排除——需要使用 all_terms / any_terms / exclude_terms。
4. 优先考虑准确性——用户明确要求结果准确或匹配度最高，或者较便宜的端点已返回偏题结果。这是四种 API 中检索质量最高的；直接使用它，不要为了省 ¥0.29 而反复尝试。旧版 paper_qa_search 也能解析句子，但结果容易偏向主导词：在 how do LLM agents implement long-term memory 这一查询的测试中，Pro 返回的 4/4 条结果都专门讨论 Agent 长期记忆，而旧版仅有 1/5 条符合，其余都是泛泛介绍“基于 LLM 的 Agent”的综述。

以上四项都不符合 = 白白多花 30 倍费用。改用更低成本的 API。

paper_qa_search_pro 的重要规则：

• 使用自然语言 query 字段（query_type="auto"，这是默认值），并将用户的原始问题作为完整句子传入。不要提前将问题拆成关键词，再用 all_terms 重新拼装——拆分会丢失你付费获得的语义理解能力，准确度还不如直接提问。只有确实需要按字面匹配词语时，才改用 query_type="topic"。
• 每页大小固定为 10。不要发送 size。使用 next_cursor 翻页 → 下一次请求的请求体只需 {"cursor":"..."}。
• sort：relevance / balanced / recent / citation。“引用数最多”使用 citation；“最新”使用 recent。
• 响应卡片仅包含以下字段：paper_id、title、title_zh、authors.name/name_zh、n_citation_bucket、venue_name、year。需要完整摘要/关键词时，使用 paper_detail。
• 始终附上 https://www.aminer.cn/pub/{paper_id}。 旧版 paper_qa_search——只有它能做到的事情：
• 加权嵌套 AND/OR：topic_high / topic_middle / topic_low 提供三个加权层级。Pro 没有同等功能。适用于“必须包含 A，大幅提高 B 的权重，略微提高 C 的权重”。
• 深度分页：size ≤ 100，且 offset ≤ 10000——¥0.05 可获取 100 条结果。Pro 的游标无法做到这一点（每页 10 条 × ¥0.30）。
• sci_flag 可将搜索范围限定为 SCI 论文；Pro 没有此筛选条件。
• query 与 topic_high/topic_middle/topic_low 互斥；不要同时传入。
• 响应现在还包含 first_author、venue_name、year、n_citation_bucket——付费调用 paper_detail 前，先用这些字段筛选。

实验检索选择：

• 仅当用户明确要检索实验级信息时，才使用 experiment_search（¥0.10/次调用）。
• 精确筛选条件：paper_id、method、dataset_name（→ 后端 dataset）。
• 自由文本（论文标题、实验名称、问题/方法/结论等）→ search_text（针对 paper_title、experiment_name、research_problem、research_problem_description、research_goal、方法名称/描述文本、conclusion、limitations、key_results 进行 ES 搜索）。
• 响应结构：每条结果都包含 methods: [{name, description, ...}]（一个列表）；部分较早的记录可能仍包含扁平的 method / method_description。原样返回对象——优先读取 methods，绝不要将列表扁平化为单个 method 字符串。
• 不要调用 paper_search 来解析标题；不要单独传入 experiment_name 参数。
• paper_id、method、dataset_name、search_text 中至少有一个非空。只做修剪；不要编造字段。
• 原始 JSON 请求返回 { "results": [...] }，不会改写 Experiment 对象。

免费层级可用的筛选字段：

• paper_search：venue_name、first_author、n_citation_bucket、year
• paper_info：abstract_slice、year、venue_id、author_count
• person_search：interests、n_citation、org/org_id
• organization_search：aliases
• venue_search：aliases、venue_type
• patent_search：inventor_name、app_year、pub_year
• patent_info：app_year、pub_year

三个论文搜索端点（paper_search、paper_search_pro、paper_qa_search）现在都返回相同的筛选字段集——first_author、venue_name、year、n_citation_bucket；paper_qa_search_pro 则返回 authors、venue_name、year、n_citation_bucket。调用 paper_detail（每条 ¥0.01）前，先用这些字段筛选；只获取你实际会引用的论文的详细信息。n_citation_bucket 是粗略分档，不是精确计数——不要对分档进行数值比较，也不要据此声称精确的引用次数。

---

处理工作流之外的请求

当用户的请求不属于这 6 个工作流时：

1. 阅读 references/api-catalog.md，确认可用的 API、参数和响应字段。
2. 设计最短的可行调用链：定位 ID → 补充详情 → 扩展关系。
3. 不要因为“没有适用的现成工作流”就放弃；应根据 api-catalog 主动组合 API。

---

6 个组合工作流

工作流 1：学者档案（约 ¥6.00）

适用场景：完整的学术档案——简介、研究兴趣、论文、专利、项目。 费用说明：完整执行超过 ¥5 阈值 → 必须在继续前征得用户确认（规则 7）。展示计划步骤和费用。确认需要哪些子模块；如果用户未要求，则跳过专利/项目。

调用链：

Scholar search (name → person_id)
    ↓
Parallel calls (pick as needed):
  ├── Scholar details (bio/education/honors)         ¥1.00
  ├── Scholar portrait (interests/work history)      ¥0.50
  ├── Scholar papers (paper list)                    ¥1.50
  ├── Scholar patents (patent list)                  ¥1.50
  └── Scholar projects (funding info)                ¥1.50

回退方案：如果子步骤中的 paper_search 没有返回结果，则回退到 paper_search_pro。

---

工作流 2：论文深入分析（约 ¥0.12）

适用场景：根据标题或关键词获取论文的完整信息和引用链。

调用链：

Paper search / Paper search pro (title/keyword → paper_id)
    ↓
Paper details (abstract/authors/DOI/journal/year/keywords)  ¥0.01
    ↓
Paper citations (cited papers → cited_ids)                  ¥0.10
    ↓
(Optional) Batch paper_info for cited papers                Free

回退方案：如果 paper_search 没有返回结果，则回退到 paper_search_pro。

---

工作流 3：机构分析（约 ¥0.81）

使用场景：了解机构学者规模、论文产出和专利数量，适用于竞争研究或合作评估。

调用链：

Org disambiguation pro (raw string → org_id)  ¥0.05
    ↓
Parallel calls:
  ├── Org details (description/type)             ¥0.01
  ├── Org scholars (scholar list, 10/call)       ¥0.50
  ├── Org papers (paper list, 10/call)           ¥0.10
  └── Org patents (patent IDs, up to 10,000)     ¥0.10

如果机构消歧专业版未返回 ID，则回退到 org_search（免费）。

---

工作流 4：期刊论文（约 ¥0.10 - ¥0.30）

使用场景：按年份追踪期刊论文，适用于投稿研究或趋势分析。

调用链：

Venue search (name → venue_id)                          Free
    ↓
(Optional) Venue details (ISSN/type/abbreviation)       ¥0.20
    ↓
Venue papers (venue_id + year → paper_id list)          ¥0.10
    ↓
(Optional) Batch paper detail query

---

工作流 5：专利分析（约 ¥0.02）

使用场景：搜索某个技术领域的专利，或获取学者／机构的专利组合。

调用链（独立搜索）：

Patent search (query → patent_id)        Free
    ↓
Patent info / Patent details             Free / ¥0.01

调用链（通过学者／机构）：

Scholar search → Scholar patents (patent_id list)
Org disambiguation → Org patents (patent_id list)
    ↓
Patent info / Patent details

---

工作流 6：实验检索（约 ¥0.10）

使用场景：通过用户提供的 paper_id / method / dataset_name / search_text 获取明确的实验 JSON。 费用说明：experiment_search 每次调用 ¥0.10。--dry-run 仅预览 experiment_search。

调用链：

Experiment search (paper_id / method / dataset_name / search_text)

单次 POST；不解析论文标题。返回 { "results": [...] }（或结构化 API 错误）。结果受分页限制（通常 ≤10）。切勿将此工作流加入论文深度分析。不要概述原始 JSON，也不要臆造缺失字段。

---

单个 API 快速参考

完整参数文档：请参阅 references/api-catalog.md

#	标题	方法	价格	API 路径（基址：datacenter.aminer.cn/gateway/open_platform）
1	论文问答搜索专业版	POST	¥0.30	/api/paper/qa/searchPro
2	论文问答搜索（旧版）	POST	¥0.05	/api/paper/qa/search
3	学者搜索	POST	免费	/api/person/search
4	论文搜索	GET	免费	/api/paper/search
5	论文搜索专业版	GET	¥0.01	/api/paper/search/pro
6	专利搜索	POST	免费	/api/patent/search
7	机构搜索	POST	免费	/api/organization/search
8	期刊搜索	POST	免费	/api/venue/search
9	学者详情	GET	¥1.00	/api/person/detail
10	学者项目	GET	¥1.50	/api/project/person/v3/open
11	学者论文	GET	¥1.50	/api/person/paper/relation
12	学者专利	GET	¥1.50	/api/person/patent/relation
13	学者画像	GET	¥0.50	/api/person/figure
14	论文信息	POST	免费	/api/paper/info
15	论文详情	GET	¥0.01	/api/paper/detail
16	论文引用	GET	¥0.10	/api/paper/relation
17	专利信息	GET	免费	/api/patent/info
18	专利详情	GET	¥0.01	/api/patent/detail
19	机构详情	POST	¥0.01	/api/organization/detail
20	机构专利	GET	¥0.10	/api/organization/patent/relation
21	机构学者	GET	¥0.50	/api/organization/person/relation
22	机构论文	GET	¥0.10	/api/organization/paper/relation
23	期刊详情	POST	¥0.20	/api/venue/detail
24	期刊论文	POST	¥0.10	/api/venue/paper/relation
25	机构消歧	POST	¥0.01	/api/organization/na
26	机构消歧专业版	POST	¥0.05	/api/organization/na/pro
27	论文批量查询	GET	¥0.10	/api/paper/list/citation/by/keywords
28	按年份和期刊查询论文详情	GET	¥0.20	/api/paper/platform/allpubs/more/detail/by/ts/org/venue
29	实验搜索	POST	¥0.10	/api/v3/paper/search/experiment_data/SearchPro

---

参考资料

• 完整 API 参数文档：请参阅 references/api-catalog.md
• 可选 Python 客户端：scripts/aminer_client.py
• 测试用例：evals/evals.json
• 官方文档：https://open.aminer.cn/open/docs
• 控制台：https://open.aminer.cn/open/board?tab=control