前言¶
在 DSH 里做文献相关对话时，模型本身拿不到你 Zotero 里的条目、附件索引和当前选中的分类。常见做法是手动复制标题、DOI 或 BibTeX，或另开脚本调 Zotero 本地 API，再把结果贴回对话。dsh-zotero 把搜索、读索引全文、导入 RIS/BibTeX、导出参考文献和插入引用收进 DSH 的 zotero 技能，通过本机 HTTP 连正在运行的 Zotero Desktop，不依赖云端 Zotero Key，也不额外起一个 MCP 服务。
下面按「是什么 → 能做什么 → 怎么装 → 怎么用 → 注意点」说明。事实以仓库 README 与 package.json 为准；社区目录页见文末链接。
这是什么¶
dsh-zotero（npm 包名 dsh-zotero，当前发布版本 0.2.0）由维护者 chanhaoxian5-ship-it 发布，在 DeepSeek Harness 中注册 zotero 技能。它在 OpenAI Zotero plugin 0.1.2 之上做 DSH 适配，保留原插件与原始 Python 脚本，并按 DSH 官方 bundle 格式分发。
在 SkillHub 等社区目录中，该插件归类为「记忆」——含义是：对话可以基于你本机已索引的文库与附件文本，而不是每次从零粘贴摘要。
环境要求¶
安装前确认下列条件（README 原文）：
- DSH 版本
>=0.2.1-rc.5且<0.3.0，profile 中需启用skills服务。 - Node.js
>=22，Python>=3.10。 - Zotero Desktop 正在运行，本地 API 已启用；默认地址为
http://127.0.0.1:23119。
README 记载的实际验证环境为 Windows、DSH 0.2.1-rc.5、Zotero 10.0.6。适配层在 Windows/Linux CI 中通过；macOS 与实际模型对话调用尚未验收。
可选环境变量：
ZOTERO_LOCAL_BASE_URL：修改本地 API 地址。ZOTERO_PYTHON：指定 Python 解释器路径（不要附加参数）；未设置时优先 DSH 自带 Python，再尝试 PATH 上的 Python。ZOTERO_DSH_STATE_DIR：导入状态目录，默认~/.dsh/state/dsh-zotero。
核心功能¶
以下能力均来自 README，未在资料中出现的功能不写。
搜索与浏览
- 在 personal 或指定群组文库中搜索；0.2.0 适配层修复了原脚本 DOI 搜索漏命中，搜索会完整分页读取文库并返回 DOI 和分类 key。
- 通过 Zotero 文本索引读取附件正文；图表、扫描件和版式仍可能需要 PDF 阅读工具。插件不内置外部 DOI 元数据解析、全文或补充材料下载器。
导入与导出
- 导入 RIS；BibTeX 若含宏、字符串拼接、指令或标题内 TeX 命令，文档要求改用字面值 BibTeX 或 RIS。
- 导出参考文献（例如对话中要求生成
references.bib）。 - 安全导入目前只支持个人文库；群组场景的搜索、inventory 和 duplicates 可显式指定
--library groups/数字ID。
导入可靠性（CLI）
除对话示例外，仓库提供 run-zotero.mjs 子命令做计划导入、执行导入、查状态和查重复，详见下文「导入可靠性」一节。
组成概要
| 组件 | 作用 |
|---|---|
index.mjs |
DSH 原生技能提供器，注册 zotero |
skills/zotero/scripts/zotero_dsh.py |
完整扫描、身份核对、导入记录、并发锁和回读验证 |
skills/zotero/scripts/zotero.py |
原始 Zotero API / Connector 脚本 |
读取与导入经本机 HTTP 完成；送入模型的文本仍由所选模型服务处理。插件以当前 DSH 进程权限运行，安装前应自行查看源码与 MIT 许可证（见仓库 LICENSE、NOTICE.md）。
安装与启用¶
先在终端执行官方安装命令（只在你准备好安装时运行）：
dsh plugin --profile desktop add 'github:chanhaoxian5-ship-it/dsh-zotero#v0.2.0'
DSH 会根据包内 dsh.bundle 声明维护 profile 的依赖与 bundles，无需手工改 profile，也无需把 skill 复制到全局目录。插件直接分发可运行的 .mjs 和 .py，没有安装构建脚本。本项目目前未发布到 npm。
查看组合配置是否已包含该插件：
dsh --profile desktop --dump-config
确认输出中出现 dsh-zotero 后，重新启动 DSH。若 dsh 不在 PATH，可使用桌面安装目录下的 resources/runtime/cli/bin/dsh.cmd。若 profile 里其他插件有版本兼容性错误，须先处理；这与 Zotero 本地 API 是否可连是两项独立检查。
也可从 GitHub Releases 下载 .tgz，再执行：
dsh plugin --profile desktop add 'D:/下载目录/dsh-zotero-0.2.0.tgz'
需要不可变来源时，用发布提交的完整 SHA 替代 #v0.2.0。
卸载：
dsh plugin --profile desktop remove dsh-zotero
典型用法¶
安装并重启后，在新对话中可以用自然语言触发技能。README 示例：
用 zotero 技能搜索我的文库中关于 retron 的论文。
更多可复现表述：
- 「用 zotero 搜索 cross-species retron，列出标题、年份和条目 key。」
- 「读取这篇论文的 PDF 正文，先检查附件和索引覆盖情况。」
- 「把这条已核对的 RIS 文献加入 Zotero 当前分类，先检查是否重复。」
- 「把选中的文献导出成 references.bib。」
连接 Zotero 后，可用 CLI 做快速检查（需 Zotero 已启动）：
node skills/zotero/scripts/run-zotero.mjs status --json
node skills/zotero/scripts/run-zotero.mjs search 'cross-species retron' --json
路径相对于插件安装后的 skill 目录；在已安装环境中通常由 DSH 解析，开发时可于仓库根目录对照 README 执行。
导入可靠性¶
大批量或脚本化导入时，README 推荐先 plan 再 import，并用 status 核对，避免盲目重发：
node skills/zotero/scripts/run-zotero.mjs plan-import --format ris --file 'D:/论文/paper.ris'
node skills/zotero/scripts/run-zotero.mjs import-ris --file 'D:/论文/paper.ris' --yes
node skills/zotero/scripts/run-zotero.mjs import-status
node skills/zotero/scripts/run-zotero.mjs duplicates
文档说明的要点：
- 全文库按规范化 DOI 去重；已有条目在其他分类也会跳过；批次内同 DOI 重复也会跳过。
- 仅同标题或 DOI 冲突的条目暂停核查，避免误合并预印本与正式版。
- 读失败、分页不完整、文库版本变化或目标分类切换时会停止；不会把读失败当作「文库里没有」。
- 导入前记录 pending，并发进程加锁；响应成功后仍回读新 key 才报告成功。
- 超时、客户端中断或部分导入后会阻止盲目重发；
import-status只核对结果，不再次发送。
安全导入写入个人文库当前选中的分类；操作前应确认目标分类，过程中避免在 Zotero UI 里切换分类。已有条目的分类不会自动改变，已有副本也不会自动合并或删除。锁只协调同一本地 API 地址与同一状态目录下的本插件进程，无法阻止其他软件或原生 UI 同时导入。升级插件时保留状态目录；待核查结果不能靠改 session 或清记录自动重试。更细说明见仓库内 skills/zotero/references/import-reliability.md 与 docs/import-hardening.md。
适用场景与注意¶
适合谁
- 已在日常使用 Zotero Desktop，并开启本地 API 的研究者或开发者。
- 希望在 DSH 对话里直接搜文库、读已索引全文、导入 RIS、导出 BibTeX，而不想每次手工复制元数据的人。
需要注意
- DSH 生态理念是「一切皆插件」；SkillHub 等目录是社区站点，与 DeepSeek / 幻方无官方从属关系，不要把它当成官方应用商店。
- 插件不替代 Zotero 本身的 PDF 阅读与附件管理；索引缺失时全文能力会受限。
- 安装即信任维护者代码在本机进程内执行；请阅读 GitHub 源码与许可证后再安装。
结尾¶
dsh-zotero 把 Zotero Desktop 的搜索、索引全文、导入导出接到 DSH 的 zotero 技能上，适合在本机已有文库的前提下做文献向对话。安装命令、版本约束与导入行为以仓库 README 为准。
- 社区目录页：https://www.skillhub.cn/plugins/chanhaoxian5-ship-it/dsh-zotero
- 源码与文档：https://github.com/chanhaoxian5-ship-it/dsh-zotero
