zotpilot

Category: Tools & Productivity | Uploader: xunhe730 | Downloads: 0 | Version: v1.0（Latest）

Changelog: Source: GitHub https://github.com/xunhe730/ZotPilot

Directory Structure

Current level: tree/main/

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 553 B
  - 📄 release.yml 1.4 KB
📁 assets/
- 📄 banner.jpg 202.7 KB
- 📄 zotero-api-key.png 91.0 KB
📁 config/
- 📄 zotpilot.example.toml 469 B
📁 docs/
- 📄 supported-clients.md 1.4 KB
- 📄 tools-reference.md 3.4 KB
📁 references/
- 📄 setup-guide.md 5.9 KB
- 📄 tool-guide.md 8.6 KB
- 📄 troubleshooting.md 4.7 KB
📁 scripts/
- 📄 platforms.py 21.5 KB
- 📄 run.py 9.8 KB
📁 src/
- 📁 zotpilot/
  - 📁 data/
    
    📄 journal_overrides.csv 253 B
    
    📄 scimago_quartiles.csv 2.1 KB
  - 📁 embeddings/
    
    📄 __init__.py 1.8 KB
    
    📄 base.py 340 B
    
    📄 dashscope.py 5.4 KB
    
    📄 gemini.py 5.2 KB
    
    📄 local.py 1.3 KB
  - 📁 feature_extraction/
    
    📁 methods/
    
    📄 __init__.py 0 B
    
    📄 figure_detection.py 15.5 KB
    
    📁 paddle_engines/
    
    📄 __init__.py 183 B
    
    📄 paddleocr_vl.py 10.5 KB
    
    📄 pp_structure.py 9.2 KB
    
    📁 postprocessors/
    
    📄 __init__.py 0 B
    
    📄 cell_cleaning.py 6.2 KB
    
    📄 __init__.py 482 B
    
    📄 captions.py 11.5 KB
    
    📄 debug_db.py 5.7 KB
    
    📄 local_vision_api.py 8.3 KB
    
    📄 paddle_extract.py 7.1 KB
    
    📄 vision_api.py 13.4 KB
    
    📄 vision_extract.py 27.6 KB
  - 📁 pdf/
    
    📄 __init__.py 342 B
    
    📄 chunker.py 2.9 KB
    
    📄 extractor.py 62.2 KB
    
    📄 orphan_recovery.py 11.5 KB
    
    📄 reference_matcher.py 3.6 KB
    
    📄 section_classifier.py 2.7 KB
  - 📁 tools/
    
    📄 __init__.py 173 B
    
    📄 admin.py 5.8 KB
    
    📄 citations.py 3.0 KB
    
    📄 context.py 6.6 KB
    
    📄 indexing.py 6.4 KB
    
    📄 ingestion.py 9.7 KB
    
    📄 library.py 5.1 KB
    
    📄 search.py 19.2 KB
    
    📄 write_ops.py 6.3 KB
  - 📄 __init__.py 394 B
  - 📄 __main__.py 108 B
  - 📄 _platforms.py 22.3 KB
  - 📄 bridge.py 7.2 KB
  - 📄 cli.py 41.8 KB
  - 📄 config.py 9.0 KB
  - 📄 crossref_client.py 4.5 KB
  - 📄 doctor.py 7.3 KB
  - 📄 filters.py 3.9 KB
  - 📄 identifier_resolver.py 8.2 KB
  - 📄 indexer.py 24.8 KB
  - 📄 interfaces.py 3.6 KB
  - 📄 journal_ranker.py 8.7 KB
  - 📄 models.py 16.2 KB
  - 📄 openalex_client.py 5.5 KB
  - 📄 py.typed 0 B
  - 📄 reranker.py 7.8 KB
  - 📄 result_utils.py 2.8 KB
  - 📄 retriever.py 3.0 KB
  - 📄 server.py 352 B
  - 📄 state.py 11.7 KB
  - 📄 vector_store.py 13.7 KB
  - 📄 zotero_api_reader.py 2.0 KB
  - 📄 zotero_client.py 49.2 KB
  - 📄 zotero_detector.py 4.9 KB
  - 📄 zotero_writer.py 9.9 KB
