Zotero 文献阅读 nftuoa/dsh-zotero

dsh-zotero — 给 DeepSeek Harness 用的 Zotero

一个本地 DeepSeek Harness 插件，用来在 DSH Web GUI 里读取 Zotero 文库：

- Zotero 面板 — 浏览并搜索本地 Zotero 文库（条目、作者、年份、类型、分类、标签），一眼看出哪些条目有 PDF。
- 文件夹栏 — 把 Zotero 分类显示成文件夹树（全部文献 / 未分类 / 带计数的嵌套分类）；选中一个就筛选条目列表。面板变窄时收进 分类 抽屉。
- 论文阅读器 — 在面板内嵌的同源 PDF.js 阅读器里打开附件 PDF（连续翻页、真实文本层、可选中）。
- 论文对话，停靠右侧 — 每篇论文在阅读器右侧都有自己的对话窗格。它绝不碰用户的主 DSH 会话：第一次提问会为该论文创建（或复用）一个会话，之后提问只发进那个会话。仅仅打开论文不会创建空会话。
- 每篇论文多个会话 — 新对话 为同一篇论文再开一个会话，顶部下拉框在它们之间切换；每个会话保留自己的记录。
- Markdown + 公式 — 助手回答能渲染标题、列表、代码块和行内/独立 LaTeX，用的是随包内置的 KaTeX（不依赖外部 CDN）；$…$、$$…$$、\(…\) 和 \[…\] 都支持。
- 阅读进度 — 每个 PDF 记住最后停留的页码和位置；重新打开论文（或重启 DSH）会回到你停下的地方。
- Zotero 原生标注与笔记 — 标注与笔记 标签页按页列出 Zotero 高亮和笔记。你可以把当前 PDF 选中内容存成 Zotero 原生高亮、编辑高亮评论、创建/编辑 Zotero 子笔记。写入走 Zotero 本地 API（不直接改数据库）。
- 选中内容 → 对话 — 选中任意段落，对话输入框会显示 已选 N 字 · 第 P 页；输入（或跳过）问题后按 发送。第一条提示词带上选中内容、论文元数据、Zotero 条目 key 和 PDF 路径；后续提问保持精简。没有选中内容时省略【框选内容】块，默认问题变成整篇论文摘要。智能体立即作答，并可通过 zotero_paper 工具或 PDF 路径读取全文。
- 打开完整对话 — 需要完整记录、工具或附件时，点 ↗ 按钮在常规 DSH 聊天里打开该论文的会话。

模型工具

宿主侧还注册了两个面向模型的工具（前提是配置档里有工具注册表）：

- zotero_search(query) — 搜索本地文库，返回条目 key。
- zotero_paper(itemKey) — 标题/作者/年份，外加 PDF 前约 40 页的文本（pdftotext），让后续提问能超出选中范围。

环境要求

- DSH Web 配置档（dsh web）。已用 dsh 0.2.1-rc.2 测试（客户端依赖 uiConversation ChatSnapshot API，见兼容性）。
- Node ≥ 22.13 / 23.4 / 24（宿主使用 node:sqlite；在旧版 Node 上插件仍能加载，Zotero 运行时回退到 Zotero 本地 HTTP API）。
- Zotero 桌面版，带本地文库（默认 ~/Zotero，Windows 上是 C:\Users\<you>\Zotero）。Zotero 不需要一直开着：宿主读取的是 zotero.sqlite 的快照副本。
- pdftotext（poppler）可选——启用后可用 zotero_paper 模型工具访问全文。
- 要创建/编辑批注和笔记，Zotero 必须正在运行，并开启 Settings → Advanced → Allow other applications on this computer to communicate with Zotero。首次写入会弹出 Zotero 授权对话框，选择 Always Allow。读取批注/笔记不需要这项设置。
- 运行时无网络访问：pdf.js 和 KaTeX 已随包内置。

在另一个 DSH 上安装

包是自包含的：lib/、assets/、vendor/（pdf.js + KaTeX + 字体）、cordis.patch.yml、图标和 README。它声明了 dsh.bundle.patch，所以 DSH Plugin Manager 能像安装任何官方 bundle 一样安装并启用它。

