dsh-lit-fetch

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。

这不是网页正文抓取工具。 插件不解析网页正文、不做 readability/HTML 转文本，只做三件事： 检索文献元数据、下载 PDF 文件、生成可点击的获取清单。 This is not a web-page text extractor. No readability/HTML-to-text; only metadata search, PDF download, and manifest generation.

功能总览 · At a glance（中英对照 / Bilingual）

检索 / Search

下载 / Download

清单 / Manifest

宿主路由 / Host route

⚠️ 状态枚举的差异（重要） · Status enum mismatch (important)

两个工具的状态词汇表不一致，混用会让清单显示错误：

也就是说：把 download_papers 的结果数组原样喂给 generate_manifest，只有 ok 会显示成「✓已下载」，其余全部落到灰色「—」， 不会显示成「✗需手动」。若希望失败项显示为橙色「✗需手动」，需要先把非 ok 状态映射成 failed 再传入。

generate_manifest only recognises ok and failed. Every other value — including the four failure statuses actually produced by download_papers — renders as a neutral grey dash. Map non-ok statuses to failed yourself if you want the "needs manual retrieval" badge.

使用方式 · Usage

在 DSH 对话中对 agent 说 / Talk to the agent in a DSH session：

1. 搜索 · Search：「帮我找关于 static mixer CFD 的文献」→ agent 调用 search_papers
2. 下载 · Download：「把这些 DOI 下载到 D:\papers\」→ agent 调用 download_papers
3. 生成清单 · Manifest：「给没下载到的文献生成获取清单」→ agent 调用 generate_manifest

下载策略 · Download strategy

1. Sci-Hub 优先：依次遍历 8 个域名（sci-hub.ren / ee / st / ru / se / wf / hk、tesble.com）， 请求 域名 + DOI 页面（超时 25 秒），用 <(?:iframe|embed)[^>]*src="..."> 正则解析出 PDF 直链 （// 开头补 https:、/ 开头拼域名），再把整个 PDF 完整下载到内存、校验 %PDF- 魔数与体积， 通过后写 .part 再原子 rename。任一步失败就换下一个域名继续。
2. 开放获取兜底：Sci-Hub 全部失败（或直链下载校验不过）时查 Unpaywall， 优先 best_oa_location，其次遍历 oa_locations（取 url_for_pdf，退化为 url）， 命中后走同一套下载与校验流程。
3. 最终兜底：两者均失败 → 状态标为 closed-access / scihub-fail / oa-fail， 用 generate_manifest 生成 HTML 供手动获取（DOI 官方入口 / 向作者索取 / 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 未收录。
• 实现说明（非功能）：PDF 是一次性 arrayBuffer() 全量读入内存再落盘的，没有流式写入、没有断点续传， 也没有下载进度；Content-Length 虽然被读进局部变量，但未参与任何判断或输出（无进度/无大小预检）。
• Sci-Hub stopped indexing new papers after 2021, and mirror throughput is often throttled. The OA fallback only consults Unpaywall. Downloads are fully buffered in memory — no streaming, no resume, no progress reporting.

安装 · 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
• 注入的服务：tools、webServer / Injects the tools and webServer services
• PDF 魔数（%PDF-，前 5 字节）+ 体积（≥3000 字节）双重校验 / Magic-byte and size validation
• 下载先写 .part 临时文件，校验通过后 rename 成正式文件名（原子改名，避免留下半截 PDF） / Writes a .part temp file, then renames it into place
• 并发控制：默认 4，Math.min(Math.max(n,1),8) 夹紧 / Bounded concurrency
• 下载报告 JSON 自动落盘 / Automatic JSON report
• 页面抓取超时 25 秒、PDF 读取超时 180 秒、Unpaywall 30 秒 / Timeouts: page 25 s, PDF 180 s, Unpaywall 30 s

License

MIT