📁 tests/
- 📄 __init__.py 0 B
- 📄 conftest.py 3.2 KB
- 📄 test_advanced_search.py 17.7 KB
- 📄 test_annotations.py 3.6 KB
- 📄 test_bridge.py 5.2 KB
- 📄 test_cache.py 2.1 KB
- 📄 test_chunker.py 3.2 KB
- 📄 test_cli_config.py 7.1 KB
- 📄 test_cli_update.py 29.0 KB
- 📄 test_collection_items.py 5.7 KB
- 📄 test_config.py 11.6 KB
- 📄 test_crossref_client.py 10.1 KB
- 📄 test_doctor.py 12.6 KB
- 📄 test_embedder.py 2.1 KB
- 📄 test_feeds.py 6.3 KB
- 📄 test_identifier_resolver.py 15.9 KB
- 📄 test_indexer.py 2.9 KB
- 📄 test_indexer_import.py 252 B
- 📄 test_journal_ranker.py 3.6 KB
- 📄 test_library_filter.py 13.4 KB
- 📄 test_no_rag.py 9.0 KB
- 📄 test_notes.py 11.0 KB
- 📄 test_reranker.py 4.0 KB
- 📄 test_retriever.py 4.5 KB
- 📄 test_section_classifier.py 3.6 KB
- 📄 test_state.py 8.6 KB
- 📄 test_switch_library.py 7.5 KB
- 📄 test_tools.py 4.6 KB
- 📄 test_tools_ingestion.py 17.6 KB
- 📄 test_tools_search.py 4.6 KB
- 📄 test_tools_write_batch.py 3.9 KB
- 📄 test_translation_removed.py 1.7 KB
- 📄 test_vector_store.py 2.3 KB
- 📄 test_zotero_client.py 5.8 KB
- 📄 test_zotero_detector.py 3.6 KB
📄 .env.example 340 B
📄 .gitignore 343 B
📄 .python-version 5 B
📄 ARCHITECTURE.md 4.2 KB
📄 CHANGELOG.md 8.4 KB
📄 CLAUDE.md 6.4 KB
📄 CODE_OF_CONDUCT.md 947 B
📄 CONTRIBUTING.md 1.5 KB
📄 LICENSE 1.0 KB
📄 pyproject.toml 2.7 KB
📄 README.md 21.6 KB
📄 README_EN.md 22.1 KB
📄 SECURITY.md 2.0 KB
📄 SKILL.md 5.4 KB
📄 uv.lock 927.8 KB

SKILL.md

---
name: zotpilot
description: >-
  Use when user mentions Zotero, academic papers, citations,
  literature reviews, research libraries, or wants to search/organize their
  paper collection. Also triggers on "find papers about...", "what's in my
  library", "organize my papers", "who cites...", "tag these papers".
  Always use this skill for Zotero-related tasks.
license: MIT
compatibility:
  - Python 3.10+
  - Zotero desktop (installed and run at least once)
---

# ZotPilot

> All script paths are relative to this skill's directory.

## Step 1: Check readiness

**Python command:** Use `python3` on Linux/macOS. On Windows, use `python`.

Run: `python3 scripts/run.py status --json`  (Windows: `python scripts/run.py status --json`)

Parse the JSON output and follow the FIRST matching branch:

1. Command fails entirely → **Prerequisites** (see `references/setup-guide.md`)
2. `config_exists` is false → **First-Time Setup** (see `references/setup-guide.md`)
3. `errors` is non-empty → **First-Time Setup** (note: `warnings` like API key not in env are OK if key was passed to `register`)
4. `index_ready` is false or `doc_count` is 0 → go to **Index** below
5. All green → go to **Research**

**Inline fallback** (if agent cannot access references/):
```bash
python3 scripts/run.py setup --non-interactive --provider gemini
python3 scripts/run.py register
# Restart your AI agent, then ask again.
```

