158 lines
5.3 KiB
Markdown
Executable File
158 lines
5.3 KiB
Markdown
Executable File
---
|
|
name: aminer-academic-search
|
|
description: >
|
|
ACADEMIC PRIORITY: Activate whenever the user's query involves academic,
|
|
scholarly, or research-related topics — papers, citations, scholars,
|
|
institutions, venues, patents, research trends, or any "who published what /
|
|
where / when" question. Takes precedence over general web search for academic
|
|
data needs. Routes through the z-ai gateway's `/v1/functions/invoke` endpoint
|
|
to the AMiner Open Platform (27 APIs, 5 workflows).
|
|
---
|
|
|
|
# aminer-academic-search
|
|
|
|
Wraps 27 AMiner Open Platform APIs through the local gateway. The gateway owns
|
|
the `AMINER_API_KEY`; the skill only needs a `.z-ai-config` file to reach the
|
|
gateway.
|
|
|
|
## When to activate
|
|
|
|
Any academic/scholarly query — papers, citations, scholars, institutions,
|
|
venues, patents. Covers:
|
|
- Scholar full profile (bio, education, honors, papers, patents, projects)
|
|
- Paper deep dive (full abstract, keywords, authors, citation chain)
|
|
- Multi-condition or semantic paper search
|
|
- Institution research capability analysis
|
|
- Venue annual monitoring
|
|
- Patent deep details (IPC/CPC, assignee, claims)
|
|
|
|
## Config
|
|
|
|
Script reads `.z-ai-config`, in order:
|
|
1. `./.z-ai-config`
|
|
2. `~/.z-ai-config`
|
|
3. `/etc/.z-ai-config`
|
|
|
|
Required fields: `baseUrl`, `apiKey`, `token` (JWT). Optional: `chatId`,
|
|
`userId`.
|
|
|
|
## Invocation
|
|
|
|
```bash
|
|
python3 "{baseDir}/scripts/aminer.py" <ACTION> [--flag value …]
|
|
```
|
|
|
|
The script POSTs to `${baseUrl}/functions/invoke` with
|
|
`Authorization: Bearer ${apiKey}`, `X-Z-AI-From: Z`, `X-Token: ${token}`,
|
|
and prints the upstream JSON result (pretty-formatted).
|
|
|
|
Run `python3 scripts/aminer.py --help` to list actions, or
|
|
`python3 scripts/aminer.py <ACTION> --help` for per-action flags.
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Locate paper_id by title
|
|
python3 scripts/aminer.py paper_search --title "Attention is all you need"
|
|
|
|
# Locate scholar by name + org
|
|
python3 scripts/aminer.py person_search --name "Jie Tang" --org "Tsinghua"
|
|
|
|
# Full paper details
|
|
python3 scripts/aminer.py paper_detail --id 57a4e91aac44365e35c98a1e
|
|
|
|
# Natural-language Q&A search
|
|
python3 scripts/aminer.py paper_qa_search --query "retrieval-augmented generation" --size 5
|
|
|
|
# Venue papers for a given year (body with JSON list param)
|
|
python3 scripts/aminer.py venue_paper_relation --id "53e9ba63b7602d9702f08c5d" --year 2024 --limit 10
|
|
```
|
|
|
|
JSON-typed flags (`--title`, `--ids`, `--keywords`, `--year` on qa_search, etc.)
|
|
expect a JSON-encoded value, e.g. `--ids '["abc","def"]'`.
|
|
|
|
## 27 APIs (quick reference)
|
|
|
|
| Action | Method | Purpose |
|
|
|---|---|---|
|
|
| paper_search | GET | Locate paper_id by title |
|
|
| paper_search_pro | GET | Multi-condition paper search |
|
|
| paper_qa_search | POST | Natural-language / topic Q&A |
|
|
| paper_info | POST | Batch paper info by IDs |
|
|
| paper_detail | GET | Full paper details |
|
|
| paper_relation | GET | Citation chain |
|
|
| paper_list_by_keywords | GET | Batch thematic retrieval |
|
|
| paper_detail_by_condition | GET | Year + venue dimension |
|
|
| person_search | POST | Locate person_id |
|
|
| person_detail | GET | Scholar bio/education/honors |
|
|
| person_figure | GET | Interests + work history |
|
|
| person_paper_relation | GET | Scholar's papers |
|
|
| person_patent_relation | GET | Scholar's patents |
|
|
| person_project | GET | Funded projects |
|
|
| org_search | POST | Locate org by name |
|
|
| org_detail | POST | Org description/type |
|
|
| org_person_relation | GET | Affiliated scholars |
|
|
| org_paper_relation | GET | Org papers |
|
|
| org_patent_relation | GET | Org patents |
|
|
| org_disambiguate | POST | Normalize org string |
|
|
| org_disambiguate_pro | POST | Extract org IDs |
|
|
| venue_search | POST | Locate venue_id |
|
|
| venue_detail | POST | ISSN/type/abbreviation |
|
|
| venue_paper_relation | POST | Papers by venue (+ year filter) |
|
|
| patent_search | POST | Patent keyword search |
|
|
| patent_info | GET | Basic patent info |
|
|
| patent_detail | GET | Full patent details (IPC/claims) |
|
|
|
|
## 5 Workflows (orchestrate via multiple calls)
|
|
|
|
### Scholar Profile
|
|
```
|
|
person_search → person_detail
|
|
→ person_figure
|
|
→ person_paper_relation
|
|
→ person_patent_relation
|
|
→ person_project
|
|
```
|
|
|
|
### Paper Deep Dive
|
|
```
|
|
paper_search → paper_detail → paper_relation → paper_info
|
|
```
|
|
If `paper_search` is empty, fall back to `paper_search_pro`.
|
|
|
|
### Org Analysis
|
|
```
|
|
org_disambiguate_pro → org_detail
|
|
→ org_person_relation
|
|
→ org_paper_relation
|
|
→ org_patent_relation
|
|
```
|
|
If `org_disambiguate_pro` returns no ID, fall back to `org_search`.
|
|
|
|
### Venue Papers
|
|
```
|
|
venue_search → venue_detail (optional) → venue_paper_relation
|
|
```
|
|
|
|
### Patent Analysis
|
|
```
|
|
patent_search → patent_info / patent_detail
|
|
```
|
|
|
|
## Error handling
|
|
|
|
- `warning: .z-ai-config has no 'token' field` → add `token` to config.
|
|
- `http 401 … missing X-Token header (hint: …)` → same.
|
|
- `http 403` → gateway auth rejected; check `apiKey` / `X-Z-AI-From`.
|
|
- `gateway error: aminer_* failed: http 4xx …` → upstream refused; check API
|
|
key on the gateway side (`AMINER_API_KEY` env var) or parameter shape.
|
|
|
|
## Entity URL templates
|
|
|
|
- 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}`
|
|
|
|
Always append the relevant URL when presenting entities to the user.
|