增加语音对话功能

docs/newidea/DUAL_MODE_ARCHITECTURE.md

@@ -0,0 +1,944 @@
+# ChatPapers 双模式集成架构设计
+
+| 字段 | 内容 |
+|------|------|
+| 产品名称 | ChatPapers for Zotero |
+| 文档名称 | 双模式集成架构（方案 A） |
+| 文档版本 | v0.1 |
+| 状态 | 草案 |
+| 目标平台 | Zotero 9（macOS / Windows） |
+| 关联文档 | [双模式 PRD](./DUAL_MODE_PRD.md)、[开发文档](../development.md)、[BanDu 架构参考](./ARCHITECTURE.md) |
+
+> **本文档定位**：描述 ChatPapers 插件在保留**文字对话**能力的基础上，扩展**语音伴读**（备课 → 听课 → 语音问答）的架构设计。  
+> 产品统一品牌为 **ChatPapers**；两种模式是同一条「与论文对话」产品线的不同交互形态——文字即时聊 vs 语音系统讲。
+
+---
+
+## 1. 架构概述
+
+### 1.1 架构演进
+
+```
+v0.2（当前）                         v1.0（目标）
+─────────────────                   ─────────────────────────────────
+ChatPapers 插件                      ChatPapers 插件（单一 .xpi）
+  └── 文字对话 pane                    ├── 文字对话 pane（已有）
+      PDFWorker 纯文本                   │     即时问答 / 总结 / JSON 会话
+      LLM 流式                           │
+      sessions/*.json                    └── 语音伴读 pane（新增）
+                                             MinerU 段落树
+                                             Lecture 备课 + TTS + 播放器
+                                             SQLite + mp3 缓存
+                                         共享：LLM · PDF 附件 · 笔记 · BibTeX
+```
+
+### 1.2 架构风格
+
+**Local-first 双模式插件架构**：核心计算与缓存均在用户机器完成；仅将段落文本与用户问题发送至用户配置的 LLM / TTS 服务。无自建后端。
+
+### 1.3 设计原则
+
+| 原则 | 说明 |
+|------|------|
+| 单一插件、两种对话形态 | 文字对话与语音伴读并存，共享 LLM 与 Zotero 集成 |
+| 模块隔离 | 语音模块不侵入文字对话代码路径 |
+| 备课一次、缓存复用 | Lecture 持久化；attachment ID + 文件哈希为缓存键 |
+| 增量交付 | 摘要 → beats → 逐段 → TTS 分阶段就绪 |
+| UI / 领域 / 集成 分离 | 降低 Zotero API 变动影响 |
+| Grounding 优先 | 生成内容必须可追溯到段落 ID |
+| 优雅降级 | refs 无效、无 timestamps、无 BBT 均有 fallback |
+
+### 1.4 系统上下文
+
+```
+                         ┌─────────────────┐
+                         │      用户        │
+                         └────────┬────────┘
+                                  │
+                   ┌──────────────▼──────────────┐
+                   │     Zotero 9（宿主）         │
+                   │  ┌────────────────────────┐ │
+                   │  │   ChatPapers 插件       │ │
+                   │  │ ┌──────────┬─────────┐ │ │
+                   │  │ │文字对话   │语音伴读  │ │ │
+                   │  │ │ ChatView │LectureUI│ │ │
+                   │  │ └────┬─────┴────┬────┘ │ │
+                   │  │      │  Shared   │      │ │
+                   │  │      └─────┬─────┘      │ │
+                   │  └────────────┼────────────┘ │
+                   └───────────────┼──────────────┘
+                                   │
+         ┌─────────────────────────┼─────────────────────────┐
+         │                         │                         │
+         ▼                         ▼                         ▼
+  ┌─────────────┐          ┌─────────────┐          ┌─────────────┐
+  │ Zotero      │          │ LLM API     │          │ TTS API     │
+  │ PDFWorker   │          │ / Ollama    │          │ 火山/Azure等 │
+  │ MinerU      │          │ （共享）     │          │（语音模式）  │
+  └─────────────┘          └─────────────┘          └─────────────┘
+         │
+         ▼
+  ┌─────────────────────────────────────┐
+  │ {Profile}/chatpapers/               │
+  │   sessions/*.json    ← 文字对话      │
+  │   lecture/lecture.db ← 语音伴读      │
+  │   lecture/audio/                     │
+  └─────────────────────────────────────┘
+```
+
+### 1.5 两种对话形态对比
+
+| 维度 | 文字对话（已有） | 语音伴读（新增） |
+|------|------------------|------------------|
+| 用户意图 | 「我现在想问什么」 | 「请 AI 先读完再给我讲」 |
+| 交互 | 打字 → 文字流式回复 | 听课 → 打字提问 → 文字 + 语音回复 |
+| PDF 输入 | PDFWorker 整篇纯文本 | MinerU 结构化段落树 |
+| LLM 用法 | 每轮即时组装 context | 一次性备课 + 按需问答 |
+| 持久化 | `sessions/{itemKey}.json` | `lecture/lecture.db` + mp3 |
+| TTS | 无 | 讲解 + 问答回答均支持 |
+| 笔记 | `ChatPapers:` 前缀 | `ChatPapers 伴读报告:` 前缀 |
+
+---
+
+## 2. 整体分层架构
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    Presentation Layer（表现层）                    │
+│  【文字】chatView.ts · multiChatView.ts · readerPane (Chat sec)   │
+│  【语音】lecturePane.ts · player/ · libraryWindow.ts（P1）         │
+│  【共享】prefs.ts · preferences.xhtml                            │
+└───────────────────────────────┬──────────────────────────────────┘
+                                │
+┌───────────────────────────────▼──────────────────────────────────┐
+│              Application Layer（应用层 / 用例）                    │
+│  【文字】buildChatMessages · buildMultiChatMessages（已有）        │
+│  【语音】PrepareLectureUseCase · PlayUseCase                      │
+│         AskQuestionUseCase · GenerateReportUseCase               │
+└───────────────────────────────┬──────────────────────────────────┘
+                                │
+┌───────────────────────────────▼──────────────────────────────────┐
+│                   Domain Layer（领域层）                            │
+│  【文字】ChatMessage · ExtractResult（已有）                        │
+│  【语音】PaperCache · Paragraph · Chapter · Lecture · Beat         │
+│         ParagraphExplanation · QARecord · Progress · Highlight     │
+│         LecturePreparationState · PlayerState                      │
+└───────────────────────────────┬──────────────────────────────────┘
+                                │
+┌───────────────────────────────▼──────────────────────────────────┐
+│              Infrastructure Layer（基础设施层）                    │
+│  ┌─ 共享 ─────────────────────────────────────────────────────┐  │
+│  │ llm/client · llm/providers · zotero/notes · zotero/citeExport│  │
+│  │ pdf/extractor (附件定位) · pdf/selection · utils/*          │  │
+│  └────────────────────────────────────────────────────────────┘  │
+│  ┌─ 文字专属 ─────────────────────────────────────────────────┐  │
+│  │ pdf/context · pdf/multiContext · storage/sessions           │  │
+│  └────────────────────────────────────────────────────────────┘  │
+│  ┌─ 语音专属 ─────────────────────────────────────────────────┐  │
+│  │ lecture/infrastructure/pdf (MinerU) · tts/ · storage/sqlite │  │
+│  │ lecture/infrastructure/rag · audioStorage · promptRegistry  │  │
+│  └────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 现有代码映射
+
+### 3.1 共享层（已实现，语音模式直接复用）
+
+| 模块路径 | 职责 | 文字对话 | 语音伴读 |
+|----------|------|:--------:|:--------:|
+| `src/hooks.ts` | 生命周期、注册入口 | ✓ | 扩展注册 |
+| `src/modules/ui/readerPane.ts` | Item pane section 注册 | ✓ | 扩展第二 section |
+| `src/modules/llm/client.ts` | LLM 流式请求 | ✓ | ✓ 备课 + 问答 |
+| `src/modules/llm/providers.ts` | Provider 预设 | ✓ | ✓ 只读共享 prefs |
+| `src/modules/llm/types.ts` | ChatMessage 等类型 | ✓ | 问答层可复用类型 |
+| `src/modules/pdf/extractor.ts` | PDF 附件定位 | ✓ | ✓ 路径 + 扩展 hash |
+| `src/modules/pdf/selection.ts` | Reader 选区 | ✓ | ✓ 「解释这句」 |
+| `src/modules/zotero/notes.ts` | 子笔记创建 | ✓ | ✓ 伴读报告 |
+| `src/modules/zotero/citeExport.ts` | BibTeX 导出 | ✓ | ✓ 参考文献卡片 |
+| `src/utils/markdown.ts` | Markdown 渲染 | ✓ | ✓ 报告预览 |
+| `src/utils/prefs.ts` | Preference 读写 | ✓ | ✓ 扩展 TTS prefs |
+| `src/utils/abort.ts` | 请求取消 | ✓ | ✓ |
+
+### 3.2 文字对话专属（已实现，语音模式不得引用）
+
+| 模块路径 | 职责 |
+|----------|------|
+| `src/modules/ui/chatView.ts` | 文字对话 UI |
+| `src/modules/ui/multiChatView.ts` | 多 PDF 联合对话 |
+| `src/modules/pdf/context.ts` | 单篇 context 组装 |
+| `src/modules/pdf/multiContext.ts` | 多篇 context 组装 |
+| `src/modules/llm/prompts.ts` | 文字对话 system / summary prompt |
+| `src/modules/llm/history.ts` | 论文材料持久化到消息历史 |
+| `src/modules/storage/sessions.ts` | JSON 会话文件 |
+
+### 3.3 语音伴读新建（`src/modules/lecture/`）
+
+| 模块 | 职责 |
+|------|------|
+| `lecture/ui/lecturePane.ts` | Item pane「语音伴读」section |
+| `lecture/ui/playerController.ts` | 播放状态机 + `<audio>` |
+| `lecture/ui/unitList.ts` | beats / 段落列表 |
+| `lecture/ui/qaPanel.ts` | 锚定提问 + 流式 + 重播 |
+| `lecture/application/prepareLecture.ts` | 备课流水线编排 |
+| `lecture/application/playLecture.ts` | 播放 / 跳播 / 断点 |
+| `lecture/application/askQuestion.ts` | 锚定问答 + RAG |
+| `lecture/application/generateReport.ts` | 报告组装 + Note 回写 |
+| `lecture/domain/*` | 领域实体与状态机 |
+| `lecture/infrastructure/pdf/parser.ts` | MinerU 封装 |
+| `lecture/infrastructure/pdf/fileHash.ts` | SHA-256 |
+| `lecture/infrastructure/tts/client.ts` | TTS 多提供商 |
+| `lecture/infrastructure/tts/providers.ts` | TTS 预设 |
+| `lecture/infrastructure/storage/repository.ts` | SQLite CRUD |
+| `lecture/infrastructure/storage/audioStorage.ts` | mp3 路径管理 |
+| `lecture/infrastructure/rag/index.ts` | FTS5 段落检索 |
+| `lecture/infrastructure/llm/lecturePrompts.ts` | 备课 / beats / 三层讲解 prompt |
+| `lecture/infrastructure/events.ts` | EventBus |
+
+---
+
+## 4. 依赖规则
+
+```
+                    ┌─────────────┐
+                    │   utils/    │
+                    └──────┬──────┘
+                           │
+          ┌────────────────┼────────────────┐
+          │                │                │
+          ▼                ▼                ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────┐
+    │   llm/   │    │ pdf/ext  │    │ zotero/  │
+    └────┬─────┘    └────┬─────┘    └────┬─────┘
+         │               │               │
+    ┌────┴───────┐       │          ┌────┴─────┐
+    │            │       │          │          │
+    ▼            ▼       ▼          ▼          ▼
+ chatView   multiChat  selection  notes   citeExport
+ (文字 UI)   (文字 UI)              (共享)
+
+ lecture/* ──可引用──► llm/, pdf/extractor, pdf/selection, zotero/, utils/
+
+ chatView / multiChat / context / sessions ──禁止引用──► lecture/*
+ lecture/* ──禁止引用──► chatView, context, sessions, multiContext
+```
+
+**运行时隔离**：两个 pane 的 `onAsyncRender` 各自实例化 View，异常在 View 边界捕获，不向上冒泡至 `hooks.ts` 导致整个插件失效。
+
+---
+
+## 5. 启动与注册流程
+
+```typescript
+// hooks.ts（目标形态，伪代码）
+async function onStartup() {
+  await Promise.all([Zotero.initializationPromise, ...]);
+
+  initLocale();
+  registerPrefs();           // 扩展 TTS / 教师风格分组
+  registerChatPane();        // 已有：文字对话 section
+  registerLecturePane();     // 新增：语音伴读 section
+  registerReaderSelectionHook();
+
+  addon.data.initialized = true;
+}
+```
+
+```typescript
+// readerPane.ts 扩展策略
+export function registerChatPane() { /* 现有，不动 */ }
+
+export function registerLecturePane() {
+  Zotero.ItemPaneManager.registerSection({
+    paneID: "chatpapers-lecture",
+    pluginID: config.addonID,
+    header: { l10nID: "chatpapers-item-section-lecture-head", ... },
+    onItemChange: ({ item, setEnabled }) => {
+      setEnabled(Boolean(item && findPdfAttachment(item)));
+    },
+    onAsyncRender: async ({ body, item }) => {
+      const view = new LecturePaneView(doc, body, item);
+      await view.mount();
+    },
+    // ...
+  });
+}
+```
+
+---
+
+## 6. 语音伴读模块详细设计
+
+### 6.1 Zotero 集成适配（复用 + 薄封装）
+
+语音模块不新建独立 Adapter 文件树，而是在 `lecture/infrastructure/zotero/` 做薄封装，内部调用已有模块：
+
+| 接口 | 实现 |
+|------|------|
+| `getPdfAttachment(item)` | 委托 `findPdfAttachment` |
+| `computeFileHash(path)` | 新增：`IOUtils.read` + SubtleCrypto / nsICryptoHash |
+| `openPdfAtPage(itemId, page)` | 新增：Zotero.Reader API |
+| `createLectureNote(item, markdown)` | 委托 `createChildNote`，标题 `ChatPapers 伴读报告: {title}` |
+| `exportBibtex(item)` | 委托 `citeExport.formatCiteText` |
+
+### 6.2 PdfParser（MinerU）
+
+**与文字对话 PDF 路径分离**：文字对话继续 `PDFWorker.getFullText`；语音伴读走 MinerU。
+
+**输入**：PDF 本地路径（来自 attachment）  
+**输出**：
+
+```typescript
+interface ParseResult {
+  chapters: Chapter[];
+  paragraphs: Paragraph[];
+  metadata: { pageCount: number; detectedLanguage?: "en" | "zh" };
+}
+
+interface Paragraph {
+  id: string;           // "p-0017"
+  chapterId: string;
+  orderIndex: number;
+  text: string;
+  page: number;
+  language?: "en" | "zh";
+  bulletPoints?: string[];
+}
+```
+
+**失败策略**：
+
+| 错误类型 | UI 文案 |
+|----------|---------|
+| `ScannedPdfError` | 扫描版 PDF，请先 OCR |
+| `ParseTimeoutError` | 解析超时，请重试 |
+| `MinerUNotFoundError` | 未检测到 MinerU，见设置页安装说明 |
+
+### 6.3 LLM 扩展（共享 client，专属 prompt）
+
+`llm/client.ts` 保持通用 `chatStream`；语音备课在 `lecture/infrastructure/llm/lecturePrompts.ts` 定义模板，通过 client 调用：
+
+| 方法 | 位置 | 用途 |
+|------|------|------|
+| `chatStream` | `llm/client.ts`（已有） | 文字对话 + 语音问答 |
+| `generateSummary` | `lecture/.../lectureLlm.ts` | 全文摘要四字段 |
+| `generateBeats` | 同上 | 8–15 beats + refs[] |
+| `generateParagraphExplanation` | 同上 | 三层讲解 |
+| `generateSentenceExplanation` | 同上 | 逐句讲解 |
+| `answerWithRag` | `lecture/application/askQuestion.ts` | 锚定问答 |
+
+**配置**：语音备课 temperature 0.2–0.4；与文字对话共用 `getRuntimeConfig()`，不新增 LLM prefs 键。
+
+### 6.4 TtsClient
+
+```typescript
+interface TtsResult {
+  audioPath: string;
+  timestamps: WordTimestamp[];
+  durationMs: number;
+}
+
+interface WordTimestamp {
+  text: string;
+  startMs: number;
+  endMs: number;
+}
+
+interface TtsProvider {
+  name: string;
+  synthesize(text: string, options: TtsOptions): Promise<TtsResult>;
+  supportsTimestamps: boolean;
+}
+```
+
+**高亮降级链**：`WORD` → `SENTENCE` → `PARAGRAPH` → `NONE`（仅进度条）
+
+**Prefs 键（建议）**：`extensions.zotero.chatpapers.ttsProvider` / `ttsApiKey` / `ttsVoice`
+
+### 6.5 RagIndex
+
+```typescript
+interface RagIndex {
+  build(paperId: string, paragraphs: Paragraph[]): Promise<void>;
+  search(paperId: string, query: string, topK: number): Paragraph[];
+}
+```
+
+一期 SQLite FTS5，不引入 embedding。索引在解析完成后构建，与 `paragraph_fts` 表同步。
+
+### 6.6 PrepareLectureUseCase
+
+**职责**：编排备课流水线；发出增量就绪事件；保证同一 paper 互斥（备课锁）。
+
+**伪流程**：
+
+```
+start(paperId):
+  if lecture_status != idle && != failed: return  // 防重入
+  set status → parsing
+  paragraphs ← PdfParser.parse(path)
+  persist paragraphs + FTS
+  set status → summarizing
+  summary ← Llm.generateSummary(paragraphs)
+  persist lecture.summary
+  set status → beats_generating
+  beats ← Llm.generateBeats(summary, paragraphIndex)
+  beats ← validateRefs(beats, paragraphIds)
+  persist beats
+  emit lecture:beats_ready          // UI 可开整体讲解
+  set status → paragraphs_generating
+  for batch in paragraphs.chunk(5):
+    explanations ← Llm.generateParagraphExplanation(batch)
+    persist + emit lecture:paragraph_ready
+  set status → tts_generating
+  for unit in beats + explanations:
+    audio ← Tts.synthesize(unit.script)
+    persist audio_path + emit tts:unit_ready
+  set status → ready
+```
+
+### 6.7 PlayUseCase + PlayerController
+
+```typescript
+interface PlayerState {
+  mode: "overview" | "paragraph";
+  currentUnitId: string;
+  isPlaying: boolean;
+  playbackRate: 1 | 1.5 | 2;
+  highlightCursorMs: number;
+}
+```
+
+**跳播**：`currentUnitId` 变更 → 加载 mp3 → `audio.currentTime = 0` → 更新 `progress` 表。
+
+**断点续播**：pane 打开时读 `progress.last_unit_id` + `last_position_ms`。
+
+### 6.8 AskQuestionUseCase
+
+与文字对话的差异：
+
+| 项 | 文字对话 | 语音伴读问答 |
+|----|----------|--------------|
+| 上下文 | 整篇 PDF 文本（可能截断） | 锚点 + 摘要 + RAG topK=5 |
+| 存储 | sessions JSON | qa_record 表 |
+| 输出 | 仅文字流 | 文字流 + TTS mp3 |
+| 锚点 | 选区字符串 | beat / paragraph / sentence / global |
+
+```typescript
+interface AskContext {
+  question: string;
+  anchor: {
+    type: "beat" | "paragraph" | "sentence" | "global";
+    id?: string;
+    text?: string;
+    explanation?: string;
+  };
+  summary: SummaryJson;
+  ragParagraphs: Paragraph[];
+  paperTitle: string;
+}
+```
+
+### 6.9 GenerateReportUseCase
+
+```
+ReportBuilder.build(paperId):
+  summary      ← lecture.summary_json
+  progress     ← progress.listened_units_json
+  qas          ← qa_record ORDER BY created_at
+  highlights   ← highlight JOIN paragraph
+  bibtex       ← citeExport
+
+MarkdownRenderer → createLectureNote(parentItem, markdown)
+```
+
+**Note 策略**：同名 `ChatPapers 伴读报告: {title}` 存在则更新，避免笔记爆炸。
+
+---
+
+## 7. 数据模型
+
+### 7.1 存储目录
+
+```
+{ZoteroProfile}/chatpapers/
+├── sessions/                         # 文字对话（已有）
+│   └── {itemKey}-{attachmentKey}.json
+└── lecture/                          # 语音伴读（新增）
+    ├── lecture.db                    # SQLite
+    └── audio/
+        └── {cacheKey}/
+            ├── beat-{id}.mp3
+            ├── para-{id}.mp3
+            └── qa-{id}.mp3
+```
+
+### 7.2 缓存键
+
+```
+cacheKey = SHA256(attachmentId + "|" + fileHash)
+
+失效条件：
+  • fileHash 变化
+  • 用户强制重新备课
+  • lecture prompt_version major 升级（可选）
+```
+
+### 7.3 ER 关系
+
+```
+PaperCache 1──* Paragraph
+PaperCache 1──1 Lecture
+Lecture    1──* Beat
+Lecture    1──* ParagraphExplanation
+PaperCache 1──* QARecord
+PaperCache 1──1 Progress
+PaperCache 1──* Highlight
+```
+
+### 7.4 SQLite 表结构
+
+```sql
+-- 论文缓存根表
+CREATE TABLE paper_cache (
+  id              TEXT PRIMARY KEY,
+  attachment_id   TEXT NOT NULL,
+  item_id         TEXT NOT NULL,
+  file_hash       TEXT NOT NULL,
+  file_path       TEXT NOT NULL,
+  title           TEXT,
+  language        TEXT,
+  parse_status    TEXT NOT NULL,
+  lecture_status  TEXT NOT NULL,
+  created_at      INTEGER NOT NULL,
+  updated_at      INTEGER NOT NULL,
+  UNIQUE(attachment_id, file_hash)
+);
+
+CREATE TABLE chapter (
+  id              TEXT PRIMARY KEY,
+  paper_id        TEXT NOT NULL REFERENCES paper_cache(id),
+  title           TEXT NOT NULL,
+  order_index     INTEGER NOT NULL
+);
+
+CREATE TABLE paragraph (
+  id              TEXT PRIMARY KEY,
+  paper_id        TEXT NOT NULL REFERENCES paper_cache(id),
+  chapter_id      TEXT REFERENCES chapter(id),
+  order_index     INTEGER NOT NULL,
+  text            TEXT NOT NULL,
+  page            INTEGER NOT NULL
+);
+
+CREATE TABLE lecture (
+  paper_id        TEXT PRIMARY KEY REFERENCES paper_cache(id),
+  summary_json    TEXT NOT NULL,
+  prompt_version  TEXT NOT NULL,
+  created_at      INTEGER NOT NULL
+);
+
+CREATE TABLE beat (
+  id              TEXT PRIMARY KEY,
+  paper_id        TEXT NOT NULL REFERENCES paper_cache(id),
+  order_index     INTEGER NOT NULL,
+  title           TEXT,
+  type            TEXT NOT NULL,
+  script          TEXT NOT NULL,
+  refs_json       TEXT NOT NULL,
+  audio_path      TEXT,
+  timestamps_json TEXT,
+  tts_status      TEXT NOT NULL
+);
+
+CREATE TABLE paragraph_explanation (
+  paragraph_id    TEXT PRIMARY KEY REFERENCES paragraph(id),
+  paper_id        TEXT NOT NULL REFERENCES paper_cache(id),
+  layer_what      TEXT NOT NULL,
+  layer_how       TEXT NOT NULL,
+  layer_where     TEXT NOT NULL,
+  audio_path      TEXT,
+  timestamps_json TEXT,
+  gen_status      TEXT NOT NULL,
+  tts_status      TEXT NOT NULL
+);
+
+CREATE TABLE progress (
+  paper_id        TEXT PRIMARY KEY REFERENCES paper_cache(id),
+  last_mode       TEXT,
+  last_unit_id    TEXT,
+  last_position_ms INTEGER DEFAULT 0,
+  listened_units_json TEXT,
+  updated_at      INTEGER NOT NULL
+);
+
+CREATE TABLE qa_record (
+  id              TEXT PRIMARY KEY,
+  paper_id        TEXT NOT NULL REFERENCES paper_cache(id),
+  anchor_type     TEXT NOT NULL,
+  anchor_id       TEXT,
+  question        TEXT NOT NULL,
+  answer          TEXT NOT NULL,
+  audio_path      TEXT,
+  created_at      INTEGER NOT NULL
+);
+
+CREATE TABLE highlight (
+  paper_id        TEXT NOT NULL REFERENCES paper_cache(id),
+  paragraph_id    TEXT NOT NULL REFERENCES paragraph(id),
+  note            TEXT,
+  created_at      INTEGER NOT NULL,
+  PRIMARY KEY (paper_id, paragraph_id)
+);
+
+CREATE VIRTUAL TABLE paragraph_fts USING fts5(
+  paragraph_id,
+  paper_id,
+  text,
+  tokenize='unicode61'
+);
+```
+
+### 7.5 Beat refs 校验
+
+```
+输入: beats[], validParagraphIds (Set)
+对每个 beat:
+  beat.refs = beat.refs.filter(id => validParagraphIds.has(id))
+  if beat.refs.isEmpty:
+    beat.degraded = true
+输出: beats[]
+```
+
+### 7.6 摘要 JSON
+
+```json
+{
+  "problem": "…",
+  "method": "…",
+  "result": "…",
+  "limitation": "…"
+}
+```
+
+---
+
+## 8. 核心流水线
+
+### 8.1 语音伴读端到端
+
+```
+PDF attachment path
+  → findPdfAttachment + computeFileHash
+  → [MinerU PdfParser] → paragraphs[] → SQLite + FTS
+  → [generateSummary] → lecture.summary
+  → [generateBeats] → refs 校验 → SQLite
+  → emit lecture:beats_ready ──► 整体讲解可播（文本）
+  → [generateParagraphExplanation] × N → SQLite
+  → emit lecture:paragraph_ready
+  → [Tts.synthesize] × units → mp3 → SQLite
+  → emit tts:unit_ready ──► 播放器加载音频
+  → 用户提问 → [AskQuestion + RAG] → 文字流 + TTS
+  → [GenerateReport] → Zotero Note
+```
+
+### 8.2 增量备课时序
+
+```
+时间 ──────────────────────────────────────────────►
+
+解析 ████████
+摘要      ███
+beats         ██████          ← beats_ready（~1-2min，可先听文本/TTS排队）
+逐段讲解           ████████████████████
+TTS(beats)              ████████
+TTS(段落)                      █████████████████
+```
+
+### 8.3 文字对话路径（不变）
+
+```
+Item → findPdfAttachment → PDFWorker.getFullText
+     → buildChatMessages → chatStream → ChatView 渲染
+     → saveSession (JSON)
+     → createChildNote（可选）
+```
+
+---
+
+## 9. 状态机
+
+### 9.1 备课状态（lecture_status）
+
+```
+idle → parsing → parsed → summarizing → beats_generating
+  → paragraphs_generating (batch loop) → tts_generating → ready
+任何阶段 ──error──► failed（可从 failed 或任意已完成阶段 resume）
+```
+
+**可恢复**：每阶段结束写库；重启后读 `lecture_status`，跳过已完成步骤。
+
+### 9.2 播放器状态
+
+见 §6.7。pane `onDestroy` 时持久化 progress，释放 `<audio>` 引用。
+
+---
+
+## 10. 内部事件（EventBus）
+
+| 事件 | 载荷 | 订阅者 |
+|------|------|--------|
+| `parse:progress` | `{ paperId, percent, message }` | LecturePane |
+| `lecture:beats_ready` | `{ paperId, beatCount }` | LecturePane, Player |
+| `lecture:paragraph_ready` | `{ paperId, paragraphId }` | LecturePane |
+| `tts:unit_ready` | `{ paperId, unitId, audioPath }` | Player |
+| `lecture:failed` | `{ paperId, error }` | LecturePane |
+| `qa:chunk` | `{ textDelta }` | QAPanel |
+| `qa:complete` | `{ qaRecordId, audioPath? }` | QAPanel |
+
+EventBus 实例按 `paperId` 或全局单例均可；MVP 用模块级 `EventTarget` 即可。
+
+**长时间任务**：
+- MinerU：子进程（不阻塞 UI）
+- LLM / TTS：`async fetch` + AbortController
+- SQLite 写：单线程队列，避免并发锁
+
+---
+
+## 11. 设置与 Preference 设计
+
+### 11.1 分组结构（preferences.xhtml）
+
+```
+ChatPapers 设置
+├── 通用 · LLM              ← 两模式共享
+│     Provider / Base URL / API Key / Model / Temperature
+├── 文字对话                ← 已有
+│     System Prompt / Summary Prompt / Answer Language
+└── 语音伴读                ← 新增
+      TTS Provider / API Key / Voice
+      教师风格（简洁 / 详细）
+      MinerU 路径（若需）
+      数据流向说明（静态文案）
+```
+
+### 11.2 Prefs 键命名
+
+沿用 `extensions.zotero.chatpapers.*` 前缀，不新增 addon ID：
+
+| 键 | 模式 | 说明 |
+|----|------|------|
+| `provider` | 共享 | 已有 |
+| `apiKey` | 共享 | 已有 |
+| `systemPrompt` | 文字 | 已有 |
+| `ttsProvider` | 语音 | 新增 |
+| `ttsApiKey` | 语音 | 新增 |
+| `ttsVoice` | 语音 | 新增 |
+| `lectureTeacherStyle` | 语音 | 新增 |
+| `mineruPath` | 语音 | 新增，可选 |
+
+---
+
+## 12. 目标工程结构
+
+在 [development.md](../development.md) 现有结构基础上扩展：
+
+```text
+src/
+├── hooks.ts
+├── modules/
+│   ├── ui/
+│   │   ├── readerPane.ts          # 注册 Chat + Lecture 两个 section
+│   │   ├── chatView.ts            # 文字对话（不动）
+│   │   ├── multiChatView.ts       # 文字多 PDF（不动）
+│   │   └── prefs.ts
+│   ├── pdf/
+│   │   ├── extractor.ts           # 共享：附件定位
+│   │   ├── context.ts             # 文字专属
+│   │   ├── multiContext.ts        # 文字专属
+│   │   └── selection.ts           # 共享
+│   ├── llm/                       # 共享 client + providers
+│   ├── storage/
+│   │   └── sessions.ts            # 文字专属
+│   ├── zotero/                    # 共享
+│   └── lecture/                   # ★ 语音伴读（新建）
+│       ├── ui/
+│       │   ├── lecturePane.ts
+│       │   ├── playerController.ts
+│       │   ├── unitList.ts
+│       │   └── qaPanel.ts
+│       ├── application/
+│       │   ├── prepareLecture.ts
+│       │   ├── playLecture.ts
+│       │   ├── askQuestion.ts
+│       │   └── generateReport.ts
+│       ├── domain/
+│       │   ├── types.ts
+│       │   ├── lectureState.ts
+│       │   └── playerState.ts
+│       └── infrastructure/
+│           ├── pdf/
+│           │   ├── parser.ts
+│           │   └── fileHash.ts
+│           ├── tts/
+│           │   ├── client.ts
+│           │   └── providers.ts
+│           ├── storage/
+│           │   ├── repository.ts
+│           │   ├── schema.ts
+│           │   └── audioStorage.ts
+│           ├── rag/
+│           │   └── index.ts
+│           ├── llm/
+│           │   ├── lectureLlm.ts
+│           │   └── lecturePrompts.ts
+│           ├── zotero/
+│           │   └── adapter.ts
+│           └── events.ts
+```
+
+**样式**：`addon/content/chatpapers.css` 增加 `.chatpapers-lecture-*` 前缀类，与文字对话样式并列。
+
+**i18n**：`addon/locale/*/chatpapers.ftl` 增加 `item-section-lecture-*` 等键。
+
+---
+
+## 13. 外部集成
+
+### 13.1 LLM（共享）
+
+| 提供商 | 协议 | 文字对话 | 语音伴读 |
+|--------|------|:--------:|:--------:|
+| OpenAI 兼容 | HTTPS SSE | ✓ | ✓ 备课 + 问答 |
+| Ollama | localhost | ✓ | ✓ |
+
+### 13.2 TTS（语音专属）
+
+| 提供商 | 选型维度 |
+|--------|----------|
+| 火山 / Azure / MiniMax / ElevenLabs | 中文自然度、价格、word timestamps |
+
+### 13.3 MinerU（语音专属）
+
+- 集成：子进程 CLI，stdout JSON
+- 分发：Phase 0 决定「随插件文档安装」vs「用户自装 Python 环境」
+
+### 13.4 Better BibTeX（共享，可选）
+
+语音报告参考文献卡片复用 `citeExport`；逻辑已在 Chat 多 PDF 模式验证。
+
+---
+
+## 14. 安全与隐私
+
+| 项 | 文字对话 | 语音伴读 |
+|----|----------|----------|
+| PDF 文件 | 不上传 | 不上传 |
+| 发往 LLM | 正文 text（可能截断） | 段落 text + 摘要 + 问题 |
+| 发往 TTS | — | 讲解/回答中文文本 |
+| API Key | Zotero prefs | LLM 共享；TTS 独立 pref |
+| 日志 | 不记录 Key | 不记录 Key；段落正文可截断 |
+
+设置页「数据流向」分组须同时覆盖两种模式。
+
+---
+
+## 15. Phase 0 技术验证（Go / No-Go）
+
+| # | 验证项 | 通过标准 | 阻塞 MVP |
+|---|--------|----------|----------|
+| P0-1 | 第二 Item pane 与 Chat 并存 | 切换 tab 互不影响 | 是 |
+| P0-2 | MinerU 解析 3 篇论文 | 段落可用率 ≥ 80% | 是 |
+| P0-3 | Zotero 9 插件内 SQLite CRUD | lecture.db 读写正常 | 是 |
+| P0-4 | `<audio>` 10 min+ 播放 | 无泄漏 / 崩溃 | 是 |
+| P0-5 | TTS 中文样本 | 自然度可接受 | 是 |
+| P0-6 | TTS timestamps | 有则记录；无则句子级降级 | 否 |
+| P0-7 | Chat 模式回归 | 对话 / 总结 / 存笔记不受影响 | 是 |
+
+P0-1、P0-7 验证**双模式隔离**；P0-2 ~ P0-6 验证**语音链路**。
+
+---
+
+## 16. 性能与扩展
+
+### 16.1 长论文策略
+
+| 页数 | 策略 |
+|------|------|
+| ≤ 30 | 全量逐段备课 |
+| 30–80 | 逐段 lazy：按章节或用户触发 |
+| > 80 | 默认仅整体讲解；逐段需用户确认 |
+
+### 16.2 并发控制
+
+- 备课 LLM：beats 小批量并行 ≤ 3
+- TTS：队列化，beats 优先
+- 同一 paper 备课互斥锁
+- SQLite 写串行队列
+
+### 16.3 伴读库窗口（P1）
+
+`libraryWindow.ts` 扫描 `paper_cache` 表 + Zotero Items；>5000 items 时仅索引「有过备课记录」的 attachment。
+
+---
+
+## 17. 可观测性
+
+| 类型 | 内容 |
+|------|------|
+| 结构化日志 | `mode: "lecture"`, paperId, stage, durationMs, errorCode |
+| 用户可见进度 | 解析 %、beats n/total、TTS n/total |
+| 调试导出 | 单篇 metrics JSON（开发者菜单，可选） |
+
+日志前缀建议 `[ChatPapers:Lecture]`，与 `[ChatPapers:Chat]` 区分。
+
+---
+
+## 18. 风险与对策
+
+| 风险 | 对策 |
+|------|------|
+| 语音模块影响文字对话稳定性 | 依赖隔离 + pane 级 try/catch + P0-7 回归 |
+| MinerU 打包复杂 | Phase 0 验证；文档化安装 |
+| refs 幻觉 | 校验器 + degraded beat |
+| TTS 无 timestamps | 高亮降级链 |
+| SQLite 在插件环境不可用 | Phase 0 备选 sql.js / JSON 分文件 |
+| 双 pane 内存占用 | onDestroy 释放 audio、取消进行中的 fetch |
+
+---
+
+## 19. 开放问题
+
+| # | 问题 | 影响 |
+|---|------|------|
+| 1 | SQLite：better-sqlite3 vs sql.js vs 纯 JSON | 存储层选型 |
+| 2 | MinerU 分发方式 | 安装体验 |
+| 3 | 问答 TTS：流式 vs 整段合成 | AskQuestion 复杂度 |
+| 4 | 文字对话是否未来支持 TTS 朗读回复 | v1.1+ 可统一 TtsClient |
+| 5 | Chat 会话 → 语音问答上下文导入 | v1.1 产品决策 |
+
+---
+
+## 20. 文档关系
+
+```
+docs/requirements.md              ChatPapers 文字对话需求（不变）
+docs/development.md               现有工程与工具链（不变）
+docs/newidea/
+  ├── PLAN.md / PRD.md            BanDu 原始策划（参考）
+  ├── ARCHITECTURE.md             独立插件架构（参考）
+  ├── DUAL_MODE_PRD.md            ★ 双模式集成需求
+  └── DUAL_MODE_ARCHITECTURE.md   ★ 本文：双模式集成架构
+```
+
+**实施顺序**：需求看 DUAL_MODE_PRD.md → 架构看本文 → 领域细节参考 ARCHITECTURE.md §4–§6。
+
+---
+
+## 21. 文档修订记录
+
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| v0.1 | 2026-08-29 | 初稿：ChatPapers 双模式集成架构；语音模块命名 `lecture/` |