docs: expand README with features, changelog, and English version.

Document voice lecture, selection explain, multi-paper compare, and link between zh-CN and English readme files. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-29 23:31:34 +08:00
parent 0fcc662464
commit 36b806378f
2 changed files with 189 additions and 2 deletions
@@ -0,0 +1,114 @@
+# 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))
@@ -1,13 +1,39 @@
 # ChatPapers

-面向 **Zotero 9** 的 AI 论文阅读与总结插件：在 Zotero 内对 PDF 文献对话、摘要，并把结果保存为笔记。
+**语言 / Language**: 中文 | [English](readme.en.md)

-## 功能（MVP）
+面向 **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 生成句法/术语与上下文讲解，并朗读原文与中文讲解
+- 若选区与已备课内容匹配，优先复用缓存，减少重复调用
+- 侧栏同样提供 **在独立窗口中打开**、**自适应高度**

 ## 文档

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

 ## 开发

@@ -32,10 +59,56 @@ npm run start    # 需本机已安装 Zotero 9，并配置 .env（见 .env.examp

 ## 使用

+### 论文对话
+
 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)）