Hongcheng-LI/dsh-zotero

English | 中文

DeepSeek Harness 的 Zotero 工具插件：让 agent 直接检索你的 Zotero 文献库、阅读条目元数据与摘要、列出分类和 PDF 附件、读 PDF 全文、写回读书笔记与 PDF 高亮。通过 Zotero 本地 API（7 代及以上可用，实测 9.x / 10.0.7；http://127.0.0.1:23119）访问：读取不需要任何密钥，写入需要一次性本地授权（见「写入授权」），纯 Node 实现，零核心改动。

兼容版本：按 DSH 运行时 0.2.0-rc.x（桌面版 44.x 内核）的插件规范更新——schemastery Config 配置校验与设置表单、locale/ 插件管理器元信息、预构建 lib/ 直装、dsh.plugin.json 已按新规范移除（新运行时不读取该文件）。插件本体不声明任何 @deepseek-ai/dsh-* peer，能通过所有版本的兼容门禁；并用真实 @deepseek-ai/dsh-tools 注册表做契约测试（见「开发」）。

前置条件

1. 本机安装并运行 Zotero 7 及以上（本地 API 自 7 代引入；本项目在 Zotero 9.0.6 / Windows 上实测通过）；
2. 打开 Zotero：设置 → 高级 → 通用 → 勾选「允许本机上的其他应用程序与 Zotero 通信」。

兼容性说明：读取类工具（检索/条目/全文/附件路径/笔记读取/批注读取）在 Zotero 9 / 10.0.7 上全部实测通过。写入（笔记 create/append/update/delete、PDF 高亮）在 Zotero 7+ 上可用，但必须先完成一次「本地 API 授权」：早期判断「本地 API 只读」是不准确的，实际只是写请求缺 Zotero-Server-ID 与 Zotero-API-Key 两个头，详见下节。

写入授权（Zotero 7+ / 9 / 10）

Zotero 本地 API 的 GET 读取无认证；POST / PATCH / PUT / DELETE 写请求必须同时带：

1. Zotero-Server-ID：每个响应头都会返回，插件自动缓存并在写请求里回传（缺失 → 428，不匹配 → 412）；
2. Zotero-API-Key：通过 POST /api/local/authorize 获取。调用 zotero_authorize 工具后，Zotero 桌面端会弹出「本地 API 授权」窗口：
   • 点 「始终允许 / Always Allow」 → 持久密钥写入 <profile>/localAPIKeys.json，插件以后自动读取，一劳永逸；
   • 点 「允许 / Allow」 → 一次性密钥，首次成功写入后即被消费，下次写会返回 401，需重新授权。

也可以把密钥直接填进插件配置 localApiKey（或 cordis.patch.yml）。授权弹窗需要人工点击，zotero_authorize 会等待最多 120 秒（authorizeTimeoutMs 可调）。

写回能力：

• zotero_note：create / append / update / delete 子笔记（POST /items、PATCH /items/<key>、DELETE /items/<key>）；
• zotero_highlight：在某个 PDF 附件下新建高亮批注（annotation item，POST /items），带页码、印刷页码标签、颜色、选中文字与坐标。
• zotero_annotation_comment：修改已有 PDF 高亮的批注评论（annotationComment）；传空字符串可清空评论。

工具一览

