| name | zotero |
| description | Manage the user's Zotero library — search papers, add/organize items, export citations, OCR PDFs, and run semantic search (RAG). Use whenever the user mentions Zotero, "我的文献库", finding/adding/citing papers, "参考文献", "文献综述", or wants to read/extract content from their PDFs. Requires Zotero desktop running with the zotron XPI plugin. Check with `zotron ping`. |
Zotero
Read-write bridge to the user's local Zotero library via the zotron CLI and Zotero-side XPI plugin.
Dependency: The zotron CLI must be on PATH, and Zotero desktop must be running with the XPI plugin installed.
Before your first CLI call, check:
command -v zotron — if missing, run /zotron:setup which handles the full install chain (cargo-binstall → GitHub Releases → mirror fallback → cargo install from source).zotron ping — if it fails, ask the user to start Zotero; if the XPI was never installed, run /zotron:setup
Do not curl HTTP endpoints directly; always use the zotron CLI.
Pick a workflow
| User intent | Workflow | Sub-file |
|---|
| Find / read papers, browse collections, get fulltext or annotations | search | search.md |
| Add by DOI/URL/ISBN/file, update metadata, manage collections & tags, dedupe | manage | manage.md |
| Generate references in GB/T 7714, BibTeX, RIS, CSL-JSON | export | export.md |
| OCR scanned/Chinese PDFs into hidden per-PDF raw/block/chunk sidecars | ocr | ocr.md |
| RAG retrieval hits for literature review / academic-zh span provenance | rag | rag.md |
A typical session chains them: search to locate papers → manage to organize → ocr + rag for literature review → export for citations.
CLI conventions
All commands use the zotron CLI with noun-verb structure:
zotron <namespace> <verb> [args] [--flags]
Typed subcommands cover normal operations — always prefer these over raw RPC:
zotron ping
zotron search "数字经济" --limit 10
zotron search "数字经济" --collection "宏观因子" --limit 10
zotron collections get-items "宏观因子" --limit 20
zotron items get YR5BUGHG
zotron items fulltext YR5BUGHG
zotron notes list --parent YR5BUGHG
zotron items attachments YR5BUGHG
zotron annotations list YR5BUGHG
zotron annotations create YR5BUGHG --quote "要高亮的文字"
zotron tags add YR5BUGHG --tag "已读"
zotron collections tree
zotron export YR5BUGHG
zotron settings list
zotron system schema
zotron system schema --type journalArticle
zotron system methods
Keys (primary): All item-scoped commands accept an 8-char item key (YR5BUGHG) as the primary identifier. RPC params use key/parentKey/keys — never id/parentId. Collections accept 8-char key or name ("数字经济").
Search vs collection browsing:
zotron search "关键词" searches the whole library.zotron search "关键词" --collection "集合名" searches only items in that collection.zotron search "关键词" --fulltext searches inside PDF content, not just metadata.zotron collections get-items "集合名" lists items in a collection; use this when the user asks "这个集合里有什么".zotron collections items "集合名" is an alias for get-items.
Filtering output: zotron outputs JSON. Pipe to jq for filtering. Many list/search commands return an envelope such as {"items":[...],"total":N}, so filter through .items[]:
zotron search "数字经济" | jq '.items[].title'
zotron collections get-items "宏观因子" | jq '.items[].title'
zotron collections tree | jq '.[] | {key, name}'
The CLI does not have built-in --jq; use external jq.
Discovery:
zotron --help — list all namespaceszotron <namespace> --help — list subcommands in a namespacezotron system methods — list all RPC methodszotron system methods items.get — describe a specific method's parameters
Web academic search
Search public academic databases and import papers:
zotron web search "query" [--limit N] [-s openalex|crossref|s2|arxiv]
zotron web fetch --doi 10.1038/xxx | zotron push
zotron web fetch --arxiv 2301.00001 | zotron push
Default source is OpenAlex (250M records). fetch cascades open-access PDF
resolvers (Unpaywall, DOAJ, CORE, fatcat, publisher-direct) and attaches the
PDF when one downloads. Optional keys live in Zotero Settings -> Zotron ->
Data Sources; everything works keyless.
