dsh-zotero

English · 中文

让 Agents 搜索、阅读并引用你的本地 Zotero 文献库：找文献、查看笔记与批注、按问题取证、打开原文、生成引用。

在会话里用自然语言描述需求，Agent 自动按需调用下面的工具；唯一的手动命令是 /zotero status。

工具

工具	用途
zotero_search	发现：按标题/作者/年份搜索库里的资料，everything 模式连全文索引一起搜；可限定某个分类或已保存搜索
zotero_get	检查：读取一条资料的结构化核心元数据，可选检查笔记、注释、附件的清单与预览。
zotero_retrieve	取证：按问题返回最相关的有界证据片段（注释、笔记、摘要、全文分块）
zotero_attachment	原文：解析条目或附件 ref，返回原始附件已验证的磁盘路径或链接 URL
zotero_export	引用：让 Zotero 按自己的 citation/export 能力生成结果（引用、CSL 参考文献表、bibtex / biblatex / ris / csljson）。

使用示例

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 命令报告版本不匹配，请升级。

安装

按包名安装

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.1.0.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）。以下为默认值。

字段	默认值	含义
baseUrl	http://127.0.0.1:23119/api	本地 API 基础 URL。仅支持纯回环 HTTP。
provider	local	要选择的 provider id。
timeoutMs	5000	每个请求的 provider 超时时间。
maxSearchResults	20	zotero_search limit 的上限。
maxNoteScanRecords	200	zotero_search 补扫笔记正文的笔记数量上限。
maxEvidenceChars	6000	检索证据的总字符预算。
maxEvidencePassages	4	证据片段数量的上限。
maxDetailChars	3000	zotero_get 摘要预览的字符预算。
maxNoteBodyChars	30000	zotero_get 返回 note 条目自身正文的字符预算。
maxNoteChars	2000	zotero_get 单条笔记预览的字符预算。
maxNoteRecords	50	zotero_get 返回笔记数量的上限。
maxAnnotationRecords	100	zotero_get 返回批注数量的上限。
fulltextChunkWords	200	进入证据排序的全文片段词数。
maxFulltextChars	250000	进入证据排序的全文大小上限。
maxResponseBytes	16777216	每个 API 响应的流式字节上限。
maxExportChars	1000000	导出输出的硬上限。不会中途截断。
maxExportRefs	1000	单次 zotero_export 的 refs 数量上限，保护请求行不超服务器 HTTP 头限制。
defaultStyle	apa	引用/参考文献使用的 CSL 样式。
defaultLocale	en-US	引用/参考文献使用的 CSL locale。

Web 配置

插件在 dsh web 的 设置 → 插件 → 插件配置 页注册了一张 "Zotero" 卡片，列出上表全部 19 个字段。卡片绑定 zotero 设置命名空间：写入的内容落在 $DSH_HOME/settings.yaml 的 zotero: 段（与补丁 entry 的 config 叠层，用户段优先），保存即热生效——传输层与 provider 会按新值重建，下一个工具调用或 /zotero status 立即使用新配置，无需重启 dsh。

• 非法值（如非回环的 baseUrl、非正整数的限制）在写入前被拒绝，卡片提示保存失败并保留草稿，插件继续运行于上一个合法值。
• 每个字段显示当前生效值；被设置文档覆盖的字段带「已覆盖」标记，可一键恢复默认（清除用户段，回到补丁 entry 值）。
• 设置文档被外部编辑（如直接改 settings.yaml）时同样会热生效。
• 无 settings 服务的组合（纯 headless）不注册命名空间，插件行为与未配置时完全一致。

Web 视图

dsh web 的会话视图是一个标签环（聊天、轨迹……）。插件注册了专属的 Zotero 标签（conversation.view，id zotero，排在轨迹与 dsh-context 之后），不修改 dsh 自带的聊天与轨迹显示：

• 顶部是一条连接状态条：挂载时探测一次，点击「刷新」再探测一次（请求驱动，无轮询定时器）；显示连接状态、API/Schema 版本、Server ID（Zotero 10+）、上次检查时间，Zotero 不可用时显示诊断信息。
• 下面是本会话的 Zotero 工具活动：搜索、读取、取证、附件、导出每次调用都以富卡片呈现（可展开、可复制 ref、证据片段按来源标注），完全由会话快照回放驱动——同样的轨迹渲染同样的卡片，无元数据时退化为原文内容。
• 设置页 Web → 会话工具卡片 开关（webEnabled，默认开）控制该标签的注册；关闭后 Zotero 调用在轨迹中显示为 dsh 内置的通用卡片。

限制

• 对文献库只读：没有任何修改条目、笔记、标签、分类等文献库数据的路径。
• 全文证据依赖 Zotero 的全文索引：everything 搜索和 retrieve 的全文片段都以索引为前提。
• 笔记正文搜索是插件侧补扫：仅库/分类范围、仅结果首页、受 maxNoteScanRecords 上限约束，超出上限的笔记不参与匹配。
• 附件深度分析取决于当前 Harness 配置：zotero_attachment 返回文件位置，能否继续读取该 PDF 由 composition 里是否有相应文件/PDF 能力决定。
• 证据排序是词项相关度检索，不是 embedding 或语义搜索。

开发

命令

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

常驻实例：打包为 tarball 并安装到 profile，插件以 tarball 中的副本运行；代码更新需重新打包安装。安装后运行生产栈 smoke 验证：

npm pack
dsh plugin --profile <name> add ./dsh-zotero-0.1.0.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 表示打包后的插件通过安装路径验证。

开发实例（热替换）：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 版本。

浏览器半边的开发：Web 端只扫描 Loader 行 name 为裸包名（npm 可解析到 package.json）的条目——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 许可证发布。