前言¶
在 DSH（DeepSeek Harness）中做智能體時，如果論文和資料存放在本地 Zotero，通常會遇到幾個具體動作：按關鍵詞找文獻、讀條目摘要、打開 PDF 全文、確認附件路徑、把閱讀結果寫進筆記。這些資料在本地應用裏，agent 如果沒有對應工具，就只能依靠人工整理。
dsh-zotero 是 DeepSeek Harness 的 Zotero 工具插件。它讓 agent 通過 Zotero 本地 API 訪問本機文獻庫，無需 API Key，用於檢索文獻、讀取元數據與摘要、查看附件、讀全文以及處理筆記。
這是什麼¶
dsh-zotero 是 DeepSeek Harness 的 Zotero 工具插件，由 Hongcheng-LI 維護，許可證爲 MIT。
它的一行定位是：讓 agent 直接檢索你的 Zotero 文獻庫、閱讀條目元數據與摘要、列出分類和 PDF 附件、讀 PDF 全文、代寫讀書筆記。
它通過 Zotero 本地 API 訪問，默認地址爲：
http://127.0.0.1:23119
使用前提是本機已安裝並運行 Zotero 7 及以上，並且開啓：
Settings → Advanced → 允許本機上的其他應用程序與 Zotero 通信
資料說明該項目在 Zotero 9.0.6 / Windows 上實測通過。
核心功能¶
下面介紹插件提供的工具。
檢索與條目¶
1、zotero_collections：列出文獻庫的所有分類，返回 collectionKey 和條目數，用於限定後續檢索範圍。
2、zotero_search：按關鍵詞檢索文獻庫，支持條目類型、分類、標籤、年份區間、排序、分頁；mode 控制返回粒度。
3、zotero_recent：列出最近添加的條目。
4、zotero_item：按 key 讀取條目詳情，包括作者、期刊、DOI、摘要、標籤、附件列表。
全文與附件¶
1、zotero_fulltext：讀取條目全文純文本。優先讀 Zotero 全文緩存；無緩存時解析本地 PDF 並寫緩存；遠程鏈接附件才下載到工作區。
2、zotero_attachment_path：返回附件在 storage 的原始絕對路徑。
3、zotero_download：把條目的 PDF 附件下載到會話工作區。
筆記¶
1、zotero_notes：列出某條目的子筆記，或全庫按關鍵詞搜索筆記正文。
2、zotero_note：支持 create / append / update / delete。注意：筆記寫操作受 Zotero 本地 API 只讀限制，多數版本不可用；工具會返回明確提示並建議手動操作。
安裝與啓用¶
先確認 Zotero 已按上面要求啓動並開啓本地通信。然後執行：
dsh plugin --profile web add dsh-zotero
裝好後重啓 dsh web。
package.json 聲明 node >=20，並聲明 peerDependencies 包含 @deepseek-ai/cordis ^4.0.1。
注意：插件會以當前 dsh 進程權限運行。安裝前應檢查源碼、依賴和 MIT 許可證，確認它只會訪問你本機允許的 Zotero 數據。
可選配置¶
如果需要使用不同的 Zotero 地址、庫、下載目錄或數據目錄，可以在你使用的 profile 的 cordis.patch.yml 中覆蓋 tool-zotero 行，然後重啓。
可選配置項包括：
baseUrl
library
downloadDir
dataDir
storageDir
maxAttachmentBytes
maxFulltextChars
maxLimit
timeoutMs
示例結構如下。這裏 baseUrl 可填本機 Zotero 本地 API 地址；其餘配置項可按本機 Zotero 數據目錄和下載需求填寫：
- id: tool-zotero
config:
baseUrl: http://127.0.0.1:23119
library:
downloadDir:
dataDir:
storageDir:
maxAttachmentBytes:
maxFulltextChars:
maxLimit:
timeoutMs:
修改後重啓。
典型用法¶
倉庫資料給出的示例對話是：
在我的 Zotero 裏搜一下 transformer 相關的論文，挑 2020 年以後的，把第一篇的全文讀一遍，給我寫個摘要存進筆記。
這句話會涉及 zotero_search、zotero_fulltext 和筆記相關工具。其中“存進筆記”依賴 zotero_note 的寫操作；如果本機 Zotero 本地 API 只讀，寫操作會返回明確提示並建議手動操作。
適用場景與注意¶
適合：
- 本機已有 Zotero 7 及以上文獻庫；
- 希望 DSH agent 直接讀取論文元數據、摘要、PDF 全文和附件路徑；
- 需要把本地 Zotero 作爲 agent 的資料源。
注意：
- 需要本機 Zotero 正在運行；
- 需要開啓本地 API 通信；
- 筆記寫操作多數版本不可用；
- 插件以 dsh 進程權限運行，安裝前應審查源碼和許可證；
- DSH 社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係，不應視爲官方應用商店。
結尾¶
dsh-zotero 的價值是把本地 Zotero 文獻庫變成 DSH agent 可直接調用的工具：檢索文獻、讀取元數據、讀取全文、獲取附件路徑、處理筆記讀取。它依賴本機 Zotero 本地 API，而不是把文獻庫遷移到雲端。
GitHub：
https://github.com/Hongcheng-LI/dsh-zotero
目錄頁 URL 未在已覈實資料中確認，本文不給出具體地址；可在 DSH 社區目錄中按 dsh-zotero 檢索。
