aminer-academic-search

AMiner 开放平台学术数据查询

30 个 API + 6 个工作流。需要 Token：设置 AMINER_API_KEY 环境变量。

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

---

强制规则（重要）

1. Token 安全：仅检查 AMINER_API_KEY 是否存在；绝不要以明文形式在任何地方泄露 Token。
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.50）和临时制定的多步骤计划。
8. 实验数据意图边界：仅当用户明确要求实验级数据、Experiment JSON、方法、数据集或结构化实验结果时，才调用 experiment_search。绝不要将它用于常规论文搜索、摘要/引文查询、学者/机构/会议/专利请求、宽泛主题搜索或默认的 Paper Deep Dive 工作流。

实体 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}

---

Token 检查（必需）

在任何 API 调用之前检查 AMINER_API_KEY 是否存在。绝不要以明文形式泄露 Token。

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

• 如果 ${AMINER_API_KEY} 存在：继续。如果不存在：检查 --token 参数。如果两者都没有：停止，引导用户前往控制台生成 Token。
• 如果用户在消息中直接提供 AMINER_API_KEY（例如“我的 Token 是 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（免费卡片）和 paper_detail（每篇返回的论文收费 ¥0.01，提供完整详情）都接受 {"ids": [...]}（≤100）。请在一次 paper_detail 调用中获取多篇论文的详情，而不是每篇论文调用一次。
3. 需要多篇论文的详情时，先使用低成本 API 筛选，再获取少量论文的详情。
4. 逐级攀升搜索阶梯，每次只升一级。 请参阅“论文搜索 API 选择指南”。从免费版 paper_search 开始；只有当前级别缺少所需参数时才升级。在花费 ¥0.30 调用 paper_qa_search_pro 之前，必须能说出四个理由之一——复杂问题、引用次数范围、布尔排除或精确优先；如果说不出，就降级。年份范围绝不是理由：paper_search 和 paper_search_pro 都接受 year_from/year_to。

---

论文搜索 API 选择指南

四个论文搜索端点构成一条升级阶梯。选择包含所需参数的最低级别。

级别	API	提供的功能	硬性限制	费用
1	paper_search	单个搜索框 query（标题 + 关键词）；year / year_from / year_to	≤20 条/页，≤10 页；无单字段条件、无排序	免费
2	paper_search_pro	包含级别 1 的全部功能，另提供按字段搜索 title/keyword/abstract/author/org/venue、order=year|n_citation、≤100 条/页 — 批量检索成本最低	—	¥0.01
3	paper_qa_search	服务端从 query 提取关键词；加权主题 topic_high/middle/low；作者/机构/期刊 ID 筛选；doi；sci_flag；offset ≤ 10000	仅支持精确 year 列表，不支持范围；不支持布尔排除	¥0.05
4	paper_qa_search_pro	自然语言理解；年份和引用次数范围；all/any/exclude；sort 模式；完整的 authors 列表；检索质量最佳	固定每页 10 条；每增加一页需再付 ¥0.30	¥0.30
—	paper_list_by_keywords	批量主题检索	—	¥0.10
—	paper_detail_by_condition	按年份 + 期刊筛选，直接返回详情	—	¥0.20

升级规则

1. 从 paper_search 开始。 短语、已知标题或简短句子都能返回结果；要搜索时间范围，请添加 year_from/year_to。
2. 需要按字段条件（作者、机构、期刊、摘要）筛选、排序或每页超过 20 条吗？ → paper_search_pro。
3. 需要按作者/机构/期刊 ID 筛选、按 DOI 筛选、仅查 SCI，或使用加权主题级别吗？ → paper_qa_search。
4. 需要理解复杂问题、按引用次数范围筛选、布尔排除，或优先精确匹配吗？ → paper_qa_search_pro。

成本断崖——请牢记。 获取 100 条结果：使用 size=100 的 paper_search_pro，一次调用只需 ¥0.01；paper_qa_search_pro 则需要 10 个游标分页，费用为 ¥3.00。相差 300 倍。 批量检索绝不要使用级别 4。

¥0.30 费用的硬性规则

调用 paper_qa_search_pro 之前，必须能说出至少一个以下理由。如果说不出，就降级。

1. 复杂问题——仅靠词语匹配无法捕捉含义的自然语言问题（涉及多个概念或关系、口语表达或中文措辞），或者更便宜的级别已返回不相关的结果。
2. 引用次数范围——需要 min_citations/max_citations。（paper_search / paper_search_pro 支持年份范围，这不是升级理由。）
3. 布尔排除——需要 all_terms / any_terms / exclude_terms。
4. 优先精确匹配——用户明确要求准确或最匹配的结果。在 how do LLM agents implement long-term memory 这个问题上进行的测评中，Pro 返回的 4 条结果全部与 Agent 长期记忆有关，而旧版 paper_qa_search 返回的 5 条结果中只有 1 条相关。

四个理由都不适用 = 白白多花 30 倍费用。请降级。 Key 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、doi、authors.name / name_zh、n_citation_bucket、venue_name、year。需要完整摘要/关键词或精确引用次数（n_citation）时，使用 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 条结果，paper_qa_search_pro 的游标分页无法与之匹配（每页 10 条 × ¥0.30）。单纯追求数量时，paper_search_pro 更便宜（每 100 条 ¥0.01）。
• sci_flag 可限定为 SCI 论文；Pro 没有此筛选条件。
• query 与 topic_high/topic_middle/topic_low 不能同时使用；不要同时传入。query 和 topic_* 都需要 use_topic: true。
• 响应包含 doi、first_author、venue_name、venue_id、year、n_citation_bucket——先依据这些字段筛选，再为 paper_detail 付费。

实验检索选择：

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

免费层可用的筛选字段：

• paper_search：doi、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 返回相同的筛选字段集——doi、first_author、venue_name、year、n_citation_bucket；paper_qa_search 还会返回 venue_id（关联时的 venue 实体 ID——可用于 venue API）；paper_qa_search_pro 会返回完整的 authors 列表，以及 doi、venue_name、year、n_citation_bucket。调用 paper_detail（每篇返回的论文 ¥0.01，未找到 ID 则免费）之前，先依据这些字段筛选；仅获取确实要引用的论文的详情，并一次调用完成。n_citation_bucket 是粗略分级，绝非精确数量——不要对分级进行数值比较，也不要据此声称精确的引用次数；paper_detail 会返回精确的 n_citation。

处理工作流之外的请求

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

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

---

6 个组合工作流

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

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

调用链：

Scholar search (name → person_id)
    ↓
Parallel calls (pick as needed):
  ├── Scholar details (bio/education/honors)         ¥1.00
  ├── Scholar statistics (h-index/g-index/citations) ¥0.50
  ├── 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

---

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

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

调用链：

Paper search / Paper search pro (title/keyword → paper_id)
    ↓
Paper details (abstract/authors/DOI/journal/year/keywords/n_citation)  ¥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, 100 per page)     ¥0.10

如果消歧 pro 没有返回 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 显式获取 Experiment 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	论文问答搜索 Pro	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	论文搜索 Pro	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	论文详情（≤100 个 ID）	POST	¥0.01/篇返回的论文	/api/paper/detail/batch
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	机构消歧 Pro	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
30	学者统计	POST	¥0.50	/api/person/stat

---

参考资料

• 完整的 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