Skip to content
Back to search

paper-search-pro

"Find academic papers across up to 8 sources (OpenAlex, Semantic Scholar, CrossRef, PubMed, arXiv; OpenReview for AI venues; NSSD 国家哲社文献中心 + yiigle 中华医学期刊), from Quick scan to Audit prep. Use to run a literature search, gather references, scope a topic, search Chinese/中文原生 literature (中文文献/中文核心/CSSCI/C刊/国内研究/中华××期刊/心理学报/经济研究), filter by journal tier (中科院分区/一区/几区, Q1, JCR/SJR quartile, 影响因子/impact factor, 顶刊/top journal, 按分区筛), or export paste-ready boolean search strategies/检索式 for external databases (PubMed/WOS/Scopus/Embase/PsycINFO/知网 CNKI/万方/SinoMed: 写检索式/导出检索式/知网专业检索). Triggers: scoping/systematic review, SR prep, literature review, 'help me write a lit review', 找文献/找论文/论文搜索/学术检索/文献检索/文献综述/综述前期/求文献/找中文的. Outputs HTML report + BibTeX/RIS/CSV + PRISMA-S log. Do NOT use for concept explanations ('what is X'/'X 是什么', e.g. '影响因子怎么算'), writing ('帮我写'/'help me write a paragraph'), interpreting one paper or PDF download (use paper-downloader-portable), or an existing literature set (use literature-set-review)."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/o0000-code--paper-search-pro/badge.svg)](/listings/o0000-code--paper-search-pro)

HTML

<a href="/listings/o0000-code--paper-search-pro"><img src="/api/listings/o0000-code--paper-search-pro/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone into your agent's Skills directory. The target path varies by agent — pick the one matching what you use:

# Pick ONE target directory, depending on your agent:
#   ~/.claude/skills/paper-search-pro          # Claude Code
#   ~/.codex/skills/paper-search-pro           # Codex CLI
#   ~/.agents/skills/paper-search-pro          # cross-agent convention (Goose, Roo, etc.)
#   ~/.config/opencode/skills/paper-search-pro # OpenCode
#   ~/.codeium/windsurf/skills/paper-search-pro # Windsurf
#   ./.claude/skills/paper-search-pro          # project-local (Cursor, etc.)

git clone https://github.com/O0000-code/paper-search-pro.git \
  ~/.claude/skills/paper-search-pro   # change to your chosen path

# Point PSP_HOME at wherever you cloned. SKILL.md STEP 0 also auto-resolves
# the common paths above, so this manual export is only needed for non-standard locations.
export PSP_HOME="$HOME/.claude/skills/paper-search-pro"

python3 -m pip install -r "$PSP_HOME/scripts/requirements.txt"

# Optional: install the exact dependency versions validated by CI.
python3 -m pip install -r "$PSP_HOME/scripts/requirements.lock"

Five free API keys (~15 min total) — see [`references/setup.md`](references/setup.md).

