学术文献检索 rasyidmmz/dsh-paper-search

dsh-paper-search

面向 DeepSeek Harness 的文献检索：十七个来源，全部使用原生 HTTP——无外部 CLI，无 Python 包。其中十五个完全不需要凭证。

注册为 paper-search 技能和五个模型工具（paper_search、 paper_status、paper_citations、paper_oa、paper_fulltext）。

来源

国际（14 个）——除 IACR 为解析 HTML 外，其余均为官方 JSON API：

| id | 来源 | 说明 |
| crossref | Crossref | 跨出版商的 DOI 元数据，覆盖范围最广 |
| acm | ACM Digital Library | ACM 自有产出，无需密钥——Crossref 限定于 DOI 前缀 10.1145（上游 PR #123） |
| openalex | OpenAlex | 元数据 + 摘要；提供邮箱可提高速率限制 |
| doaj | DOAJ | 开放获取期刊——包含许多印度尼西亚期刊 |
| europepmc | Europe PMC | 生物医学，OA 记录提供全文 |
| pubmed | PubMed | 生物医学；每次检索需两次调用（esearch + esummary） |
| pmc | PubMed Central | 开放获取全文；每次检索需两次调用 |
| arxiv | arXiv | 预印本；根据 arXiv 的 TOU，插件自行限速为每 3 秒 1 次请求 |
| semantic | Semantic Scholar | 免费密钥可提高速率限制 |
| core | CORE | 开放获取仓储聚合器——需要 CORE_API_KEY |
| zenodo | Zenodo | 通用仓储：数据、软件、预印本 |
| hal | HAL | 法国开放获取仓储 |
| iacr | IACR ePrint | 密码学预印本 |
| unpaywall | Unpaywall | 输入 DOI，而非关键词——将 DOI 解析为其开放获取副本；需要邮箱 |

印度尼西亚（3 个）——从公开页面解析：

| id | 来源 | 说明 |
| garuda | Garuda (Kemdiktisaintek) | 印度尼西亚期刊文章 |
| sinta | Sinta (Kemdiktisaintek) | 经认证的期刊，而非文章 |
| ios | IOS OneSearch (Perpusnas) | 印度尼西亚仓储聚合器 |

sources: "all" 与 DOI 输入来源

unpaywall 仅在查询是 DOI 时才会应答。因此，当你用关键词检索时，它会被跳过，而不是运行后报告为空结果——输出会说明这一点：

CATATAN: unpaywall dilewati karena query ini bukan DOI — sumber itu memang mencari dengan DOI, bukan kata kunci.

传入 DOI，它就会运行。传入 sources: "unpaywall" 并附带关键词，它也会运行，但返回空——因为这正是它的真实行为，输出会如实说明，而不是假装该来源已损坏。

有意排除及其原因

每一项排除均于 2026-09-28 实测。一个始终为空的来源比一个不存在的来源更糟，因此这些来源被舍弃，而不是为了显得更大而注册：

| 来源 | 原因 |
| moraref | 仅有落地页，无可解析的结果标记（3,964 个字符） |
| dblp | API 位于机器人防护之后——返回 "Making sure you're not a bot!"，而非 JSON |
| openaire | 测试请求在 30 秒时超时，40 秒时再次超时 |
| biorxiv、medrxiv | 其 API 基于日期范围，而非关键词检索 |
| base | OAI-PMH 要求机构 IP 注册（Access denied for IP address …） |
| citeseerx | 返回 HTTP 404，然后挂起，直到请求被终止 |
| ssrn | 以 HTTP 403 拒绝普通请求 |
| google_scholar | 机器人检测已启用；需要代理 |

安装

从 npm 安装
dsh plugin --profile add dsh-paper-search

或直接从仓库安装
dsh plugin --profile add github:rasyidmmz/dsh-paper-search

