在 DeepSeek Harness (DSH) 中构建本地智能体或进行模型推理时，经常会遇到需要 AI 阅读私有文献的场景。手动上传 PDF 既繁琐，又难以进行全文检索。
下面介绍 dsh-zotero 插件，它通过连接本机 Zotero，对整个文库中的 PDF 全文建立索引，从而在 DSH 的侧边栏面板或对话中直接检索并阅读文献。
插件简介¶
dsh-zotero 是一个连接 Zotero 7 的 DSH 插件。它利用 Zotero 自带的索引能力或直接解析 PDF 文本层，建立文献全文索引。用户既可以在侧边栏面板中进行检索，也可以在对话中直接提问让 AI 查阅文献。
- 维护者：H-xie
- 类别：模型推理
- 许可证：MIT
核心功能¶
- 全文索引：优先使用 Zotero 自带的全文索引；若无索引，则直接读取 PDF 并解析文本层。纯图片（扫描件）无法解析，但不会影响其他文献。
- 面板检索：在 DSH 侧边栏新增「Zotero 文献」面板。支持配置连接、建立索引、限定分类检索以及逐块阅读全文。
- 对话检索：在对话中直接提问，AI 会自动调用检索工具查询文献并阅读相关段落。提及分类名时，会自动限定检索范围。
安装与启用¶
前置条件¶
在安装插件前，请确保满足以下条件：
- 运行 Zotero 7（或更高版本）。
- 开启本地 API：在 Zotero 中依次点击
编辑→设置→高级，勾选允许其他应用与 Zotero 通信。
安装步骤¶
插件以目录链接方式安装，因此需要先克隆代码并安装依赖。
git clone https://github.com/<你的用户名>/dsh-zotero.git
cd dsh-zotero
npm install # 安装 PDF 解析依赖（必做）
安装完成后，在 DSH 界面中：
- 进入「插件」页面。
- 点击「安装插件 / Install bundle」。
- 选择刚才解压的
dsh-zotero文件夹。 - 启用插件并刷新页面，左侧栏将出现「Zotero 文献」图标。
注意：DSH 以目录链接方式安装插件，不会自动处理插件的 npm 依赖，因此必须手动运行一次
npm install（或pnpm install）。
典型用法¶
- 连接设置：打开左侧栏「Zotero 文献」面板，在「1. 连接设置」中填写本地服务地址（默认
http://localhost:23119/api），点击「测试连接」确认成功后点击「保存设置」。 - 建立索引：在「2. 全文索引」区域点击「建立 / 更新索引」，等待索引完成（首次可能需要几分钟）。
- 面板检索：在「3. 全文检索」中输入关键词，可选择性填写「限定分类」（支持子分类），点击「阅读全文」逐块阅读。
- 对话检索：直接在对话中说「检索我的 Zotero 文献中关于 XXX 的文章」，AI 会自动检索。如果提及分类名（如「检索我的 Zotero 文献中关于 XXX 的文章，限定分类为 CSS」），检索范围会自动限定。
注意事项¶
- 依赖安装：必须先运行
npm install，否则插件无法正常工作。 - Zotero 版本：建议使用 Zotero 7 或更高版本。
- API 开关：必须确保在 Zotero 设置中勾选了允许其他应用通信。
- 扫描件限制：纯图片格式的文献（扫描件）无法解析，需要先在 Zotero 中进行 OCR 识别后再更新索引。
- 存储位置：文献索引与设置保存在
~/.dsh-zotero/目录下，更换电脑或端口时需重新配置地址。
结语¶
dsh-zotero 通过将本地 Zotero 库与 DSH 的 RAG 能力结合，解决了私有文献快速检索与阅读的问题。安装简单，检索精准，适合需要在本地环境中处理大量文献的开发者。
