dsh-zotero
English | 中文
中文
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 负责链接）；包发布后此步骤可删。
致谢
License
MIT
