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 生態提供了標準化的論文檢索接口，適合需要在應用中集成學術檢索功能的場景。