工具	作用
zotero_collections	列出文献库的所有分类（collectionKey + 条目数），用于限定检索范围
zotero_search	按关键词检索文献库（标题/作者/年份），支持条目类型、分类、标签、年份区间（sinceYear/beforeYear）、排序、分页；mode 控制返回粒度省 token
zotero_recent	列出最近添加的条目（"我刚导入的文献"场景）
zotero_item	按 key 读取条目详情：作者、期刊、DOI、摘要、标签、附件列表
zotero_fulltext	读条目全文纯文本：优先读 Zotero 全文缓存（.zotero-ft-cache，零下载），无缓存时现场解析本地 PDF（pdfjs-dist，约 0.3s）并写缓存；仅远程链接附件才下载到工作区
zotero_attachment_path	返回附件在 storage 的原始绝对路径，让 read 工具零拷贝直读
zotero_download	把条目的 PDF 附件下载到会话工作区（默认），供模型用 read 工具阅读
zotero_notes	列出某条目的子笔记，或全库按关键词搜笔记正文
zotero_note	笔记写入：create 新增 / append 追加 / update 更新 / delete 删除。需先完成写入授权
zotero_authorize	触发 Zotero「本地 API 授权」弹窗获取写密钥；已有持久 key 时直接报告、不重复弹窗
zotero_highlight	把 PDF 高亮（annotation item）写回指定附件：选中文字、页码、印刷页码标签、颜色、坐标
zotero_annotation_comment	修改已有 PDF 高亮的批注评论（annotationComment），空字符串清空
zotero_export	把条目导出为引用格式：BibTeX / RIS / CSL JSON（逐 key 抓取后拼接，最多 25 条/次），可直接贴进 .bib/.ris 或引用管理器
zotero_annotations	读取条目附件上的 PDF 批注（高亮、批注笔记），带 PDF 页码、文中页码标签、引文和你的评论；自动翻页拉全（实测有附件挂 1000+ 条批注）
zotero_browse	列出库内用户标签（可喂给 zotero_search 的 tag 参数）和保存的智能搜索
zotero_retrieve	段落级检索：在条目的全文+笔记+批注里按 query 打分（BM25 风格 tf-idf，中英文分词），返回 Top-K 最相关段落，带页码锚点，适合精确引用和"这篇哪里说了 X"
zotero_digest	一次打包条目简报：完整元数据 + 摘要 + BibTeX 引用 + 附件列表 + 与 query 最相关的段落（缺省用标题词），"总结这篇论文"的首选入口

示例对话：

在我的 Zotero 里搜一下 transformer 相关的论文，挑 2020 年以后的，把第一篇的全文读一遍，给我写个摘要存进笔记。

安装

方式一：GUI 插件管理器（桌面版 44.x）——设置 → 插件 → 安装，填入仓库地址：

github:Hongcheng-LI/dsh-zotero

方式二：CLI（web / desktop profile 均可）：

dsh plugin add github:Hongcheng-LI/dsh-zotero           # 当前 profile
dsh plugin --profile web add github:Hongcheng-LI/dsh-zotero

装好后重启 DSH。仓库自带预构建的 lib/，且不声明任何生命周期脚本——pnpm 10 对声明 prepare 的 git 依赖会直接拒装（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED），本插件零脚本、免白名单直装；插件自带空配置，不会弄崩启动；Zotero 未运行时工具会返回明确的连接提示。

配置（可选）

默认配置即可用（本地库、端口 23119）。插件导出了 schemastery Config schema：

• GUI：插件管理器 → dsh-zotero → 配置，直接用表单改（中英双语描述）；
• cordis.patch.yml：在你的 profile（$DSH_HOME/profiles/<name>/）里覆盖 tool-zotero 行，然后重启：

- id: tool-zotero
  config:
    baseUrl: http://127.0.0.1:23119   # Zotero 本地 API 地址
    library: user                      # user（我的文献库）或 group:<群组ID>
    downloadDir: D:/papers             # 附件下载目录，缺省存到会话工作区
    dataDir: D:/ZoteroData             # Zotero 数据目录（含 profiles.ini），默认自动探测
    storageDir: .../zotero/storage     # 直接指定 storage 目录（zotero_fulltext / attachment_path 用）
    maxAttachmentBytes: 67108864       # 单附件下载上限，默认 64MB
    maxFulltextChars: 80000            # zotero_fulltext 返回的最大字符数，默认 80000
    maxLimit: 50                       # 检索结果条数上限，默认 50
    timeoutMs: 15000                   # 本地 API 超时（毫秒）
    localApiKey: ''                    # 本地 API 写密钥；留空自动读 Zotero「始终允许」保存的持久 key
    authorizeTimeoutMs: 120000         # 等待授权弹窗的超时（毫秒）

非法配置（比如 library: abc）会在加载期被 Config schema 拒绝并明确报错，而不是等到调用才失败。

全文与附件路径：插件通过本地 API /file 端点的 302 重定向拿到附件的真实磁盘路径（自定义数据目录也能自动识别，无需配置），全文优先读 Zotero 自己维护的 .zotero-ft-cache 缓存（与附件同目录）。dataDir/storageDir 配置仅在重定向不可用时作为兜底。

开发

npm install
npm test           # 构建单元测试（离线，不需要 Zotero）
npm run audit      # 运行时审计：清单 / patch / 构建产物 / locale / 兼容门禁
npm run test:smoke # 真实环境冒烟测试：对本机 Zotero 完整跑一遍工具链

