@local/dsh-zotero

Zotero

适用于 DeepSeek Harness Web GUI 的 Zotero 文献库浏览器、PDF 阅读器和单篇论文 AI 聊天功能

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:nftuoa/dsh-zotero#9103cdb3b6d5b20a709b9e07ae0d6f4c6cd05279

兼容性与来源证明

Zotero 以 @local/dsh-zotero 发布，当前版本为 1.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: web
发布来源: github
Registry 更新时间: 2026/10/23

版本

1.0.0stable

2026/10/23

README

dsh-zotero — Zotero for DeepSeek Harness

A local DeepSeek Harness plugin for reading a Zotero library inside the DSH Web GUI:

Zotero panel — browse and search the local Zotero library (items, creators, year, type, collections, tags), see which entries have a PDF.
Folder rail — Zotero collections as a folder tree (全部文献 / 未分类 / nested collections with counts); picking one filters the item list. It collapses into a 分类 drawer on narrow panels.
Paper reader — open the attached PDF in a same-origin PDF.js reader embedded in the panel (continuous pages, real text layer, selection).
Paper chat, docked right — every paper has its own conversation pane on the right of the reader. It never touches the user's main DSH conversation: opening a paper creates (or reuses) a session for that paper, and asking sends into that session only.
Multiple sessions per paper — 新对话 creates another session for the same paper and the header dropdown switches between them; each keeps its own transcript.
Markdown + formulas — assistant answers render headings, lists, code blocks and inline/display LaTeX through a vendored KaTeX (no external CDN); $…$ , $$…$$, $…$ and \[…\] all work.
Reading progress — every PDF remembers its last page and position; reopening the paper (or restarting DSH) returns to where you stopped.
Native Zotero annotations & notes — the 标注与笔记 tab lists Zotero highlights and notes by page. You can save the current PDF selection as a native Zotero highlight, edit highlight comments, and create/edit Zotero child notes. Writes go through Zotero's local API (no direct DB edits).
Selection → chat — select any passage and the chat composer shows 已选 N 字 · 第 P 页; type (or skip) a question and press 发送. The first prompt carries the selection, paper metadata, Zotero item key and PDF path; follow-ups stay lean. Without a selection the 【框选内容】 block is omitted and the default question becomes a whole-paper summary. The agent answers immediately and can read the full paper through the zotero_paper tool or the PDF path.
Open full conversation — the ↗ button opens the paper's session in the regular DSH chat if you need the full transcript, tools, or attachments.

Model tools

The host half also registers two model-facing tools (when the profile has a tool registry):

zotero_search(query) — search the local library, returns item keys.
zotero_paper(itemKey) — title/authors/year plus the first ~40 pages of the PDF as text (pdftotext), so follow-up questions can go beyond the selection.

Requirements

