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 内容。