Vncntvx/dsh-zotero

dsh-zotero

English · 中文

dsh-zotero 是面向 DeepSeek Harness 的本地 Zotero 插件。模型可以直接检索文献库、读取 PDF 全文与笔记、定位原文片段并生成学术引用。

所有操作均通过 Zotero 本地 API（127.0.0.1:23119）与桌面端交互，读取无需配置 API Key。

主要功能

• 文献检索与发现：按标题、作者、年份、标签或全文搜索文献，支持限定合集分类或查找最近导入的条目。
• PDF 全文与笔记阅读：模型可直接读取文献元数据、摘要、用户笔记，并解析本地 PDF 附件全文。
• 段落级原文检索：围绕具体研究问题检索论文全文、批注与笔记，定位相关段落；PDF 批注附带原始页码与直达跳转，便于核验。
• 引用生成与导出：一键生成标准学术引用，支持以 BibTeX、RIS、CSL JSON 或文本参考文献格式复制与下载。
• 会话文献标签页（Sources）：对话中引用的文献会自动同步到会话顶部的「Zotero」专属标签页，可集中查看条目详情、回溯原文片段与打开本地 PDF。
• 双向笔记与标签管理：支持让模型创建读书笔记、添加标签和整理分类；所有写入操作均提供计划审查卡片并需手动确认。
• 学术文献检索（可选组件）：在插件管理器「包含的组件」中启用 dsh-zotero/scholarly 后可跨 arXiv、OpenAlex、Crossref、Semantic Scholar、PubMed、Europe PMC、DBLP 检索文献，读取开放获取全文并核验参考文献真伪。该组件随包发布但默认关闭，启用它即授权其向外部服务发起请求。

安装

从 npm 安装（推荐）：

dsh plugin --profile <name> add dsh-zotero

从 GitHub 预构建分支安装：

dsh plugin --profile <name> add github:Vncntvx/dsh-zotero#release

安装完成后新建会话即可使用。在插件管理器中打开 dsh-zotero 详情页，其配置区提供完整配置表单，支持调整 API 地址、并发限制与检索参数。

提示：从 main 源码分支直接安装需要本地执行构建。pnpm 默认拦截依赖构建，使用 #release 分支可免除构建配置直接安装。

前置条件

1. 安装并运行 Zotero 7 及以上桌面版（写入功能需 Zotero 10）。
2. 在 Zotero 中开启本地 API：设置 → 高级 → 勾选“允许此计算机上的其他应用程序与 Zotero 通信”。

使用示例

Agent 在对话中按需调用工具，检索结果会作为上下文并同步沉淀到 Sources 面板：

用户：帮我找 Risk 相关的论文
Agent → zotero_search(query: "Risk", itemTypes: ["journalArticle"])
       返回 5 篇匹配结果，条目同步到会话顶部的 Zotero 标签页

用户：第一篇的摘要说了什么？
Agent → zotero_get(ref: "zotero://user/0/item/ABCD1234")
       返回文献元数据与摘要全文

用户：这篇里关于方法论的讨论，帮我找出来
Agent → zotero_retrieve(ref: "zotero://user/0/item/ABCD1234", query: "methodology",
                        sources: ["annotation", "fulltext"])
       返回排序段落与来源标注（批注附带原始页码）

用户：把这三篇导出为 BibTeX
Agent → zotero_export(refs: ["zotero://user/0/item/ABCD1234",
                             "zotero://user/0/item/EFGH5678",
                             "zotero://user/0/item/IJKL9012"], format: "bibtex")
       生成 BibTeX 条目，支持在界面中复制或下载

工具一览

插件提供 8 个读取工具与 15 个写入工具。写入工具默认关闭，可在配置中开启 writeEnabled。

工具 · 用途 zotero_search · 按标题、作者、年份或全文搜索文献，支持按分类与标签筛选 zotero_browse · 浏览文献库结构，包括分类合集树、标签列表和保存的搜索 zotero_get · 读取单篇文献的元数据详情、摘要、附件与笔记列表 zotero_children · 查看文献关联的子条目，包括独立笔记、PDF 附件和阅读批注 zotero_retrieve · 围绕问题从全文、笔记与批注中检索相关段落（批注保留页码） zotero_changes · 检查文献库最近的新增、修改或删除记录 zotero_attachment · 获取文献关联的本地 PDF 文件路径 zotero_export · 生成格式化引用、参考文献列表，或导出 BibTeX、RIS、CSL JSON

写入工具（默认关闭，开启后仅写入个人库）：

工具 · 用途 zotero_create_note · 创建独立笔记或条目子笔记，支持标签、合集与来源关联 zotero_update_note · 按版本前置替换已有笔记正文，创建与更新共用同一字符上限 zotero_update_item_tags · 在一次调用中增删条目标签，保留既有标签类型 zotero_update_item_collections · 在一次调用中增删条目的合集归属 zotero_create_collection · 创建顶层或子合集，同级同名拒绝 zotero_update_collection · 重命名合集或移动其父合集 zotero_delete_collection · 删除合集（不可逆），计划卡先给出条目数与子合集数 zotero_create_item · 从闭合字段集创建文献条目 zotero_update_item · 订正条目标量元数据，字段合法性按条目类型校验 zotero_restore_items · 将回收站条目恢复为活动状态，逐项返回回执 zotero_create_saved_search · 创建保存搜索，至少需要一个条件 zotero_update_saved_search · 更新保存搜索的名称或条件 zotero_delete_saved_search · 删除保存搜索 zotero_delete_library_tags · 按名称全库删除标签（不可逆），未命中的名称可安全重试 zotero_batch_items · 批量创建文献、更新标签与合集归属、移入回收站，合并确认

全部 23 个宿主工具的参数定义见 工具参考。学术文献检索另属 dsh-zotero/scholarly 组件，随包发布但默认关闭；启用该组件即启用这 7 个工具。

安全与隐私

• 本地通信：插件仅向本地 Zotero 接口（http://127.0.0.1:23119/api）发起请求，不调用 Zotero 官方云端服务。
• 文件访问：仅读取本地附件文件状态，不执行系统 shell 命令，不启动后台常驻守护进程。
• 写入确认：写入工具默认禁用。开启后，每次修改文献库都会在界面展示审批卡片，经用户确认后才执行。

说明文档

文档 · 内容 快速入门 · 安装步骤、前置条件与连接验证 功能概览 · Sources 来源面板、对话集成与导出工作流 工具参考 · 全部 23 个宿主工具的参数、返回值与错误码 配置参考 · 37 个配置项说明与默认值 系统架构 · 数据流、分层职责与设计边界 开发指南 · 构建、测试、调试与发布流程 使用场景 · 典型对话用例与使用示例 故障排查 · 常见连接问题诊断与处理方法

许可证