English · 中文

让 Agent 从你的 Zotero 文献库中发现来源、提取与问题相关的证据，并始终保留证据与原始文献之间的联系。

dsh-zotero 面向 Agent 的研究工作流设计：从文献检索、元数据与笔记查看，到证据检索、原文打开和引用生成，Agent 可以根据当前任务逐步获取所需信息，而不必一次读取整篇文献或整个文献库。

工具

使用示例

Agent 按需求逐层深入，一段典型对话：

用户：「帮我找 FlashAttention 相关论文」 Agent → zotero_search，返回候选条目与 ref。

用户：「第一篇是什么？我以前读过吗？」 Agent → zotero_get：元数据、17 条批注、2 条笔记与有限预览。

用户：「我当时对 evaluation 有什么意见？」 Agent → zotero_retrieve(query:"evaluation", sources:["annotations","notes"])，返回相关笔记与批注证据。

用户：「论文自己怎么解释 memory efficiency？」 Agent → zotero_retrieve(query:"memory efficiency", sources:["fulltext","abstract"])，返回摘要与全文片段。

用户：「我要看原 PDF」 Agent → zotero_attachment(条目 ref)，返回已验证的文件路径；若当前 Harness 配置了 PDF/file 读取能力，再交给该能力继续分析。

用户：「把这三篇生成 APA 参考文献表」 Agent → zotero_export(format:"bibliography", style:"apa")。

命令

/zotero status 报告连通性、API/schema 版本和数据库身份标识（Server ID，Zotero 10+）。这是唯一的健康检查。普通调用失败时返回带类型的领域错误。

环境要求

• 已安装 Zotero 桌面版，并启用本地 API：设置 → 高级 → “Allow other applications on this computer to communicate with Zotero”。
• 本地 API 为无认证读取，地址为 http://127.0.0.1:23119/api。V1 没有任何修改文献库数据（条目、笔记、标签、分类等）的路径。
• Zotero ≥ 7，本地 API 版本为 3。如果 status 命令报告版本不匹配，请升级。
• Node.js ≥ 22.19（或 24+）；宿主 dsh 运行时为 rc.7 系。运行时依赖（peer）见 package.json 的 peerDependencies（@deepseek-ai/cordis ≥ 4、dsh-tools、dsh-llm、dsh-settings、dsh-user-questions、dsh-typert-protocol、dsh-typert-registry、dsh-api-remotes、dsh-commands、dsh-timeout），当前均声明为 ^0.1.0-rc.7。

能力边界与副作用

• 网络：只访问强制回环的 http://127.0.0.1:23119/api（拒绝重定向、流式字节上限）；没有任何外部网络调用。
• 文件：仅读取附件磁盘路径的存在性（existsSync），不写入、不执行。
• 进程：无 Shell 调用、无 native 模块、无常驻后台任务或定时器——所有请求都由工具调用驱动，加载插件不会探测 Zotero。
• 外部副作用：唯一的持久化写入是设置卡片保存时对 $DSH_HOME/settings.yaml 中 zotero: 小节（用户层）的更新；无遥测、无埋点。

安装

按包名安装

dsh plugin --profile <name> add dsh-zotero

tarball 内含已构建的 lib/（node 半与浏览器半 lib/client.js），无需本地构建。浏览器半边是配置卡片：dsh web 会扫描到包内声明的 dsh.client 清单并自动挂载，无需额外配置。

本地 tarball

cd dsh-zotero
npm pack
dsh plugin --profile <name> add ./dsh-zotero-0.3.1.tgz

npm pack 先运行 prepare 构建 lib/，适合未发布或本地试装。

从 GitHub 源码安装

dsh plugin --profile <name> add github:Vncntvx/dsh-zotero

git 安装拉取源码而非构建产物，pnpm 安装依赖后运行本包的 prepare 现场构建（TypeScript 与 @types/node 在 dependencies 中）。pnpm ≥ 10 默认拒绝运行 git 依赖的 prepare，首次 add 会失败并提示：把包名加进 profile 的 pnpm-workspace.yaml 后重新执行：

allowBuilds:
  dsh-zotero: true

allowBuilds 授权该包在安装时执行代码，只允许你信任的来源，建议固定到具体提交（github:Vncntvx/dsh-zotero#<sha>）。

插件以 id zotero 挂载，下次启动 dsh 时生效。安装或启用插件后，如果当前会话创建于插件加载之前，请新建会话，确保 Agent 获得 Zotero 工具。

配置

所有值都是 Config 字段，可在 bundle 的 config 块中修改（例如通过 dsh plugin config）。以下为默认值。

Web 配置

插件在 dsh web 的 Settings → Plugins → Plugin configuration 页面注册一张 "Zotero" 卡片，列出上表全部字段。卡片绑定 zotero 设置命名空间：写入落在 $DSH_HOME/settings.yaml 的 zotero: 小节（叠加在 patch 条目 config 之上，用户层优先），保存即时生效——传输层与 provider 按新值重建，下一次工具调用或 /zotero status 无需重启 dsh 即可使用。

• 非法值（非回环 baseUrl、非正数上限）在写入前被拒绝；卡片提示保存失败并保留草稿，插件继续运行在最后一个合法值上。
• 每个字段显示有效值；被设置文档覆盖的字段带有 "Overridden" 徽标，提供一键重置（清除用户层，回到 patch 条目值）。
• 直接编辑设置文档（如手工修改 settings.yaml）同样热生效。
• 没有设置服务的组合（纯 headless）不会注册命名空间，插件行为与未配置时完全一致。

Web 视图

dsh web 的会话视图是标签页环（Chat、Trajectory、…）。插件注册一个专属 Zotero 标签页（conversation.view，id zotero，位于 Trajectory 与 dsh-context 之后），不触碰 dsh 自带的聊天与轨迹视图：

