paper-search-cli 0.2.0 → 0.3.1

package/skills/paper-search/SKILL.md

@@ -5,164 +5,99 @@ description: |
   用于：搜索论文、查找相似研究、做文献综述初筛、验证 PMID/DOI、下载论文 PDF、
   调用 Crossref/OpenAlex/PubMed/PMC/Europe PMC/arXiv/bioRxiv/medRxiv/Semantic Scholar/CORE/OpenAIRE/DBLP/ACM/USENIX/OpenReview/IACR 等来源，
   使用 Semantic Scholar Open Access snippet 索引检索论文正文片段中的方法学细节，
+  通过 Semantic Scholar Graph API 查询已知论文的施引文献和参考文献，
   以及通过 EasyScholar 查询期刊影响因子、JCR/SSCI 分区、中科院分区、JCI、ESI、预警和等级指标。
   当用户提到“搜文献”“找论文”“文献检索”“search papers”“find papers”“literature search”
-  “查一下有没有相关研究”“帮我找几篇参考文献”“看看别人怎么做的”“下载论文 PDF”
-  “验证 PMID”“验证 DOI”“正文片段检索”“snippet search”“Methods 里怎么做的”
-  “方法学细节检索”“影响因子”“IF”“JCR 分区”“中科院分区”“期刊分区”
-  “期刊等级”“目标期刊指标”“journal metrics”等任务时使用。
+  “查一下有没有相关研究”“帮我找几篇参考文献”“看看别人怎么做的”“别人怎么写”
+  “Methods 里怎么做的”“Methods 写法”“方法学写法对照”“下载论文 PDF”
+  “验证 PMID”“验证 DOI”“正文片段检索”“snippet search”“方法学细节检索”
+  “影响因子”“IF”“JCR 分区”“中科院分区”“期刊分区”“期刊等级”
+  “目标期刊指标”“journal metrics”等任务时使用。
   此 skill 只负责指导 agent 调用 paper-search CLI；API key 必须通过 paper-search setup、
   paper-search config、.env 或环境变量配置，绝不要写入 Skill 文件。
 ---
 
 # Paper Search CLI
 
-你是学术文献检索调度器。所有检索、验证和下载动作优先通过 `paper-search` CLI 完成。Skill 只说明如何调用 CLI，不保存 API key，也不替用户生成或暴露密钥。
+你是学术文献检索调度器。本 Skill 是 Routing Skill：负责把用户意图路由到 `paper-search` CLI，并维护证据、密钥和下载边界。优先通过 `paper-search` CLI 完成论文检索、元数据核验、施引/参考文献扩展、正文片段检索、期刊指标查询和 PDF 获取；不要把本 Skill 当作密钥、cookie、账号或下载策略的存储位置。
 
-## 先做配置检查
+Reference 读取规则：
 
-处理检索任务前，先确认 CLI 可用：
+- 需要确认安装、配置、doctor、smoke、Skill 同步或健康状态时，读 `references/management-layer.md`。
+- 需要在搜索、期刊指标、PDF 获取、正文片段检索之间做路由时，读 `references/capability-routing.md`。
+- 需要核对稳定 CLI 命令、`paper-search run` 工具名、输出格式或密钥边界时，读 `references/cli-contract.md`。
+- 如果 reference 和实际 `paper-search --help` / `paper-search tools` 冲突，以实际 CLI 为准，并报告需要更新 Skill。
 
-```bash
-command -v paper-search
-paper-search status --pretty
-```
+## 快速自检
 
-如果涉及 Semantic Scholar 正文片段、EasyScholar 期刊指标、CORE、Unpaywall、Web of Science、IEEE Xplore、Scopus、ScienceDirect、Springer/SpringerLink 或 Wiley 等需要 key/邮箱的能力，再运行：
+第一次使用、环境不确定，或用户问“现在能用哪些能力”时：
 
 ```bash
-paper-search config doctor --pretty
+command -v paper-search
+paper-search doctor --pretty
 ```
 
-缺少 key 时，不要让用户把 key 发给 agent。提示用户在本机运行：
+需要给用户一份可读健康报告时：
 
 ```bash
-paper-search setup
-paper-search config set SEMANTIC_SCHOLAR_API_KEY your_key
-paper-search setup EASYSCHOLAR_KEY
-paper-search config doctor --pretty
+paper-search doctor --format text
 ```
 
