Getting Started
1. Install Official Workflow Packages
The plugin itself contains no business logic. After installing the plugin, you first need to install the official workflow packages:
- Right-click any Zotero item → Zotero Agents → 📦 Install Official Workflow Packages
- Wait for the download and installation to complete
- After successful installation, all official workflows will be visible in the Dashboard
You can also install or update the official packages at any time from Zotero → Settings → Zotero Agents.
2. Configure a Backend
ACP Backend (Recommended)
This is the most recommended approach — as long as you have any ACP-compatible agent tool installed on your machine, it requires zero additional configuration.
- Open Tools → Backend Manager
- Switch to the ACP tab
- Select your agent tool from the Add from Preset dropdown (Codex / OpenCode / Claude Code, etc.)
- The preset auto-fills the command; click Save in the bottom-right corner
First time using an agent tool? Refer to the official documentation of the respective tool for installation:
| Agent | Installation Guide |
|---|---|
| OpenCode | opencode.ai docs |
| Codex | OpenAI Codex docs |
| Claude Code | Anthropic docs |
| Gemini CLI | Google docs |
| Qwen Code | Alibaba Cloud docs |
→ See ACP Backend Configuration for details
MinerU Backend (for PDF Parsing)
The MinerU workflow can convert PDFs to Markdown, making it the ideal preprocessing step for all subsequent literature analysis. Configuration is straightforward:
- Visit mineru.net to register an account, and obtain an API Token from API → API Management
- Open Tools → Backend Manager
- Switch to the Generic HTTP tab, click Add Generic HTTP Profile from Preset, and choose
MinerU Official - Replace the token placeholder with your API Token and keep Timeout
600000 - Click Save in the bottom-right corner
→ See MinerU Usage Guide for details
Alternative: Docker-deployed Skill-Runner
If you need persistent background execution or LAN sharing, you can deploy Skill-Runner with Docker. After deployment, add a backend instance in the SkillRunner tab.
For detailed operation instructions, see Backend Manager.
3. Complete Workflow
Below is a complete end-to-end workflow. It is recommended to try each step in order. First, select a paper with a PDF attachment from your library.
Step 1: PDF → Markdown (MinerU)
Right-click this paper (or directly right-click its PDF attachment), and select Zotero Agents → MinerU. After a short wait, a .md file of the paper content will be generated in the same directory as the PDF.
Step 2: Try the Built-in Markdown Reader
Find the newly generated .md file in the Zotero attachment list and double-click to open it in the built-in reader — featuring outline navigation, search, math formula rendering, and code syntax highlighting. If you prefer not to use the built-in reader, you can disable it in Preferences and revert to the system default opener.
→ See Built-in Markdown Reader for details
Step 3: Run Literature Analysis
Right-click this paper (or directly right-click the .md attachment), and select Zotero Agents → Literature Analysis. The agent will automatically generate three artifacts; upon completion, three note attachments will appear under the item:
| Note | Content |
|---|---|
| Digest | Paper digest — research background, methods, results, and conclusions |
| References | Structured references — a tabular citation list |
| Citation Analysis | Citation analysis report — citation context and citation intent classification |
→ See Literature Analysis for details
Step 4: Interactive Literature Explainer
If you have any questions about this paper, right-click and select Zotero Agents → Literature Explainer. The sidebar will automatically open the chat panel, where you can freely converse with the agent about the paper's content. The agent's answers go through a verification gateway, so you don't need to worry about fabrication. After the conversation, the Q&A record will be generated as study notes.
→ See Literature Explainer for details
Step 5: Deep Reading
When you need to thoroughly and systematically read an important paper, right-click and select Zotero Agents → Deep Reading. The agent will produce a polished standalone HTML document — including section analysis, key concepts, references, and bilingual translations. Enriched with your library information (if available), this document will also carry the broader research context, related concepts, and key questions.
→ See Deep Reading for details
Step 6: Topic Synthesis — From Individual Papers to the Big Picture
Once your library has reached a certain size and the relevant papers have all undergone literature analysis and tag normalization, you can create a Topic Synthesis.
Run Create Topic Synthesis from the Dashboard, enter a description of your research direction, and the agent will automatically identify relevant papers in your library and generate an extremely rigorous, accurate, and comprehensive synthesis report. This report is written entirely based on your library content, far more precise and reliable than generic AI responses.
→ See Topic Synthesis for details
Next Steps
- Batch Processing: Run Literature Analysis on papers in your library in bulk to build the foundation for Synthesis
- Tag System: Use Tag Bootstrapper to create a controlled vocabulary and standardize your metadata
- Graph Exploration: Visualize your citation network in the Synthesis Workbench
- Custom Development: Refer to Custom Workflows to create your own workflows
- Report Issues: Report problems on GitHub or Gitee