• 标签页顶部是连接条：挂载时探测一次、每次手动刷新再探测一次（请求驱动，无轮询定时器）；显示连接状态、API/Schema 版本、Server ID（Zotero 10+）与上次检查时间；Zotero 不可用时显示诊断信息。
• 下方是本会话的 Zotero 工具活动：每次搜索、精读、取证、附件解析与导出调用都渲染为富卡片（可展开、ref 可复制、证据段落标注来源），完全由会话快照重放驱动——同一段记录永远渲染出同样的卡片，meta 缺失时降级为原始内容。
• 设置页的 Web → 会话工具卡片 开关（webEnabled，默认开启）控制标签页的注册；开关即时生效——打开立即显示、关闭立即隐藏，无需刷新页面。关闭后，Zotero 调用在轨迹中显示为 dsh 内置的通用卡片。

限制

• 只读文献库：没有任何路径会修改条目、笔记、标签或合集。
• 全文证据依赖 Zotero 的索引：everything 搜索与 retrieve 的全文段落都需要已建立索引。
• 笔记正文搜索是客户端扫描：仅限 library/collection 作用域与第一页结果（offset 0），受 maxNoteScanRecords 限制；命中并入第一页直到 limit，计数在返回的 noteMatches 字段中，不计入分页 total。
• 附件深度取决于宿主组合：zotero_attachment 返回文件位置；继续阅读该 PDF 需要宿主具备对应的文件/PDF 能力。
• 证据排序是基于词项的相关性，而非向量或语义检索。

开发

命令

npm install                      # 使用本地 npm 缓存（见下方 workspace 说明）
npm test                         # 单元测试（mock Zotero server + 浏览器卡片测试）
npm run test:coverage            # 对 src/ 的 100% 覆盖率门禁
npm run typecheck                # tsc --noEmit，node / test / client 三个项目
npm run build                    # tsc 生成 node 半 lib/ + esbuild 生成浏览器半 lib/client.js
npm run build:client             # 只重建浏览器半（含 loader 交接格式自检）
npm run dev:client               # 浏览器半 watch 模式（配合热替换 overlay）
npm run format                   # prettier --write 全仓格式化
npm run format:check             # 校验格式化（提交前执行）

本仓库位于 deepseek-harness workspace 树内：父目录 package.json 声明了 workspaces，npm 会向上找到它并尝试安装整个 workspace。请使用 npm install --no-workspaces（或在本仓库放置含 workspaces=false 的 .npmrc）。

集成测试面向真实 Zotero，默认跳过，需显式开启：

npm run test:integration
# 或：ZOTERO_INTEGRATION=1 npx vitest run tests/integration/zotero.integration.spec.ts

本地启动

从 dsh 源码启动

在 deepseek-harness 源码 checkout 中构建一次（pnpm install && pnpm run build），然后通过 dev overlay 加载插件源码：

pnpm dsh web --patch ./dsh-zotero/dev.cordis.yml

dev.cordis.yml 将插件入口指向绝对的 src/index.ts。dsh 的源码启动经 tsx 加载该 TypeScript 入口，插件因此无需预构建；若 checkout 路径不同，需同步修改文件中的绝对路径。

使用 npm 安装的 dsh

本插件分两部分构建：Node 端（lib/，由 tsc 生成，包含服务、工具、provider 等逻辑）与浏览器端（lib/client.js，由 esbuild 生成，包含 dsh web 的配置卡片与 Zotero 标签视图）。下面三种开发流程覆盖了不同场景。

① 常驻实例验证（tarball 安装）

打包为 tarball 并安装到 profile，插件以 tarball 内的构建产物运行；代码更新后需重新打包安装。安装后通过生产栈 smoke 脚本验证：

npm pack
dsh plugin --profile <name> add ./dsh-zotero-0.3.1.tgz
cd ~/.dsh/profiles/<name>
node --input-type=module < /path/to/dsh-zotero/scripts/smoke.mjs

smoke 脚本必须在 profile 目录内运行，这样裸导入才能从 profile 的扁平 node_modules 中解析。脚本依次验证 status、search、get、retrieve、export、策略提示词分区，以及五个工具的注册情况；输出 SMOKE PASS 表示打包后的插件通过了安装路径验证。

② Node 端热替换开发

dev-lib.cordis.yml 覆盖层会禁用 profile 中的 tarball 行（id zotero），转而插入 zotero-dev 行指向本仓库的 lib/index.js，并重新启用 HMR。生产 web profile 默认关闭 loader HMR，且 HMR 的监视根位于 profile 目录，因此覆盖层显式设置了 base。构建产物变化后，HMR 会在同一进程内销毁旧实例并重新构造插件，无需重启 dsh：

cd ./dsh-zotero                 # 从 deepseek-harness checkout 进入本仓库
npm run dev &                    # tsc --watch：修改 src 后自动重建 lib
dsh web --patch ./dev-lib.cordis.yml --port 3307

热替换仅对通过 --patch 启动的实例生效；常驻实例仍运行 tarball 版本，互不影响。

③ 浏览器端开发

dsh web 只会扫描 Loader 行中 name 为裸包名（npm 能解析到 package.json）的条目来加载浏览器端 bundle。dev-lib.cordis.yml 使用的是绝对路径行，不会触发浏览器端加载，因此卡片不会出现在 ② 的 dev 实例中。开发卡片时需要先把本仓库装进 profile（npm install <本仓库路径> 作为 file: 依赖，或 npm pack 后安装 tarball），再配合 npm run dev:client（esbuild watch）与热替换 overlay 一起使用：浏览器 bundle 变化会触发 HMR 重新拉取 /plugins/dsh-zotero/client.js。

许可证

本插件以 MIT 许可证发布。