zotero-harvest — Zotero 文献采集入库插件（DSH external plugin）

zotero-harvest 把"检索文献 → 判断够不够 → 存进本地 Zotero → 让 zotero-wave-rag 能检索到"这条链路做成 6 个纯确定性工具（无 LLM 依赖），机制取自 AgentLaboratory / STORM / PaperQA / Anaxa：

• 检索原语化（AgentLab）：lit_fetch 一次取多源结果
• 高精度命中 + 下载链接（参考 paper-qa 的 OpenAlex/Crossref/Unpaywall 客户端设计）：
  • query 传 DOI 或 arXiv id 直接精确定位该文献（OpenAlex doi: 过滤 / arXiv id_list / Crossref DOI）
  • 每篇结果解析 OA 下载链接：arXiv/Europe PMC/OpenAlex 直链 + Unpaywall（DOI→最佳 OA PDF + 全部 OA 位置）
  • open_access_only 过滤、sort_by: relevance|citations
• 充分性判定 = 配额 + 覆盖审计（Anaxa + AgentLab）：lit_sufficiency_check
• 缺口显式化（STORM）：审计输出 gaps + 由缺口推导下一轮查询
• 循环驱动 + 预算上限（AgentLab）：lit_review_run 凑够配额或预算耗尽即停
• 入库：Zotero 本地 API（桌面运行）→ 离线 sqlite 直写（桌面关闭）→ inbox（RIS/BibTeX+PDF）
• 与 RAG 打通：入库后触发 zotero-wave-rag 增量重建，zotero_search 立即可检索新文献

数据源（全部免费 API，实测可达）

工具

配置

优先级：运行时配置文件 > 环境变量 > 默认值。

• 运行时配置 ~/.config/lit-harvest/config.json： {"dataDir": "/path/to/zotero", "minCorePapers": 5, "minTotalPapers": 10, "maxRounds": 3, "autoReindex": true}
• 环境变量：LIT_DATA_DIR、LIT_INBOX_DIR、LIT_MIN_CORE、LIT_MIN_TOTAL、LIT_MAX_ROUNDS、 LIT_AUTO_REINDEX、LIT_S2_API_KEY、LIT_UNPAYWALL_EMAIL（默认 lit-harvest@users.noreply.github.com）、 LIT_RESOLVE_DOWNLOADS、LIT_SCHOLAR_PROXY（可选 scholar 源的 HTTP 代理，如 http://<proxy-host>:7890）、LIT_ZWR_DIR
• Zotero 数据目录与 zotero-wave-rag 共享：优先读 ZWR_DATA_DIR / ~/.config/zotero-wave-rag/config.json 的 dataDir（本机即 <zotero-data-dir>，如 Windows 侧的 C:\Users\<user>\Zotero）， 无需额外配置即可入库真实库。

保存模式

• zotero-api：Zotero 桌面运行时走本地 HTTP API（127.0.0.1:23119），创建条目 + 上传 PDF 附件
• sqlite：桌面未运行时直接写 zotero.sqlite（仅当 Zotero 未运行；introspection 驱动插入， 兼容真实 Zotero 6/7 schema；DOI/标题去重，从不更新/删除已有行，单事务提交）
• inbox：不可写时落 ~/.local/share/lit-harvest/inbox/<slug>/（paper.json + citation.ris + citation.bib + paper.pdf），可用 Zotero 的"文件→导入"收编
• auto：探测本地 API → 不可达且有库 → sqlite → 否则 inbox

构建与测试

# 构建（用 DSH checkout 的 tsc）
<dsh-checkout>/node_modules/.bin/tsc -p tsconfig.json

# 冒烟：5 工具注册 + 真实 API 调用 + 入库 inbox
node tests/smoke.mjs

# 端到端：空测试库 → review 采集 → sqlite 入库 → zotero-wave-rag 重建 → BM25 可检索
node tests/e2e.mjs

# 真实 Zotero schema 兼容性（在副本上验证写入/去重/附件/RAG 读回）
# 先 cp 真实库到 /tmp/lit-real-test/zotero/ 再运行（路径可改，见脚本内 DB/STORAGE）：
#   node tests/real-lib-check.mjs

挂载

dshx install zotero-harvest <plugin-dir>   # 需要用户确认启用

注意：node_modules/@deepseek-ai/dsh-tools 是指向 DSH checkout 的符号链接（构建期类型 + 运行期解析）， staging 轮转后若失效，重建一次 ln -sfn <dsh-checkout>/packages/core/tools node_modules/@deepseek-ai/dsh-tools。

License

MIT © 2026 — 本插件为个人研究工具，无外部依赖分发（运行时仅依赖 DSH 宿主提供的 @deepseek-ai/dsh-tools），数据源均为公开免费 API（OpenAlex / arXiv / Crossref / Europe PMC / Unpaywall / Semantic Scholar）。