dsh-arxiv：arXiv 搜索与摘要获取插件

前言¶

在 DeepSeek Harness（DSH）的开发中，智能体需要访问外部知识库以获取最新的学术信息。面对海量的 arXiv 论文，直接爬取 PDF 或构建全文索引不仅成本高，而且往往超出本地处理能力。dsh-arxiv 插件旨在解决这一需求，它通过 arXiv 的公开 Atom API 提供轻量级的论文搜索与摘要获取能力。

插件定位¶

这是一款为 DSH 设计的函数插件，由开发者 jwilson411 维护。其核心定位是“只读查询工具”，不涉及 PDF 下载、全文提取或本地存储，仅用于回答“关于 X 有什么论文”和“这篇论文是什么”这两个问题。

核心功能¶

插件注册了两个面向模型的工具：
* arxiv_search：执行论文搜索。
* arxiv_get：获取特定论文的详细信息。

该插件严格遵循以下原则：
* 只读：仅查询，不修改 arXiv 服务器数据。
* 无状态：不维护本地缓存或会话。
* 无凭证：不需要 API 密钥或登录信息。
* 无 PDF 处理：不下载或解析 PDF 文件，仅返回元数据和摘要。

安装与启用¶

在终端中执行以下命令，将插件添加到 web profile 中：

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

该命令会将插件的 manifest 作为 bundle patch 追加到 profile 的配置中。

典型用法¶

1. 搜索论文¶

使用 arxiv_search 工具，通过关键词或 arXiv 的查询语法进行搜索。

示例调用：

// 在 DSH 上下文中
{
  "tool": "arxiv_search",
  "arguments": {
    "query": "au:Hinton AND cat:cs.LG",
    "max_results": 5
  }
}

返回结果结构：

{
  "query": "au:Hinton AND cat:cs.LG",
  "search_query": "...",
  "max_results": 5,
  "returned": 5,
  "papers": [
    {
      "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"
    }
  ],
  "plugin": "dsh-arxiv"
}

查询语法说明：
该工具支持 arXiv 的字段前缀（如 ti: 标题，au: 作者，cat: 分类）。如果查询以字段前缀开头，会原样传递给 arXiv API。

2. 获取论文详情¶

使用 arxiv_get 工具通过 ID 获取论文信息。

示例调用：

{
  "tool": "arxiv_get",
  "arguments": {
    "id": "1706.03762"
  }
}

ID 格式支持：
插件会自动规范化 ID，支持多种格式：
* 标准格式：1706.03762
* 带版本：1706.03762v7
* 协议前缀：arxiv:1706.03762
* URL 形式：/abs/1706.03762

注意： 插件会保留版本后缀（如 v7），以避免版本歧义。如果 ID 不存在，会抛出 ARXIV_NOT_FOUND 错误。

配置与无头模式¶

网络限制配置¶

插件通过 HTTP 调用 https://export.arxiv.org/api/query。为了避免阻塞，请求受到以下限制，这些限制可在配置文件中调整：

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

Headless 使用¶

在 Node.js 环境下，无需启动完整 profile，可直接使用工厂函数驱动工具。

示例代码：

import { createArxivSearchTool } from 'dsh-arxiv'

// 使用全局 fetch 进行实际网络请求
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}`)
}

如果需要离线测试，可传入一个模拟的 fetch 函数。

适用场景与注意事项¶

适用场景：
* 需要快速检索特定领域的最新论文列表。
* 需要获取论文的元数据（作者、摘要、发布时间）用于后续处理。
* 在无头环境中（如 CI/CD、服务器）运行自动化查询。

注意事项：
1. 数据归属：插件仅返回 arXiv 官方 API 的数据，数据版权归 arXiv 及其作者所有，不归插件所有。
2. 引用规范：使用返回的 abs_url 或 pdf_url 进行引用，不要将插件视为数据源。
3. 合规性：插件会通过自定义 User-Agent 标识自身，使用时请遵守 arXiv API Terms of Use，避免高频请求影响服务。
4. 许可：插件代码遵循 MIT 许可证，但该许可证仅覆盖插件代码本身，不覆盖检索到的论文内容。

总结¶

dsh-arxiv 是一个专注于“查询”而非“存储”的轻量级插件。它通过封装 arXiv 的 Atom API，为 DSH 生态提供了标准化的论文检索接口，适合需要在应用中集成学术检索功能的场景。