A. 从 Web UI 安装（推荐最终用户使用）

1. 从 GitHub Releases 下载 tarball，或自行构建（见打包）：
npm pack # → dsh-zotero-1.0.1.tgz

2. 在 DSH 中：Plugins → Add plugin → 选择 Install a third-party plugin → 输入 tarball 的绝对路径（或 Git URL / 包名）。
3. 安装后点击 Enable now（或打开 bundle 开关），然后刷新 GUI。侧边栏会出现 Zotero 入口。

B. 从命令行 / 配置档安装

dsh plugin --profile web add /absolute/path/dsh-zotero-1.0.1.tgz

然后把 bundle 加入配置档清单（UI 的 Enable now 做的就是这件事）：

// ~/.dsh/profiles/web/package.json
{
"dependencies": { "@local/dsh-zotero": "file:/absolute/path/dsh-zotero-1.0.1.tgz" },
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "...", "@local/dsh-zotero"] } }
}

dsh plugin add 只添加依赖；真正激活它的是 bundle 列表（或 UI 开关）。重启 dsh web（或让 HMR 重新组合），然后刷新页面。

C. 从 Git / GitHub 安装

dsh plugin --profile web add github:nftuoa/dsh-zotero
then add "@local/dsh-zotero" to dsh.profile.bundles as above

vendor/ 已提交到仓库，所以使用方无需安装或构建。预构建的 tarball 附在 GitHub Releases 上。

D. 发布到 npm（可选）

本地包名 @local/dsh-zotero 有意设为不可发布。要发布：

1. 把 package.json 里的 "name" 改成你的 scope（例如 @yourname/dsh-zotero）；
2. 修改 cordis.patch.yml 里的 name:，同步更新配置档 bundle 字符串；
3. 执行 npm publish --access public。

之后用户就能在 Plugins → Add plugin 里按包名安装。

配置

默认无需配置：dataDir 会从 $ZOTERO_DATA_DIR 或 ~/Zotero 自动探测，本地 API 默认指向 http://127.0.0.1:23119。要覆盖这些值，改配置档补丁层（~/.dsh/profiles/web/cordis.patch.yml）：

- id: zotero
config:
dataDir: /home/you/Zotero # Zotero data directory
localAPI: http://127.0.0.1:23119 # only while Zotero runs
cacheDir: ~/.cache/dsh-zotero # snapshot cache (optional)

本地 API 兜底方案（只在旧版 Node 上、或 Zotero 运行时数据库读不出来时才需要）：打开 Zotero → Settings → Advanced → Allow other applications on this computer to communicate with Zotero。

兼容性

- 在 DSH 0.2.1-rc.2 上测试通过。浏览器端使用公开的 /client 导出
（uiConversation.binding(...).target('chat')、ChatSnapshot）渲染论文转录。
如果未来 DSH 改了这些内部实现，PDF 阅读器仍可用，聊天面板会显示可重试的错误； ↗ 仍能在 DSH 原生会话里打开该会话。
- 用到的宿主 API：ctx.webServer.register、可选的 ctx.tools，以及普通对象形式的工具定义。
不导入任何 DSH 包，所以运行时不需要解析 npm 依赖。
- 插件在 DSH Web UI 的同源下提供 /zotero/（不额外占端口，无 CORS）。它和 DSH 服务器其余部分一样只在本机可用；不要把 DSH Web UI 直接暴露到公网，除非前面加了认证。

故障排查

| 现象 | 处理 |
| 找不到 Zotero 入口 | 配置档 bundle 没启用，或 GUI 页面没刷新 |
| “未找到 Zotero 数据” | 先打开一次 Zotero 生成 zotero.sqlite，或设置 dataDir |
| node:sqlite 报错 | 用 Node ≥ 22.13/24 运行 DSH，或保持 Zotero 打开并启用本地 API |
| 本地 API 403 | 在 Zotero 高级设置里勾选 Allow other applications…* |
| 公式显示成 TeX | 检查 /zotero/katex/katex.min.css 是否加载（看网络面板）；刷新页面 |
| zotero_paper 失败 | 安装 pdftotext（poppler），或让模型直接读 PDF 路径 |
| 标注 tab 提示写入需要本地 API | 在 Zotero → Settings → Advanced 勾选 Allow other applications…，保持 Zotero 运行 |
| 第一次“保存高亮”卡住 | Zotero 弹出了授权对话框；选 Always Allow |