运行时契约测试（可选但推荐）：test/registry-contract.test.mjs 会用真实的 DSH 工具注册表注册全部 17 个工具，并跑一遍 execute → output schema 校验 → render 管线（mock 的 Zotero 本地 API，离线可跑）。@deepseek-ai/dsh-tools 刻意不出现在 package.json（插件对 DSH 零运行时依赖），想跑契约测试时装一份与目标运行时一致的版本即可，不装则自动跳过：

npm install --no-save @deepseek-ai/dsh-tools@0.2.0-rc.2
npm test

lib/ 是入库的，且没有 prepare 脚本：DSH 的插件安装走 pnpm，pnpm 10 对声明了 prepare 的 git 依赖会硬性拒装（不是静默跳过），所以构建产物必须入库、生命周期脚本必须为空。改动 src/ 后先 npm run build，把刷新后的 lib/ 一起提交。

结构遵循 DSH 插件规范（0.2.0-rc.x）：package.json 的 dsh.bundle.patch 声明、cordis.patch.yml 运行时注入行、schemastery Config 配置 schema、locale/ 插件管理器元信息、src/ 源码、lib/ 构建产物。

---

Zotero tools for DeepSeek Harness: search your library, read item metadata and abstracts, list collections and PDF attachments, read full text, download PDFs into the session workspace, write back child notes and PDF highlights — all through the Zotero local API. Reads need no key; writes need a one-time local authorization (zotero_authorize, choose "Always Allow" in the Zotero dialog).

Compatibility: updated for the DSH 0.2.0-rc.x plugin contract (desktop 44.x core) — schemastery Config (validated config + settings form), locale/ metadata for the plugin manager, prebuilt lib/ shipped in-repo (pnpm 10 blocks dependency build scripts), dsh.plugin.json removed per the current spec. The plugin declares no @deepseek-ai/dsh-* peers, so it passes the version-compatibility gate on every DSH release; a contract test runs every tool through the real @deepseek-ai/dsh-tools registry.

Requires Zotero 7+ (tested on 9.0.6 / Windows) running locally with "Allow other applications on this computer" enabled in Settings → Advanced.

Tool	What it does
zotero_collections	List library collections with keys and counts
zotero_search	Quick-search items; filters by type, collection, tag, year range; sort/pagination; mode controls verbosity
zotero_recent	Recently added items
zotero_item	Full metadata of one item plus attachment keys
zotero_fulltext	Full text as plain text (Zotero fulltext cache first, PDF download fallback)
zotero_attachment_path	On-disk path of a stored attachment (zero-copy read)
zotero_download	Download an attachment (PDF) to the workspace
zotero_notes	List an item's child notes or search notes library-wide
zotero_note	Create / append / update / delete child notes (needs write authorization)
zotero_authorize	Obtain a local API write key via Zotero's authorization dialog; reports an existing persistent key without re-prompting
zotero_highlight	Write a PDF highlight (annotation item) back under an attachment, with text, page, printed page label, color and rects
zotero_annotation_comment	Update an existing PDF highlight's annotation comment (annotationComment); empty string clears it
zotero_export	Export items as BibTeX / RIS / CSL JSON (keys fetched one by one, up to 25 per call)
zotero_annotations	Read PDF annotations on an item's attachments: highlight text, your comments, PDF page numbers and printed page labels (auto-paginates past 100)
zotero_browse	List user tags (feed them to zotero_search's tag) and saved searches
zotero_retrieve	Passage-level retrieval: rank the item's full text + notes + annotations against a query (tf-idf, mixed Latin/CJK), top-K passages with page anchors
zotero_digest	One-shot briefing: metadata + abstract + BibTeX citation + attachments + top query-relevant passages (defaults to title-derived query)

Install: dsh plugin add github:Hongcheng-LI/dsh-zotero (or via the desktop plugin manager), then restart DSH. For write tools, run zotero_authorize once and pick "Always Allow" in Zotero's dialog. Optional config (baseUrl, library, downloadDir, maxAttachmentBytes, maxLimit, timeoutMs, localApiKey, authorizeTimeoutMs, …) is available both as a settings form (schemastery Config) and under the tool-zotero row of your profile's cordis.patch.yml.

Development: npm install && npm test (offline unit tests), npm run audit (runtime audit), npm run test:smoke (live Zotero). Opt-in contract test against the real DSH registry: npm install --no-save @deepseek-ai/dsh-tools@0.2.0-rc.2 && npm test. lib/ is committed on purpose and the package declares no lifecycle scripts — pnpm 10 hard-fails git installs of packages that declare prepare (ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED).

License

MIT