arXiv 论文检索 jwilson411/dsh-arxiv

dsh-arxiv

一个用于在 arXiv 上查找论文的小型 DeepSeek Harness 函数插件。它通过 arXiv 的公共 Atom API 恰好注册两个面向模型的工具——arxiv_search 和 arxiv_get——除此之外不拥有任何其他东西。

它刻意不是一个科学平台。没有 PDF 摄取，没有全文提取，没有嵌入存储，没有引用图，没有参考文献管理器。它回答两个问题——关于这个已经写了些什么？ 和 这篇论文是什么？——并返回元数据和摘要。如果你想要 PDF，工具会告诉你它在哪里；获取它是别人的工作。

只读，无 API 密钥，无凭据，无状态。

安装

dsh plugin --profile web add github:jwilson411/dsh-arxiv

dsh plugin 会转发到 $DSH_HOME/profiles/web 内的 pnpm，然后根据已安装状态协调 profile：由于此包的清单声明了 dsh.bundle.patch，它会被追加到 profile 清单中有序的 dsh.profile.bundles 列表，其补丁成为一个层。

移除它的方式相同，只需将 add 替换为 remove。

固定的 DSH 候选发布版本

此包是针对固定的候选发布版本 0.1.1-rc.2 编写和测试的——即当前的 @deepseek-ai/dsh 版本以及匹配的 @deepseek-ai/dsh-tools@0.1.1-rc.2，后者被精确固定在 devDependencies 中，以便测试针对一个已知的 API 运行。peer 范围是 ^0.1.1-rc.2，与 harness 自己的工具包声明方式一致。

请注意，@deepseek-ai/dsh-tools 的 npm latest 标签仍指向较旧的 0.0.1-rc.1；0.1.1-rc.2 系列发布在 next 下。请显式固定版本，而不要依赖标签。

它注册了什么

| Cordis 插件 id | arxiv（cordis.patch.yml 中的行 id） |
| 注入 | tools——一个硬依赖；插件会等待而不是降级 |

| 工具 | 参数 | 返回 |
| arxiv_search | query（字符串，必填）、max_results（整数，可选，1–25，默认 5） | { query, search_query, max_results, returned, papers[], plugin } |
| arxiv_get | id（字符串，必填） | { requested_id, paper, plugin } |

两个工具中的每篇论文都是同一个对象：

{
"id": "1706.03762v7",
"title": "Attention Is All You Need",
"authors": ["Ashish Vaswani", "Noam Shazeer", "..."],
"published": "2017-06-12T17:57:34Z",
"abstract": "The dominant sequence transduction models are based on …", "pdf_url": "https://arxiv.org/pdf/1706.03762v7", "abs_url": "https://arxiv.org/abs/1706.03762v7" }

pdf_url 会被报告出来，以便调用者可以打开它。此插件从不获取它。

arxiv_search 在所有字段中发送一个普通短语。以 arXiv 的字段前缀之一（ti:、au:、abs:、cat:、all: 等）开头的查询会按原样传递，因此 au:Hinton AND cat:cs.LG 可以正常工作。max_results 会被限制在 1–25 范围内，而不是被拒绝——这是一个查找工具，不是采集器。
arxiv_get 接受 1706.03762、1706.03762v7、arxiv:1706.03762、 /abs/ 或 /pdf/ URL，以及 2007 年之前的 hep-th/9901001 形式；所有这些都会规范化为裸标识符。版本后缀会保留，因为丢弃它会在不知不觉中回答与所请求的不同修订版本。arXiv 对未知 id 会返回 HTTP 200 和一个错误条目，因此 arxiv_get 会检查并抛出 ARXIV_NOT_FOUND，而不是静默地报告什么都没有。

与 arXiv 通信

一个端点，通过 HTTPS，无需密钥：https://export.arxiv.org/api/query。
没有任何地方会抓取 HTML 页面。

每个请求都受到双重限制，并且在任一限制下都会失败关闭——一个 AbortSignal 截止时间（15 秒）和一个在正文流式传输时强制执行的响应字节上限（2 MiB），因此超大响应会被放弃而不是被缓冲。两者都可以从插件的 patch 行进行配置：