该包附带一个 dsh.bundle.patch，因此 DSH 会自动安装其加载器行。
不要同时手动写入 id: paper-search 行——加载器会抛出 duplicate loader entry id，而不是发出警告。

安装后重启 DSH。

插件选项

| 选项 | 默认值 | 含义 |
| tools | "five" | "five" 注册五个独立的工具。"one" 注册单个名为 paper 的工具，带一个 mode 参数（search · status · citations · oa · fulltext）。 |
| anydocPath / markitdownPath | 自动检测 | paper_fulltext 使用的 PDF→Markdown 转换器的显式路径。 |
| folderTeksLengkap | ~/.dsh/paper-search | 下载的 PDF 和转换后的 Markdown 的存放位置。 |

为什么存在 tools: "one"。 每个工具定义都会在每次请求时发送给模型。
2026 年 9 月 29 日实测（test/uji-satu-pintu.mjs）：

| | JSON 字符数 | ≈ token 数 |
| "five"（默认） | 4,959 | ~1,240 |
| "one" | 2,159 | ~540 |
| 节省 | 56% | 每次请求约 700 |

它的代价，直白地说。 工具名称不再能自我描述（paper_fulltext 不再作为名称存在；它变成
paper({ mode: "fulltext" })），而且一个 JSON schema 无法为不同模式要求不同的
参数——因此按模式进行的必需参数检查从测试框架移到了插件中。不带 identifier 的 paper({ mode: "oa" }) 会被插件拒绝，并给出一个模仿 schema 拒绝的消息，而不是在调用之前被 DSH 拒绝。
这就是默认值保持为 "five" 的原因。

无法识别的值会回退到 "five"，并在插件的启动说明中说明这一点——它绝不会被静默应用。该选项从你 DSH 配置文件中的插件配置读取；当 "one" 处于活动状态时，随附的技能会在其自身正文中添加一条简短说明，因此文档永远不会指向该配置文件中不存在的工具名称。

使用

paper_search({ query: "machine learning" })
paper_search({ query: "pendidikan karakter", sources: "indonesia" })
paper_search({ query: "CRISPR", sources: "pubmed,europepmc,doaj", max_results: 10 })
paper_search({ query: "digital literacy", open_access_only: true, year_from: 2020 })
paper_search({ query: "eye tracking", sources: "acm" }) # 仅 ACM Digital Library
paper_status() # 当前哪些来源可响应
paper_status({ probe: false }) # 仅配置，不联网
paper_citations({ identifier: "10.1145/3290605.3300233" }) # 谁引用了它
paper_citations({ identifier: "10.1145/3290605.3300233", arah: "rujukan" }) # 它引用了什么
paper_oa({ identifier: "10.1371/journal.pone.0266789" }) # 免费副本？
paper_fulltext({ identifier: "1706.03762" }) # 阅读整篇论文

对于印度尼西亚语主题，使用印度尼西亚语关键词："pendidikan karakter" 会返回真正的印度尼西亚语期刊，而英语对应词会返回与意图不符的国际结果。

引文图谱与开放获取查询

有两个工具使用 OpenAlex——免费、无需密钥、无需邮箱（上游 PR #96）：

- paper_citations 沿任一方向遍历引文图谱。
arah: "pengutip"（默认）列出引用该作品的论文——向前滚雪球；arah: "rujukan" 列出该作品引用的作品——向后滚雪球。输入可以是 DOI、OpenAlex id（W…）或标题。
- paper_oa 报告开放获取状态（gold/green/hybrid/bronze/closed）以及每个 OA 副本及其 PDF/落地页链接、许可证和版本。它不需要 unpaywall 源所需的 Unpaywall 邮箱。

有三个限制会被报告出来，而不是被隐藏：

