Preface

In the DSH plugin-based workflow, Agents often need to answer research questions based on local literature. Relying solely on context or model memory often lacks verifiable sources; manually opening Zotero to copy abstracts and citations can interrupt the conversation flow.

dsh-zotero is a DSH plugin designed to connect the local Zotero library with the Agent: searching literature, reading metadata and notes, extracting evidence passages based on queries, and generating citations.

What is This

The dsh-zotero repository is Vncntvx/dsh-zotero, licensed under MIT. It solves the problem of enabling the Agent to directly access papers, abstracts, notes, annotations, and attachments in the local literature library, and then organize relevant evidence into citable output.

Core Capabilities

The following capabilities are read-only for the local literature library and do not modify items, notes, tags, or collections.

  1. Search Literature: Search by title, author, year, supporting library, collection, savedSearch, and publications scopes; everything mode also includes full-text indexing.

  2. Browse Library Structure: Discover libraries, collection trees, saved searches, tag facets, item types, and their fields.

  3. Read Individual Literature: Read metadata for a single item; can return notes, annotations, and attachment lists; fields:"all" preserves all metadata.

  4. Explore Sub-objects: View notes and attachments directly linked to an item, as well as annotations attached under PDFs.

  5. Extract Evidence: Return the most relevant evidence passages based on query terms, which can include annotations, notes, abstracts, and full text; supports multi-attachment retrieval.

  6. Incremental Awareness: Based on local transaction versions, determine which items, collections, or full-text indexes have changed, and what has been deleted.

  7. Locate Attachments: Parse an item ref into a validated disk path or link URL.

  8. Export Citations: Generate citations, reference lists, BibTeX, BibLaTeX, RIS, CSL JSON.

Installation and Enabling

First, execute the plugin installation command:

dsh plugin --profile <name> add dsh-zotero

After installation, restart DSH and start a new session. The Agent will then be able to use the Zotero tool.

The plugin provides a configuration card in Settings -> Plugins. The only write operation by the plugin is after saving the configuration card, which writes to:

$DSH_HOME/settings.yaml

under the zotero: user layer. Configuration changes are hot-reloaded upon saving, without requiring a restart; after installing or uninstalling the plugin, you need to restart DSH and start a new session.

Typical Usage

The following explains the invocation method based on a common research workflow.

First, search for journal articles related to Risk:

zotero_search(query: "Risk", itemType: "journalArticle")

This step returns matching literature results.

Read the abstract field of the 1st literature item:

zotero_get(ref: 1, fields: ["abstractNote"])

This step retrieves only the specified field, making it easy to use the abstract as subsequent context.

Extract evidence passages around methodology:

zotero_retrieve(query: "methodology", sources: ["fulltext", "notes"])

This step searches for passages related to the query term in full text and notes.

Export three literature items as BibTeX:

zotero_export(refs: [1,2,3], format: "bibtex")

The exported result is static text and needs to be manually copied to the target location.

Use Cases and Limitations

It is suitable for Agent workflows that use the local Zotero literature library as an evidence source, such as finding papers, verifying abstracts, finding evidence in notes and annotations, and generating references.

Please note:

  • Network requests are only sent to http://127.0.0.1:23119/api, without following redirects; resolveConfig forces the loopback address.
  • File access is read-only; zotero_attachment uses existsSync to validate attachment paths returned by Zotero, without writing to the file system.
  • The plugin does not execute shell commands, load native modules, or start resident processes.
  • Evidence ranking is based on BM25, sorted by the word frequency match between the query term and the passage.
  • Full-text evidence relies on Zotero indexing; PDFs that are not indexed cannot provide full-text passages.
  • After zotero_attachment returns the file location, the host must have the corresponding capability to continue reading PDFs.

Since the plugin runs according to the current DSH process permissions, it is recommended to check the source code and MIT license before installation.

Conclusion

dsh-zotero integrates the steps of “finding papers, reading abstracts, extracting annotations, and exporting citations” into the Agent workflow, suitable for scenarios requiring local literature evidence and citable output.

GitHub: https://github.com/Vncntvx/dsh-zotero