A DSH Web profile (dsh web). Tested with dsh 0.2.1-rc.2 (the client relies on the uiConversation ChatSnapshot API, see Compatibility).
Node ≥ 22.13 / 23.4 / 24 (the host uses node:sqlite; on older Node the plugin still loads and falls back to Zotero's local HTTP API while Zotero is running).
Zotero desktop with a local library (default ~/Zotero, or C:\Users\<you>\Zotero on Windows). Zotero does not need to stay open: the host reads a snapshot copy of zotero.sqlite.
pdftotext (poppler) optional — enables the zotero_paper model tool for full-text access.
To create/edit annotations and notes, Zotero must be running with Settings → Advanced → Allow other applications on this computer to communicate with Zotero enabled. The first write opens Zotero's authorization dialog; choose Always Allow. Reading annotations/notes never needs it.
No network access at runtime: pdf.js and KaTeX are vendored in the package.

Install on another DSH

The package is self-contained: lib/, assets/, vendor/ (pdf.js + KaTeX + fonts), cordis.patch.yml, icon and README. It declares dsh.bundle.patch, so the DSH Plugin Manager can install and enable it like any official bundle.

A. From the Web UI (recommended for end users)

Download the tarball from GitHub Releases or build one (see Packaging):
```
npm pack          # → dsh-zotero-1.0.0.tgz
```
In DSH: Plugins → Add plugin → choose Install a third-party plugin → enter the absolute tarball path (or a Git URL / package name).
After installation click Enable now (or switch the bundle on), then refresh the GUI. The Zotero entry appears in the sidebar.

B. From the CLI / profile

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

Then add the bundle to the profile manifest (this is what the UI's Enable now does):

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

dsh plugin add only adds the dependency; the bundle list (or the UI toggle) is what activates it. Restart dsh web (or let HMR recompose) and refresh the page.

C. From Git / GitHub

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

vendor/ is committed in the repository, so no install or build step is required at the consumer side. Prebuilt tarballs are attached to GitHub Releases.

D. Publish to npm (optional)

The local package name @local/dsh-zotero is intentionally not publishable. To publish:

rename "name" in package.json to your scope (e.g. @yourname/dsh-zotero);
update name: in cordis.patch.yml and the profile bundle string to match;
npm publish --access public.

Users can then install it through Plugins → Add plugin by package name.

Configuration

Defaults require no configuration: dataDir is detected from $ZOTERO_DATA_DIR or ~/Zotero, and the local API defaults to http://127.0.0.1:23119. Override them in the profile patch layer (~/.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)

For the local-API fallback (only needed on old Node or when the DB is unreadable while Zotero runs), enable Zotero → Settings → Advanced → Allow other applications on this computer to communicate with Zotero.

Compatibility

Tested on DSH 0.2.1-rc.2. The browser half uses public /client exports (uiConversation.binding(...).target('chat'), ChatSnapshot) to render the paper transcript. If a future DSH changes those internals, the PDF reader still works and the chat pane shows a retryable error; ↗ still opens the session in the native DSH conversation.
Host APIs used: ctx.webServer.register, optional ctx.tools plus plain-object tool definitions. No DSH package imports, so no npm dependency resolution is needed at runtime.
The plugin serves /zotero/* on the same origin as the DSH Web UI (no extra port, no CORS). It is local-only like the rest of the DSH server; do not expose the DSH Web UI publicly without putting authentication in front of it.

Troubleshooting

symptom	fix
Zotero entry missing	profile bundle not enabled, or the GUI page not refreshed
“未找到 Zotero 数据”	open Zotero once to create `zotero.sqlite`, or set `dataDir`
`node:sqlite` error	run DSH on Node ≥ 22.13/24, or keep Zotero open with local API enabled
本地 API 403	enable Allow other applications… in Zotero Advanced settings
formulas stay as TeX	check `/zotero/katex/katex.min.css` loads (network panel); reload the page
`zotero_paper` fails	install `pdftotext` (poppler), or let the model read the PDF path directly
标注 tab says writes need local API	enable Allow other applications… in Zotero → Settings → Advanced, keep Zotero running
first “保存高亮” hangs	Zotero is showing an authorization dialog; choose Always Allow

Uninstall: remove @local/dsh-zotero from the profile dependencies and the dsh.profile.bundles list (or use Plugins → Remove), then refresh. The Zotero library is never modified.

Packaging

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

vendor/ lives outside node_modules (vendor/pdfjs, vendor/katex) because npm always excludes node_modules from tarballs. Third-party licenses: pdf.js is Apache-2.0, KaTeX is MIT; both LICENSE files stay in vendor/.

Architecture

half	file	role
host	`lib/index.js`	cordis plugin: registers the `/zotero` route prefix and optional model tools
host	`lib/zotero-data.mjs`	read-only SQLite snapshot reader, local-API fallback, PDF resolution
host	`lib/routes.mjs`	JSON API, PDF streaming (Range/HEAD), static viewer + pdf.js assets
host	`assets/viewer.{html,js}`	self-contained PDF.js reader page (canvas + selectable text layer)
host	`vendor/pdfjs`, `vendor/katex`	vendored pdf.js and KaTeX runtime (JS/CSS/fonts, no CDN)
host	`lib/tool.mjs`	`zotero_paper` / `zotero_search` model tools (optional)
host	`lib/local-api.mjs`	Zotero local-API write client (authorization, server id, item CRUD)
client	`lib/client.js`	hand-written lazy-CJS browser plugin: sidebar entry + main panel

HTTP surface

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)

Why the SQLite snapshot

Zotero holds an exclusive lock while it runs and its local HTTP API only exists while Zotero is open. A read-only copy of zotero.sqlite (plus -wal/-shm) refreshed on demand gives the panel a stable, offline library view; the local API is used only as a metadata fallback when the DB is missing.

Development

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 (19 checks)

Build/debug against an isolated profile instead of the live GUI:

DSH_HOME="$HOME/.dsh-zotero-test" \
  dsh --profile zotero-test --port 3302 --no-open

CONTRACT.md documents the pack between the host and browser halves.

README

dsh-zotero — Zotero for DeepSeek Harness

A local DeepSeek Harness plugin for reading a Zotero library inside the DSH Web GUI:

Zotero panel — browse and search the local Zotero library (items, creators, year, type, collections, tags), see which entries have a PDF.
Folder rail — Zotero collections as a folder tree (全部文献 / 未分类 / nested collections with counts); picking one filters the item list. It collapses into a 分类 drawer on narrow panels.
Paper reader — open the attached PDF in a same-origin PDF.js reader embedded in the panel (continuous pages, real text layer, selection).
Paper chat, docked right — every paper has its own conversation pane on the right of the reader. It never touches the user's main DSH conversation: opening a paper creates (or reuses) a session for that paper, and asking sends into that session only.
Multiple sessions per paper — 新对话 creates another session for the same paper and the header dropdown switches between them; each keeps its own transcript.
Markdown + formulas — assistant answers render headings, lists, code blocks and inline/display LaTeX through a vendored KaTeX (no external CDN); $…$ , $$…$$, $…$ and \[…\] all work.
Reading progress — every PDF remembers its last page and position; reopening the paper (or restarting DSH) returns to where you stopped.
Native Zotero annotations & notes — the 标注与笔记 tab lists Zotero highlights and notes by page. You can save the current PDF selection as a native Zotero highlight, edit highlight comments, and create/edit Zotero child notes. Writes go through Zotero's local API (no direct DB edits).
Selection → chat — select any passage and the chat composer shows 已选 N 字 · 第 P 页; type (or skip) a question and press 发送. The first prompt carries the selection, paper metadata, Zotero item key and PDF path; follow-ups stay lean. Without a selection the 【框选内容】 block is omitted and the default question becomes a whole-paper summary. The agent answers immediately and can read the full paper through the zotero_paper tool or the PDF path.
Open full conversation — the ↗ button opens the paper's session in the regular DSH chat if you need the full transcript, tools, or attachments.

Model tools

The host half also registers two model-facing tools (when the profile has a tool registry):

zotero_search(query) — search the local library, returns item keys.
zotero_paper(itemKey) — title/authors/year plus the first ~40 pages of the PDF as text (pdftotext), so follow-up questions can go beyond the selection.

Requirements

A DSH Web profile (dsh web). Tested with dsh 0.2.1-rc.2 (the client relies on the uiConversation ChatSnapshot API, see Compatibility).
Node ≥ 22.13 / 23.4 / 24 (the host uses node:sqlite; on older Node the plugin still loads and falls back to Zotero's local HTTP API while Zotero is running).
Zotero desktop with a local library (default ~/Zotero, or C:\Users\<you>\Zotero on Windows). Zotero does not need to stay open: the host reads a snapshot copy of zotero.sqlite.
pdftotext (poppler) optional — enables the zotero_paper model tool for full-text access.
To create/edit annotations and notes, Zotero must be running with Settings → Advanced → Allow other applications on this computer to communicate with Zotero enabled. The first write opens Zotero's authorization dialog; choose Always Allow. Reading annotations/notes never needs it.
No network access at runtime: pdf.js and KaTeX are vendored in the package.

Install on another DSH

A. From the Web UI (recommended for end users)

Download the tarball from GitHub Releases or build one (see Packaging):
```
npm pack          # → dsh-zotero-1.0.0.tgz
```
In DSH: Plugins → Add plugin → choose Install a third-party plugin → enter the absolute tarball path (or a Git URL / package name).
After installation click Enable now (or switch the bundle on), then refresh the GUI. The Zotero entry appears in the sidebar.

B. From the CLI / profile

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

Then add the bundle to the profile manifest (this is what the UI's Enable now does):

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

dsh plugin add only adds the dependency; the bundle list (or the UI toggle) is what activates it. Restart dsh web (or let HMR recompose) and refresh the page.

C. From Git / GitHub

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

vendor/ is committed in the repository, so no install or build step is required at the consumer side. Prebuilt tarballs are attached to GitHub Releases.

D. Publish to npm (optional)

The local package name @local/dsh-zotero is intentionally not publishable. To publish:

rename "name" in package.json to your scope (e.g. @yourname/dsh-zotero);
update name: in cordis.patch.yml and the profile bundle string to match;
npm publish --access public.

Users can then install it through Plugins → Add plugin by package name.

Configuration

- 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)

Compatibility

Tested on DSH 0.2.1-rc.2. The browser half uses public /client exports (uiConversation.binding(...).target('chat'), ChatSnapshot) to render the paper transcript. If a future DSH changes those internals, the PDF reader still works and the chat pane shows a retryable error; ↗ still opens the session in the native DSH conversation.
Host APIs used: ctx.webServer.register, optional ctx.tools plus plain-object tool definitions. No DSH package imports, so no npm dependency resolution is needed at runtime.
The plugin serves /zotero/* on the same origin as the DSH Web UI (no extra port, no CORS). It is local-only like the rest of the DSH server; do not expose the DSH Web UI publicly without putting authentication in front of it.

Troubleshooting

symptom	fix
Zotero entry missing	profile bundle not enabled, or the GUI page not refreshed
“未找到 Zotero 数据”	open Zotero once to create `zotero.sqlite`, or set `dataDir`
`node:sqlite` error	run DSH on Node ≥ 22.13/24, or keep Zotero open with local API enabled
本地 API 403	enable Allow other applications… in Zotero Advanced settings
formulas stay as TeX	check `/zotero/katex/katex.min.css` loads (network panel); reload the page
`zotero_paper` fails	install `pdftotext` (poppler), or let the model read the PDF path directly
标注 tab says writes need local API	enable Allow other applications… in Zotero → Settings → Advanced, keep Zotero running
first “保存高亮” hangs	Zotero is showing an authorization dialog; choose Always Allow

Uninstall: remove @local/dsh-zotero from the profile dependencies and the dsh.profile.bundles list (or use Plugins → Remove), then refresh. The Zotero library is never modified.

Packaging

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

Architecture

half	file	role
host	`lib/index.js`	cordis plugin: registers the `/zotero` route prefix and optional model tools
host	`lib/zotero-data.mjs`	read-only SQLite snapshot reader, local-API fallback, PDF resolution
host	`lib/routes.mjs`	JSON API, PDF streaming (Range/HEAD), static viewer + pdf.js assets
host	`assets/viewer.{html,js}`	self-contained PDF.js reader page (canvas + selectable text layer)
host	`vendor/pdfjs`, `vendor/katex`	vendored pdf.js and KaTeX runtime (JS/CSS/fonts, no CDN)
host	`lib/tool.mjs`	`zotero_paper` / `zotero_search` model tools (optional)
host	`lib/local-api.mjs`	Zotero local-API write client (authorization, server id, item CRUD)
client	`lib/client.js`	hand-written lazy-CJS browser plugin: sidebar entry + main panel

HTTP surface

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)

Why the SQLite snapshot

Development

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 (19 checks)

Build/debug against an isolated profile instead of the live GUI:

DSH_HOME="$HOME/.dsh-zotero-test" \
  dsh --profile zotero-test --port 3302 --no-open

CONTRACT.md documents the pack between the host and browser halves.

Zotero

兼容性与来源证明

版本

相关插件

Zotero

README

dsh-zotero — Zotero for DeepSeek Harness

Model tools

Requirements

Install on another DSH

A. From the Web UI (recommended for end users)

B. From the CLI / profile

C. From Git / GitHub

D. Publish to npm (optional)

Configuration

Compatibility

Troubleshooting

Packaging

Architecture

HTTP surface

Why the SQLite snapshot

Development

兼容性与来源证明

版本

相关插件

相关插件

相关插件

README

dsh-zotero — Zotero for DeepSeek Harness

Model tools

Requirements

Install on another DSH

A. From the Web UI (recommended for end users)

B. From the CLI / profile

C. From Git / GitHub

D. Publish to npm (optional)

Configuration

Compatibility

Troubleshooting

Packaging

Architecture

HTTP surface

Why the SQLite snapshot

Development