中文 · English
dsh-zotero is a local Zotero plugin for DeepSeek Harness. The agent searches, reads, cites, and (optionally) modifies the library in conversation; you browse the whole library and copy citations in the literature panel; the literature trail gathers the papers, passages, and exports from the session for verification.
All operations interact with Zotero through its local API (`127.0.0.1:23119`). Reads need no API key.
## Features
- **Conversation & Retrieval**
- Search & reading: Search papers by title, author, year, or full text, and read bibliographic metadata, notes, and local PDF full text.
- Passage extraction: Locate relevant passages across full text, notes, and annotations for specific research questions, with original page numbers preserved on PDF annotations.
- Citation & export: Generate in-text citations or bibliographies in specified CSL styles, and export BibTeX, RIS, or CSL-JSON.
- Writing & extensions (optional): With write access enabled, create notes and update tags or collections (each write requires approval); with the scholarly component enabled, search across seven external indexes and verify references.
- **Literature Trail**
- Search history: The session header shows query terms, scopes, filter conditions, and hit counts for every tool call on the first screen.
- Passage review: Review extracted passages and annotations grouped by paper, complete with source tags and page numbers for easy verification.
- Export collection: Review all citations and BibTeX entries generated in the conversation, deduplicated across items and ready to copy or download.
- **Literature Panel**
- Library browsing: Browse collection trees, tags, saved searches, and the Trash in the right sidebar, with multi-field filtering.
- Details & reading: Inspect metadata, notes, and attachment lists, and open local PDFs directly in the reading pane.
- Citations & handoff: Copy BibTeX entries, CSL citations, or item details directly from the action row, or send selected items into the chat draft with one click.
See the [product model](docs/product-model.en.md) for how the two entry points and three components divide the work.
## 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
```
Start a new session after installation. Open the **dsh-zotero** detail page in the plugin manager; its configuration section carries the full configuration form.
> Note: Installing directly from the `main` source branch needs a local build. pnpm blocks dependency builds by default, so use the `#release` branch to skip build configuration and install directly.
## Prerequisites
1. Zotero 7 or newer desktop app installed (writes require Zotero 10).
2. Enable the local API in Zotero: **Settings → Advanced → check "Allow other applications on this computer to communicate with Zotero"**.
## Usage example
Search first, then check:
```text
User: Find papers about Risk
Agent → zotero_search(query: "Risk", itemTypes: ["journalArticle"])
Returns 5 matches; the literature trail at the top of the session shows the same 5 papers
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 labels (annotations carry original page numbers)
User: Export these three as BibTeX
Agent → zotero_export(refs: [...], format: "bibtex")
Generates BibTeX entries, which can be copied or downloaded from the exports view
of the literature trail
```
To use the literature while writing: find an item in the literature panel, click "Copy citation" or "Copy BibTeX" in the action row, and paste the citation text or entry into your paper's source file. To bring the agent in, click "Ask" or "Add to chat"; the content is prefilled into the session draft.
## Tools
The plugin provides eight read tools and fifteen write tools. Write tools are off by default; turn on `writeEnabled` in configuration to enable them.
| Tool | Purpose |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `zotero_search` | Search papers by title, author, year, tag, or full text, with collection and tag filters |
| `zotero_browse` | Browse the library structure, including the collection tree, tag list, and saved searches |
| `zotero_get` | Read the metadata detail, abstract, attachments, and note list of a single paper |
| `zotero_children` | View the child items associated with a paper, including standalone notes, PDF attachments, and reading annotations |
| `zotero_retrieve` | Find passages relevant to a question in full text, notes, and annotations (annotations keep page numbers) |
| `zotero_changes` | Check recent additions, modifications, and deletions in the library |
| `zotero_attachment` | Get the local PDF file path associated with a paper |
| `zotero_export` | Generate formatted citations or a bibliography, or export BibTeX, RIS, or CSL JSON |
The fifteen write tools (notes, tags and collection membership, collections, items, saved searches, Trash restore, library-wide tags, and batch operations) are off by default. Once enabled they write only to the personal library, and every write needs approval. See the [tool reference](docs/tools.en.md) for the full contract of all 23 tools.
## Security and privacy
- The plugin sends requests only to the local Zotero API and does not call Zotero cloud services. External requests come only from the scholarly retrieval component, which is off by default.
- Write tools are disabled by default. Once enabled, every library modification shows an approval and plan review card and runs only after the user confirms it. Writes are not retried automatically.
- The plugin only resolves and validates local attachment paths. It runs no system commands and starts no background resident process.
## Documentation
### Usage
| Document | Covers |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [Getting started](docs/getting-started.en.md) | Installation, connection verification, and the first task |
| [Product model](docs/product-model.en.md) | Two entry points, three concepts, three components, and four boundaries |
| [Features](docs/features.en.md) | Conversation capabilities, the literature trail, the literature panel, writes, and scholarly retrieval |
| [Troubleshooting](docs/troubleshooting.en.md) | Common issues, diagnostic steps, and remedies |
### Maintenance
| Document | Covers |
| --------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [Architecture](docs/architecture.en.md) | Data flow, layer responsibilities, component boundaries, and design boundaries |
| [Tool reference](docs/tools.en.md) | Parameters, return values, and error codes for the 23 local tools and 7 scholarly tools |
| [Configuration reference](docs/configuration.en.md) | Fields, defaults, and hot-reload behavior of each settings namespace |
| [Development guide](docs/development.en.md) | Build, test, debug, and release workflow |
The acceptance scenarios ([docs/scenarios.en.md](docs/scenarios.en.md)) are for maintainers.
## License
[MIT](./LICENSE)
