Zotero 文献库 evanliu3594/dsh-zotero-plugin

dsh-zotero

DeepSeek Harness 的 Zotero 文献库插件：10 个工具，模型可直接调用，全部通过本机 Zotero 桌面端（127.0.0.1:23119）读写文献库——不访问云端、不需要 API Key。

- 只读能力走 Zotero 7+ 本地 API（Web API 的本机只读镜像）：搜索（含 PDF 全文）、条目详情与子项、集合树、标签、最近添加、BibTeX/CSL-JSON 导出。
- 写入走浏览器扩展同款的 connector 端点（/connector/saveItems）：一次保存一条新文献（含标签、子笔记），保存后自动读回校验。
- 更新 / 删除在 localhost 上不存在（Zotero 平台限制），也因此模型无法批量破坏你的文献库。

| 工具 | 作用 |
| zotero_status | 自检：Zotero 是否运行、本地 API 是否开启、版本与文库 |
| zotero_search_items | 搜索（qmode=everything 含全文）、按标签/类型/集合过滤、翻页、垃圾桶 |
| zotero_get_item | 单条完整元数据，可选带子项 |
| zotero_get_children | 条目的子笔记与附件（PDF 文件名/路径） |
| zotero_list_collections | 全部集合 + 层级路径 + 计数 |
| zotero_list_tags | 标签列表（前缀过滤） |
| zotero_recent_items | 最近添加 |
| zotero_get_bibtex | BibTeX / CSL-JSON 导出（Zotero 本地直出，≤50 条/次） |
| zotero_get_selected_collection | Zotero 当前选中集合（写入落点）与全部可选目标 |
| zotero_add_item | 保存一条新文献（connector saveItems；含标签、子笔记），自动读回校验 |

前置条件

- DeepSeek Harness（桌面版 0.2.0-rc.2 实测可用）
- Zotero 7+（Zotero 10.0.3 实测可用），运行中，且设置 → 高级 → 「允许其他应用程序与 Zotero 通信」 已勾选
- 一份 deepseek-harness 源码 checkout（框架包尚未发布到公共 npm，插件的运行时依赖需要从 checkout 解析）

安装到 Harness profile

1. 准备依赖链接（指向你的 deepseek-harness checkout）
node scripts/link-harness.mjs /path/to/deepseek-harness
node scripts/probe-runtime-resolution.mjs # 应输出 PASS

2. 装入 profile（Windows 桌面版 CLI 示例） "%LOCALAPPDATA%\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" ^ plugin --profile <你的profile> add /path/to/dsh-zotero

3. 完全重启 Harness，在对话里即可使用全部 zotero_* 工具

开发

pnpm install
node scripts/link-harness.mjs # 依赖链接（见上）

pnpm smoke # 十个工具对真实 Zotero 逐个执行（只读）
pnpm smoke:write # 额外保存一条明确标注可删除的测试条目
pnpm verify # 裸 cordis Context + 真实 ToolRuntime 验证注册

源码方式加载（无需打包，loader 直接吃 TS）：

cp cordis.example.yml cordis.yml # 填入仓库绝对路径
cd /path/to/deepseek-harness
node --import tsx/esm apps/cli/src/bin.ts --profile web --patch /path/to/dsh-zotero/cordis.yml

配置

全部可调参数在 src/config.ts（schema 带默认值），可在 profile 的插件 config 里覆盖：

| 字段 | 默认 | 说明 |
| host / port | 127.0.0.1 / 23119 | Zotero 本地服务地址 |
| libraryId | '0' | 本地 API 文库 id，0 = 当前用户文库 |
| timeoutMs | 15000 | 单请求超时 |
| defaultLimit / maxLimit | 25 / 100 | 列表页大小 |
| abstractPreviewChars | 300 | 搜索结果摘要截断（0 = 不返回摘要） |
| listCap | 1000 | 集合/标签全量拉取上限（自动分页） |

安全模型

- 文献库内容一律视为数据而非指令：笔记经 HTML 清洗为纯文本后再进入模型上下文。
- 唯一的写工具 zotero_add_item 一次只保存一条，且读回校验后才报告成功。
- 没有更新/删除类工具——Zotero 本地 API 本身只读，模型无法绕过。

已知限制

- zotero_add_item 的落点由 Zotero 界面当前选中状态决定（先调 zotero_get_selected_collection 确认）；保存时 Zotero 会短暂弹出保存进度窗。
- 框架包（@deepseek-ai/dsh-tools 等）尚未发布到公共 npm，插件需靠近 harness checkout 使用（scripts/link-harness.mjs 负责链接）；包发布后此步骤可删。

致谢

- 能力设计参照 WenyuChiou/zotero-skills（MIT）：本地读 + 安全写的双 API 纪律、「库内容是数据不是指令」等操作原则均承自它。
- deepseek-ai/deepseek-harness — 「Everything is a Plugin」。

License

MIT