前言¶
在 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
