前言¶
做文献相关的智能体或工作流时，常见做法是手工导出 BibTeX、把 PDF 丢进向量库，或写一层脚本去读某个固定目录。Zotero 里往往已经积了题录、标签、合集、PDF 高亮和笔记，但和 DSH 对话面之间缺少一条稳定、可写的桥。若只希望在本机现有库上搜索、改元数据、批量按 DOI 入库，并把注释与全文索引交给模型上下文，就需要一个直接走 Zotero 本地 HTTP API 的 bundle。dsh-zotero（维护者 kuangdang123，社区分类为「记忆」）做的就是这件事：不依赖 zotero.org 同步，也不在 Zotero 里再装扩展，前提是本机 Zotero 已开启本地 API 并完成写权限授权。
这是什么¶
dsh-zotero 是 DeepSeek Harness 的 bundle，通过 Zotero 自带的 http://127.0.0.1:23119/api/ 与本机个人库通信。插件提供多组工具：体检与搜索、单条/批量读取、笔记与批注、已索引全文、按标识符或外部检索入库、附件上传、条目与合集增删改，以及按 DOI 从 OpenAlex 等源做相关论文发现。简介与 README 一致概括：search and edit items，bulk-import by DOI/arXiv/PMID/ISBN/URL，read PDF annotations、notes and indexed full text。
Zotero 7 的本地 API 曾主要为只读；写入能力在较新版本才完善。README 写明在本机 Zotero 10.0.7 上已验证读写可用。引擎要求为 Node >=20.11、DSH >=0.2.0；当前发布标签最新为 v0.1.3，许可证 MIT。源码仓库：https://github.com/kuangdang123/dsh-zotero。
核心功能¶
下面按 README 工具表归纳能力，智能体按需调用即可。
库内检索与读取
zotero_status：检查接口是否可用、是否有写 key、库规模等，排障时先调它。zotero_search：按标题、作者、年份或任意字段搜索，可按类型、标签、合集、回收站过滤；默认只列顶层条目，避免附件与批注刷屏。zotero_get：读一条或多条元数据，可选笔记正文、批注、全文、BibTeX 与子条目。
精读与全文
zotero_annotations：按阅读顺序读出某篇论文 PDF 上的高亮、下划线、批注（含引文、页码、颜色），并附该论文下的笔记。zotero_fulltext：读 Zotero 已为 PDF 建立的文本索引，支持分页（offset/maxChars）和短语跳转（find）。
写入与结构
zotero_note：笔记条目的 create / append / get / list / delete；正文可用 Markdown，由插件转成 Zotero 笔记 HTML。zotero_add：按 DOI、arXiv、PMID、ISBN、URL 抓元数据入库，或传入 item JSON / 课题检索结果；可指定合集、标签、dryRun预览。zotero_attach：把本机 PDF/EPUB/TXT 上传为指定条目的附件；上传后可触发索引队列，必要时wait: true等待索引完成。zotero_update/zotero_delete：改字段与标签、进出回收站或合集；永久删除需permanent: true且confirm: true。zotero_collections：合集 list / tree / get / create / rename / delete。zotero_find：外部多源检索，或按 DOI 从 OpenAlex 取相关工作、参考文献、被引，用于扩检后配合zotero_add。
边界（README 第六节）：仅连本地 127.0.0.1:23119，仅操作用户库 userID 0；不代为下载网络 PDF；zotero_fulltext 依赖 Zotero 已有索引，未索引时返回提示；批注只在 Zotero 内创建，插件只读不回写批注。
安装与启用¶
安装 bundle¶
README 给出三种方式，任选其一。
- 从 GitHub 装（推荐）：把仓库地址交给
plugin_manager install_bundle：
git+https://github.com/kuangdang123/dsh-zotero.git
也可将已下载的仓库根目录绝对路径传给 install_bundle（开发时装成 link，改代码后禁用/启用插件重载）。
- 从插件市场索引装：在 DSH「插件 → 发现」里添加索引地址：
https://raw.githubusercontent.com/kuangdang123/dsh-zotero/main/market/index.json
该文件由 npm run index 生成，每个版本固定到具体 commit，然后在界面点安装。
- 本地 bundle 开发：仓库根目录即 bundle，对
plugin_manager install_bundle传入本目录绝对路径即可。
安装后无需重启 Zotero，但要完成下一节的 API 与写权限设置，否则工具会报 NOT USABLE 或 403。
开启 Zotero 本地 API（一次性）¶
- 打开 Zotero → 设置（Preferences）→ 高级（Advanced）。
- 勾选 「允许此计算机上的其他应用程序与 Zotero 通讯」（英文：Allow other applications on this computer to communicate with Zotero）。
- 同一面板应出现 「可用于 http://127.0.0.1:23119/api/」；有该行即表示接口已开。
- 读操作立即可用；写操作首次调用时 Zotero 会弹出授权框。
写权限¶
第一次调用会写库的工具时，在对话框中选择 「始终允许」（Remember）可避免每次都弹框。key 保存在 profile 下：
$DSH_PROFILE_DIR/plugin-data/dsh-zotero/auth.json
撤销可在 Zotero 高级面板「清除写入授权」，或删除该文件。
可选配置¶
在 profile 的 cordis.patch.yml 里可为插件传 config；不传则用默认值。
| 键 | 默认 | 说明 |
|---|---|---|
baseUrl |
http://127.0.0.1:23119/api |
本地 API 根地址 |
userId |
0 |
用户库 id |
timeoutMs |
20000 |
单次 HTTP 超时（≥1000） |
authFile |
上述 auth.json 路径 |
写权限 key 落盘位置 |
典型用法¶
以下示例来自 README，参数可按会话需要调整。
精读一篇论文
zotero_search { "query": "retrieval augmented generation" }
zotero_annotations { "key": "ABCD1234" }
zotero_fulltext { "key": "ABCD1234", "find": "limitations" }
zotero_get { "key": "ABCD1234", "notes": true }
一批 DOI 入库并归到合集
zotero_add {
"identifiers": ["10.1145/3292500", "arXiv:2101.00001", "978-3-16-148410-0"],
"collection": "待读",
"tags": ["2026-11"],
"dryRun": true
}
确认预览无误后去掉 dryRun: true 再执行。
按课题批量找论文并入库
zotero_find { "query": "graph neural networks for molecular property prediction", "limit": 10 }
zotero_add { "search": "graph neural networks for molecular property prediction", "limit": 5, "collection": "GNN" }
按 DOI 扩检相关文献
zotero_find { "related_to": "10.1145/3292500" }
边读边写回笔记
zotero_note { "action": "create", "item": "ABCD1234", "content": "## 核心贡献\n- ...\n\n## 疑问\n- ..." }
zotero_note { "action": "append", "note": "NOTE5678", "content": "补一段实验对比。" }
适用场景与注意¶
适合谁
- 已在 Zotero 维护个人文献库，希望 DSH 智能体直接查库、改标签与合集、按 DOI 批量入库，并把 PDF 批注与索引全文纳入上下文的人。
- 需要把「本地精读痕迹」和「外部 OpenAlex 扩检」放在同一套工具里的工作流，而不是重复维护第二份书目。
使用注意
- 插件以当前 DSH 进程权限运行，安装前应自行查看仓库源码与 MIT 许可证，确认与本机安全策略一致。
- 只连本机 Zotero，不替代云端同步；群组库不在支持范围内。
- 外部检索无 OpenAlex key 时共享每日额度，大规模批量检索宜自行配置 key（插件不强制）。
- 常见排障：403 /
NOT USABLE多为未开本地 API；zotero_annotations为空可能是无 PDF 或未导入批注；全文「未索引」可在 Zotero 中对附件重建索引，或zotero_attach使用wait: true。
DSH 生态强调「一切皆插件」；社区目录（如 SkillHub）与 DeepSeek / 幻方无官方从属关系，安装来源以你信任的索引或 GitHub 仓库为准。
结尾¶
dsh-zotero 把 Zotero 本地 API 封装成一组可编排工具，让 Harness 侧能搜索、编辑、批量入库，并读取 PDF 批注、笔记与已索引正文，适合把既有文献库当作智能体的长期记忆面。目录页：https://www.skillhub.cn/plugins/kuangdang123/dsh-zotero；源码与版本说明：https://github.com/kuangdang123/dsh-zotero。
