aminer-data-search

使用AMiner开放平台API进行学术数据查询和分析。当用户需要查找学者简介、论文详细信息、机构数据、期刊内容或专利信息时，请使用此技能。 触发场​​景：AMiner提及、学术数据查询、论文/学者/机构/期刊/专利检索、学术问答检索、引文分析、研究机构分析、学者画像、论文引用链、期刊投稿分析等。 支持 6 种组合工作流程（学者简介、论文深度探究、组织分析、场地论文、论文 QA 搜索、专利分析）以及对所有 28 个单独 API 的直接调用。 即使用户只是简单地说“查找学者XXX”或“查找有关XXX的论文”，也要主动使用此技能。

## 概述（中文）

使用AMiner开放平台API进行学术数据查询和分析。当用户需要查找学者简介、论文详细信息、机构数据、期刊内容或专利信息时，请使用此技能。
触发场​​景：AMiner提及、学术数据查询、论文/学者/机构/期刊/专利检索、学术问答检索、引文分析、研究机构分析、学者画像、论文引用链、期刊投稿分析等。
支持 6 种组合工作流程（学者简介、论文深度探究、组织分析、场地论文、论文 QA 搜索、专利分析）以及对所有 28 个单独 API 的直接调用。
即使用户只是简单地说“查找学者XXX”或“查找有关XXX的论文”，也要主动使用此技能。

## 原文

# AMiner Open Platform Academic Data Query

AMiner is a globally leading academic data platform that provides comprehensive academic data covering scholars, papers, institutions, journals, patents, and more.
This skill covers all 28 open APIs and organizes them into 6 practical workflows.
Before use, please generate a token in the console and set it as the environment variable `AMINER_API_KEY` for automatic script access.

- **API Documentation**: https://open.aminer.cn/open/docs
- **Console (Generate Token)**: https://open.aminer.cn/open/board?tab=control

---

## High-Priority Mandatory Rules (Critical)

The following four rules are the **highest priority** and must be followed in any query task:

1. **Token Security**: Only check whether `AMINER_API_KEY` exists; never expose the token in plain text in any location (including terminal output, logs, example results, or debug information).
2. **Cost Control**: Always prefer the optimal combined query; never perform indiscriminate full-detail retrieval. When many results are matched and the user has not specified a count, default to fetching details for only the top 10 results.
3. **Free-First**: Prefer free APIs unless the user explicitly requires deeper fields or higher precision; only upgrade to paid APIs when free ones cannot meet the need.
4. **Result Links**: Whenever this skill is used and the result contains entities (papers/scholars/patents/journals), an accessible URL must be appended after each entity, regardless of the scenario or output format.

Entity URL templates (mandatory):
- Paper: `https://www.aminer.cn/pub/{paper_id}`
- Scholar: `https://www.aminer.cn/profile/{scholar_id}`
- Patent: `https://www.aminer.cn/patent/{patent_id}`
- Journal: `https://www.aminer.cn/open/journal/detail/{journal_id}`

> Enforcement note: This rule applies to all returned results (including summaries, lists, details, comparative analyses, workflow outputs, and raw output transcriptions). Whenever an entity appears and a usable ID is available, a link must be attached.

> Violating any of the above rules is considered a process non-compliance; execution must be immediately halted and corrected before continuing.

---

## Step 1: Check Environment Variable Token (Required)

Before making any API call, you must first check whether the environment variable `AMINER_API_KEY` exists (request headers must include both: `Authorization: <your_token>` and `X-Platform: openclaw`).
Only determine whether it "exists / does not exist"; never output, echo, or log the token in plain text (including logs, terminal output, or example results).

**Standard check (recommended for direct use):**
```bash
if [ -z "${AMINER_API_KEY+x}" ]; then
    echo "AMINER_API_KEY does not exist"
else
    echo "AMINER_API_KEY exists"
fi
```

- **If the token already exists in the environment variable**: proceed with the subsequent query workflow.
- **If no token is in the environment variable**: check whether the user has explicitly provided `--token`.
- **If neither the environment variable nor `--token` is available**: stop immediately; do not call any API or enter any subsequent workflow; guide the user to obtain a token first.