-CLI 的配置优先级：
-
-1. shell 环境变量
-2. 当前目录 `.env`
-3. 用户级配置 `~/.config/paper-search-cli/config.json`
-4. 免费来源的内置默认值
-
-## 安装缺失时
-
-如果 `paper-search` 不存在，先告知用户需要安装。用户要求你安装时再执行：
+安装缺失时先说明缺失；用户要求安装时再执行：
 
 ```bash
 npm install -g paper-search-cli
 paper-search setup
-paper-search status --pretty
+paper-search doctor --pretty
 ```
 
-## 常用命令
+用户问“如何更新”、安装后怀疑 Skill 过期，或 `doctor`/`skills status` 显示 Skill 不同步时，先区分包本体更新和 Skill 同步；不要只运行 `skills update`。完整流程查看 `references/management-layer.md` 的 `Package Update And Capability Setup`。
 
-### 快速检索
+普通用户更新：
 
 ```bash
-paper-search search "machine learning" --platform crossref --max-results 5 --pretty
-paper-search search "osteoarthritis occupational exposure" --platform pubmed --max-results 10 --pretty
-paper-search search "transformer attention mechanism" --sources arxiv,semantic,crossref --max-results 5 --pretty
-paper-search search "graph neural networks" --platform dblp --max-results 5 --pretty
-paper-search search "large language models" --platform openreview --max-results 5 --pretty
+npm install -g paper-search-cli@latest
+paper-search skills update --targets agents --pretty
+paper-search doctor --pretty
 ```
 
-`--platform all` 或 `--sources all` 只用于需要广覆盖召回时。精确任务优先指定平台或 `--sources`。
-
-### 精确工具调用
+本地维护者更新：
 
 ```bash
-paper-search run search_pubmed --arg query="osteoarthritis occupational exposure" --arg maxResults=10 --pretty
-paper-search run search_openalex --arg query="causal inference target trial emulation" --arg maxResults=5 --pretty
-paper-search run search_acm --arg query="software testing" --arg maxResults=5 --pretty
-paper-search run search_usenix --arg query="file systems" --arg maxResults=5 --pretty
-paper-search run get_paper_by_doi --arg doi="10.xxxx/xxxxx" --pretty
+git pull
+npm install
+npm run build
+npm install -g .
+paper-search skills update --targets agents --pretty
+paper-search doctor --pretty
 ```
 
-复杂参数使用 JSON：
+缺少 API key 或 email 时，不要让用户在聊天里发送密钥；提示用户用 `paper-search setup` 或 `paper-search config` 在本机配置。
 
-```bash
-paper-search run search_semantic_scholar --json-args '{"query":"graph neural network medicine","maxResults":5,"year":"2020-2025"}' --pretty
-```
-
-### 期刊指标查询
-
-当用户询问影响因子、JCR/SSCI 分区、中科院分区、JCI、ESI、预警、北大核心、南大核心、CSCD、A&HCI、CCF、EI 或目标期刊等级时，使用 EasyScholar 原生 CLI 工具，而不是通用论文检索。
-
-```bash
-paper-search journal-metrics "Nature" "BMJ" --pretty
-paper-search journal-metrics --file journals.txt --include-raw --pretty
-paper-search run query_journal_metrics --json-args '{"journals":["Nature"],"includeRaw":true}' --pretty
-```
-
-返回时优先解释标准化的 `core` 字段：`impact_factor`、`impact_factor_5y`、`jcr_quartile`、`ssci_quartile`、`jci`、`cas_base`、`cas_upgraded`、`cas_small`、`cas_top`、`cas_zone`、`esi`、`warning`、`pku`、`cssci`、`cscd`、`ahci`、`ccf`、`ei`、`china_st_core`。如果需要完整字段，使用 `--include-raw` 并检查 `official_all`、`official_select`、`custom_rank`。
-
-EasyScholar 文档要求每秒最多 2 次请求；批量查询时不要并发调用。
+## 功能地图
 