卸载：从配置档依赖和 dsh.profile.bundles 列表里移除 @local/dsh-zotero（或用 Plugins → Remove），然后刷新。Zotero 文库不会被改动。

打包

npm pack # tarball includes lib, assets, vendor, patch, README, LICENSE, icon
tar -tzf dsh-zotero-1.0.1.tgz | head

vendor/ 放在 node_modules 之外（vendor/pdfjs、vendor/katex），因为 npm 总是打包时排除 node_modules。第三方许可证：pdf.js 采用 Apache-2.0，KaTeX 采用 MIT；两份 LICENSE 文件都保留在 vendor/ 下。

架构

| 端 | 文件 | 职责 |
| 宿主 | lib/index.js | cordis 插件：注册 /zotero 路由前缀和可选的模型工具 |
| 宿主 | lib/zotero-data.mjs | 只读 SQLite 快照读取器、本地 API 兜底、PDF 解析 |
| 宿主 | lib/routes.mjs | JSON API、PDF 流式传输（Range/HEAD）、静态阅读器 + pdf.js 资源 |
| 宿主 | assets/viewer.{html,js} | 自包含的 PDF.js 阅读页（canvas + 可选中文字层） |
| 宿主 | vendor/pdfjs、vendor/katex | 内置的 pdf.js 和 KaTeX 运行时（JS/CSS/字体，不走 CDN） |
| 宿主 | lib/tool.mjs | zotero_paper / zotero_search 模型工具（可选） |
| 宿主 | lib/local-api.mjs | Zotero 本地 API 写入客户端（授权、服务器 id、条目 CRUD） |
| 客户端 | lib/client.js | 手写的懒加载 CJS 浏览器插件：侧边栏入口 + 主面板 |

HTTP 接口

GET /zotero/api/status library source, counts, diagnostics
GET /zotero/api/items?q=&limit=&offset= item list (searchable)
GET /zotero/api/items?collection=<KEY> papers directly in one folder
GET /zotero/api/items?unfiled=1 papers in no folder
GET /zotero/api/item/:itemKey item detail + PDF metadata (absolute path)
GET /zotero/api/collections folder tree (parentKey, count/totalCount) + unfiledCount
GET /zotero/api/annotations/:itemKey native annotations + notes + writable
POST /zotero/api/annotations create highlight / update comment+color
POST /zotero/api/notes create / update a Zotero child note
GET /zotero/file/:attachmentKey PDF bytes (Range + HEAD)
GET /zotero/viewer.html?file=/zotero/file/… the reader page GET /zotero/pdfjs/* vendored pdf.js runtime GET /zotero/katex/* vendored KaTeX (JS/CSS/fonts)

为什么用 SQLite 快照

Zotero 运行时持有排他锁，本地 HTTP API 也只在 Zotero 打开时才存在。按需刷新一份 zotero.sqlite 的只读副本（连同 -wal/-shm），面板就能拿到稳定、离线的文库视图；只有数据库缺失时，才用本地 API 兜底元数据。

开发

cd ~/dsh-zotero
node test/host.test.mjs # host data layer + routes (16 tests)
node --test test/local-api.test.mjs test/write-routes.test.mjs
local-API auth/writes + annotation/note routes (4 tests)
node client-test/smoke.mjs # client bundle + helpers + note sanitizer + progress (38 checks)
node client-test/e2e.mjs <url> # live GUI: reader, chat, sessions, math (20 checks)

构建和调试请用隔离的配置档，不要动正在用的 GUI：

DSH_HOME="$HOME/.dsh-zotero-test" \
dsh --profile zotero-test --port 3302 --no-open
CONTRACT.md 记录了宿主端与浏览器端之间的约定。