# ChatPapers

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

面向 **Zotero 9** 的 AI 论文阅读与总结插件：在 Zotero 内对 PDF 文献对话、摘要、多篇对照，并提供 AI 语音伴读，把结果保存为笔记。

## 功能

### 论文对话（ChatPapers）

- PDF / 条目侧栏 **ChatPapers** 对话面板
- 一键总结、添加选区、流式回复、停止生成
- 保存为 Zotero 子笔记
- Provider 预设：**Ollama / LM Studio / OpenRouter / OpenAI / DeepSeek / 硅基流动 / 自定义**
- 侧栏标题栏：**在独立窗口中打开**、**自适应高度**（与 Zotero 其他插件一致）

### 多篇文献对照

- 从主窗口条目菜单发起 **多篇对照** 对话
- 支持添加最多 8 篇文献，进行 **对比差异**、**各自摘要**、**共同主题**、**主题综述**

### 语音伴读（Voice lecture）

- 条目侧栏 **语音伴读** 面板：一键 **备课** → 听 AI 讲解整篇论文
- **整体讲解**：分段概览，逐段播放
- **逐段精读**：先读原文、再听译文/讲解；可切换 **按段** / **按句** 粒度
- 播放时在 PDF 阅读器中 **高亮对应原文**（支持跨行选区）
- 文字提问，获得语音回答；可将伴读笔记写入 Zotero 子笔记
- 本地 TTS（如 Piper）与云端 TTS 可配置；偏好设置中可配置 MinerU 路径以启用 PDF 结构化解析

### 划句 / 划段 AI 伴读

- 在 PDF 中选中文本后，选区弹窗或侧栏可 **解释朗读**
- AI 生成句法/术语与上下文讲解，并朗读原文与中文讲解
- 若选区与已备课内容匹配，优先复用缓存，减少重复调用
- 侧栏同样提供 **在独立窗口中打开**、**自适应高度**

## 文档

| 文档 | 说明 |
| --- | --- |
| [需求文档](docs/requirements.md) | 产品范围与验收 |
| [开发文档](docs/development.md) | 技术架构与开发说明 |
| [架构与规划](docs/newidea/) | 语音伴读等后续能力设计 |

## 开发

```bash
npm install
npm run build    # 产出 .scaffold/build/*.xpi
npm run start    # 需本机已安装 Zotero 9，并配置 .env（见 .env.example）
```

## 安装

1. `npm run build`
2. 打开 Zotero → 工具 → 插件 → 从文件安装
3. 选择 `.scaffold/build/chatpapers.xpi`（文件名以构建产物为准）

## 使用

### 论文对话

1. 偏好设置 → ChatPapers：选择 Provider（如 Ollama）并填写模型
2. 打开 PDF 或选中条目，在条目面板侧栏进入 **ChatPapers**
3. 提问 / 总结 → 可将回复「保存为笔记」

### 多篇对照

1. 在 Zotero 主窗口选中 2 篇及以上文献
2. 右键 → **ChatPapers：多篇对照**
3. 在对话框中添加文献、输入主题，使用对比或综述功能

### 语音伴读

1. 偏好设置 → ChatPapers → **语音伴读**：配置 LLM、TTS 引擎；如需结构化 PDF 解析，填写 MinerU 路径
2. 打开带 PDF 的条目，侧栏进入 **语音伴读**
3. 点击 **开始备课**，完成后选择整体讲解或逐段/逐句精读播放
4. 播放过程中 PDF 会同步高亮当前段落

### 划句解释朗读

1. 在 PDF 阅读器中选中一句或一段文字
2. 在选区弹窗点击 **解释朗读**，或在 **语音伴读** 侧栏点击 **解释朗读选区**
3. 等待生成完成后自动播放；可在侧栏查看讲解详情并重播

## 更新日志

### Unreleased（main，v0.2.1 之后）

- **语音伴读**：备课、整体讲解、逐段/逐句精读、TTS 播放与笔记保存
- **PDF 同步高亮**：伴读播放时在阅读器中高亮对应原文，修复跨行选区只高亮一行的问题
- **划句/划段 AI 伴读**：PDF 选区解释朗读；侧栏与选区弹窗双入口；匹配已备课句子时复用缓存
- **播放互斥**：修复多句/多段选区解释时多路语音重叠播放；关闭面板时停止音频
- **侧栏增强**：对话与语音伴读面板支持独立窗口、自适应高度
- **品牌**：更新插件 Logo

### v0.2.1

- 发布流程与可安装 `.xpi` 包优化

### v0.2.0

- **多篇文献对照**：对比差异、各自摘要、共同主题、主题综述（最多 8 篇）

### v0.1.0（MVP）

- PDF / 条目侧栏对话、一键总结、选区提问、流式回复
- 多 Provider 预设与偏好设置
- 保存 AI 回复为 Zotero 子笔记

## 许可

AGPL-3.0-or-later（基于 [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template)）