中文 · English
dsh-zotero is a local Zotero plugin for DeepSeek Harness. It allows chat agents to search your library, read PDF full text and notes, extract relevant passages, and generate academic citations.
All operations interact with the local Zotero API (`127.0.0.1:23119`); reads need no API key.
## Features
- **Library search and discovery**: Search papers by title, author, year, tags, or full text, with support for collection scopes and recently added items.
- **PDF full text and note reading**: Agents can read structured bibliographic metadata, abstracts, personal notes, and parse local PDF attachments directly.
- **Passage retrieval**: Query papers to locate relevant passages across full text, notes, and annotations; PDF annotations retain original page numbers for direct verification.
- **Citation formatting and export**: Generate formatted citations or export selected items as BibTeX, RIS, or CSL JSON for copying or downloading.
- **Dedicated conversation tab**: Papers referenced in chat automatically sync to the "Zotero" tab at the top of the session, where you can inspect item details, review passages, or open local PDFs.
- **Library panel**: the Zotero icon in the DSH sidebar opens a global library panel for browsing the collection tree, saved searches, and the trash without a conversation, with search, sort, paging, full item details, and PDF reading in the right reader; gated by the `webEnabled` switch.
- **Two-way notes and organization**: Allow the agent to draft reading notes, add tags, and organize collections, with plan review and interactive approval for every write operation.
- **Scholarly literature retrieval (optional component)**: With `dsh-zotero/scholarly` enabled under "Included components" in the Plugins manager, search across arXiv, OpenAlex, Crossref, Semantic Scholar, PubMed, Europe PMC, and DBLP, read open-access full texts, and verify reference lists. The component ships with the bundle but off, and enabling it is the authorization for its outbound requests.
## Install
From npm (recommended):
```sh
dsh plugin --profile add dsh-zotero
```
From GitHub prebuilt branch:
```sh
dsh plugin --profile add github:Vncntvx/dsh-zotero#release
```
After installation, start a new session to use Zotero tools. Open the **dsh-zotero** detail page in the plugin manager: its configuration section carries the full form for the API address, concurrency limits, and retrieval parameters.
> Note: Installing directly from the main source branch requires local compilation. Because pnpm blocks dependency builds by default, use the `#release` branch to skip local build setup.
## Prerequisites
1. Zotero 7 or newer desktop app (writes require Zotero 10).
2. Enable local API in Zotero: **Settings → Advanced → check "Allow other applications on this computer to communicate with Zotero"**.
## Usage example
The agent calls tools during conversation, and referenced papers update the Sources panel in real time:
```text
User: Find papers about Risk
Agent → zotero_search(query: "Risk", itemTypes: ["journalArticle"])
5 matches; items populate the session's Zotero tab
User: What does the first one's abstract say?
Agent → zotero_get(ref: "zotero://user/0/item/ABCD1234")
Returns metadata and full abstract
User: Find the methodology discussion in this paper
Agent → zotero_retrieve(ref: "zotero://user/0/item/ABCD1234", query: "methodology",
sources: ["annotation", "fulltext"])
Returns ranked passages with source tags (annotations include page numbers)
User: Export all three as BibTeX
Agent → zotero_export(refs: ["zotero://user/0/item/ABCD1234",
"zotero://user/0/item/EFGH5678",
"zotero://user/0/item/IJKL9012"], format: "bibtex")
Generates BibTeX entries; copy or download directly in the UI
```
## Tools
The plugin includes 8 read tools and 15 write tools. Write tools are disabled by default until `writeEnabled` is turned on in settings.
| Tool | Purpose |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `zotero_search` | Search by title, author, year, or full text across libraries, collections, and tags |
| `zotero_browse` | Browse library hierarchy: collections tree, saved searches, and tags |
| `zotero_get` | Read structured metadata for an item, including abstract, notes, and attachment list |
| `zotero_children` | List child items, including standalone notes, PDF attachments, and annotations |
| `zotero_retrieve` | Query passages across full text, notes, and annotations (annotations retain page numbers) |
| `zotero_changes` | Check recently added, modified, or deleted items in the library |
| `zotero_attachment` | Resolve an item to its local PDF file path |
| `zotero_export` | Generate formatted citations or export BibTeX, RIS, and CSL JSON |
Write tools (disabled by default; they write to the personal library only):
| Tool | Purpose |
| -------------------------------- | ---------------------------------------------------------------------------------------------- |
| `zotero_create_note` | Create a standalone note or a child note, with tags, collections, and sources |
| `zotero_update_note` | Replace an existing note body under a version precondition, same character ceiling as creation |
| `zotero_update_item_tags` | Add and remove an item's tags in one call, preserving existing tag types |
| `zotero_update_item_collections` | Add and remove an item's collection membership in one call |
| `zotero_create_collection` | Create a top-level or nested collection; same-name siblings are refused |
| `zotero_update_collection` | Rename a collection or move it under a different parent |
| `zotero_delete_collection` | Delete a collection (irreversible); the plan card reports item and child counts |
| `zotero_create_item` | Create an item from a closed field set |
| `zotero_update_item` | Correct an item's scalar metadata, validated against its type |
| `zotero_restore_items` | Restore items from the Trash, reporting each entry separately |
| `zotero_create_saved_search` | Create a saved search, which needs at least one condition |
| `zotero_update_saved_search` | Update a saved search name or its conditions |
| `zotero_delete_saved_search` | Delete a saved search |
| `zotero_delete_library_tags` | Delete tags library-wide by name (irreversible); missed names are safe to retry |
| `zotero_batch_items` | Create, retag, recollection, or trash items in one call, under one plan card |
See [Tool reference](docs/tools.en.md) for complete parameter definitions of all 23 host tools. The scholarly literature tools belong to the `dsh-zotero/scholarly` component, which ships with the bundle but off; enabling that component enables its seven tools.
## Security and privacy
- Local requests: The plugin sends HTTP requests only to the local Zotero API (`http://127.0.0.1:23119/api`), without depending on Zotero cloud servers.
- Filesystem access: The plugin only checks the existence of local attachment files, executing no shell commands and running no background daemons.
- Write safety: Write tools are disabled by default. When enabled, any changes to your library present an approval card in the interface and require user confirmation before executing.
## Documentation
| Document | Covers |
| --------------------------------------------------- | ------------------------------------------------------------- |
| [Getting started](docs/getting-started.en.md) | Installation, prerequisites, and connection verification |
| [Features](docs/features.en.md) | Sources panel, chat integration, and export workflows |
| [Tool reference](docs/tools.en.md) | Parameters, return values, and error codes for all 17 tools |
| [Configuration reference](docs/configuration.en.md) | 37 configuration fields and default values |
| [Architecture](docs/architecture.en.md) | Data flow, layer responsibilities, and design boundaries |
| [Development guide](docs/development.en.md) | Build, test, local development, and release workflow |
| [Scenarios](docs/scenarios.en.md) | Real-conversation acceptance cases and everyday usage prompts |
| [Troubleshooting](docs/troubleshooting.en.md) | Common issues, diagnostic steps, and fixes |
## License
[MIT](./LICENSE)