If any errors: run `python3 scripts/run.py doctor` for diagnostics.

## Index (if doc_count = 0)

MCP tools are now available. Index the user's papers:

```bash
python3 scripts/run.py index
```

Indexing takes ~2-5 seconds per paper. Documents over 40 pages are skipped by default.
After indexing, check for "Skipped N long documents" — offer to index them with `--max-pages 0`.

## Research (daily use)

### Tool selection — pick the RIGHT tool first

| User intent | Tool | Key params |
|---|---|---|
| Find specific passages or evidence | `search_papers` | `query`, `top_k=10`, `section_weights`, `required_terms` |
| Survey a topic / "what do I have on X" | `search_topic` | `query`, `num_papers=10` |
| Find a known paper by name/author | `search_boolean` | `query`, `operator="AND"` |
| Find data tables | `search_tables` | `query` |
| Find figures | `search_figures` | `query` |
| Read more context around a result | `get_passage_context` | `doc_id`, `chunk_index`, `window=3` |
| See all papers | `get_library_overview` | `limit=100`, `offset=0` |
| Paper details | `get_paper_details` | `item_key` |
| Who cites this? | `find_citing_papers` | `doc_id` |
| Tag/organize one paper | `add_item_tags`, `add_to_collection` | `item_key` |
| Batch tag/organize many papers | `batch_tags`, `batch_collections` | `items` or `item_keys`, `action` |
| Search external databases for new papers | `search_academic_databases` | `query`, `limit=20` |
| Add a paper by DOI/arXiv/URL | `add_paper_by_identifier` | `identifier` |
| Batch add papers from search results | `ingest_papers` | `papers` (from search_academic_databases) |

### Workflow chains

**Literature review:**
search_topic → get_paper_details (top 5) → find_references → search_papers with section_weights

**"What do I have on X?":**
search_topic(num_papers=20) → report count, year range, key authors, top passages

**Organize by theme (batch):**
search_topic → create_collection → batch_collections(action="add", item_keys=[...]) → batch_tags(action="add", items=[...])

**Find specific paper:**
search_boolean first (exact terms) → fallback to search_papers (semantic) → get_paper_details

**Find and add new papers:**
search_academic_databases → review candidates with user → ingest_papers → index_library

**Organize library (classification advisor):**
get_library_overview + list_collections + list_tags → analyze themes via
search_topic → diagnose issues (uncategorized papers, inconsistent tags,
oversized collections) → propose collection hierarchy + tag normalization
→ interview user for confirmation → batch_collections + batch_tags(add/remove) to execute

### Output formatting

- Lead with paper title, authors, year, citation key
- Quote the relevant passage directly
- Include page number and section name
- Group results by paper, not by chunk
- Render table content as markdown tables
- NEVER dump raw JSON to the user

### Error recovery

| Error | Fix |
|---|---|
| Empty results | Try broader query, or `search_boolean` for exact terms. Check `get_index_stats` |
| "GEMINI_API_KEY not set" | Expected if key was passed to `register`. Only re-run setup if provider is wrong |
| "ZOTERO_API_KEY not set" | Write ops need Zotero Web API credentials — see `references/setup-guide.md` |
| "Document has no DOI" | Cannot use citation tools for this paper |
| "No chunks found" | Paper not indexed — run `index_library(item_key="...")` |

### Write operations (tags, collections)

Write tools require Zotero Web API credentials (`ZOTERO_API_KEY` + `ZOTERO_USER_ID`).
If missing, see **Configure Zotero Web API** in `references/setup-guide.md`.

**Single-item:** `add_item_tags`, `set_item_tags`, `remove_item_tags`, `add_to_collection`, `remove_from_collection`, `create_collection`

**Batch (max 100 items):** `batch_tags(action="add|set|remove")`, `batch_collections(action="add|remove")`
Partial failures are reported per-item without rollback.

For detailed parameter reference, see `references/tool-guide.md`.
For common issues and fixes, see `references/troubleshooting.md`.

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

zotpilot

Directory Structure

SKILL.md

Report

Notice