1. 标题输入可能解析到错误的记录。 测量于 2026-09-29：标题 "Attention is all you need" 解析到 W2626778328，一个带有无关 DOI 的重复记录。因此每个输出都会指明它实际使用的作品——在得出结论之前请检查这一点。
2. 向后滚雪球每次调用最多读取 100 条参考文献，因此 "被引最多者优先"仅适用于所检查的那些。
3. 失败的源会说明情况。 paper_citations/paper_oa 将 OpenAlex 的 429/503/504 转换为可操作的句子，而不是裸状态码。

此插件不会为 paper_citations/paper_oa 下载 PDF——那两个只报告存在的内容。下载是 paper_fulltext 的工作，见下文。

全文：开放获取 PDF → Markdown

paper_fulltext 获取论文的全文，以便智能体可以阅读它，而不仅仅是其标题和摘要。它接受 DOI、OpenAlex id（W…）、 arXiv id（1706.03762）或标题。

paper_fulltext({ identifier: "1706.03762" }) # arXiv id
paper_fulltext({ identifier: "10.1371/journal.pone.0266789" }) # OA DOI
paper_fulltext({ identifier: "Attention Is All You Need" }) # 标题
paper_fulltext({ identifier: "…", paksa_ulang: true }) # 强制重新下载

它如何找到 PDF——arXiv 优先，即上游 PR #124：

1. 作品自身的 arXiv id（来自 10.48550/arXiv. 或 arXiv 位置），或者否则通过标题查找的 arXiv 版本；
2. OpenAlex 报告的每个开放获取 PDF 位置；
3. Unpaywall，最后，使用配置的邮箱。

然后 PDF 会与其 Markdown 一起保存在 ~/.dsh/paper-search/md/ （用 folderTeksLengkap 插件选项覆盖），由 anydoc 本地转换——回退为 markitdown——该工具返回文件路径、使用了它，以及要么是全文（当 ≤ 20,000 个字符时），要么是预览加上用于继续的 read({ file_path, offset, limit }) 调用。

测量于 2026-09-29：Attention Is All You Need（2.1 MB PDF）→ 424 ms 内生成 39.8 KB 的 Markdown；一篇 PLOS ONE 论文（2.9 MB）→ 363 ms 内生成 70.8 KB，且参考文献链接完好。通过该工具端到端运行，包括下载和 arXiv 查找：2.4–4.4 s，而当文件已存在时为 0.3 s。

安装一个转换器（两者均未捆绑）：

npm i -g @firecrawl/anydoc # 推荐：Rust 二进制文件，无需 Python
uv tool install markitdown # 备选

paper_status 会报告找到了哪个转换器以及在哪里找到——在你遇到失败之前。

明确说明而非隐藏的限制

1. 仅限开放获取副本。 如果不存在合法的免费副本，该工具会失败并说明原因，列出它尝试过的候选来源。它从不绕过付费墙，也从不使用 Sci-Hub 或 Anna's Archive。
2. 转换始终在本地进行。 anydoc 有一个 --ocr hosted 模式，会将文档上传到 Firecrawl；本插件从不使用它。
3. 标题查找可能会选错作品。 实测：标题 "Attention is all you need" 在 OpenAlex 中解析为 W2626778328，这是一条重复记录。每个输出都会指明它实际使用的作品——在信任结果之前请核对它。使用 DOI 或 arXiv id 更安全。
4. 文件永远不会替你删除。 库每篇论文增长约 2–3 MB（PDF + Markdown）。

验证状态

精确陈述，因为单独说“已测试”并不是一个有用的说法：

已验证——连接器，针对实时 API 和页面。 node test/uji-sumber.mjs 针对真实服务运行全部十七个连接器：77/77 断言。在上一次运行中，17 个中有 14 个作出了响应；未响应的那些被报告为失败——OpenAlex 和 Semantic Scholar 返回 HTTP 429，PubMed Central 返回一个暂时性的 HTTP 500 error forwarding request——而这正是本包旨在提供的行为。来源 acm 在 520 ms 内以真实的 ACM 记录作出了响应。