- insert:
- id: arxiv
name: dsh-arxiv
config:
timeoutMs: 15000
maxBytes: 2097152

失败会携带一个稳定的 code——ARXIV_TIMEOUT、ARXIV_HTTP_ERROR、 ARXIV_RESPONSE_TOO_LARGE、ARXIV_NOT_FOUND、ARXIV_BAD_ID、 ARXIV_BAD_QUERY、ARXIV_PARSE_ERROR、ARXIV_UNREACHABLE——因此调用方可以区分超时和论文缺失，而无需匹配文字描述。

请求会通过一个 User-Agent 表明自身身份，其中包含插件名称及其仓库，正如 arXiv 的使用条款所要求的那样。

无头使用

工具工厂会接收要使用的 fetch，因此你可以在不启动 profile 的情况下，从普通 Node 脚本中驱动任一工具：

// titles.mjs — node titles.mjs
import { createArxivSearchTool } from 'dsh-arxiv'

// Omit fetch to use the global one and hit the real API. Doing so sends live
// requests to export.arxiv.org: be polite, and read the terms linked below.
const search = createArxivSearchTool({ fetch: globalThis.fetch })

const exec = { signal: AbortSignal.timeout(20_000) }
const result = await search.execute({ query: 'au:Hinton AND cat:cs.LG', max_results: 5 }, exec)

console.log(${result.returned} paper(s) for ${result.search_query})
for (const paper of result.papers) {
console.log( ${paper.id} ${paper.title})
}

换入一个 stub fetch，同一个脚本就可以完全离线运行——这正是测试套件驱动它的方式：

const canned = async () =>
new Response(await readFile('feed.xml', 'utf8'), {
status: 200,
headers: { 'content-type': 'application/atom+xml' },
})

const search = createArxivSearchTool({ fetch: canned })

execute 会在主体运行之前验证其参数，因此错误调用会以 ToolArgsError 拒绝，并且永远不会到达网络。

arXiv 的条款，以及这是谁的文本

这个插件是一个 API 客户端。它与 arXiv 无关联，也未得到 arXiv 的认可。

API 的使用受 arXiv API Terms of Use 约束。简而言之：标明你的客户端，不要频繁冲击服务，并尊重元数据的许可。
这些工具返回的摘要和元数据属于 arXiv 及其作者，而非本插件。 除合并 arXiv 用于包裹正文的换行符外，它们均原样传递。请将其归属于 arXiv 和论文作者，并引用论文——每个结果上的 abs_url 就是应指向的位置。感谢 arXiv 公开提供 API 及其数据。

布局

package.json 清单 + dsh.bundle.patch —— 使其成为 bundle 的关键 cordis.patch.yml bundle 的补丁层：一次插入，一行插件 src/index.js 插件：name、inject、apply(ctx)、两个工具 src/arxiv.js HTTP 客户端：端点、边界、id 和查询处理 src/atom.js 针对 arXiv Atom feed 的小型专用解析器 src/errors.js ArxivError 及其错误码 test/ 离线测试，附带已检入的 feed 测试夹具

Atom 解析器是针对 arXiv 唯一有文档记载的响应结构手写的，而非引入通用 XML 库，因此本包完全没有运行时依赖。

测试

npm install
npm test

从构造上即为离线。 每个测试都注入一个 fetch 替身，从已检入的测试夹具返回响应，并且每个测试文件都会用一个会抛错的守卫替换全局 fetch——因此，忘记使用注入的 fetch 的代码路径会以测试失败的形式暴露，而不是向 export.arxiv.org 发起真实请求。npm test 不会打开任何套接字，也不会读取任何凭据。

测试套件覆盖注册、针对捕获的真实 feed 的 Atom 解析器、钳制、id 规范化、两种渲染投影、输出模式验证、超时、超大、非 2xx、未知 id 和错误参数时的显式失败，以及清单/补丁接线。

CI（.github/workflows/ci.yml）在 Node 22 和 24 上运行相同的两条命令，使用 contents: read 且无任何机密。

许可证

MIT —— 见 LICENSE。仅涵盖本插件的代码，不涵盖其检索的 arXiv 内容。