-### 下载 PDF
+本 Skill 只有五个文献主功能。`doctor`、`smoke`、`config`、`skills` 是管理层命令，不属于文献任务本身。
 
-```bash
-paper-search download 2301.12345 --platform arxiv --save-path ./downloads --pretty
-paper-search run download_paper --arg paperId="10.xxxx/xxxxx" --arg platform=springer --arg savePath="./downloads" --pretty
-paper-search run download_with_fallback --json-args '{"source":"crossref","paperId":"10.xxxx/xxxxx","doi":"10.xxxx/xxxxx","title":"Paper title","savePath":"./downloads"}' --pretty
-```
+| 用户意图 | 能力名 | 首选入口 | 关键边界 |
+|---|---|---|---|
+| 搜论文、找相关研究、验证 DOI/PMID、做文献初筛 | `metadata_search` | `paper-search search` 集成入口 / `paper-search run search_*` 精确工具入口 | 只返回和核验论文元数据；Sci-Hub 不属于搜索源 |
+| 查询已知论文的施引文献或参考文献 | `citation_expansion` | `paper-search run get_paper_citations` / `paper-search run get_paper_references` | 需要已知 `paperId`、DOI 或 arXiv ID；不是关键词检索 |
+| 查影响因子、JCR/SSCI/中科院分区、JCI、ESI、预警、期刊等级 | `journal_metrics` | `paper-search journal-metrics` / `paper-search run query_journal_metrics` | 这是期刊指标查询，不是论文检索；需要 `EASYSCHOLAR_KEY` |
+| 获取或下载已确认论文的 PDF | `pdf_discovery` | `paper-search download` / `paper-search run download_with_fallback` | 先核验论文身份，再下载；Sci-Hub 是默认开启的最后 fallback |
+| 在论文正文片段中找 Methods/参数/写法线索 | `body_snippet_search` | `paper-search run search_semantic_snippets` | 查 Semantic Scholar OA snippet 索引；需要 `SEMANTIC_SCHOLAR_API_KEY`；不是完整全文解析 |
 
-下载漏斗默认包含 Sci-Hub 作为最后兜底；只有用户明确要求关闭该阶段时，才把 `useSciHub` 设为 `false`。
+## 默认工作流
 
-## 平台选择
+开放式文献任务使用 Two-Stage Paper Workflow：
 
-| 任务 | 首选 | 补充 |
-|---|---|---|
-| 生物医学、临床、药学、公卫 | `pubmed` | `pmc`, `europepmc`, `semantic`, `crossref` |
-| 正文方法学片段 | `search_semantic_snippets` | 先用 `pubmed`/`semantic` 找题名和同义词 |
-| 计算机、AI、数学、物理 | `arxiv` | `semantic`, `crossref`, `openalex` |
-| 计算机文献目录/会议元数据 | `dblp` | `acm`, `usenix`, `openreview`, `ieee` 需要 key |
-| 跨学科广覆盖 | `crossref` | `openalex`, `semantic` |
-| 开放获取全文发现 | `pmc`, `europepmc`, `core`, `openaire`, `unpaywall` | `download_with_fallback` |
-| 期刊影响因子/分区/等级 | `journal-metrics` | `query_journal_metrics` |
-| 密码学 | `iacr` | `arxiv` |
-| 引用统计排序 | `semantic`, `crossref`, `openalex` | `webofscience`, `scopus` 需要 key |
-| 出版商/付费数据库 | `webofscience`, `ieee`, `scopus`, `sciencedirect`, `springer`/`springerlink`, `wiley` | 仅在 key 已配置时使用 |
+1. 先做 `metadata_search`：检索和核验文献条目，确认题名、作者、年份、期刊、DOI、PMID/PMCID、URL、摘要线索和相关性。
+2. 用户确认条目或任务明确需要 PDF 后，再做 `pdf_discovery`：下载选中的已核验条目；下载失败项记录原因，不阻塞其他条目。
 
-平台边界：
+Direct Paper Request 可以跳过广泛发现：用户给出单个 DOI、PMID、PMCID、arXiv ID 或已核验清单并明确要求下载时，先核验目标身份，再进入下载。
 