已验证——接线，针对模拟的 Cordis 上下文。 node test/uji-plugin.mjs，57/57 断言：全部五个工具均已注册，新工具确实被调用并返回数据，paper_fulltext 下载并转换一篇真实论文，且生成的 .md 已在磁盘上检查，技能提供者报告 rank 450，frontmatter 在 500 字符的目录限制内解析，并且每个工具都声明了 DSH 所需的 output: { schema, render }。

已验证——在实时 harness 内加载该 bundle。 node test/uji-di-dsh.mjs 将 headless 配置文件复制到一个一次性的测试配置文件，插入本插件以及一个见证插件，启动一个真实的 DSH（0.2.0-rc.1），并从内部检查全部五个工具均已注册、技能提供者已注册、技能出现在目录中，以及 paper_search 确实被调用并返回真实论文。27 个断言，0 个失败。 见证记录
schemas=Array(15): paper_search, paper_status, paper_citations, paper_oa,
paper_fulltext, …。

最后那个测试证明了它的价值：它捕获了一个 mock 永远无法发现的致命 bug。
DSH 要求每个工具都声明 output: { schema, render }，而 0.1.0 没有这样做——因此注册时抛出异常，而由于异常发生在 apply() 内部，整个插件加载失败。0.1.0 无法使用；请使用 0.1.1。

报告为何诚实

每个结果都将失败的来源与做出应答的来源区分开来：

v Crossref 3 results (2316 ms)
x Semantic Scholar FAILED — HTTP 429 — {"message": "Too Many Requests... v Garuda 3 results (1428 ms)

失败的来源绝不允许伪装成“无结果”。这并非细枝末节：该领域中一个被广泛使用的工具对每一个非 200 响应都返回空列表，且完全不记录任何错误，因此一个被限流的请求会被读作“这些文献不存在”。而在这里，失败及其 HTTP 状态会被打印出来，并且 paper_status 的存在就是为了按需证明服务是否存活。

凭据（全部可选）

不捆绑任何密钥。读取顺序：

1. 你的 DSH 配置文件中的插件配置，
2. 环境变量 PAPER_SEARCH_MCP_，然后是 ，
3. 文件 ~/.config/paper-search-mcp/.env（属于上游 CLI）。

| 名称 | 用途 |
| UNPAYWALL_EMAIL | 任意邮箱——用作 Crossref/OpenAlex 的“礼貌池”联系方式 |
| OPENALEX_EMAIL | 同上，仅用于 OpenAlex |
| SEMANTIC_SCHOLAR_API_KEY | 提高 Semantic Scholar 的速率限制 |
| DOAJ_API_KEY | 提高 DOAJ 的每小时限制 |
| CORE_API_KEY | core 来源必需——没有它，CORE 会返回 HTTP 429 和空响应体 |

十七个来源中有十五个无需任何凭据即可工作；密钥可提高速率限制和稳定性。有两个是例外，且每个都会报告为清晰、可操作的失败，而不是令人困惑的 429：

- core 需要 CORE_API_KEY。
- unpaywall 需要一个邮箱（任意真实地址）——它还需要 DOI 作为输入。

本包不做什么

- 它不绕过付费墙或访问控制，也从不使用 Sci-Hub 或 Anna's Archive。paper_fulltext 仅下载合法开放获取的副本；下载的文件保留在你的机器上，不会重新分发。
- 它不会将你的文档上传到任何地方。PDF→Markdown 转换在本地通过 anydoc/markitdown 运行；从不使用 anydoc 的托管 OCR 模式。
- 除上面列出的来源外，它不调用任何其他服务。
- 它不要求也不安装 paper-search-mcp。如果该 CLI 恰好已安装，你可以用它来获取其额外来源（CORE、Zenodo、HAL、 SSRN、Unpaywall、OpenAIRE、CiteSeerX、BASE）——本插件从不依赖它。

许可证与署名

MIT——见 LICENSE。署名和来源条款见 NOTICE.md。