<br/>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 816 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: paper-search-pro
  3. description: "Find academic papers across up to 8 sources (OpenAlex, Semantic Scholar, CrossRef, PubMed, arXiv; OpenReview for AI venues; NSSD 国家哲社文献中心 + yiigle 中华医学期刊), from Quick scan to Audit prep. Use to run a literature search, gather references, scope a topic, search Chinese/中文原生 literature (中文文献/中文核心/CSSCI/C刊/国内研究/中华××期刊/心理学报/经济研究), filter by journal tier (中科院分区/一区/几区, Q1, JCR/SJR quartile, 影响因子/impact factor, 顶刊/top journal, 按分区筛), or export paste-ready boolean search strategies/检索式 for external databases (PubMed/WOS/Scopus/Embase/PsycINFO/知网 CNKI/万方/SinoMed: 写检索式/导出检索式/知网专业检索). Triggers: scoping/systematic review, SR prep, literature review, 'help me write a lit review', 找文献/找论文/论文搜索/学术检索/文献检索/文献综述/综述前期/求文献/找中文的. Outputs HTML report + BibTeX/RIS/CSV + PRISMA-S log. Do NOT use for concept explanations ('what is X'/'X 是什么', e.g. '影响因子怎么算'), writing ('帮我写'/'help me write a paragraph'), interpreting one paper or PDF download (use paper-downloader-portable), or an existing literature set (use literature-set-review)."
  4. license: Apache-2.0
  5. allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task
  6. metadata:
  7. author: Bo
  8. version: 2.5.0
  9. vendored-from: futurehouse/paper-qa (Apache 2.0)
  10. ---
  11. # paper-search-pro
  12. Multi-source literature search with adjustable depth. Four tiers, five data sources orchestrated by you (the main agent). Python helpers handle deterministic work; LLM classification is delegated to parallel Inline SubAgents — no external API key required.
  13. ## When to use this skill
  14. - User wants to find academic papers / 找文献 / 论文搜索
  15. - User is preparing a literature review, systematic review (SR), scoping review, or meta-analysis
  16. - User wants to scope research on a topic for a thesis / proposal / coursework / news story
  17. - User asks "what research exists on X" / "find me papers about Y"
  18. - User uploads a query that suggests literature gathering (PICO, SPIDER, MeSH, RCT, etc.)
  19. ## When NOT to use
  20. - User wants to **read** a specific paper (use PDF reader / download tool)
  21. - User wants to **summarize** a single known paper (use a summarizer)
  22. - User wants to **download** PDFs given DOIs (use `paper-downloader-portable`)
  23. - User already has a literature set and wants to write a review (use `literature-set-review` / `factor-outcome-review`)
  24. - User wants concept explanation, not papers ("what is prospect theory" → just answer)
  25. ---
  26. ## 🤖 Called by another agent / headless mode
  27. **If you are an agent driving this Skill for your own reasoning (not for a human
  28. who wants an HTML report)**, do NOT hand-run the 14-STEP recipe below. There is a
  29. single structured-data channel built for you:
  30. ```bash
  31. PYTHONPATH=$PSP_HOME python3 -m scripts.agent_search "<query>" > result.json
  32. ```
  33. One command runs the whole deterministic core — multi-strategy retrieve → dedup →
  34. heuristic relevance score (computed for every paper) → saturation signal → quota
  35. snapshot → per-paper journal metric — and prints **one JSON envelope** (no HTML,
  36. no PRISMA, no LLM classification SubAgent). The human path below is unaffected.
  37. That command gives you a deterministic **floor**, not the finished job — agent mode
  38. is *not* meant to stop at the machine output; `references/agent_mode.md` is where you
  39. layer your own semantic judgement on top to reach human-recipe quality (the command
  40. guarantees the floor; you supply the quality).
  41. 📖 **Read `references/agent_mode.md`** for the full envelope schema, every flag
  42. (`--verify`, `--min-relevance`, `--quartile`, `--min-impact`, …), the relevance
  43. formula, error codes / exit codes, and source selection. This is the SSOT for
  44. agent callers — everything else in this section is just the pointer to it.
  45. Everything from here down is the **human-facing 14-STEP recipe** (HTML report +
  46. exports). Use it when the consumer is a person.
  47. ---
  48. ## 🔥 Execution discipline (read before running anything)
  49. Four invariants govern every step — ignoring them is the dominant failure mode in real sessions:
  50. - **A — NEVER `cd` into the Skill directory.** `cd $PSP_HOME` rebinds `./` to the Skill asset folder, so `./paper-search-results/...` lands inside the Skill instead of the user's workspace (and a re-install wipes it). Run every helper from the user's PWD: `PYTHONPATH=$PSP_HOME python3 -m scripts.<name> … > "$SEARCH_DIR/..."`. `$PSP_HOME` (STEP 0) is the install dir; `$SEARCH_DIR` (STEP 0) is an absolute path under the user's PWD.
  51. - **B — Dispatch classifier SubAgents in parallel.** STEP 6 puts up to 5 `Task` blocks in one assistant message; serial dispatch inflates Standard tier from ~10 to ~17 min. The worked example lives in STEP 6 — it is not repeated elsewhere.
  52. - **C — Announce every skip.** If you skip a STEP (budget / empty data / user choice), say *what* you skipped, *why*, *what's lost*, and *how to recover* (e.g. "re-run at `--tier deep`"). Skipping is fine; surprising the user is not.
  53. - **D — Read a step's cited reference when that step is non-trivial for this case.** Each STEP names a `references/<file>.md` carrying edge cases not duplicated here. You won't read all of them every run, nor should you — but skipping the reference for a step you are *actually about to run* is where boundary knowledge (dict-vs-list shapes, enrich-not-search, DOI casing) gets lost. Read the one in front of you.
  54. ---
  55. ## Architecture at a glance
  56. ```
  57. You (main agent) drive the workflow per this SKILL.md.
  58. Python helpers do deterministic work — NO LLM inside, NO external API key.
  59. L1 OpenAlex (primary) → deep top-100 multi-strategy
  60. L2 PubMed (medical) → MeSH enricher (mostly; Audit-tier can search independently)
  61. L2 arXiv (CS/AI) → last-year recent layer (+ 4-day sentinel on freshness words)
  62. L2 OpenReview (AI) → accepted-venue labels (ICLR / NeurIPS / ICML …)
  63. L3 Semantic Scholar → influentialCitationCount + abstract fallback
  64. L3 CrossRef → funder / license / clinical-trial-number
  65. Classification → Inline SubAgents (parallel, file-IPC, 5 per message)
  66. Output → HTML (Shadcn) + MD + BibTeX/RIS/CSV + PRISMA-S log
  67. ```
  68. ---
  69. ## The 4 tiers — pick first
  70. | Tier | Wall-clock | Papers | When to pick |
  71. |------|------------|--------|--------------|
  72. | Quick | ~5-8 min | 20-60 | "查一下" / "几篇" / "before tomorrow" / fast scope |
  73. | **Standard** (default) | ~10-17 min | 60-180 | Scope a topic / write background / general lit search |
  74. | Deep | ~30-45 min | 180-400 | "thorough" / writing a review article / 综述写作 |
  75. | Audit | ~2-3 hr | 400-1000+ | "systematic review" / "PRISMA" / "Cochrane" / "meta-analysis" |
  76. 📖 **BEFORE picking, read `references/tier_decision.md`.** Tell the user your choice and why. For Audit, show limitations warning + get explicit confirmation before starting.
  77. ---
  78. ## The recipe
  79. For every literature search, follow these steps in order. Each step references a `references/` file for details. Skip files only when the step is obviously trivial for the case at hand — and announce the skip per Rule C.
  80. ### STEP 0 — Setup ($PSP_HOME + working directory)
  81. 📖 BEFORE THIS STEP, read: `references/setup.md`.
  82. **Resolve the Skill install path into `$PSP_HOME`** (every later step uses `PYTHONPATH=$PSP_HOME`). Prefer explicit injection / agent env var; otherwise scan the known cross-agent install locations. If your harness already exposes this SKILL.md's absolute path, just `export PSP_HOME="<that dir>"` and skip the scan. 📖 Full rationale, why this can't be a script, and the complete path list: `references/runtime_bootstrap.md`.
  83. ```bash
  84. PSP_HOME="${PSP_HOME:-${CLAUDE_SKILL_DIR:-${CODEBUDDY_SKILL_DIR:-}}}" # explicit / agent-injected
  85. if [ -z "$PSP_HOME" ]; then # else scan known installs
  86. for base in "$HOME/.claude" "$HOME/.codex" "$HOME/.agents" "$HOME/.config/opencode" \
  87. "$HOME/.codeium/windsurf" "$HOME/.config/goose" "$HOME/.cline" "$HOME/.roo" \
  88. "$HOME/.copilot" ./.claude ./.codex ./.agents ./.cursor ./.opencode ./.windsurf; do
  89. [ -f "$base/skills/paper-search-pro/SKILL.md" ] && PSP_HOME="$base/skills/paper-search-pro" && break
  90. done
  91. fi
  92. [ -z "$PSP_HOME" ] && { echo "ERROR: paper-search-pro install not found. Set PSP_HOME to the dir containing SKILL.md."; exit 1; }
  93. export PSP_HOME; echo "Using Skill install: $PSP_HOME"
  94. ```
  95. **Verify config keys** (executed from any cwd, never `cd` into the Skill dir):
  96. ```bash
  97. PYTHONPATH=$PSP_HOME python3 -c \
  98. "from scripts.config import load_config; c = load_config(); print('OK' if c.openalex_api_key and c.ncbi_email else 'MISSING — see references/setup.md')"
  99. ```
  100. If "MISSING", point the user to `references/setup.md` (5 keys, all free, ~15 min total) and halt.
  101. **Set up the working directory variable** — every subsequent step uses `$SEARCH_DIR`:
  102. ```bash
  103. SEARCH_ID="<topic_slug>_<tier>_$(date +%Y%m%d_%H%M%S)" # e.g. clt_education_quick_20260522_103045
  104. SEARCH_DIR="$(pwd)/paper-search-results/$SEARCH_ID"
  105. mkdir -p "$SEARCH_DIR/raw" "$SEARCH_DIR/batches" "$SEARCH_DIR/classifications"
  106. echo "Outputs will land in: $SEARCH_DIR"
  107. ```
  108. `$SEARCH_DIR` is now an **absolute path under the user's PWD**. Use `"$SEARCH_DIR/..."` (quoted, with the variable) in every helper command below — not `./paper-search-results/...`.
  109. ### STEP 1 — Plan the query (MANDATORY for all tiers)
  110. 📖 BEFORE THIS STEP, read: `references/query_planner.md`.
  111. **Detect the report UI language** — `UI_LANG` (`zh` for Chinese queries, `en` for everything else) selects which UI language the final HTML report renders in. Paper titles / abstracts / authors / venues are NEVER translated — only the report's UI chrome. Pass `--language $UI_LANG` to STEP 12b.
  112. ```bash
  113. UI_LANG=$(PYTHONPATH=$PSP_HOME python3 -m scripts.detect_language "$USER_QUERY")
  114. ```
  115. The detector routes Japanese / Korean / European queries to **English** (the bundle ships only EN + ZH dictionaries; English is the international academic default). 📖 The exact Unicode rule and why kana is checked before Han live in `references/runtime_bootstrap.md`.
  116. **Determine the search language space** (`search_language`, axis 2 — *which literature ocean*, distinct from `UI_LANG` above which is only *report chrome*). 📖 The parsing SSOT is `references/source_routing.md` §"Language scope"; resolve the space here, before phrasing the query, because it changes how STEP 3's query is built. This is **additive and opt-in — a pure English query resolves to the `en` space with zero new prompts or behavior (R-19)**; everything below fires only for Chinese queries or explicit signals.
  117. - Read the persisted default `config.search_language` (auto | en | zh | both) and apply the priority ladder **flags > in-query markers > config > auto**. CJK presence is the mechanical fact from `detect_language` above; markers (`CSSCI`, `中文文献`, `SSCI`, `知网`, …) and non-signals (`中科院一区`, topic-about-China) are your semantic judgment per the §"Language scope" tables.
  118. - **`auto` + a Chinese (CJK) query + no language marker + no persisted value → ask ONE question before retrieving** (this is the human path's job; the CLI/agent path passes through instead). Two sentences, offer to persist, and don't re-ask later this session:
  119. > 你用中文提问——文献要英文、中文,还是都要?顺便可以说"以后都这样",我就记成默认、下次不再问。
  120. - "中文" / "都要" → enter that space (STEP 2 discipline routing takes over; report one line there).
  121. - "英文" → v2.2 behavior (Chinese topic planned as an English query), report one line.
  122. - "无所谓 / 都行" → **this run uses `both`** (Recall > Precision), not persisted; if the same user answers "无所谓" a second time, add one light offer to set `both` as default, then never ask again.
  123. - Only an explicit "以后都…" persists to `config.search_language` (single answers never auto-persist).
  124. - **If a rank ambiguity (bare "Q1") also fired this run, merge both questions into ONE message** — ask language + platform together, never in two rounds (over-asking is a red line).
  125. - Once the space is known, phrase the query per `references/query_planner.md` §"Cross-language query handling": **`zh` keeps Chinese search terms (no translation)**, `en` uses the English terms (v2.2 behavior), `both` builds two sets.
  126. **Write each retrieval query as concept blocks, not a word list.** OpenAlex requires every bare word, so synonyms written as words exclude every paper that uses only one of them (a user's 11-word query matched one paper by title and abstract over five years). Synonyms go in OR groups, 2–3 blocks joined by AND, phrases in quotes — `("short video" OR TikTok OR Douyin) AND (attention OR concentration)` — and keep the population block out of at least one strategy. 📖 `references/query_planner.md` §"How OpenAlex reads a query".
  127. Apply PICO / SPIDER / PEO depending on domain:
  128. - Medical/clinical → PICO (Population/Intervention/Comparator/Outcome)
  129. - Qualitative → SPIDER
  130. - Scoping → PEO (Population/Exposure/Outcome)
  131. - Open-ended → just extract 2-4 concept blocks + 2-5 synonyms each
  132. **Journal-rank intent recognition (additive — only acts when the query mentions a partition).** Before you extract concept blocks, check whether the user's query carries a journal-rank/partition phrase — "中科院一区", "Q1", "JCR Q1", "SJR Q2", "顶刊 / top journal". If so, that phrase is a **filter condition, not a search term**, and it MUST be **stripped from the topic** before retrieval. This roots out the failure that motivated the whole feature: "中科院一区 情绪调节" used to send "中科院一区" to the search engine as a topic word, so it searched for papers *about* 中科院一区 instead of papers *on* 情绪调节 *filtered to* CAS tier 1. The deterministic parser does both jobs (extract + strip) for you:
  133. ```bash
  134. PYTHONPATH=$PSP_HOME python3 -c "
  135. from scripts.rank_intent import parse_rank_intent
  136. i = parse_rank_intent('''<original user query>''')
  137. import json; print(json.dumps({
  138. 'platform': i.platform, 'tiers': i.tiers, 'quartiles': i.quartiles,
  139. 'top': i.top, 'ambiguous': i.ambiguous, 'candidates': i.candidate_platforms,
  140. 'cleaned_query': i.cleaned_query, 'stripped': i.matched}, ensure_ascii=False))
  141. "
  142. ```
  143. Then act on the parse:
  144. - **`cleaned_query`** is the rank-stripped retrieval input — use it (NOT the raw query) when building STEP 3 queries and the query plan. It is not automatically `SEARCH_TOPIC` or the report title: the semantic planning step below still removes conversational and operational text. When the query had no rank phrasing, `cleaned_query == query` and retrieval behavior remains unchanged (R-19).
  145. - **`platform` + `tiers`/`quartiles`/`top`** are the filter you will apply right after STEP 5 — remember them (and record them as `rank_filter` in `query_plan.json`); do not filter here.
  146. - **`ambiguous == True`** (a tier or quartile with no platform word, e.g. a bare "Q1" or "SSCI 一区" — the recogniser never guesses a platform): **ask the user one short question inline** before going further, offering the platforms in `candidates` — *"按 JCR 还是 SJR 的 Q1 筛?"* / *"按中科院分区还是 JCR 分区?"*, plus *"顺便要不要设为以后的默认?"* The CLI/headless path cannot ask, so this inline question is specifically the human path's job.
  147. - If the query mentions no partition at all, skip this entirely — STEP 1 proceeds exactly as before.
  148. **Time scope — decide the year window before retrieving.** 📖 `references/query_planner.md` §"Year filter heuristics". Sort the request into one of four cases:
  149. - **Explicit range** ("2020–2024", "近两年", "2023 年以后", "last 3 years", "只要 2026 年的") → set `year_min` / `year_max`; relative ranges count back from the current year ("近两年" = current year − 1 … current year). No question. One line: *"本次限定 2025–2026。"*
  150. - **"New" without a number** ("最新", "最近", "近年", "前沿", "recent", "latest", "cutting-edge") → how recent is genuinely ambiguous and changes the result set. If `config.recent_years` is set, use it and say so in one line. Otherwise **ask one question** — in the same message as any language or rank question from above, never a second round:
  151. > 「最新」想要多近?近一年 / 近两年 / 近三年 / 近五年,或者直接给区间(如 2023–2026)。说「以后都这样」我就记成默认。
  152. Only an explicit "以后都…" persists (`recent_years: <N>` in `~/.paper-search-pro/config.yaml`, same mechanism as `search_language`).
  153. - **Classics** ("经典", "奠基", "起源", "seminal", "classic") → no year window; add `seminal` in STEP 3.
  154. - **Nothing said** (most requests) → no year window, and **do not ask**: STEP 3's recent leg still brings the most relevant papers of the last year and of the two years before. One line: *"没说时间范围:本次不限年份,并单独补一层近一年的新文献。只要近几年的,说「只要近两年」即可。"* If a language or rank question is being asked anyway, you may offer the time choices in that same message.
  155. - **Audit tier**: date limits belong to the protocol (PRISMA-S reports them) — confirm the window as part of the Audit confirmation you already ask for.
  156. Where the host has a structured-choice tool (Claude Code's AskUserQuestion; Codex's `request_user_input` when it is listed), ask with these options plus free input; otherwise ask in text. The agent/headless path never asks — it takes `--year-min` / `--year-max` as given.
  157. Even Quick tier needs a lightweight version of this step — never skip silently. Output: 1-3 search strategies (concept blocks + year range + work type filter). Write to `"$SEARCH_DIR/query_plan.json"` as `{"strategies": [{"query": "..."}, ...], "year_min": …, "year_max": …, "rank_filter": {"platform": "cas", "tiers": [1, 2]}, "work_type_filter": …}` (other keys are fine; omit what does not apply). The report's audit tab and the PRISMA-S log (STEP 12a, 13) read the queries and filters from it.
  158. **Define `SEARCH_TOPIC`, but do not freeze the report title yet.** Read `references/report_title.md` §"STEP 1". `SEARCH_TOPIC` is the normalized semantic retrieval scope derived from the concept blocks, not the user's prose with a few regex matches removed. Strip greetings, tool/output instructions, tier/language/date/database constraints, and other operating directions; retain population, exposure/intervention, outcome, mechanism, and setting only when they are scientific concepts. Keep the exact user message separately as `USER_QUERY` for PRISMA-S. The final visual title is authored in STEP 11 after the retained evidence is known.
  159. ### STEP 2 — Route supplemental sources within the STEP-1 language space
  160. 📖 BEFORE THIS STEP, read: `references/source_routing.md`.
  161. **You make these routing calls by judging the query's domain — the reference's keyword tables are calibration examples, not a match list** (mechanical facts — CJK detection, explicit `--flags` — stay deterministic). Within the language space fixed in STEP 1, route the per-discipline boosters:
  162. - **English space** (`en`, or the English half of `both`) — unchanged from v2.2:
  163. - Medical signals (RCT, PRISMA, MeSH, clinical, disease names) → enable PubMed
  164. - CS / AI topics (machine learning, LLM, transformer, NeurIPS, computer vision, …) → enable arXiv's recent layer **and OpenReview** (ICLR / NeurIPS / ICML / COLM / TMLR review platform — adds accepted-venue labels such as "ICLR 2026 Oral" and a few papers only it holds)
  165. - Freshness signals (preprint, "最新", "this week") → also the 4-day arXiv sentinel
  166. - Cross-domain (e.g. "AI in radiology") → enable both
  167. - Pure social science / humanities → OpenAlex only
  168. - *(Judgment call: a core AI/CS query may also raise the primary engine to Semantic Scholar — see `source_routing.md` §"AI / CS queries → consider Semantic Scholar as primary".)*
  169. - **Chinese space** (`zh`, or the Chinese half of `both`) — route the Chinese boosters the same way, by discipline:
  170. - Social-science / humanities signal → add **NSSD** (国家哲社文献中心; carries the CSSCI 收录标识 OpenAlex has ≈0 coverage of)
  171. - Medical signal → add **yiigle** (中华医学期刊全文数据库); PubMed still covers MEDLINE-indexed 中华 journals, so the two are complementary
  172. - Pure sci-tech with neither → Chinese side runs on OpenAlex only (sci-tech Chinese core journals mostly register DOIs, so OpenAlex covers them well)
  173. **Report one line** (axis-3 style — a statement, not a question; 22 §6.3). For an English-only run this is the PubMed/arXiv notice (*"I detected medical + AI signals — also searching PubMed, arXiv (last year) and OpenReview. Override with `--no-pubmed`."*). For a Chinese space, e.g.:
  174. > 本次按「中英都要」检索;中文侧检测到社科主题,已加 NSSD(国家哲社文献中心)。想去掉说 `--no-nssd`,只查一边说"只要英文/中文"。
  175. **Coverage honesty rides with the notice:** if the zh space has a social-science topic but the user declined NSSD, add that OpenAlex hits ≈0 on CSSCI flagship journals (经济研究 / 管理世界 …), so that layer is missing. User can override any of this with an explicit instruction (a per-query override wins over everything).
  176. **On the `--flag` shorthands above (`--no-nssd`, `--no-pubmed`, `--source …`):** on this human path they are **natural-language override *notation*** — a compact way to write what the user can *say* ("去掉 NSSD" / "只查 OpenAlex"), which you (the LLM) interpret. They are **not executable CLI flags** — no script parses them here. The only real, script-parsed flags live on the agent/headless path (`agent_search`), and there the Chinese-source control is opt-**in**: `--with-nssd` / `--with-yiigle` (there is no `--no-nssd` / `--source` there). See `references/agent_mode.md`.
  177. ### STEP 3 — Retrieve from OpenAlex (deep)
  178. 📖 BEFORE THIS STEP, read: `references/openalex_helper_cheatsheet.md`.
  179. Always run OpenAlex first. (OpenAlex is the default primary source; `primary_source` in `config.yaml` can change that — see *Primary source selection & quota fallback* in `references/source_routing.md`.)
  180. **When OpenAlex cannot serve a call** (daily budget spent, persistent throttling, outage), `openalex_helper` serves that same call from Semantic Scholar and still prints the same JSON shape — no flag, no config. It says so in one stderr line starting `[paper-search-pro] OpenAlex unavailable`: tell the user in one sentence (Rule C) and carry on; do not stop to ask. If Semantic Scholar cannot serve it either, the call behaves as an OpenAlex error always did: exit status `3` (stdout is still valid JSON), and the stderr line says what happened and when OpenAlex resets — report it to the user as you would any OpenAlex error. `journal-list` is the exception: as before, it comes back empty with exit 0.
  181. For Standard+ tiers, use multi-strategy deep crawl:
  182. ```bash
  183. PYTHONPATH=$PSP_HOME \
  184. python3 -m scripts.openalex_helper double-sort "<query>" \
  185. --n 50 \
  186. > "$SEARCH_DIR/raw/openalex.json"
  187. ```
  188. Three legs, one file: **cited** (the topic's most-cited work), **recent** (the most relevant work of the last 12 months, then of the two years before), **relevance** (the best matches overall). The recent leg is what finds this year's papers — relevance ranking leans on citations, so without it new work barely appears.
  189. For Quick tier, relevance plus a smaller recent layer:
  190. ```bash
  191. PYTHONPATH=$PSP_HOME \
  192. python3 -m scripts.openalex_helper search "<query>" \
  193. --limit 30 --recent 20 \
  194. > "$SEARCH_DIR/raw/openalex.json"
  195. ```
  196. Then record how many works OpenAlex holds for the main query — one line under the report's year chart, so a thin recent bar is not read as a thin field (it counts title-and-abstract matches in the STEP 1 window, or the last two years when there is none):
  197. ```bash
  198. PYTHONPATH=$PSP_HOME \
  199. python3 -m scripts.openalex_helper count "<query>" [--year-min YYYY] [--year-max YYYY] \
  200. > "$SEARCH_DIR/pool_count.json"
  201. ```
  202. If `count` reports fewer than 30 works, or a helper warns about a long run of bare words, the query is too narrow (unless the topic is genuinely niche): regroup it as in STEP 1 and rerun retrieval before classifying.
  203. Add the STEP 1 window to the retrieval commands too: `--year-min YYYY` / `--year-max YYYY` (inclusive). No window given → none is added (the helpers cap at the current year themselves). The recent leg stays inside the window: for a window ending in the past, it takes that window's last year.
  204. **`raw/` holds retrieval output only — one file per search, as the helpers wrote it.** STEP 7 estimates coverage from how often these separate searches found the same papers. A subset, merge or screened copy you derive goes in `"$SEARCH_DIR/_working/"`, not `raw/`: in `raw/` it would look like another search that re-found everything.
  205. The full subcommand + flag reference (`search` / `double-sort` / `seminal` / `reviews` / `journal-list` / `citation-network`, all verified against argparse) is in `references/openalex_helper_cheatsheet.md` — read it before reaching for anything beyond the two commands above. For Deep+Audit, also call topic-specific subcommands (e.g. `seminal`, `reviews`, `journal-list`), append outputs to `$SEARCH_DIR/raw/openalex_*.json`, and federate them all together in STEP 5.
  206. ### STEP 4 — Run L2 boosters (if enabled by STEP 2)
  207. 📖 BEFORE THIS STEP, read: `references/pubmed_helper_cheatsheet.md` and `references/arxiv_helper_cheatsheet.md`.
  208. **PubMed — default mode is `enrich`, NOT `search`**:
  209. - **Standard / Deep tier**: enrich OA-found papers with MeSH terms (mutates the openalex.json file in place):
  210. ```bash
  211. PYTHONPATH=$PSP_HOME \
  212. python3 -m scripts.pubmed_helper enrich \
  213. --input-file "$SEARCH_DIR/raw/openalex.json" \
  214. --output-file "$SEARCH_DIR/raw/openalex.json"
  215. ```
  216. - **Audit tier with explicit MeSH query**: independent MeSH search (produces a new file to federate later):
  217. ```bash
  218. PYTHONPATH=$PSP_HOME \
  219. python3 -m scripts.pubmed_helper search-mesh "Diabetes Mellitus, Type 2" \
  220. --year-min 2020 --limit 30 --pub-type "Randomized Controlled Trial" \
  221. > "$SEARCH_DIR/raw/pubmed.json"
  222. ```
  223. - Generic `pubmed_helper search` is a fallback when no MeSH term is known — prefer `enrich` or `search-mesh` whenever possible.
  224. **arXiv — CS / AI topics: the recent layer.** The most relevant preprints of the last year (OpenAlex indexes arXiv late and incompletely: in one check, 7 of 20 recent on-topic papers from OpenReview were not in OpenAlex):
  225. ```bash
  226. PYTHONPATH=$PSP_HOME \
  227. python3 -m scripts.arxiv_helper search "<query>" \
  228. --sort relevance --since-days 365 --limit 30 \
  229. > "$SEARCH_DIR/raw/arxiv.json"
  230. ```
  231. **Freshness signals ("最新", preprint, "this week") — also the 4-day sentinel**, for preprints too new for any index:
  232. ```bash
  233. PYTHONPATH=$PSP_HOME \
  234. python3 -m scripts.arxiv_helper freshness "<query>" \
  235. --days 4 --limit 30 \
  236. > "$SEARCH_DIR/raw/arxiv_fresh.json"
  237. ```
  238. Plain words in the query are all required (arXiv would OR them). Both commands print `[]` and a stderr note when arXiv fails or times out — carry on without it (Rule C: say so in one line).
  239. Subcommand reference:
  240. - `arxiv_helper freshness <query> --days N --limit M [--all-cats]`
  241. - `arxiv_helper search <query> --limit M --sort submitted|relevance|lastUpdated [--since-days N] [--all-cats]`
  242. - `arxiv_helper get <arxiv_id>`
  243. **OpenReview — CS / AI topics only.** 📖 `references/openreview_helper_cheatsheet.md`. The review platform of ICLR, NeurIPS, ICML, COLM and TMLR. The helper returns only accepted papers, labelled like "ICLR 2026 Oral" — the label OpenAlex and Semantic Scholar lack (they list these as arXiv preprints). STEP 5 merges each into the same paper's arXiv/OpenAlex record.
  244. ```bash
  245. PYTHONPATH=$PSP_HOME \
  246. python3 -m scripts.openreview_helper --search "<query>" --n 30 \
  247. [--year-min YYYY] [--year-max YYYY] \
  248. --output-file "$SEARCH_DIR/raw/openreview.json"
  249. ```
  250. Only its search endpoint is open to anonymous use; if OpenReview blocks it, the helper returns `[]` — say so in one line and carry on.
  251. **NSSD / yiigle — Chinese boosters (ONLY when STEP 1-2 put this run in the `zh` space, and only the one(s) the discipline routing selected):**
  252. Each is an independent primary source for the Chinese space (same role as `ss_helper --search`) and emits the **same `UnifiedPaperEntity` shape** as openalex.json, so STEP 5 federates them identically. Keep the query in **Chinese** (do NOT translate — query_planner §Cross-language) and write to `raw/nssd.json` / `raw/yiigle.json`:
  253. ```bash
  254. # NSSD — Chinese social-sciences & humanities (adds the CSSCI-tier layer OpenAlex lacks)
  255. PYTHONPATH=$PSP_HOME \
  256. python3 -m scripts.nssd_helper --search "<中文检索式>" \
  257. --n 50 [--year-min YYYY] \
  258. > "$SEARCH_DIR/raw/nssd.json"
  259. # yiigle — Chinese medical (中华医学期刊全文数据库; native-Chinese titles + abstracts)
  260. PYTHONPATH=$PSP_HOME \
  261. python3 -m scripts.yiigle_helper --search "<中文检索式>" \
  262. --n 50 [--year-min YYYY] \
  263. > "$SEARCH_DIR/raw/yiigle.json"
  264. ```
  265. Both degrade gracefully to `[]` on any network / HTTP failure (they never raise) — an empty file just federates to nothing. Both take **only** 题录 + 摘要 (compliance: no full-text download, no caching) and print their source attribution to stderr. `--year-min` filters client-side; drop it to keep all years.
  266. **config `search_language: en` but a Chinese query arrived (hard boundary 2):** do NOT enable Chinese boosters, but say one line — never a silent translation (22 §6.4):
  267. > 按你的默认(只查英文),我把中文主题规划成英文检索式了。想要中文文献这次说一声即可,想改默认说"以后…"。
  268. **User names 知网 / CNKI / 万方 / 维普 (marker hit + compliance):** these are closed subscription databases PSP does not scrape. Say one line, offer the substitute + the export, don't re-argue (22 §6.5):
  269. > PSP 不抓知网/万方(合规,不做封闭库抓取);中文侧用 OpenAlex 中文底座 + NSSD(社科,含 CSSCI 标识)/yiigle(医学)覆盖。但可以**把你的知网专业检索式写好**——按 CNKI 专业检索语法(`SU %=` 相关匹配、块内 OR/块间 AND、全英文半角、检索值单引号)生成可直接**粘贴进「专业检索」框**的检索式,粘贴即查。中文医学题另可给 SinoMed(CMeSH 受控词双轨)。要导出吗?
  270. "要导出吗?" accepted = an explicit-ask trigger for STEP 11.5 — run the export at any tier.
  271. ### STEP 5 — Federate (dedup + merge)
  272. 📖 BEFORE THIS STEP, read: `references/source_routing.md` §"Field priority table".
  273. Combine all retrieval results into a single deduped KG. **Default output is a dict keyed by canonical_key** — that's what `rcs_parser` expects later, so do NOT pass `--as-list`:
  274. ```bash
  275. PYTHONPATH=$PSP_HOME \
  276. python3 -m scripts.federated_kg_resolver \
  277. --input-files "$SEARCH_DIR/raw/openalex.json" \
  278. "$SEARCH_DIR/raw/pubmed.json" \
  279. "$SEARCH_DIR/raw/arxiv.json" \
  280. "$SEARCH_DIR/raw/openreview.json" \
  281. --output "$SEARCH_DIR/kg.json"
  282. ```
  283. Pass only the input files you actually produced — skip ones that were not enabled by STEP 2 (and add `raw/arxiv_fresh.json` when the 4-day sentinel ran). OpenReview records carry no DOI; the resolver folds each into the same paper's arXiv/OpenAlex record by title and gives it the accepted venue label. **If STEP 4 ran the Chinese boosters, add `"$SEARCH_DIR/raw/nssd.json"` / `"$SEARCH_DIR/raw/yiigle.json"` to the same `--input-files` list** — they carry the identical entity shape and federate exactly like the others (CJK-safe dedup is handled by the Phase 0 canonical-key fix, so distinct Chinese titles don't collapse). For an English-only run those files don't exist, so the call is byte-identical to v2.2 (R-19). This handles DOI normalization (arXiv X→x case), version stripping, E5b guard (same title+year but different DOIs are kept separate), and field-priority merge.
  284. `--as-list` exists but is only for consumers that want a sorted list (by citation_count); do not use it in this pipeline.
  285. **Only when STEP 1 found a journal-tier request — filter before classifying.** A tier is a cheap deterministic filter; classifying papers it will drop is the expensive part. 📖 `references/journal_metrics.md`. Keep `kg.json` as the full pool and classify `kg_ranked.json`:
  286. ```bash
  287. PYTHONPATH=$PSP_HOME \
  288. python3 -m scripts.rank_filter --kg "$SEARCH_DIR/kg.json" \
  289. --output "$SEARCH_DIR/kg_ranked.json" --platform cas --tiers 1,2
  290. # JCR / SJR: --platform jcr --quartiles Q1,Q2 ; Top only: --top
  291. ```
  292. It labels every paper with all three platforms, keeps the requested ones, and writes the rest to `kg_ranked_set_aside.json`. Tell the user the printed counts in one line (*"本次按中科院 1–2 区筛:留 N / 区外 M / 不在该表 K"*) with the attribution it prints. In STEP 6 batch and merge `kg_ranked.json` instead of `kg.json`. No tier requested → skip this entirely; nothing changes.
  293. ### STEP 6 — Classify in parallel batches (LLM happens here — main agent + SubAgents)
  294. 📖 BEFORE THIS STEP, read: `references/classifier_subagent_prompt.md` and `references/rcs_rubric.md`.
  295. Split the KG into batches of 10 papers each. Write to `"$SEARCH_DIR/batches/batch_NNN.jsonl"`. If the pool is larger than the tier can classify, trim evenly across the raw files and never by citation count: new papers have almost none, so a citation cut removes exactly the recent layer.
  296. **Before dispatch**, expand `$PSP_HOME/references/rcs_rubric.md` into the actual absolute path (e.g. `/Users/alice/.claude/skills/paper-search-pro/references/rcs_rubric.md`) and substitute it for `{rubric_path}` in the classifier prompt template. Each SubAgent runs in its own shell where `$PSP_HOME` is **not** exported — passing the literal `$PSP_HOME` token would leave the SubAgent unable to find the rubric, which silently degrades scoring quality. See `references/classifier_subagent_prompt.md` for the full placeholder table.
  297. 🔥 **PARALLELISM IS MANDATORY** (Rule B):
  298. You MUST dispatch up to **5 classifier SubAgents in a single assistant message** using multiple `Task` tool_use blocks. Serial dispatch (one Task per message, waiting for each result) is the single biggest performance failure observed — it inflates Standard tier from ~10 min to ~17 min.
  299. ✅ **CORRECT — in ONE assistant message:**
  300. ```
  301. Task tool_use #1 → subagent_type="general-purpose", prompt="<classifier prompt for batch_001.jsonl>"
  302. Task tool_use #2 → subagent_type="general-purpose", prompt="<classifier prompt for batch_002.jsonl>"
  303. Task tool_use #3 → subagent_type="general-purpose", prompt="<classifier prompt for batch_003.jsonl>"
  304. Task tool_use #4 → subagent_type="general-purpose", prompt="<classifier prompt for batch_004.jsonl>"
  305. Task tool_use #5 → subagent_type="general-purpose", prompt="<classifier prompt for batch_005.jsonl>"
  306. ```
  307. All five tool_use blocks live in the same `<assistant>` message, so they run in parallel. Some harnesses hand the five results back together; others start the SubAgents in the background and report each one as it finishes. Either way, merge only once every `batch_NNN_result.json` of the round exists.
  308. ❌ **WRONG — five separate messages (this is what serial dispatch looks like):**
  309. ```
  310. Message N: Task tool_use #1 ─→ wait for result
  311. Message N+1: Task tool_use #2 ─→ wait for result ← SERIAL, makes Standard run 70% slower
  312. Message N+2: Task tool_use #3 ─→ wait for result
  313. ...
  314. ```
  315. If you have more than 5 batches, send 5-at-a-time across multiple messages — each message still contains 5 parallel Task blocks.
  316. Each SubAgent reads its batch file, applies the RCS rubric, and writes `"$SEARCH_DIR/classifications/batch_NNN_result.json"`. Then merge classifications into the KG:
  317. ```bash
  318. PYTHONPATH=$PSP_HOME \
  319. python3 -m scripts.rcs_parser \
  320. --input-dir "$SEARCH_DIR/classifications/" \
  321. --kg "$SEARCH_DIR/kg.json" \
  322. --output "$SEARCH_DIR/kg_classified.json"
  323. ```
  324. ### STEP 7 — Compute saturation curve (MANDATORY for all tiers)
  325. 📖 BEFORE THIS STEP, read: `references/stop_decision.md`.
  326. This step is NOT optional, even for Quick: `curve.json` is what STEP 8 decides on, and STEP 12 renders the same estimate.
  327. ```bash
  328. PYTHONPATH=$PSP_HOME \
  329. python3 -m scripts.discovery_curve \
  330. --kg "$SEARCH_DIR/kg_classified.json" \
  331. --output "$SEARCH_DIR/curve.json"
  332. ```
  333. `curve.json` gives `coverage_estimate` (0-1) with `ci_lower` / `ci_upper`, and `method`: `sample_coverage` means it was estimated from how often this run's separate searches in `raw/` re-found the same highly relevant papers (`relevance_band` 7 = rcs ≥ 7; 6 = rcs ≥ 6, used when the rcs ≥ 7 papers are too few for the estimator to say anything); `prior` means there was nothing to measure — fewer than two searches, no relevant paper found, or too few in either band — so it is the Undermind median prior capped at 50%, not a measurement — say so if you quote it. `--raw-dir` overrides where the searches are read from (default: `raw/` next to `--kg`).
  334. ### STEP 8 — Decide next action (MANDATORY)
  335. 📖 BEFORE THIS STEP, read: `references/stop_decision.md`.
  336. This step is NOT optional. Make the decision **explicitly** — based on curve.json + tier budget + intent — and state the reasoning to the user. Do not skip based on intuition.
  337. Decision tree (on `coverage_estimate`):
  338. - coverage < 0.6 AND budget remaining AND tier in {standard, deep, audit} → expand citations (STEP 9)
  339. - coverage > 0.85 OR budget exhausted → stop, write report (STEP 10+)
  340. - ambiguous → tell user the numbers and ask
  341. ### STEP 9 — Expand citations (if applicable)
  342. 📖 BEFORE THIS STEP, read: `references/citation_chasing.md`.
  343. For top-rcs papers (rcs >= 7), get the citation network. Pass the seed's DOI when it has one: a DOI also works on the Semantic Scholar fallback, while a bare W-ID cannot be resolved outside OpenAlex.
  344. ```bash
  345. PYTHONPATH=$PSP_HOME \
  346. python3 -m scripts.openalex_helper citation-network <doi_or_openalex_id> \
  347. --refs-limit 25 --cited-by-limit 25 \
  348. > "$SEARCH_DIR/raw/citations_01.json" # one file per seed: citations_02.json, ...
  349. ```
  350. Then loop back to STEP 5: add the `raw/citations_*.json` files to `--input-files` (the resolver reads their `references` / `cited_by` lists), re-classify only the new entries in STEP 6, and re-run STEP 7.
  351. ### STEP 10 — Enrich top-N papers (L3, optional but recommended)
  352. 📖 BEFORE THIS STEP, read: `references/ss_helper_cheatsheet.md` and `references/crossref_helper_cheatsheet.md`.
  353. For papers with rcs >= 6, enrich with Semantic Scholar (influentialCitationCount + abstract fallback + tldr). Both helpers read the classified KG and write the new fields back into it, leaving every other field as it was; `--min-rcs 6` limits them to the top papers. Run this before STEP 11, so the summary can rank by `influential_citation_count`.
  354. For Quick tier, skipping STEP 10 is acceptable — but **announce the skip** per Rule C ("Skipped L3 enrichment → no influentialCitationCount; re-run at `--tier standard` to include this").
  355. ```bash
  356. # Semantic Scholar — adds influentialCitationCount + abstract fallback + tldr
  357. PYTHONPATH=$PSP_HOME \
  358. python3 -m scripts.ss_helper \
  359. --input-file "$SEARCH_DIR/kg_classified.json" \
  360. --mode enrich --min-rcs 6 \
  361. --output-file "$SEARCH_DIR/kg_classified.json"
  362. ```
  363. It prints one stderr line saying how many papers were enriched and, if Semantic Scholar refused (rejected key, rate limit), why. Relay that line when the count is short; the run continues either way.
  364. **CrossRef (funder / license / clinical-trial number) only when those matter** — a clinical or funding question, or the user asks: the report does not display these fields.
  365. ```bash
  366. PYTHONPATH=$PSP_HOME \
  367. python3 -m scripts.crossref_helper \
  368. --input-file "$SEARCH_DIR/kg_classified.json" \
  369. --mode all --min-rcs 6 \
  370. --output-file "$SEARCH_DIR/kg_classified.json"
  371. ```
  372. **Optional (additive) — journal partitions (中科院 / JCR / SJR).**
  373. The multi-platform partition layer labels every paper with **all three** platforms. It is **opt-in and off by default — skip it and the report is byte-for-byte unchanged** (R-19). 📖 Read `references/journal_metrics.md` first (it is the SSOT for sources, the ISSN join, attribution, and R-04 naming).
  374. - **First use needs a one-time fetch** (init-once; data is pulled at runtime into
  375. `~/.paper-search-pro/ranks/` and **never bundled in the repo**). If you have not
  376. fetched before, run it once (and tell the user it is a one-time step):
  377. ```bash
  378. PYTHONPATH=$PSP_HOME python3 -m scripts.journal_rank fetch # all three
  379. # or a single platform: ... journal_rank fetch --platform cas
  380. PYTHONPATH=$PSP_HOME python3 -m scripts.journal_rank info # what's cached
  381. ```
  382. - **A tier was requested** → the papers were already labelled and filtered right after STEP 5; nothing to do here.
  383. - **No tier requested, the user wants to see partitions** → label only (no filter):
  384. ```bash
  385. PYTHONPATH=$PSP_HOME python3 -m scripts.rank_filter \
  386. --kg "$SEARCH_DIR/kg_classified.json" --output "$SEARCH_DIR/kg_classified.json"
  387. ```
  388. With nothing cached it prints a one-line hint and changes nothing; tell the user they can `journal_rank fetch` to enable partitions.
  389. - **R-04 naming** is enforced for you in the serialised dict: only JCR exposes an
  390. `impact_factor` (the real IF); 中科院"区" and SJR quartile are **分区/quartile**.
  391. ### STEP 11 — Write the executive summary
  392. 📖 BEFORE THIS STEP, read: `references/summary_writer.md`.
  393. 📖 Also read: `references/report_title.md`, then author `DISPLAY_TITLE` alongside the summary. This is a **scholarly, evidence-bounded report title**, finalized from the retained corpus — never a copy of `USER_QUERY`, `SEARCH_TOPIC`, or the filter list. It carries the report's central narrative and visual identity. Language, date, database, journal-tier, export, and workflow requirements stay in Methods / PRISMA-S unless they are themselves scientifically meaningful. If the evidence cannot support a specific title, use the localized safe fallback (`文献检索报告` / `Literature Search Report`) rather than putting the raw request in the H1. Run the reference's pre-render acceptance check before STEP 12.
  394. Write a ~300-word executive summary in your own words based on the classified papers:
  395. - The field's main consensus
  396. - Key methods / theoretical frameworks
  397. - Notable disagreements or open questions
  398. - Top 3-5 most influential papers (by `influential_citation_count` when available)
  399. - *(Optional)* journal tier of the leading papers, **if** you attached SJR metrics in STEP 10 — phrase as "SJR分区 / 期刊影响力", never "影响因子 / JCR" (R-04). Skip this bullet entirely when no metrics were attached.
  400. Save to `"$SEARCH_DIR/summary.md"`.
  401. **Partition default / ask / filter / report / switch flow (additive — only when partitions are in play).** When journal partitions are in play (filtered after STEP 5, or labelled in STEP 10), follow this flow; it is entirely opt-in and changes nothing on the default no-partition path (R-19):
  402. - **Factory default standard = JCR.** The persistent default lives in config `rank.default_platform` (out of the box: `jcr`; the user can set it to `cas`/`sjr`). The default platform only **labels** every paper — it does **not** filter unless the user actually asked for a tier.
  403. - **No partition mentioned → do not filter.** Just show all three platforms' labels per paper (STEP 10 annotate already did this) and let the user read / refine. Never invent a tier filter the user didn't ask for.
  404. - **A tier was requested (from STEP 1 intent or the user this round) → filter once, before classification** (right after STEP 5, with `rank_filter`). Use the STEP 1 parse: `platform` + `tiers`/`quartiles`/`top`. A per-request tier filter is **transient — never auto-persist it** to config. The persistent default is only ever changed when the user explicitly says "以后都用 X".
  405. - **Ambiguous bare "Q1" with no platform and no persistent default → ask one short question** (you should already have asked in STEP 1; if not, ask now): *"按 JCR 还是 SJR?顺带设默认吗?"* Small confirmations are welcome, but do not over-ask.
  406. - **Always report what this run did.** After filtering, tell the user in one line: *"本次按 {platform} 筛(留 N / 滤 M",* plus a light offer: *"可换中科院/JCR/SJR 或换档位、可设为以后的默认。"* Include the per-platform attribution (`journal_rank.ATTRIBUTION[platform]`).
  407. - **Switching standard or tier = RE-FILTER the pool, NOT a re-search.** When the user then says "换成中科院二区" or "看看 SJR Q1", do **not** re-run the search: re-run `rank_filter` on the full pool `kg.json` with the new platform / tiers (seconds). Papers it newly admits have no score yet — classify only those (STEP 6), then re-run `rcs_parser` over all `classifications/` with `--kg kg_ranked.json`. **Only when the re-filter leaves too few survivors** do you go back to STEP 3 and deepen the search. This "切换=重筛不重搜" rule is what makes partition exploration cheap.
  408. - **Persisting the default** (only on an explicit "以后都用 X"): set `rank.default_platform` in `~/.paper-search-pro/config.yaml`. Tier档位 is never persisted — only the platform default is.
  409. - **R-04 naming in the summary bullet too:** 中科院"区" and SJR quartile are **分区 / quartile**; only JCR IF(2024) is an **影响因子 / Impact Factor**. The OpenAlex 2yr-mean-citedness figure is "期刊影响力" (open), never a JIF.
  410. ### STEP 11.5 — Export search strategies (opt-in — never on the default path)
  411. **Trigger matrix — decide silently, before anything else:**
  412. | Run | Export behavior |
  413. |------|-----------------|
  414. | Quick | **Does not run. Do not mention it, do not ask** — go straight to STEP 12. This silent skip is the one exception to Rule C: announcing it would itself disturb the untouched default path (R-19). |
  415. | Standard | **Does not run during the search** — no question, go straight to STEP 12. **At STEP 14, offer it in one sentence only when this run has a gap the export fills:** the search space included Chinese (`zh` / `both`: 知网 / 万方 hold much of what PSP cannot reach), or `coverage_estimate` < 0.6 (other databases can fill in). No such gap → say nothing. Skip the offer if STEP 4 already made it this run. Accepted → run this step, then re-run 12a–12c so the report gains the export tab. |
  416. | Deep | Offer once, one light sentence: *"要不要顺带导出各平台可粘贴的专业检索式?"* Accepted → run; declined or unanswered → skip without further mention. |
  417. | Audit | **Runs by default** — it is the deliverable behind the Audit disclaimer's promise (Example 4). |
  418. | Explicit ask, any tier | "给我 WOS 检索式" / "我要去知网查" / "导出检索式" / STEP 4's 知网 offer accepted → run immediately, whatever the tier. |
  419. 📖 BEFORE THIS STEP (when it triggers), read: `references/search_export/methodology.md` — the rulebook for every semantic judgment below. Add `references/search_export/chinese_methodology.md` whenever the zh/both space exports CNKI / 万方 / SinoMed (Chinese strategies are NOT word-for-word translations of Western boolean).
  420. **Layer 1 — semantics. This is YOUR work (main agent); the script only assembles syntax:**
  421. 1. **Rebuild concept blocks** from `"$SEARCH_DIR/query_plan.json"` under methodology.md's block discipline — within-block OR = synonyms of ONE concept only; blocks joined by AND; default 2 blocks (P+I), C/O only when core and consistently reported in titles/abstracts; NOT banned. Do not copy query_plan blocks as-is: this rebuild is where mixed-concept blocks get fixed.
  422. 2. **Expand synonyms & entry terms** per block — spelling variants (tumour/tumor), abbreviation + full form (MBSR + "mindfulness-based stress reduction"), related terms. **On a zh / both run, also fill each block's `free_text_zh` with the Chinese synonyms** (简繁 / 别名 / 全称–缩略 variants — Chinese has no truncation, so enumerate explicitly): the CJK hosts (CNKI / 万方 / SinoMed) read **only** `free_text_zh`, and a block without it makes every Chinese strategy be honestly withheld — English words are never rendered into a Chinese database.
  423. 3. **Controlled-vocab candidates per platform** — judge MeSH / Emtree / CINAHL / APA / CMeSH independently per library; never symbol-translate one thesaurus into another. Prefer the MeSH already backfilled into the KG by STEP 4 (real descriptors from real hits).
  424. 4. **Trim the platform set by discipline** from the Audit full set (PubMed, WOS, Scopus, Embase, Cochrane CENTRAL, PsycINFO, CINAHL, ERIC, IEEE Xplore, ACM DL, EconLit, CNKI, 万方, SinoMed, ClinicalTrials.gov) — a medical topic doesn't need IEEE/ACM; a social-science topic doesn't need Cochrane/SinoMed. **zh / both runs always include CNKI + 万方 + SinoMed.**
  425. 5. **Register follows the tier** (audit = recall-leaning, controlled + free-text double-track). Need a study-design filter (e.g. RCT)? 📖 `references/search_export/filters_library.md` — use a canned validated filter verbatim; never write your own, and never add one on CENTRAL.
  426. 6. **PRESS six-domain self-review** of 1–5 before any syntax exists. 📖 `references/search_export/press_checklist.md`.
  427. Write the outcome to `"$SEARCH_DIR/concept_model.json"` in the generator's wrapper shape: `{topic, framework, register, language_space, search_id, platforms, concept_model: {blocks (free_text + free_text_zh on zh/both + controlled_vocab_candidates), operator_logic, omitted_blocks + reasons, register_notes}}`. **Write `omitted_blocks.reason` and `register_notes` in the USER'S language** — they surface verbatim in the user-facing `search_strategies.md` (a Chinese-speaking user gets Chinese notes, not English pass-through).
  428. **Layers 2+3 — mechanical assembly + verification (the script's job; never hand-assemble per-host syntax):**
  429. ```bash
  430. PYTHONPATH=$PSP_HOME \
  431. python3 -m scripts.search_export.generate \
  432. --concept-model "$SEARCH_DIR/concept_model.json" \
  433. --out "$SEARCH_DIR"
  434. ```
  435. Optional flags (verified against argparse): `--platforms pubmed,wos,cnki` (csv) overrides the wrapper's `platforms`; `--topic` / `--framework` / `--register` / `--language-space` / `--search-id` override the wrapper's run-level fields; `--no-verify-vocab` skips the MeSH/ERIC free-API check (terms stamped unverified); `--live-verify-links` live-GETs each A-tier link for a fresh `verified_http`/date.
  436. Emits `search_strategies.md` (paste-ready, per platform) + `search_strategies.json`. Under the hood it reads the per-host syntax cards (`references/search_export/syntax_cards/<host>.md`) and the proximity conversion table (n-values are never hand-computed — not by you either), builds clickable deep links only for the free A-tier platforms (PubMed / ERIC / ClinicalTrials.gov; no link ever circumvents a login or captcha wall), API-verifies MeSH/ERIC terms, leaves Emtree/CINAHL/APA/CMeSH flagged 待人工核对, and lints every strategy — **a linter-rejected string is withheld, never emitted**. Downstream pickup: STEP 12a auto-discovers `search_strategies.json` beside `report_data.json` and folds it in (no extra flag); for STEP 13, append `--search-strategies "$SEARCH_DIR/search_strategies.json"` to the `prisma_s_logger` command so PRISMA-S items 8/1/9/10 are enriched from it.
  437. **Check before handing over** (the honesty gate): the `.json` carries every platform's three-state verification label (🟩机械已验 / 🟨语法已验·词表待核 / 🟦结构参考) and review points — verify they are correct; the user-facing `.md` renders these as plain-language "使用前请核对" notes per platform (no internal jargon) — verify each note is clear and actionable; subscription-wall platforms are honestly marked "需机构登录,未在墙内实测"; CNKI / 万方 / SinoMed are delivered as paste-into-检索框 strategies, not URLs. Keep the quality claim at "专业初稿 + 标注复核点" — never "可署名直用 / 馆员级".
  438. ### STEP 12 — Render the report
  439. 📖 BEFORE THIS STEP, read: `references/output_files.md`.
  440. ```bash
  441. # 12a. Materialize data for the renderer (also writes sibling chart_data / paper_list / metadata / prisma_log)
  442. PYTHONPATH=$PSP_HOME \
  443. python3 -m scripts.data_materialization \
  444. --kg "$SEARCH_DIR/kg_classified.json" \
  445. --summary "$SEARCH_DIR/summary.md" \
  446. --query "<original query>" \
  447. --search-topic "$SEARCH_TOPIC" \
  448. --display-title "$DISPLAY_TITLE" \
  449. --language "$UI_LANG" \
  450. --tier "<quick|standard|deep|audit>" \
  451. --search-id "$SEARCH_ID" \
  452. --snapshots "$SEARCH_DIR/curve.json" \
  453. --output "$SEARCH_DIR/report_data.json"
  454. # 12b. Render HTML (Shadcn webartifacts — only renderer; no size cap)
  455. # --language $UI_LANG selects EN vs ZH UI; the bundle ships with both
  456. # dictionaries inlined, $UI_LANG just picks which one mounts. Resolution
  457. # order inside the renderer is: explicit --language > metadata.language > en.
  458. PYTHONPATH=$PSP_HOME \
  459. python3 -m scripts.html_renderer_webartifacts \
  460. --data "$SEARCH_DIR/report_data.json" \
  461. --output "$SEARCH_DIR/report.html" \
  462. --query "<original query>" \
  463. --search-topic "$SEARCH_TOPIC" \
  464. --display-title "$DISPLAY_TITLE" \
  465. --language "$UI_LANG"
  466. # add --rank-platform cas|jcr|sjr when this run filtered on a platform,
  467. # so the badges and zone filter show that platform (default: JCR)
  468. # 12c. MD report (uses materialized-dir for speed)
  469. PYTHONPATH=$PSP_HOME \
  470. python3 -m scripts.md_report \
  471. --materialized-dir "$SEARCH_DIR" \
  472. --summary "$SEARCH_DIR/summary.md" \
  473. --query "<original query>" \
  474. --search-topic "$SEARCH_TOPIC" \
  475. --display-title "$DISPLAY_TITLE" \
  476. --language "$UI_LANG" \
  477. --tier "<quick|standard|deep|audit>" \
  478. --output "$SEARCH_DIR/report.md"
  479. # 12d. Exports (BibTeX / RIS / CSV / papers.json — only rcs >= 5 by default)
  480. PYTHONPATH=$PSP_HOME \
  481. python3 -m scripts.generate_exports \
  482. --kg "$SEARCH_DIR/kg_classified.json" \
  483. --output-dir "$SEARCH_DIR/" \
  484. --min-rcs 5
  485. ```
  486. If 12a–12c print `No scholarly display title was given`, `DISPLAY_TITLE` was empty: the report H1 is the generic fallback. Write the title (STEP 11, `references/report_title.md`) and re-run 12a–12c; nothing needs re-searching.
  487. `data_materialization` accepts `--wall-clock-seconds` if you tracked elapsed time yourself; otherwise the helper computes it from session timestamps when available.
  488. ### STEP 13 — Write PRISMA-S log
  489. 📖 BEFORE THIS STEP, read: `references/prisma_s_checklist.md`.
  490. ```bash
  491. PYTHONPATH=$PSP_HOME \
  492. python3 -m scripts.prisma_s_logger \
  493. --search-id "$SEARCH_ID" \
  494. --kg "$SEARCH_DIR/kg_classified.json" \
  495. --user-query "<original query>" \
  496. --tier "<quick|standard|deep|audit>" \
  497. --query-plan "$SEARCH_DIR/query_plan.json" \
  498. --snapshots "$SEARCH_DIR/curve.json" \
  499. --output "$SEARCH_DIR/execution_log.json"
  500. ```
  501. This captures the 16 PRISMA-S items for transparency / audit.
  502. ### STEP 14 — Open the report + report to user
  503. **First**, auto-open the HTML report in the user's default browser (do NOT wait for the user to ask). Platform-aware Bash:
  504. ```bash
  505. # macOS — most common dev setup
  506. open "$SEARCH_DIR/report.html"
  507. # Linux fallback — xdg-open "$SEARCH_DIR/report.html"
  508. # Windows fallback — start "" "$SEARCH_DIR/report.html"
  509. ```
  510. Use `open` on macOS by default. If it fails (rare — only bare Linux containers), fall through to `xdg-open` then `start`. **Do NOT skip this step** — the user just waited 5-30 minutes for the report; they should see it the moment it's ready.
  511. **Then** tell the user:
  512. - "Opened report in your default browser." (1 line confirmation)
  513. - Where the report is on disk (absolute path: `$SEARCH_DIR/report.html`) — so the user can find it later
  514. - Top findings (3-5 sentences from your executive summary)
  515. - Any caveats — including any steps you skipped per Rule C (e.g. "PubMed wasn't queried because no medical signals were detected", "Skipped STEP 10 L3 enrichment because Quick tier; re-run at standard to include funder/license fields")
  516. - Standard tier, only when STEP 11.5's Standard row finds a gap: one sentence offering the strategy export, naming the gap and the cost — e.g. *"这次中文侧主要缺知网、万方的文献;需要的话我把这两个库的专业检索式写好(约 3–4 分钟),粘进检索框就能查。"* or *"估算覆盖率 45%,还有不少没找到;需要的话我把 WOS、Scopus、PubMed 的检索式写好(约 3–4 分钟),你拿去补检。"*
  517. ---
  518. ## Output convention
  519. 📖 See `references/output_files.md` for the full directory layout. All paths below are **relative to the user's working directory (PWD)** — never the Skill asset directory.
  520. ```
  521. $(pwd)/paper-search-results/<search_id>/
  522. ├── report.html # Main deliverable (Shadcn style)
  523. ├── report.md # Markdown copy
  524. ├── papers.csv # Spreadsheet export
  525. ├── papers.bib # Citation manager import (BibTeX)
  526. ├── papers.ris # Alternative citation format
  527. ├── papers.json # Full structured data
  528. ├── kg_classified.json # Internal KG with RCS scores
  529. ├── summary.md # Your executive summary
  530. ├── metadata.json # Includes original_user_query / search_topic / display_title
  531. ├── execution_log.json # PRISMA-S 16-item log
  532. ├── report_data.json # Renderer bundle
  533. ├── chart_data.json # Sibling: chart series
  534. ├── paper_list.json # Sibling: per-paper list
  535. ├── prisma_log.json # Sibling: PRISMA log JSON view
  536. ├── curve.json # Coverage snapshot (STEP 7)
  537. ├── query_plan.json # STEP 1 output
  538. ├── raw/ # Retrieval output only, one file per search (openalex.json, pubmed.json, citations_01.json, …)
  539. ├── batches/ # batch_NNN.jsonl files
  540. └── classifications/ # batch_NNN_result.json files
  541. ```
  542. ---
  543. ## Error handling
  544. 📖 See `references/error_handling.md`. Common cases:
  545. | Error | What to do |
  546. |-------|-----------|
  547. | Config missing keys | Direct user to `references/setup.md`, halt |
  548. | Rate limit (SS 429 / NCBI 429) | Helper auto-retries; if persistent, drop that enricher |
  549. | SS enrichment prints "0/N papers enriched (…)" | Semantic Scholar refused (rejected key or rate limit) and the helper stopped early; relay the line, carry on without it |
  550. | OpenAlex unavailable (budget spent / throttled / down) | `openalex_helper` switches the call to Semantic Scholar itself; relay its stderr line and continue. Exit `3` = Semantic Scholar could not serve it either: handle it like any OpenAlex error (tell the user what happened and when OpenAlex resets) |
  551. | OpenAlex 404 on DOI | Use title search fallback (helper handles) |
  552. | L2 booster returns 0 papers | Skip silently, note in PRISMA-S log via STEP 13 |
  553. | SubAgent classifier returns invalid JSON | `rcs_parser.py` has 5-layer fallback (regex parse) |
  554. | HTML output size | No size cap or fallback — `html_renderer_webartifacts` always produces the full Shadcn bundle. Typical 250-paper report is ~1.7 MB; pathological 1000+ paper Audit may reach 5-10 MB. All modern browsers handle 10+ MB HTML cleanly. |
  555. ---
  556. ## References (progressive disclosure — read the one for the step you're on)
  557. You won't read all of these every run, and shouldn't. Read a step's reference when you reach that step and it's non-trivial for the case (Rule D). **core** = read for its step; **cond** = only when its trigger fires.
  558. | File | Load | Read when |
  559. |------|------|---------|
  560. | `tier_decision.md` | core | choosing the tier (before STEP 0) |
  561. | `setup.md` | core | STEP 0 — config + 5-key acquisition |
  562. | `runtime_bootstrap.md` | cond | STEP 0/1 — only if `$PSP_HOME` env injection failed, or you need the full install-path list / language-routing rationale |
  563. | `query_planner.md` | core | STEP 1 — PICO / SPIDER / PEO frameworks |
  564. | `source_routing.md` | core | STEP 1 language scope (§"Language scope" SSOT) + STEP 2 routing + STEP 5 field-priority merge |
  565. | `openalex_helper_cheatsheet.md` | core | STEP 3 + STEP 9 — subcommands, params, gotchas |
  566. | `pubmed_helper_cheatsheet.md` | cond | STEP 4 — only if PubMed enabled |
  567. | `arxiv_helper_cheatsheet.md` | cond | STEP 4 — only if arXiv enabled |
  568. | `classifier_subagent_prompt.md`, `rcs_rubric.md` | core | STEP 6 — SubAgent prompt + RCS 0-10 rubric |
  569. | `stop_decision.md` | core | STEP 7 + STEP 8 |
  570. | `citation_chasing.md` | cond | STEP 9 — only if expanding citations |
  571. | `ss_helper_cheatsheet.md`, `crossref_helper_cheatsheet.md` | cond | STEP 10 — only if enriching top-N |
  572. | `summary_writer.md` | core | STEP 11 |
  573. | `report_title.md` | core | STEP 1 normalized topic + STEP 11 evidence-bounded display title; prevents raw-query H1 |
  574. | `search_export/methodology.md` | cond | STEP 11.5 — only when strategy export triggers (Audit default / explicit ask / accepted Deep offer); the layer-1 semantic rulebook |
  575. | `search_export/chinese_methodology.md` | cond | STEP 11.5 — zh/both track only (CNKI / 万方 / SinoMed strategies; not a translation of Western boolean) |
  576. | `search_export/press_checklist.md` | cond | STEP 11.5 — PRESS six-domain self-review of the concept model |
  577. | `search_export/filters_library.md` | cond | STEP 11.5 — only when a study-design filter is wanted (canned validated filters; never self-written) |
  578. | `search_export/syntax_cards/<host>.md` | cond | STEP 11.5 — per-host syntax facts, machine-read by the generator/linter; open one yourself only when hand-tuning a single platform's strategy |
  579. | `journal_metrics.md` (SSOT) | cond | STEP 1 / STEP 10-11 — only if the user wants journal partitions (中科院 / JCR / SJR) or SJR metrics; ISSN join, attribution, R-04 naming |
  580. | `output_files.md` | core | STEP 12 — output dir layout (PWD-relative) |
  581. | `prisma_s_checklist.md` | core | STEP 13 |
  582. | `agent_mode.md` (SSOT) | cond | only when another agent / headless calls this Skill — `agent_search` envelope + flags |
  583. | `error_handling.md` | cond | any unexpected error |
  584. ---
  585. ## Examples
  586. ### Example 1: Quick scan (5-8 min)
  587. User: "find 5-6 high-impact papers on prospect theory in decision making, classics + a couple recent ones"
  588. You: Pick Quick tier (signals: "5-6", "high-impact", short query). Run STEP 0-2 lightweight. In STEP 3 use `openalex_helper seminal` for classics + `openalex_helper search` for recent (year >= 2020). No L2 boosters in STEP 4 (pure social science). In STEP 6 classify 20-30 papers via 2 parallel SubAgents in one message. STEP 7 + 8 still run (curve renders in the report). Announce skip of STEP 9 + STEP 10 per Rule C. Render report.
  589. ### Example 2: Standard ZH (10-17 min)
  590. User: "用 paper-search-pro 帮我找一些关于工作记忆训练干预的文献 老板让我看 我对这块完全不懂 要给老年人群体的最好 谢谢🙏"
  591. You: Pick Standard tier (default; signals: "找一些", "老板让我看"). Detect medical signal ("干预" + "老年") in STEP 2 → enable PubMed enricher. Query plan: PICO (P=elderly, I=working memory training, O=cognitive outcomes). OpenAlex `double-sort` top-100 in STEP 3. PubMed `enrich` of openalex.json in STEP 4. Federate in STEP 5 (dict output). Classify 60-180 papers via 4 batches × 5 SubAgents — **all 5 Tasks in one message** (Rule B). STEP 7 curve, STEP 8 expand if saturation < 0.6. Render report.
  592. ### Example 3: Deep × Lit review writing (30-45 min)
  593. User: "I'm writing a proper literature review article on attachment and human-robot interaction in elderly care contexts. Need real depth..."
  594. You: Pick Deep tier ("proper literature review article" + "real depth"). Cross-domain (psychology + CS) in STEP 2 → enable arXiv's recent layer and OpenReview. SPIDER plan in STEP 1. OpenAlex `double-sort` top-200 + `reviews` subcommand in STEP 3. Classify 200+ papers via 8 batches in STEP 6 — dispatch 5 parallel Tasks per message, two waves. STEP 9 expand citations 2 hops. STEP 10 enrich top-50 with SS + CrossRef. Render report with PRISMA-S log.
  595. ### Example 4: Audit × SR-prep (2-3 hr)
  596. User: "Need help — preparing a systematic review on dietary interventions for IBS in adults. Inclusion criteria: RCTs, adult populations (≥18), low-FODMAP or fiber-based interventions, English-language, published 2010-present."
  597. You: Pick Audit tier ("systematic review" + PICO + IC). **Show limitations warning first and get user confirmation** — the Audit disclaimer is a deliver-on-it promise, fulfilled by STEP 11.5 (which Audit runs by default). At delivery it reads:
  598. > 这是 SR 前期助手,不是 PRISMA 替代。我已为你写好各平台**可粘贴的专业检索式初稿**——每个平台附「使用前请核对」清单(已对官方词表核实的 MeSH 主题词、与需要你在库内人工确认的 Emtree 等主题词,都分别写明了);注册制 SR 仍需你在订阅库亲自执行,并补 **ClinicalTrials.gov(注册库检索是方法学硬要求,已给检索式+直达链接)与 ICTRP/灰色文献**。
  599. (Up front, before the run, phrase the same promise in future tense — "我会为你写好…".) STEP 4 use `pubmed_helper search-mesh "Irritable Bowel Syndrome" --pub-type "Randomized Controlled Trial"` for independent MeSH search. STEP 3 also call `openalex_helper journal-list --preset Cochrane`. STEP 10 add CrossRef enrichment for funder + clinical-trial-number. STEP 11.5 exports the per-platform strategies (Audit default). Render with PRISMA flow chart in STEP 12.
README.md · README · 243 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="right">
  2. **English** · [中文](./README.zh.md)
  3. </div>
  4. <br />
  5. <div align="center">
  6. # paper-search-pro
  7. **Academic literature discovery as a Skill.**
  8. <br/>
  9. Built natively for Claude Code; runs in Codex and any agent that loads the SKILL.md format.
  10. <br/>
  11. Five open sources + native-Chinese search + AI-venue acceptances · four tiers · journal partitions · paste-ready search strategies for WOS / Scopus / Embase / 知网 · single-file Shadcn report.
  12. <br/>
  13. <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-Apache_2.0-000?style=flat-square" alt="Apache 2.0"/></a>
  14. <a href="SKILL.md"><img src="https://img.shields.io/badge/agent-Skill-000?style=flat-square" alt="Agent Skill"/></a>
  15. <img src="https://img.shields.io/badge/Python-3.10+-000?style=flat-square" alt="Python 3.10+"/>
  16. <img src="https://img.shields.io/badge/version-2.5.0-000?style=flat-square" alt="v2.5.0"/>
  17. </div>
  18. <br/>
  19. ![Findings — Swiss hero](docs/screenshots/findings.png)
  20. <div align="center">
  21. **[→ Live demo (opens the actual report in your browser)](https://o0000-code.github.io/paper-search-pro/)**
  22. If it looks useful, a star makes it easy to find later and helps it reach the next person who needs it.
  23. </div>
  24. <br/>
  25. ## What it does
  26. You ask your agent for papers; this Skill runs a real multi-source literature search across **OpenAlex · Semantic Scholar · CrossRef · PubMed · arXiv** — plus native-Chinese sources **NSSD** (社会科学) and **yiigle** (中华医学) when you query in Chinese, and **OpenReview** (ICLR / NeurIPS / ICML acceptances) for AI topics — classifies relevance via parallel LLM SubAgents, and writes a self-contained HTML report you can open in any browser. No external LLM keys — your agent **is** the LLM.
  27. For the databases it *can't* self-containedly reach (Web of Science, Scopus, Embase, 知网 CNKI, 万方, SinoMed …), it does the next best thing: on an Audit run or when you ask ("给我 WOS 检索式" / "我要去知网查"), it writes you a **paste-ready professional search strategy** per platform — correct field tags, controlled vocabulary + free-text double-track, per-host syntax — distilled from the Cochrane Handbook / PRESS / PRISMA-S, with each strategy carrying a three-state verification label and its review points. It's a professional first draft with flagged review points, not a sign-off-ready deliverable — and it never scrapes a closed database.
  28. ```text
  29. In your agent's chat, after install:
  30. Find papers on working memory training in older adults
  31. ```
  32. CJK in the query routes to Chinese UI; otherwise English. Both report flavors use the same data pipeline.
  33. <br/>
  34. ## Use cases
  35. | Scenario | Tier | What you get |
  36. |---|:---:|---|
  37. | Scope a topic before writing the proposal | Quick / Standard | 20–60 top-RCS papers + 300-word executive summary in 8 min |
  38. | Background section for course paper / thesis chapter | Standard | 60–180 papers screened, BibTeX ready for Zotero / Mendeley |
  39. | Writing a review article — need real domain coverage | Deep | 180–400 papers + 1-hop citation chasing + topic clustering |
  40. | SR-prep: PRISMA log + reproducibility audit | Audit | 400–1000+ papers, PRISMA-S 16-item disclosure, MeSH-precise |
  41. | Onboarding a research assistant in a new field | Quick | Hand them the report.html — three tabs, hover for context |
  42. <br/>
  43. ## Install
  44. Clone into your agent's Skills directory. The target path varies by agent — pick the one matching what you use:
  45. ```bash
  46. # Pick ONE target directory, depending on your agent:
  47. # ~/.claude/skills/paper-search-pro # Claude Code
  48. # ~/.codex/skills/paper-search-pro # Codex CLI
  49. # ~/.agents/skills/paper-search-pro # cross-agent convention (Goose, Roo, etc.)
  50. # ~/.config/opencode/skills/paper-search-pro # OpenCode
  51. # ~/.codeium/windsurf/skills/paper-search-pro # Windsurf
  52. # ./.claude/skills/paper-search-pro # project-local (Cursor, etc.)
  53. git clone https://github.com/O0000-code/paper-search-pro.git \
  54. ~/.claude/skills/paper-search-pro # change to your chosen path
  55. # Point PSP_HOME at wherever you cloned. SKILL.md STEP 0 also auto-resolves
  56. # the common paths above, so this manual export is only needed for non-standard locations.
  57. export PSP_HOME="$HOME/.claude/skills/paper-search-pro"
  58. python3 -m pip install -r "$PSP_HOME/scripts/requirements.txt"
  59. # Optional: install the exact dependency versions validated by CI.
  60. python3 -m pip install -r "$PSP_HOME/scripts/requirements.lock"
  61. ```
  62. Five free API keys (~15 min total) — see [`references/setup.md`](references/setup.md).
  63. <br/>
  64. ## Four tiers
  65. The Skill picks **Standard** by default. Wording like *thorough*, *systematic review*, or *几篇* overrides.
  66. | | Tier | Wall-clock | Papers | Trigger signals |
  67. |:---:|:---|:---:|:---:|:---|
  68. | `▏` | Quick | 5–8 min | 20–60 | *scan · "5 papers" · before-tomorrow scope* |
  69. | `▍` | **Standard** | 10–17 min | 60–180 | *default — background reading · course paper* |
  70. | `▋` | Deep | 30–45 min | 180–400 | *review article · thorough coverage · 综述写作* |
  71. | `█` | Audit | 2–3 hr | 400–1000+ | *systematic review · PRISMA · Cochrane-adjacent* |
  72. <br/>
  73. ## What each report contains
  74. Three tabs · three hero layouts · two list densities · responsive at 860 px · bilingual UI · Noto Sans SC inlined · fully offline.
  75. Each report has a scholarly, evidence-bounded title authored after screening. The verbatim user request remains in audit metadata, while language, date, database, journal-tier, and export constraints stay in Methods rather than being repeated in the visual H1.
  76. <table>
  77. <tr>
  78. <td width="50%" valign="top">
  79. <a href="docs/screenshots/methods.png"><img src="docs/screenshots/methods.png" alt="Methods · Coverage"/></a>
  80. <br/>
  81. <sub><strong>Methods · Coverage</strong> — saturation curve, estimated coverage with its interval, current position on the curve.</sub>
  82. </td>
  83. <td width="50%" valign="top">
  84. <a href="docs/screenshots/methods-2.png"><img src="docs/screenshots/methods-2.png" alt="Methods · Distribution"/></a>
  85. <br/>
  86. <sub><strong>Methods · Distribution</strong> — publications by year, RCS histogram, citation scatter.</sub>
  87. </td>
  88. </tr>
  89. <tr>
  90. <td valign="top">
  91. <a href="docs/screenshots/audit.png"><img src="docs/screenshots/audit.png" alt="Audit · PRISMA-S"/></a>
  92. <br/>
  93. <sub><strong>Audit · PRISMA-S</strong> — 16-item disclosure log: performed · implicit · skipped.</sub>
  94. </td>
  95. <td valign="top">
  96. <a href="docs/screenshots/discovery-report.png"><img src="docs/screenshots/discovery-report.png" alt="Discovery Report layout"/></a>
  97. <br/>
  98. <sub><strong>Discovery Report layout</strong> — preprint-style hero with abstract paragraph + Roman tabs.</sub>
  99. </td>
  100. </tr>
  101. </table>
  102. **Journal partitions.** Every paper is tagged with its 中科院 (CAS) / JCR / SJR tier — a quiet badge on each card, the full three-platform breakdown in the detail panel, and a zone filter (`Q1 / ≥Q2 / ≥Q3`, or `一区 / ≥二区`) in the toolbar. The tables are fetched at runtime from public mirrors — never bundled — and attributed; only JCR's figure is labelled an impact factor.
  103. Outputs land in `$PWD/paper-search-results/<search_id>/`:
  104. ```text
  105. report.html Self-contained Shadcn report (opens directly in browser)
  106. report.md Markdown variant for pandoc · citation managers
  107. papers.csv Spreadsheet export
  108. papers.bib BibTeX for Zotero · Mendeley · LaTeX
  109. papers.ris RIS for EndNote · Papers
  110. papers.json Full structured data (UnifiedPaperEntity[])
  111. kg_classified.json Internal KG with per-paper RCS scores
  112. execution_log.json PRISMA-S 16-item disclosure log
  113. summary.md 300-word executive summary in the main agent's voice
  114. metadata.json Separate original request · search topic · display title
  115. ```
  116. <br/>
  117. ## Configuration
  118. Five keys, all free, ~15 min total. Real config lives at `~/.paper-search-pro/config.yaml` (mode 0600, auto-created). Template lives at [`assets/default_config.yaml`](assets/default_config.yaml).
  119. | Layer | Source | Role | Cost | Apply at |
  120. |:---:|:---|:---|:---:|:---|
  121. | **L1** | OpenAlex | primary — always on | free | <https://openalex.org/settings/api> |
  122. | **L2** | PubMed | medical · MeSH enricher | free | <https://account.ncbi.nlm.nih.gov/settings/> |
  123. | **L2** | arXiv | preprint freshness (T‑0\~T‑4) · AI topics (T‑0\~T‑365) | free | *(no signup — SDK enforces 1 req / 3 s)* |
  124. | **L3** | Semantic Scholar | influentialCitationCount + abstract fallback | free | <https://www.semanticscholar.org/product/api> |
  125. | **L3** | CrossRef | funder · license · clinical-trial-number | free | *(no key — `crossref_email` only)* |
  126. Verify readiness any time:
  127. ```bash
  128. PYTHONPATH=$PSP_HOME python3 -c \
  129. "from scripts.config import load_config; c = load_config(); \
  130. print('ready' if c.openalex_api_key and c.ncbi_email else 'missing')"
  131. ```
  132. **Primary source — by preference, *and* by fallback.** Two independent capabilities from one switch:
  133. - **Pick your primary.** OpenAlex is the default; set Semantic Scholar as the primary source instead when its corpus or field coverage suits your topic better.
  134. - **Automatic quota fallback.** When the active primary runs low on its daily quota (or starts erroring), the run continues on the other source rather than stopping — a depleted key degrades gracefully.
  135. <br/>
  136. ## Topic-specific sources
  137. Beyond the five general sources in the table above, these three switch on only for their topics and need no key; each is run by an authority in its field:
  138. | Source | Run by | When it is used | What it adds |
  139. |:---|:---|:---|:---|
  140. | NSSD (National Center for Philosophy and Social Sciences Documentation) | led by the Chinese Academy of Social Sciences | Chinese-language social-science and humanities queries | CSSCI and other Chinese social-science journals, which OpenAlex barely covers |
  141. | yiigle (Chinese Medical Journals Full-text Database) | Chinese Medical Association Publishing House | Chinese-language medical queries | Chinese originals and abstracts of the Chinese Medical Association journals |
  142. | OpenReview | non-profit platform run by a team at UMass Amherst | AI / machine-learning topics | Acceptance labels from ICLR, NeurIPS, ICML and others (e.g. "ICLR 2026 Oral"); accepted papers only |
  143. <br/>
  144. ## How it works
  145. A 14-step recipe in [`SKILL.md`](SKILL.md) drives every run. Python helpers in [`scripts/`](scripts/) do deterministic API work; relevance classification is delegated to up to five parallel SubAgents per round. No third-party LLM keys required — your agent is the LLM.
  146. ```
  147. ┌──────────────────────────────────────────────────────────┐
  148. │ Main agent reads SKILL.md (recipe) and drives the run │
  149. └────────┬───────────────────────────────────────┬─────────┘
  150. │ │
  151. ▼ ▼
  152. ┌───────────────┐ ┌───────────────┐
  153. │ Python │ ← deterministic API │ SubAgents │
  154. │ helpers │ work; no LLM, │ (parallel, │
  155. │ │ no LLM key │ 5 / round) │
  156. └───────┬───────┘ └───────┬───────┘
  157. │ │
  158. └───────────────────┬───────────────────┘
  159. ▼
  160. ┌─────────────────────────────┐
  161. │ Single-file HTML report │
  162. │ + MD + BibTeX + RIS │
  163. │ + CSV + PRISMA-S log │
  164. └─────────────────────────────┘
  165. ```
  166. Per-step reference documents live in [`references/`](references/) — tier decisions, query planning (PICO / SPIDER / PEO), source routing, helper cheatsheets, the RCS rubric, stop conditions, citation chasing, the classifier SubAgent prompt, the PRISMA-S 16-item checklist, summary writer guide, error handling, output conventions.
  167. **Headless mode for agents.** When the consumer is another agent rather than a person, [`scripts/agent_search.py`](scripts/agent_search.py) runs the deterministic core in a single command and returns one structured JSON envelope — deduped, relevance-scored, saturation-checked — with no HTML and no classification SubAgents. Same search discipline, machine-readable output.
  168. <br/>
  169. ## Contributors
  170. I maintain paper-search-pro mostly on my own, with help from three lovely contributors, [@haoxinC111](https://github.com/haoxinC111), [@MatrixA](https://github.com/MatrixA) and [@jack-reson8](https://github.com/jack-reson8). You're welcome to be the fourth. If it has helped you, your star means a lot to me, and I'll keep improving it.
  171. <br/>
  172. ## License
  173. Apache License 2.0 — see [`LICENSE.txt`](LICENSE.txt).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.