**Recommended token configuration (preferred):**
1. Go to the [AMiner Console](https://open.aminer.cn/open/board?tab=control), log in, and generate an API Token.
2. Set the token as an environment variable: `export AMINER_API_KEY="<TOKEN>"`
3. The script reads the environment variable `AMINER_API_KEY` by default (if `--token` is explicitly provided, it takes precedence).

**Guidance when no token is available:**
1. Clearly inform the user: "A token is currently missing; AMiner API calls cannot continue."
2. Direct the user to the [AMiner Console](https://open.aminer.cn/open/board?tab=control) to log in and generate an API Token.
3. For assistance, refer to the [Open Platform Documentation](https://open.aminer.cn/open/docs).
4. Prompt the user to continue after obtaining a token; they can reply directly: `Here is my token: <TOKEN>`

> The token can be generated in the console and reused within its validity period. Do not execute any data query steps before obtaining a token.

---

## Quick Start (Python Script)

All workflows can be driven through `scripts/aminer_client.py`:

```bash
# Recommended: set the environment variable first (no need to pass --token repeatedly)
export AMINER_API_KEY="<TOKEN>"

# Scholar profile analysis
python scripts/aminer_client.py --action scholar_profile --name "Andrew Ng"

# Paper deep dive (with citation chain)
python scripts/aminer_client.py --action paper_deep_dive --title "Attention is all you need"

# Institution research capability analysis
python scripts/aminer_client.py --action org_analysis --org "Tsinghua University"

# Journal paper monitoring (specify year)
python scripts/aminer_client.py --action venue_papers --venue "Nature" --year 2024

# Academic Q&A (natural language query)
python scripts/aminer_client.py --action paper_qa --query "latest advances in transformer architecture"

# Patent search and details
python scripts/aminer_client.py --action patent_search --query "quantum computing"
```

You can also call a single API directly:
```bash
python scripts/aminer_client.py --action raw \
  --api paper_search --params '{"title": "BERT", "page": 0, "size": 5}'

# Or temporarily override the environment variable by explicitly passing --token
python scripts/aminer_client.py --token <TOKEN> --action raw \
  --api paper_search --params '{"title": "BERT", "page": 0, "size": 5}'
```

**Raw mode error-prevention rules (mandatory):**
1. Before calling, verify the function signature (parameter names and types must match exactly); never "guess parameters by semantics".
2. Raw parameter constraints are governed by `references/api-catalog.md`; if it conflicts with prior knowledge, the catalog always takes precedence.
3. `paper_info` is only for batch basic information; the parameter must be `{"ids": [...]}`.
4. `paper_detail` only supports single-paper details; the parameter must be `{"paper_id": "..."}`. **Never** pass `ids`.
5. When multiple paper details are needed: first use low-cost interfaces for filtering (e.g., `paper_info` / `paper_search_pro`), then call `paper_detail` only for the target subset (default top 10 if the user has not specified a count).
6. Before executing, output "the function name to be called + parameter JSON" for self-inspection, then make the request.

---

## Stability and Failure Handling Strategy (Must Read)

The client `scripts/aminer_client.py` has built-in request retry and fallback strategies to reduce the impact of network fluctuations and transient service errors on results.

- **Timeout and Retry**
  - Default request timeout: `30s`
  - Maximum retries: `3`
  - Backoff strategy: exponential backoff (`1s -> 2s -> 4s`) + random jitter
- **Retryable Status Codes**
  - `408 / 429 / 500 / 502 / 503 / 504`
- **Non-Retryable Scenarios**
  - Common `4xx` errors (e.g., parameter errors, authentication issues) are not retried by default; an error structure is returned directly.
- **Workflow Fallback**
  - `paper_deep_dive`: automatically falls back to `paper_search_pro` if `paper_search` yields no results.
  - `paper_qa`: automatically falls back to `paper_search_pro` if the `query` mode yields no results.
- **Traceable Call Chain**
  - Combined workflow output includes `source_api_chain`, marking which APIs were combined to produce the result.

---

## Paper Search API Selection Guide

When the user says "search for papers", first determine whether the goal is "find an ID", "filter results", "Q&A", or "generate an analysis report", then select the API:

| API | Focus | Use Cas