# ChatPapers

**Language / 语言**: [中文](readme.md) | English

An AI paper reading and summarization plugin for **Zotero 9**: chat with PDFs, generate summaries, compare multiple papers, listen to AI voice lectures, and save results as Zotero notes—all inside Zotero.

## Features

### Paper chat (ChatPapers)

- **ChatPapers** panel in the PDF / item sidebar
- One-click summary, add selection to context, streaming replies, stop generation
- Save replies as Zotero child notes
- Provider presets: **Ollama / LM Studio / OpenRouter / OpenAI / DeepSeek / SiliconFlow / Custom**
- Sidebar header: **Open in separate window**, **Adaptive height** (consistent with other Zotero plugins)

### Multi-paper comparison

- Start **Compare papers** from the main-window item context menu
- Add up to 8 papers for **Compare**, **Summarize each**, **Common themes**, and **Topic review**

### Voice lecture

- **Voice lecture** sidebar: one-click **Prepare** → listen to an AI walkthrough of the full paper
- **Overview**: segmented summary, play beat by beat
- **Paragraph reading**: original text first, then translation/explanation; switch **By paragraph** / **By sentence**
- **Highlight sync** in the PDF reader while playing (including multi-line selections)
- Typed Q&A with spoken answers; save lecture notes as Zotero child notes
- Configurable local TTS (e.g. Piper) and cloud TTS; optional MinerU path in preferences for structured PDF parsing

### Selection explain & read aloud

- After selecting text in a PDF, use **Explain** from the selection popup or sidebar
- AI generates syntax/terminology and context explanations, then reads original + translated/explained audio
- Reuses prepared lecture cache when the selection matches an already prepared sentence
- Sidebar also supports **Open in separate window** and **Adaptive height**

## Documentation

| Document | Description |
| --- | --- |
| [Requirements (zh-CN)](docs/requirements.md) | Product scope and acceptance criteria |
| [Development (zh-CN)](docs/development.md) | Architecture and developer guide |
| [Architecture & roadmap (zh-CN)](docs/newidea/) | Voice lecture and future capabilities |

## Development

```bash
npm install
npm run build    # outputs .scaffold/build/*.xpi
npm run start    # requires Zotero 9 locally; configure .env (see .env.example)
```

## Installation

1. Run `npm run build`
2. In Zotero: Tools → Add-ons → Install Add-on From File
3. Select `.scaffold/build/chatpapers.xpi` (exact filename may vary)

## Usage

### Paper chat

1. Preferences → ChatPapers: choose a Provider (e.g. Ollama) and set the model
2. Open a PDF or select an item, then open **ChatPapers** in the item pane sidebar
3. Ask questions or summarize → save replies as notes

### Multi-paper comparison

1. Select 2 or more items in the Zotero main window
2. Right-click → **ChatPapers: Compare papers**
3. Add papers, enter a topic, and use compare or review actions

### Voice lecture

1. Preferences → ChatPapers → **Voice lecture**: configure LLM and TTS; set MinerU path if you need structured PDF parsing
2. Open an item with a PDF attachment, then open **Voice lecture** in the sidebar
3. Click **Start preparation**, then choose overview or paragraph/sentence reading
4. The PDF highlights the current passage while audio plays

### Selection explain & read aloud

1. Select a sentence or paragraph in the PDF reader
2. Click **Explain** in the selection popup, or **Explain & read selection** in the **Voice lecture** sidebar
3. Wait for generation, then audio plays automatically; view details and replay from the sidebar

## Changelog

### Unreleased (main, after v0.2.1)

- **Voice lecture**: preparation, overview, paragraph/sentence reading, TTS playback, note export
- **PDF highlight sync**: highlight matching text while playing; fix multi-line selections only highlighting one line
- **Selection explain & read aloud**: PDF selection popup + sidebar; reuse prepared sentence cache when matched
- **Playback exclusivity**: fix overlapping audio for multi-sentence selections; stop audio when the pane is closed
- **Sidebar enhancements**: separate window and adaptive height for chat and voice lecture panes
- **Branding**: updated plugin logo

### v0.2.1

- Improved release workflow and installable `.xpi` packaging

### v0.2.0

- **Multi-paper comparison**: compare, summarize each, common themes, topic review (up to 8 papers)

### v0.1.0 (MVP)

- PDF / item sidebar chat, one-click summary, selection context, streaming replies
- Multiple Provider presets and preferences
- Save AI replies as Zotero child notes

## License

AGPL-3.0-or-later (based on [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template))