Zotero Literature Visualizer

Zotero Literature Visualizer

Purpose

Turn either a local Zotero library or a research topic into a reproducible literature workspace containing normalized metadata, evidence-aware paper notes, a bilingual synthesis, and an offline interactive dashboard.

Bundled scripts perform deterministic collection, Zotero snapshot reading, metadata normalization, dashboard rendering, citation-network enrichment, and optional Zotero API writes. The agent remains responsible for scholarly judgment: relevance screening, evidence verification, full-text interpretation, taxonomy design, and paper-specific bilingual summaries.

Choose the workflow

Do not combine modes automatically. In particular, do not apply the discovery workflow's journal or date defaults to a user's existing Zotero library unless requested.

Non-negotiable rules

Privacy and portability

• Never place names, email addresses, institutional accounts, API keys, cookies, browser profiles, Zotero databases, PDFs, or local absolute paths inside this skill or a shareable archive.
• Keep run data outside the skill directory. Treat examples/demo-review as synthetic demonstration data only.
• Read Zotero through a temporary SQLite snapshot. Never edit zotero.sqlite directly.
• Read API keys only from ZOTERO_API_KEY or a user-supplied file outside the skill directory. Never print or commit them.
• Do not copy or upload a user's Zotero PDFs unless the user explicitly requests an authorized import or upload workflow.

Evidence integrity

• Never invent bibliographic fields, Impact Factors, CAS partitions, findings, methods, datasets, limitations, or citations.
• Distinguish full_text, abstract_only, and metadata_only evidence states.
• For a paper with a readable local PDF, derive the detailed card from the full text.
• Without a readable PDF, summarize only the abstract and label the evidence level clearly.
• If neither PDF text nor abstract is available, provide metadata only and state that no substantive summary was possible.
• Do not present search snippets, inferred labels, or generic templates as paper findings.

Access and selection

• Relevance and quality determine selection; open-access status must not affect ranking.
• Analyze PDFs already available locally to the user. This skill does not claim to download subscription PDFs or control authenticated browser sessions.
• Verify journal metrics from an official journal, publisher, Clarivate, or CAS source before displaying them as official.

Common output contract

Use a run directory outside the skill, normally <workspace>/literature-reviews/<topic-slug>/.

Expected core files:

• metadata/papers.json and metadata/papers.csv: normalized paper records.
• texts/: extracted PDF text when locally available.
• review-bilingual.md: Chinese-English synthesis grounded in the available evidence.
• relationship-map.md: theme-method relationships and research gaps.
• dashboard-spec.json: editable bilingual taxonomy and paper-card semantics.
• <dashboard-name>.html: offline interactive dashboard.

Optional files include metadata/citation-network.json, metadata/journal-if-evidence.csv, metadata/papers-to-zotero.json, update-digest.md, and Zotero write-back logs.

Paper-card contract

Each card should be paper-specific and bilingual. Include only claims supported by the available evidence:

1. Research question or purpose / 研究问题或目的
2. Method and study design / 方法与研究设计
3. Data, sample, case, or setting / 数据、样本、案例或场景
4. Main findings / 主要发现
5. Limitations / 局限
6. Relevance to the review / 与综述主题的关系
7. Evidence level / 证据层级

Do not mechanically translate the English abstract into every field. With a PDF, inspect the abstract, methods, results, discussion, and conclusion; with abstract-only evidence, use cautious language such as “the abstract reports”.

Minimal command patterns

Resolve <python> to a real Python 3.10+ interpreter and <skill-dir> to this skill directory.

Local Zotero library

powershellCopy code
& '<python>' '<skill-dir>\scripts\systematic_literature_review.py' zotero-import `
  --output-dir '<workspace>\literature-reviews\zotero-library' `
  --topic 'My Zotero Library' `
  --dashboard-name 'zotero-literature-dashboard'

Omit --limit for a final full-library run. Use --zotero-dir only when auto-discovery or ZOTERO_DATA_DIR does not locate the library.

Topic discovery

powershellCopy code
& '<python>' '<skill-dir>\scripts\systematic_literature_review.py' init-config `
  --topic '<topic>' --years 1 --min-if 5 `
  --output '<run-dir>\review-config.json'

& '<python>' '<skill-dir>\scripts\systematic_literature_review.py' collect `
  --config '<run-dir>\review-config.json' `
  --output-dir '<run-dir>' --max-results 120

Verify journal evidence before finalizing. See references/discovery-workflow.md.

Dashboard

powershellCopy code
& '<python>' '<skill-dir>\scripts\build_literature_dashboard.py' init-spec `
  --papers '<run-dir>\metadata\papers.json' `
  --output '<run-dir>\dashboard-spec.json'

& '<python>' '<skill-dir>\scripts\build_literature_dashboard.py' build `
  --papers '<run-dir>\metadata\papers.json' `
  --spec '<run-dir>\dashboard-spec.json' `
  --output-dir '<run-dir>' --dashboard-name 'literature-dashboard'

Use --inline for a single-file dashboard. Large libraries automatically use the scalable layout.

Completion checks

Before reporting completion:

• Confirm the intended library or search scope and final paper count.
• Spot-check titles, DOI values, authors, years, and resolved PDF paths.
• Confirm each detailed card's evidence level matches its source.
• Confirm Chinese and English content is meaningful, not duplicated placeholder text.
• Open the dashboard and test search, filters, paper details, PDF/Zotero links, reading status, stars, and notes.
• Verify no mojibake, broken assets, personal paths, credentials, or user data entered the skill directory.
• For Zotero writes, run a dry-run first and retain the write log.

Bundled resources

• scripts/systematic_literature_review.py: topic discovery, Zotero snapshot import, metadata normalization, queues, and exports.
• scripts/build_literature_dashboard.py: dashboard spec creation and rendering.
• scripts/large_library_dashboard.py: scalable layout for large libraries.
• scripts/dashboard_common.py: shared dashboard UI, bilingual controls, reading state, stars, notes, and exports.
• scripts/citation_network.py: OpenAlex-based in-collection citation enrichment.
• scripts/zotero_api_import.py: Zotero Web API import and dashboard write-back.
• scripts/zotero_link_items.py: local DOI/title matching to Zotero item keys.
• scripts/quick_validate.py: offline portability and smoke validation.
• references/reporting-template.md: final reporting structure.
• examples/demo-review/: synthetic sample data; never cite it as real research.

Validate this skill

powershellCopy code
& '<python>' '<skill-dir>\scripts\quick_validate.py' '<skill-dir>'

Run this before creating a release archive.