-- `acm` 通过 Crossref 的 ACM DOI 前缀检索元数据，不抓取 ACM Digital Library 页面。
-- `usenix` 通过 DBLP 返回 USENIX 相关会议/期刊元数据，不抓取 USENIX 搜索页。
-- `springerlink` 是 `springer` 的别名，仍需要 Springer API key。
+## 验证与输出边界
 
-查询构建规则：
-
-- 默认把中文问题转为英文关键词。
-- 用 3-8 个核心概念词，不要写成长句。
-- 医学主题可加入 MeSH 或标准术语。
-- 找方法细节时加入软件名、参数名、模型名、章节词，例如 `methods`, `statistical analysis`, `adjusted for`, `bootstrap`, `sensitivity analysis`。
-
-## 正文片段检索
-
-PubMed 只提供题名、作者、摘要、PMID、DOI、期刊和年份等元数据，不提供论文正文抓取。
-
-正文片段检索使用：
-
-```bash
-paper-search run search_semantic_snippets --arg query="CMAverse mediation bootstrap confidence interval" --arg limit=5 --arg fieldsOfStudy=Medicine --pretty
-```
-
-使用规则：
-
-1. 该工具需要 `SEMANTIC_SCHOLAR_API_KEY`。
-2. 它检索 Semantic Scholar Open Access snippet 索引，不等于完整全文解析。
-3. 只有 `snippetKind="body"` 的结果才能作为正文片段证据；`title` 或 `abstract` 只能作为线索。
-4. 输出正文片段前，必须补齐和核验标题、作者、年份、期刊、DOI 或 PMID。
-5. 如果 snippet 无结果，不代表研究不存在；回退到 `search_pubmed`、`search_semantic_scholar` 或 `search_crossref` 做摘要级检索。
-
-## 验证规范
-
-输出给用户前，关键论文必须尽量验证：
+关键论文输出前尽量验证：
 
 ```bash
 paper-search run search_pubmed --arg query="37654321[PMID]" --arg maxResults=1 --pretty
@@ -173,36 +108,11 @@ paper-search run search_crossref --arg query="full paper title" --arg maxResults
 规则：
 
 - 不凭模型记忆编造 PMID、DOI、期刊、年份或作者。
-- PMID 必须能被 PubMed 查询确认。
-- DOI 必须能被 DOI 查询或 Crossref/OpenAlex/Semantic Scholar 结果支持。
+- PMID 必须能被 PubMed 查询确认；DOI 必须能被 DOI 查询或 Crossref/OpenAlex/Semantic Scholar 结果支持。
 - 同一论文的 PMID、DOI、题名、第一作者和年份应一致；不一致时标记为可疑。
-- snippet 结果缺少元数据时，先用完整标题二次检索补齐。
-
-## 输出格式
-
-### 文献列表
-
-```markdown
-| # | 标题 | 作者 | 年份 | 期刊/来源 | DOI | PMID | 验证 |
-|---|---|---|---:|---|---|---|---|
-| 1 | [Title](URL) | First Author et al. | 2024 | Journal | 10.xxxx/xxxxx | 12345678 | 已验证 |
-```
-
-### 正文片段结果
-
-```markdown
-### 发现 1
-
-**论文：** Full paper title  
-**引用：** Author et al. Journal. Year. DOI/PMID.  
-**片段类型：** body  
-**章节：** Methods / Statistical Analysis  
-**来源：** Semantic Scholar URL
-
-> snippet text
-```
+- `config` / `doctor` 输出应视为已脱敏，但不要复述、保存或写入任何原始密钥。
 
-## 错误处理
+## 常见失败处理
 
 | 场景 | 处理 |
 |---|---|
@@ -210,7 +120,6 @@ paper-search run search_crossref --arg query="full paper title" --arg maxResults
 | API key 缺失 | 提示运行 `paper-search setup`；不要索要或保存 key |
 | EasyScholar key 缺失 | 提示运行 `paper-search setup EASYSCHOLAR_KEY`；不要让用户在聊天中发送 SecretKey |
 | 429 限流 | 降低 `--max-results`，换平台，或提示配置可选 key |
-| EasyScholar 批量查询 | 控制在每秒最多 2 次请求；优先使用单次 `journal-metrics` 多期刊输入，不要并发 |
 | 0 结果 | 放宽关键词，换英文同义词，换平台，或用 `--sources` 扩展 |
 | 下载失败 | 优先开放获取来源和 `download_with_fallback`，报告失败原因 |
 | 用户要求完整正文 | 先下载 PDF；再交给当前环境可用的 PDF/MinerU 解析流程 |

package/skills/paper-search/references/capability-routing.md

@@ -0,0 +1,147 @@
+# Capability Routing Reference
+
+Use this reference when mapping a user literature request to one of the five main `paper-search` workflow capabilities.
+
+## Functional Map
+
+| User Intent | Capability | Preferred Entrypoint | Boundary |
+|---|---|---|---|
+| Search papers, find related work, verify DOI/PMID, screen literature | `metadata_search` | `paper-search search` integrated entrypoint / `paper-search run search_*` precise tool entrypoint | Returns and verifies paper metadata only; Sci-Hub is not a search source |
+| Expand citation graph for a known paper | `citation_expansion` | `paper-search run get_paper_citations` / `paper-search run get_paper_references` | Requires a known `paperId`, DOI, or arXiv ID; returns citing papers or cited references, not general keyword search |
+| Query impact factor, JCR/SSCI/CAS quartiles, JCI, ESI, warnings, journal rank | `journal_metrics` | `paper-search journal-metrics` / `paper-search run query_journal_metrics` | Journal-level lookup, not paper search; requires `EASYSCHOLAR_KEY` |
+| Get or download a verified paper PDF | `pdf_discovery` | `paper-search download` / `paper-search run download_with_fallback` | Verify identity before download; Sci-Hub is the default enabled final fallback |
+| Find Methods text, parameters, software, models, or statistical wording in body snippets | `body_snippet_search` | `paper-search run search_semantic_snippets` | Searches Semantic Scholar OA snippet index; requires `SEMANTIC_SCHOLAR_API_KEY`; not full-text parsing |
+
+## Workflow Boundaries
+
+Open-ended literature tasks use the Two-Stage Paper Workflow:
+
+1. Run `metadata_search`: build and verify a paper list with title, authors, year, journal/source, DOI, PMID/PMCID, URL, abstract clues, and relevance.
+2. Run `pdf_discovery` only after the user confirms selected papers or the task explicitly requires PDFs. Record failed downloads without blocking other items.
+
+Direct Paper Requests may skip broad discovery when the user provides a DOI, PMID, PMCID, arXiv ID, or already verified paper list. The target identity still needs verification before download.
+
+Do not fabricate PMID, DOI, title, author, journal, or year from model memory. Important citations should include the supported claim, title, authors, journal/source, year, DOI or PMID when available, and a stable URL.
+
+## Metadata Search
+
+Use `metadata_search` for finding papers, expanding keywords, literature screening, and verifying DOI/PMID/PMCID/arXiv ID.
+
+`paper-search search` is the integrated metadata entrypoint:
+
+- use `--platform NAME` for one source
+- use `--sources a,b,c` for explicit multi-source search
+- use `--platform all` or `--sources all` only when broad recall matters more than precision
+
+It does not call `citation_expansion`, `journal_metrics`, `pdf_discovery`, or `body_snippet_search`.
+
+```bash
+paper-search search "machine learning" --platform crossref --max-results 5 --pretty
+paper-search search "osteoarthritis occupational exposure" --platform pubmed --max-results 10 --pretty
+paper-search search "transformer attention mechanism" --sources arxiv,semantic,crossref --max-results 5 --pretty
+paper-search search "causal inference target trial emulation" --sources all --max-results 5 --pretty
+```
+
+Precise tool entrypoints:
+
+```bash
+paper-search run search_pubmed --arg query="osteoarthritis occupational exposure" --arg maxResults=10 --pretty
+paper-search run search_openalex --arg query="causal inference target trial emulation" --arg maxResults=5 --pretty
+paper-search run get_paper_by_doi --arg doi="10.xxxx/xxxxx" --pretty
+```
+
+Do not treat `search_scihub` as a search source. It is DOI/URL-targeted lookup, not `metadata_search`.
+
+## Citation Expansion
+
+Use `citation_expansion` when the user has a known paper and asks which papers cite it or which references it cites.
+
+```bash
+paper-search run get_paper_citations --arg doi="10.1038/nature12373" --arg limit=5 --pretty
+paper-search run get_paper_references --arg doi="10.1038/nature12373" --arg limit=5 --pretty
+```
+
+Target priority is `paperId` > `doi` > `arxivId`. This capability uses Semantic Scholar Graph API and is separate from keyword-based `metadata_search`.
+
+## Journal Metrics
+
+Use `journal_metrics` for journal-level metrics: impact factor, JCR/SSCI quartiles, CAS quartiles, JCI, ESI, warnings, and rank.
+
+```bash
+paper-search journal-metrics "Nature" "BMJ" --pretty
+paper-search journal-metrics --file journals.txt --include-raw --pretty
+paper-search run query_journal_metrics --json-args '{"journals":["Nature"],"includeRaw":true}' --pretty
+```
+
+`journal_metrics` requires `EASYSCHOLAR_KEY`. If missing, tell the user to configure it locally:
+
+```bash
+paper-search setup EASYSCHOLAR_KEY
+```
+
+For batch journal lookups, prefer one `journal-metrics` call with multiple journal names or `--file`; do not run parallel EasyScholar requests.
+
+## PDF Discovery
+
+Use `pdf_discovery` to get an already verified paper PDF. For open-ended literature tasks, do not begin with batch downloads.
+
+```bash
+paper-search download 2301.12345 --platform arxiv --save-path ./downloads --pretty
+paper-search run download_paper --arg paperId="10.xxxx/xxxxx" --arg platform=springer --arg savePath="./downloads" --pretty
+paper-search run download_with_fallback --json-args '{"source":"crossref","paperId":"10.xxxx/xxxxx","doi":"10.xxxx/xxxxx","title":"Paper title","savePath":"./downloads"}' --pretty
+```
+
+`download_with_fallback` order:
+
+1. source-native download
+2. metadata PDF URL
+3. repository discovery through PMC, Europe PMC, CORE, OpenAIRE
+4. Unpaywall DOI resolution
+5. Sci-Hub as the final fallback
+
+Sci-Hub Fallback is enabled by default. To suppress that final stage for one request:
+
+```bash
+paper-search run download_with_fallback --json-args '{"source":"crossref","paperId":"10.xxxx/xxxxx","doi":"10.xxxx/xxxxx","title":"Paper title","savePath":"./downloads","useSciHub":false}' --pretty
+```
+
+PDF source groups:
+
+- `open_access_sources`: arXiv, bioRxiv, medRxiv, PMC, Europe PMC, CORE, OpenAIRE, Unpaywall, OpenAlex OA metadata, Semantic Scholar openAccessPdf, publisher open-access modes, IACR
+- `entitled_access_sources`: Web of Science, ScienceDirect, Scopus, Springer, IEEE, Wiley TDM, or other sources requiring user keys, subscriptions, TDM tokens, or institutional entitlements
+- `scihub_sources`: Sci-Hub, separately identified as the default enabled final fallback; not OA and not entitled access
+
+## Body Snippet Search
+
+Use `body_snippet_search` to find Methods wording, parameters, software names, model descriptions, statistical analysis text, or similar body-snippet clues.
+
+```bash
+paper-search run search_semantic_snippets --arg query="comparative risk assessment methods uncertainty propagation" --arg limit=5 --arg fieldsOfStudy=Medicine --pretty
+```
+
+`search_semantic_snippets` requires `SEMANTIC_SCHOLAR_API_KEY` and uses `limit`, not `maxResults`.
+
+Only results with `snippetKind="body"` can be used as body-snippet evidence. Results from `title` or `abstract` are clues only. Before quoting or relying on a snippet, verify title, authors, year, journal/source, DOI or PMID.
+
+## Platform Selection
+
+| Task | First Choice | Supplements |
+|---|---|---|
+| Biomedical, clinical, pharmaceutical, public health | `pubmed` | `pmc`, `europepmc`, `semantic`, `crossref` |
+| Methods/body snippet clues | `search_semantic_snippets` | Use `pubmed`/`semantic` first for titles and synonyms |
+| Citation graph expansion | `get_paper_citations`, `get_paper_references` | Use only after a target paper identifier is known |
+| Computer science, AI, math, physics | `arxiv` | `semantic`, `crossref`, `openalex` |
+| CS bibliographies and conference metadata | `dblp` | `acm`, `usenix`, `openreview`, `ieee` requires key |
+| Cross-disciplinary coverage | `crossref` | `openalex`, `semantic` |
+| Open-access full-text discovery | `pmc`, `europepmc`, `core`, `openaire`, `unpaywall` | `download_with_fallback` |
+| Journal IF/quartiles/rank | `journal-metrics` | `query_journal_metrics` |
+| Cryptography | `iacr` | `arxiv` |
+| Citation-count sorting | `semantic`, `crossref`, `openalex` | `webofscience`, `scopus` require keys |
+| Publisher or paid databases | `webofscience`, `ieee`, `scopus`, `sciencedirect`, `springer`/`springerlink`, `wiley` | Use only when key is configured |
+
+## Query Construction
+
+- Translate Chinese research questions into English keywords by default.
+- Use 3-8 core concept terms rather than long sentences.
+- For medical topics, include MeSH or standard terminology when useful.
+- For method details, include software names, parameter names, model names, or section words such as `methods`, `statistical analysis`, `adjusted for`, `bootstrap`, `sensitivity analysis`.

package/skills/paper-search/references/cli-contract.md

@@ -0,0 +1,152 @@
+# Paper Search CLI Contract
+
+This contract records the stable CLI surface that the `paper-search` Routing Skill may rely on. The Routing Skill should stay short and should not describe commands, flags, or defaults that are absent from this contract and the current CLI.
+
+## Entrypoints
+
+- `paper-search` is the primary executable.
+- `paper-search --version`, `paper-search -v`, and `paper-search version` print the installed version.
+- `paper-search --help` and `paper-search help` print usage.
+- `paper-search tools --pretty` lists direct `run` tool names and schemas.
+- Private API keys, emails, and tokens must be configured through `paper-search setup`, `paper-search config`, `.env`, or shell environment variables. They must not be written into Skill files.
+
+## Top-Level Commands
+
+- `paper-search search <query> [--platform NAME] [--sources CSV] [--max-results N] [--year YEAR] [--pretty]`
+- `paper-search run <tool-name> --arg key=value --json-args '{"key":"value"}' [--pretty]`
+- `paper-search download <paper-id> --platform NAME [--save-path PATH] [--pretty]`
+- `paper-search journal-metrics <journal...> [--file PATH] [--include-raw] [--pretty]`
+- `paper-search metrics ...` is an alias for `journal-metrics`.
+- `paper-search status [--validate] [--pretty]`
+- `paper-search doctor [--validate] [--format text] [--pretty]`
+- `paper-search smoke --mock [--pretty]`
+- `paper-search smoke --live [--pretty]`
+- `paper-search skills status [--targets CSV] [--pretty]`
+- `paper-search skills diff [--targets CSV] [--format text] [--pretty]`
+- `paper-search skills update [--targets CSV] [--pretty]`
+- `paper-search setup [--all] [--keys CSV] [--install-skills CSV] [--skip-skills]`
+- `paper-search tools [--pretty]`
+- `paper-search diagnostics [--pretty]`
+- `paper-search requirements [--pretty]` is an alias for `diagnostics`.
+- `paper-search config init [--pretty]`
+- `paper-search config path [--pretty]`
+- `paper-search config keys [--pretty]`
+- `paper-search config list [--all] [--pretty]`
+- `paper-search config doctor [--pretty]` is a compatibility config summary; use top-level `doctor` for the full health report.
+- `paper-search config get KEY [--raw] [--pretty]`
+- `paper-search config set KEY VALUE [--pretty]`
+- `paper-search config unset KEY [--pretty]`
+- `paper-search config delete KEY [--pretty]` and `paper-search config remove KEY [--pretty]` are aliases for `unset`.
+- `paper-search config import-env [file] [--pretty]`
+
+## Direct Run Tools
+
+These names can be used with `paper-search run <tool-name>`:
+
+- `search_papers`
+- `search_arxiv`
+- `search_webofscience`
+- `search_pubmed`
+- `search_biorxiv`
+- `search_medrxiv`
+- `search_semantic_scholar`
+- `search_semantic_snippets`
+- `get_paper_citations`
+- `get_paper_references`
+- `search_iacr`
+- `download_paper`
+- `search_google_scholar`
+- `get_paper_by_doi`
+- `search_scihub`
+- `check_scihub_mirrors`
+- `get_platform_status`
+- `query_journal_metrics`
+- `search_sciencedirect`
+- `search_springer`
+- `search_wiley`
+- `search_scopus`
+- `search_crossref`
+- `search_openalex`
+- `search_unpaywall`
+- `search_pmc`
+- `search_europepmc`
+- `search_core`
+- `search_openaire`
+- `download_with_fallback`
+- `search_dblp`
+- `search_ieee`
+- `search_acm`
+- `search_usenix`
+- `search_openreview`
+- `search_springerlink`
+
+## Output Expectations
+
+- JSON is the default machine-readable output for agent and script callers.
+- `--pretty` pretty-prints JSON.
+- `--format text` is supported by top-level `doctor` and `skills diff` for explicitly requested human-readable reports.
+- `--include-text` keeps raw tool response text in JSON for commands where the CLI supports it.
+- The Routing Skill should parse JSON when making decisions and use text format only when the user needs a readable report.
+
+## Search Command Contract
+
+- `paper-search search` is the integrated metadata search entrypoint.
+- Use `--platform NAME` for one source and `--sources a,b,c` for explicit multi-source search.
+- Use `--platform all` or `--sources all` only when broad recall matters more than precision.
+- `search_papers` is the direct tool behind the integrated `search` command.
+- `search_semantic_snippets` uses `limit`, not `maxResults`, and is for body/title/abstract snippets rather than complete full text.
+- `search_unpaywall` resolves DOI-based OA metadata and returns at most one result.
+- `search_scihub` is DOI/URL-targeted lookup and is not a metadata search source.
+- `CORE_MAX_RESULTS_CAP` controls the configurable CORE-only result cap. Default is `100`; hard maximum is `500`. Other platforms keep their own current limits.
+
+## Citation Expansion Contract
+
+`get_paper_citations` and `get_paper_references` query Semantic Scholar Graph API for citation graph expansion.
+
+- Provide at least one of `paperId`, `doi`, or `arxivId`.
+- Target priority is `paperId`, then `doi`, then `arxivId`.
+- `doi` is converted to `DOI:<doi>`.
+- `arxivId` is converted to `ARXIV:<id>`.
+- `limit` defaults to `100` and accepts values from `1` to `100`.
+
+Examples:
+
+```bash
+paper-search run get_paper_citations --arg doi="10.1038/nature12373" --arg limit=5 --pretty
+paper-search run get_paper_references --arg doi="10.1038/nature12373" --arg limit=5 --pretty
+```
+
+## Download Command Contract
+
+`download_paper` tries source-native download first when available. Unsupported or failed native downloads route into the same fallback funnel used by `download_with_fallback`.
+
+`download_with_fallback` order is source-native download, metadata PDF URL, repository discovery through PMC/Europe PMC/CORE/OpenAIRE, Unpaywall DOI resolution, then Sci-Hub as the final fallback.
+
+Sci-Hub Fallback is enabled by default. To suppress that final stage for a request, pass:
+
+```json
+{"useSciHub": false}
+```
+
+The Routing Skill must not describe future-only download commands or strategy flags until they appear in `paper-search --help` or `paper-search tools`.
+
+## Configuration And Secret Boundaries
+
+Configuration sources, in priority order:
+
+1. Shell environment variables
+2. Current directory `.env`
+3. User config file under `~/.config/paper-search-cli/config.json`
+4. Free-source built-in defaults
+
+Useful configuration commands:
+
+```bash
+paper-search setup
+paper-search config set SEMANTIC_SCHOLAR_API_KEY your_key
+paper-search setup EASYSCHOLAR_KEY
+paper-search config list --pretty
+paper-search doctor --pretty
+```
+
+Do not ask users to paste secrets into chat. Do not write secrets into Skill, README, tests, or logs. `doctor` and `config` output should mask configured secret values.