# 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/` |