前言¶
在 DSH 的插件化工作流裏，Agent 經常需要基於本地文獻回答研究問題。僅憑上下文或模型記憶，往往缺少可覈對的來源；手動打開 Zotero、複製摘要和引用，也會打斷對話流。
dsh-zotero 是一個 DSH 插件，用來把本地 Zotero 文獻庫接入 Agent：搜索文獻、讀取元數據和筆記、按查詢提取證據段落，並生成引用。
這是什麼¶
dsh-zotero 倉庫爲 Vncntvx/dsh-zotero，許可證爲 MIT。它解決的問題是：讓 Agent 可以直接讀取本地文獻庫中的論文、摘要、筆記、批註和附件，再把相關證據組織成可引用的輸出。
核心能力¶
以下能力均爲讀取本地文獻庫，不修改條目、筆記、標籤或分類。
1、搜索文獻。按標題、作者、年份搜索，支持 library、collection、savedSearch、publications 作用域；everything 模式會連全文索引一起搜。
2、瀏覽庫結構。可以發現庫、合集樹、保存的檢索、標籤 facet、條目類型及其字段。
3、讀取單條文獻。讀取一條文獻的元數據；可返回筆記、批註、附件清單；fields:"all" 保留全部元數據。
4、探索子對象。查看一條文獻直連的筆記、附件，以及掛在 PDF 下的批註。
5、提取證據。按查詢詞返回最相關的證據段落，來源可包括批註、筆記、摘要、全文；支持多附件檢索。
6、增量感知。基於本地事務版本，判斷哪些條目、合集或全文索引發生了變化，以及什麼被刪除。
7、定位附件。將文獻 ref 解析爲已驗證的磁盤路徑或鏈接 URL。
8、導出引用。生成引用、參考文獻表、BibTeX、BibLaTeX、RIS、CSL JSON。
安裝與啓用¶
先執行插件安裝命令：
dsh plugin --profile <name> add dsh-zotero
安裝後，重啓 dsh 並新建會話，Agent 即可使用 Zotero 工具。
插件在 Settings -> Plugins 中提供配置卡片。插件的唯一寫入是配置卡片保存後寫入：
$DSH_HOME/settings.yaml
的 zotero: 用戶層。配置修改保存即熱更新，無需重啓；安裝或卸載插件後則需要重啓 dsh 並新建會話。
典型用法¶
下面按一個常見研究流程說明調用方式。
先搜索 Risk 相關的期刊論文：
zotero_search(query: "Risk", itemType: "journalArticle")
這一步會返回匹配的文獻結果。
讀取第 1 條文獻的摘要字段：
zotero_get(ref: 1, fields: ["abstractNote"])
這一步只取指定字段，便於把摘要作爲後續上下文。
圍繞 methodology 提取證據段落：
zotero_retrieve(query: "methodology", sources: ["fulltext", "notes"])
這一步會從全文和筆記中查找與查詢詞相關的段落。
把三條文獻導出爲 BibTeX：
zotero_export(refs: [1,2,3], format: "bibtex")
導出結果是靜態文本，需要手動複製到目標位置。
適用場景與限制¶
它適合把本地 Zotero 文獻庫作爲證據來源的 Agent 工作流，例如查找論文、覈對摘要、從筆記和批註中找依據、生成參考文獻。
需要注意：
- 網絡請求只發往
http://127.0.0.1:23119/api，不跟隨重定向；resolveConfig強制 loopback 地址。 - 文件訪問是隻讀；
zotero_attachment用existsSync校驗 Zotero 返回的附件路徑，不寫文件系統。 - 插件不執行 shell 命令、不加載 native 模塊、不啓動常駐進程。
- 證據排序基於
BM25，按查詢詞與 passage 的詞頻匹配度排序。 - 全文證據依賴 Zotero 索引；未索引的 PDF 無法提供全文段落。
zotero_attachment返回文件位置後，繼續閱讀 PDF 需要宿主具備對應能力。
由於插件會按當前 dsh 進程權限運行，安裝前建議檢查源碼與 MIT 許可證。
結尾¶
dsh-zotero 把“找論文、讀摘要、提取批註、導出引用”這幾個步驟接入了 Agent 工作流，適合需要本地文獻證據和可引用輸出的場景。
GitHub：https://github.com/Vncntvx/dsh-zotero
