dsh-lit-fetch
DSH literature fetcher — search academic papers, download PDFs by DOI (Sci-Hub mirrors with Open Access fallback), and generate a batch-access HTML manifest.
DSH 文献获取插件 — 快捷搜索学术文献、通过 DOI 批量下载 PDF（Sci-Hub 镜像 + 开放获取兜底）、生成批量获取清单 HTML。
功能总览 · At a glance（中英对照 / Bilingual）
检索 / Search
| 中文 | English |
|---|
search_papers：按 DOI 精确查询（Crossref） | search_papers: exact DOI lookup via Crossref |
| 按标题/关键词检索（OpenAlex，最多 20 条） | Title/keyword search via OpenAlex, up to 20 results |
| 返回标题、作者、期刊、年份、DOI、官方链接 | Returns title, authors, journal, year, DOI and canonical link |
下载 / Download
| 中文 | English |
|---|
download_papers：按 DOI 批量下载 PDF | download_papers: batch PDF download by DOI |
| Sci-Hub 优先：遍历 8 个镜像域名，解析 iframe/embed 取直链 | Sci-Hub first: walks 8 mirrors, resolves the PDF link from iframe/embed |
| 开放获取兜底：Unpaywall 查 OA 免费版本 | OA fallback: Unpaywall lookup for a free version |
PDF 魔数校验（%PDF-）+ 最小体积校验（≥3KB）拦截假文件 | Magic-byte (%PDF-) and minimum-size (≥3 KB) checks reject bogus files |
并发下载（默认 4，上限 8），先写 .part 再原子重命名 | Concurrent downloads (default 4, max 8), .part then atomic rename |
每篇返回状态：ok / scihub-fail / oa-fail / closed-access / no-doi | Per-paper status: ok / scihub-fail / oa-fail / closed-access / no-doi |
结果写入 _lit_fetch_report.json | Writes _lit_fetch_report.json into the output directory |
清单 / Manifest
| 中文 | English |
|---|
generate_manifest：把拿不到的文献生成可点击清单 | generate_manifest: clickable list of papers that could not be fetched |
| 输出「批量获取入口.html」，含 DOI 官方链接与状态徽章 | Emits 批量获取入口.html with DOI links and status badges |
| 提供「顺序打开全部」按钮，逐条间隔 800ms 打开 | A "open all in order" button opens each link 800 ms apart |
宿主路由 / Host route
| 中文 | English |
|---|
注册 /lit-fetch 前缀路由，返回插件存活与版本信息 | Registers a /lit-fetch prefix route reporting liveness and version |
使用方式 · Usage
在 DSH 对话中对 agent 说 / Talk to the agent in a DSH session：
- 搜索 · Search：「帮我找关于 static mixer CFD 的文献」→ agent 调用
search_papers
- 下载 · Download：「把这些 DOI 下载到
D:\papers\」→ agent 调用 download_papers
- 生成清单 · Manifest：「给没下载到的文献生成获取清单」→ agent 调用
generate_manifest
下载策略 · Download strategy
- Sci-Hub 优先：遍历 8 个域名（sci-hub.ren / ee / st / ru / se / wf / hk、tesble.com），
解析 iframe/embed 提取 PDF 直链，流式下载并校验
%PDF 魔数。
- 开放获取兜底：Sci-Hub 无收录时查 Unpaywall，寻找 OA 免费版本（
best_oa_location 优先，
其次遍历 oa_locations）。
- 最终兜底：两者均失败 → 记入清单，生成 HTML 供手动获取（向作者索取 / NSTL 文献传递）。
Sci-Hub first — walks the 8 mirrors, resolves the direct PDF link from iframe/embed.
OA fallback — Unpaywall when Sci-Hub has nothing. Final fallback — the HTML manifest.
已知限制 · Known limitations
- Sci-Hub 2021 年后基本停止收录新文献（Elsevier/Wiley/ACS 2021+ 文章大概率无收录）。
- 直连 Sci-Hub 镜像较慢（Cloudflare 限速），建议开启 VPN/代理后使用。
- OA 兜底仅查 Unpaywall；某些文献有 arXiv 预印本但 Unpaywall 未收录。
- Sci-Hub stopped indexing new papers after 2021, and mirror throughput is often throttled.
The OA fallback only consults Unpaywall.
安装 · Installation
dsh plugin --profile desktop add dsh-lit-fetch
# 或从本地目录 link
# cp -r dsh-lit-fetch ~/.dsh/local-plugins/
技术细节 · Technical notes
- 宿主端纯 Node.js，无 Python 依赖 / Host-side pure Node.js, no Python dependency
- PDF 魔数校验 + 体积校验 / Magic-byte and size validation
- 流式下载 + 原子落盘（
.part → rename）/ Streaming download with atomic rename
- 并发控制（默认 4，最大 8）/ Bounded concurrency
- 下载报告 JSON 自动落盘 / Automatic JSON report
License
MIT
