---
name: qqzot
description: Manage the user's Zotero literature database from Codex: search local Zotero items, generate and audit Zotero child-note AI literature notes, summarize selected Zotero papers into Markdown tables, export citation metadata, and provide Zotero-side inputs to QQnote, qqcites, and qqsci. Use when the user asks about Zotero item keys, Zotero child notes, Zotero Local API, missing AI notes, Zotero paper tables, Zotero metadata, or library-side citation inputs. This skill does not own Obsidian vault maintenance or manuscript writing.
---

# QQzot

Use this skill for Zotero-side literature operations. It owns Zotero item lookup,
metadata extraction, child-note generation, generated-note audits, Zotero paper
tables, and Zotero inputs for the user's QQ literature workflow.

Boundary:

- `qqzot`: Zotero library, Zotero item keys, Zotero child notes, Zotero metadata,
  local Zotero API, citation metadata exports, and Zotero-derived paper tables.
- `QQnote-skill`: Obsidian literature notes, vault organization, Markdown note
  cleanup, Dataview dashboards, and Obsidian presentation of literature notes.
- `qqcites`: sentence/claim-to-reference ranking, support grading, duplicate
  citation control, and citation verification.
- `qqsci`: manuscript writing, scientific logic, section structure, novelty,
  claim-evidence checks, and reviewer-risk audits.

## Requirements

- Zotero Desktop must be open.
- Zotero Local API must be available at `http://127.0.0.1:23119`.
- Default Obsidian vault, only when a script needs templates or an output path:
  `C:\Users\qyh15\Documents\Obsidian Vault`.
- `ZOTERO_API_KEY` is required only for Zotero Web API writes.
- LLM settings come from `AWESOMEGPT_API_KEY`, `AWESOMEGPT_BASE_URL`,
  `AWESOMEGPT_MODEL`, or AwesomeGPT preferences in the default Zotero profile.

Never store API keys in skill files, vault helpers, Git commits, zip files,
terminal output, or chat. If keys appear in logs or chat, tell the user to
rotate them.

## Workflow Decision

Use the smallest Zotero operation that answers the request:

1. Need AI child notes for Zotero items: run `generate_zotero_ai_note.py`.
2. Need to know which Zotero items lack generated notes: run
   `audit_zotero_ai_notes.py`.
3. Need a comparison table for selected Zotero papers: run
   `summarize_zotero_table.py`.
4. Need manuscript citations for a sentence or claim: hand candidates to
   `qqcites` after Zotero retrieval.
5. Need Obsidian note organization, cleanup, or Dataview: hand off to
   `QQnote-skill`.

## Generate Zotero AI Child Notes

State clearly before live writes that Zotero child notes will be created.
Use `--dry-run` for first-time validation or template changes.

Single item:

```powershell
py "$env:USERPROFILE\.codex\skills\qqzot\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --skip-existing
```

Multiple items:

```powershell
py "$env:USERPROFILE\.codex\skills\qqzot\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-keys "SXAIQUJT X7GJZ627 ZCZXGRAM" --limit 0 --skip-existing --fulltext-chars 4000
```

Whole library:

Use only after the user explicitly approves library-wide writes.

```powershell
py "$env:USERPROFILE\.codex\skills\qqzot\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --all --limit 0 --skip-existing --fulltext-chars 4000
```

For long runs, prefer 20-30 item batches. If a run times out, rerun with
`--skip-existing`; duplicate detection uses the Zotero item link inside child
notes.

## Audit Missing Generated Notes

This is deterministic library comparison. Do not use DeepSeek or another LLM to
decide whether notes are missing.

```powershell
py "$env:USERPROFILE\.codex\skills\qqzot\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --rebuild
py "$env:USERPROFILE\.codex\skills\qqzot\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
```

The cache lives at:

```text
<vault>\00 Templater\.zotero-ai-notes-index.json
```

Use `--refresh` or `--rebuild` when notes were edited outside this workflow.

## Summarize Zotero Papers Into A Table

Use this for one paper or a batch of papers when the user wants a compact
comparison table for Obsidian, Word, qqcites, or qqsci.

```powershell
py "$env:USERPROFILE\.codex\skills\qqzot\scripts\summarize_zotero_table.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-keys "SXAIQUJT X7GJZ627 ZCZXGRAM" --batch-size 3 --out "C:\Users\qyh15\Documents\Obsidian Vault\99 项目\文献对比表.md"
```

Rules:

- This workflow reads Zotero Local API plus LLM config, but does not create
  Zotero child notes.
- Prefer 3-10 papers per batch to keep tables accurate and readable.
- Use custom columns when the user asks for a specific comparison axis.
- If `--out` is omitted, print the Markdown table to stdout.

## Operating Rules

- Prefer Zotero item keys, DOI, title, first author, and year as metadata anchors.
- Do not delete duplicate Zotero notes unless the user explicitly requests
  cleanup.
- Do not add visible machine markers to note bodies.
- Reserve DeepSeek for note content generation or summarization, not
  deterministic library audits.
- If PDF full text is unavailable, fall back to metadata, abstract, BibTeX, and
  optional local PDF extraction if a Python PDF library exists.
- If PowerShell output has Unicode issues, set `PYTHONIOENCODING=utf-8` or rely
  on the scripts' UTF-8 handling.