dsh-paper-search 0.1.0

package/skills/paper-search/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: paper-search
+description: "Cari literatur ilmiah dari 13 sumber internasional (Crossref, OpenAlex, DOAJ, Europe PMC, PubMed, PubMed Central, arXiv, Semantic Scholar, CORE, Zenodo, HAL, IACR ePrint, Unpaywall) dan 3 portal jurnal Indonesia (Garuda, Sinta, IOS OneSearch) lewat tool paper_search — semuanya native, tanpa CLI atau paket luar. Pakai untuk mencari paper, jurnal, penelitian terdahulu, literatur Indonesia, atau melacak DOI."
+whenToUse: "Saat tugas menyangkut artikel atau karya ilmiah: mencari paper/jurnal/artikel penelitian, mencari penelitian terdahulu, mencari jurnal nasional Indonesia, mencari jurnal internasional, melacak DOI, atau saat pencarian literatur kosong dan perlu tahu sumber mana yang gagal. Bukan untuk berita, docs, atau riset web umum — itu tugas search-cascade."
+---
+
+# Paper Search — literatur internasional + jurnal Indonesia (DSH)
+
+Semua lewat **satu tool: `paper_search`**. Tidak ada CLI yang perlu dipasang,
+tidak ada paket Python yang perlu diinstal — 16 sumbernya native lewat HTTP.
+
+## Cara pakai
+
+```
+paper_search({ query: "machine learning" })                      # semua sumber
+paper_search({ query: "pendidikan karakter", sources: "indonesia" })
+paper_search({ query: "CRISPR", sources: "pubmed,europepmc,doaj", max_results: 10 })
+paper_search({ query: "digital literacy", open_access_only: true, year_from: 2020 })
+paper_search({ query: "transformer", sources: "crossref,openalex,arxiv" })
+```
+
+Opsi:
+
+| Opsi | Isi |
+|---|---|
+| `query` | kata kunci (wajib) |
+| `sources` | `all` · `international` · `indonesia` · atau id dipisah koma |
+| `max_results` | hasil **per sumber** (1-50, bawaan 5) |
+| `open_access_only` | hanya paper akses-terbuka |
+| `year_from` | hanya tahun >= nilai ini |
+
+## 16 sumbernya
+
+**Internasional (13)** — API JSON resmi, kecuali IACR yang diurai dari HTML:
+
+| Sumber | Catatan |
+|---|---|
+| `crossref` | metadata DOI lintas penerbit; terluas |
+| `openalex` | metadata + abstrak; email menaikkan batas laju |
+| `doaj` | jurnal akses-terbuka — **termasuk banyak jurnal Indonesia** |
+| `europepmc` | biomedis, teks penuh untuk OA |
+| `pubmed` | biomedis (dua panggilan: esearch + esummary) |
+| `pmc` | PubMed Central — teks penuh akses-terbuka (dua panggilan juga) |
+| `arxiv` | preprint; plugin membatasi sendiri 1 permintaan / 3 detik sesuai TOU mereka |
+| `semantic` | Semantic Scholar; kunci gratis menaikkan batas laju |
+| `core` | agregator repositori akses-terbuka — **wajib kunci** |
+| `zenodo` | repositori umum: data, perangkat lunak, preprint |
+| `hal` | repositori akses-terbuka Prancis |
+| `iacr` | IACR Cryptology ePrint Archive — pra-cetak kriptologi |
+| `unpaywall` | **input DOI, bukan kata kunci** — mencari salinan akses-terbuka dari sebuah DOI; **wajib email** |
+
+**Indonesia (3)** — penguraian halaman publik:
+
+| Sumber | Catatan |
+|---|---|
+| `garuda` | artikel jurnal Indonesia (Kemdiktisaintek) |
+| `sinta` | **daftar JURNAL** terakreditasi — bukan artikel |
+| `ios` | IOS OneSearch, agregator repositori Indonesia (Perpusnas) |
+
+> **Untuk topik Indonesia, pakai kata kunci BAHASA INDONESIA.** Terukur:
+> `"pendidikan karakter"` mengembalikan jurnal Indonesia nyata; padanan
+> Inggrisnya mengembalikan hasil internasional yang tidak relevan.
+
+> **Yang SENGAJA tidak didaftarkan, dan alasannya terukur (28 Sep 2026):**
+>
+> | Sumber | Alasan |
+> |---|---|
+> | `moraref` | halamannya hanya halaman pendarat, tanpa markup hasil (3.964 huruf) |
+> | `dblp` | API-nya di balik proteksi bot — mengembalikan halaman "Making sure you're not a bot!", bukan JSON |
+> | `openaire` | permintaan uji **timeout 30 detik dan 40 detik** |
+> | `biorxiv` / `medrxiv` | API-nya berbasis RENTANG TANGGAL, bukan kata kunci — tidak bisa dipakai mencari |
+> | `base` | menolak: `Access denied for IP address …` — butuh pendaftaran IP institusi |
+> | `citeseerx` | HTTP 404, lalu **menggantung** sampai permintaannya dibunuh |
+> | `ssrn` | menolak permintaan biasa dengan HTTP 403 |
+> | `google_scholar` | deteksi bot aktif; butuh proxy |
+>
+> Sumber yang selalu kosong lebih buruk daripada sumber yang tidak ada — jadi
+> yang gagal dibuang dan **alasannya dicatat**, bukan didaftarkan supaya
+> jumlahnya terlihat banyak.
+>
+> **`unpaywall` TIDAK ada di daftar ini** — ia sempat saya masukkan keliru,
+> lalu dikeluarkan setelah diuji ulang: ia **bekerja**, hanya butuh **DOI**.
+> "Bukan pencari kata kunci" ≠ "mati".
+
+## ⚠️ ATURAN UTAMA — "0 hasil" dari satu sumber BUKAN "tidak ada literatur"
+
+Tool ini **memisahkan** sumber yang gagal dari yang menjawab. Keluarannya selalu
+menampilkan baris per sumber:
+
+```
+  v Crossref            3 hasil  (2316 ms)
+  x Semantic Scholar    GAGAL — HTTP 429 (HTTP 429) — {"message": "Too Many Requests...
+  v Garuda              3 hasil  (1428 ms)
+```
+
+**Aturannya:**
+
+1. Sumber bertanda **`x`** artinya GAGAL — bukan kosong. **Sebutkan** itu saat
+   melaporkan hasil ke Rasyid. Jangan pernah menulis "tidak ada literatur" dari
+   sumber yang gagal.
+2. Kalau semua sumber balas 0 → ulangi **sekali** (batas laju sering transien),
+   lalu coba `sources` yang lain.
+3. Kalau ragu, jalankan **`paper_status`** lebih dulu — ia membuktikan sumber
+   mana yang benar-benar hidup **sekarang**, bukan sekadar terdaftar.
+
+## Kalau pencarian kosong atau terasa aneh
+
+```
+paper_status()                    # kirim satu permintaan kecil ke tiap sumber
+paper_status({ probe: false })    # hanya periksa konfigurasi, tanpa jaringan
+```
+
+Keluarannya menyebut: kredensial mana yang terbaca **dan dari mana asalnya**
+(config plugin / variabel lingkungan / `.env` milik CLI upstream), plus status
+hidup tiap sumber. Ini jawaban pertama untuk pertanyaan *"kenapa kosong?"*.
+
+## Kredensial (opsional — semua sumber tetap jalan tanpanya)
+
+Tidak ada kunci yang dibawa paket ini. Urutan pembacaan:
+
+1. config plugin di profil DSH,
+2. variabel lingkungan `PAPER_SEARCH_MCP_<NAMA>` lalu `<NAMA>`,
+3. berkas `~/.config/paper-search-mcp/.env` (milik CLI upstream).
+
+| Nama | Gunanya |
+|---|---|
+| `UNPAYWALL_EMAIL` | email apa pun — dipakai sebagai "polite pool" Crossref/OpenAlex |
+| `OPENALEX_EMAIL` | sama, khusus OpenAlex |
+| `SEMANTIC_SCHOLAR_API_KEY` | menaikkan batas laju Semantic Scholar |
+| `DOAJ_API_KEY` | menaikkan batas per jam DOAJ |
+| `CORE_API_KEY` | **wajib untuk sumber `core`** — tanpa kunci ia balas 429 tanpa pesan |
+
+**Jangan** isi kunci IEEE atau ACM — di upstream konektornya masih kerangka dan
+`search()` selalu melempar `NotImplementedError`. Plugin ini tidak memakainya.
+
+## CLI `paper-search-mcp` — opsional, bukan syarat
+
+Kalau kebetulan terpasang (`uv tool install --force "git+https://github.com/openags/paper-search-mcp"`),
+CLI itu menambah sumber lain: CORE, Zenodo, HAL, SSRN, Unpaywall, OpenAIRE,
+CiteSeerX, BASE, dan tombol unduh PDF dengan rantai cadangan. **Plugin ini tidak
+memerlukannya** — 16 sumber di atas sudah native.
+
+## Cara melaporkan hasil ke Rasyid
+
+Sajikan tabel: **judul, penulis, tahun, sumber (jurnal), DOI/URL**. Keluaran
+tool sudah memuat semuanya, termasuk kolom `sumber:` yang menyebut **semua**
+basis data yang menemukan paper itu (hasil dedup). Sebutkan juga kalau ada
+sumber yang gagal pada pencarian itu.