681 lines
23 KiB
Markdown
681 lines
23 KiB
Markdown
# 软件架构设计文档
|
||
|
||
| 字段 | 内容 |
|
||
|------|------|
|
||
| 产品名称 | BanDu（伴读）— Zotero 插件 |
|
||
| 中文名 | 伴读 |
|
||
| 英文名 | BanDu |
|
||
| 文档版本 | v0.1 |
|
||
| 状态 | 草案 |
|
||
| 关联文档 | [PLAN.md](./PLAN.md)、[PRD.md](./PRD.md) |
|
||
|
||
---
|
||
|
||
## 1. 架构概述
|
||
|
||
### 1.1 架构风格
|
||
|
||
**Local-first 桌面插件架构**：核心计算与缓存均在用户机器完成；仅将段落文本与用户问题发送至用户配置的 LLM / TTS 服务。无自建后端（一期）。
|
||
|
||
### 1.2 设计原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| 备课一次、缓存复用 | Lecture 持久化；attachment ID + 文件哈希为缓存键 |
|
||
| 增量交付 | 摘要 → beats → 逐段 → TTS 分阶段就绪，缩短 Time-to-Listen |
|
||
| UI / 领域 / 集成 分离 | 降低 Zotero API 变动影响 |
|
||
| Grounding 优先 | 生成内容必须可追溯到段落 ID |
|
||
| 优雅降级 | refs 无效、无 timestamps、无 BBT 均有 fallback |
|
||
|
||
### 1.3 系统上下文
|
||
|
||
```
|
||
┌─────────────────┐
|
||
│ 用户 │
|
||
└────────┬────────┘
|
||
│
|
||
┌──────────────▼──────────────┐
|
||
│ Zotero 7 (宿主) │
|
||
│ ┌────────────────────────┐ │
|
||
│ │ BanDu 插件 │ │
|
||
│ │ UI │ Engine │ Store │ │
|
||
│ └─────────┬──────────────┘ │
|
||
└────────────┼────────────────┘
|
||
│
|
||
┌─────────────────┼─────────────────┐
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌───────────┐ ┌────────────┐ ┌─────────────┐
|
||
│ MinerU │ │ LLM API │ │ TTS API │
|
||
│ (本地子进程)│ │ / Ollama │ │ ElevenLabs等 │
|
||
└───────────┘ └────────────┘ └─────────────┘
|
||
│
|
||
▼
|
||
┌───────────┐
|
||
│ SQLite + │
|
||
│ mp3 文件 │
|
||
└───────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 逻辑分层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Presentation Layer（表现层） │
|
||
│ • BanduPane（Item pane 伴读页） │
|
||
│ • LibraryWindow（伴读库） │
|
||
│ • SettingsPane（设置） │
|
||
│ • PlayerController（播放状态机 + <audio>） │
|
||
└───────────────────────────┬─────────────────────────────┘
|
||
│
|
||
┌───────────────────────────▼─────────────────────────────┐
|
||
│ Application Layer（应用层 / 用例） │
|
||
│ • PrepareLectureUseCase（备课编排） │
|
||
│ • PlayUseCase（播放 / 跳播 / 断点） │
|
||
│ • AskQuestionUseCase（问答 + RAG） │
|
||
│ • GenerateReportUseCase（报告 + Note 回写） │
|
||
└───────────────────────────┬─────────────────────────────┘
|
||
│
|
||
┌───────────────────────────▼─────────────────────────────┐
|
||
│ Domain Layer（领域层） │
|
||
│ • Paper, Paragraph, Chapter │
|
||
│ • Lecture, Beat, ParagraphExplanation │
|
||
│ • QARecord, Progress, Highlight │
|
||
│ • LecturePreparationState（状态机） │
|
||
└───────────────────────────┬─────────────────────────────┘
|
||
│
|
||
┌───────────────────────────▼─────────────────────────────┐
|
||
│ Infrastructure Layer（基础设施层） │
|
||
│ • ZoteroAdapter（Item / Attachment / Note） │
|
||
│ • PdfParser（MinerU 封装） │
|
||
│ • LlmClient（OpenAI-compatible / Ollama） │
|
||
│ • TtsClient（多提供商 + timestamps） │
|
||
│ • SqliteRepository │
|
||
│ • AudioStorage（mp3 路径管理） │
|
||
│ • RagIndex（段落检索） │
|
||
│ • PromptRegistry（模板版本管理） │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 模块说明
|
||
|
||
### 3.1 ZoteroAdapter
|
||
|
||
**职责**：封装所有 Zotero 7 API 调用。
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `getPdfAttachment(itemId)` | 返回主 PDF 路径、attachmentId |
|
||
| `computeFileHash(path)` | SHA-256 |
|
||
| `openPdfAtPage(itemId, page)` | 跳转 PDF 阅读器 |
|
||
| `createBanduNote(itemId, markdown)` | 创建伴读子笔记 |
|
||
| `getCitationKey(itemId)` | Better BibTeX 可选集成 |
|
||
| `listLibraryItems()` | 伴读库数据源 |
|
||
|
||
**约束**：UI 与用例层不得直接调用 `Zotero.*` 全局对象。
|
||
|
||
### 3.2 PdfParser
|
||
|
||
**职责**：调用 MinerU（一期），输出规范化段落树。
|
||
|
||
**输入**：PDF 本地路径
|
||
**输出**：`ParseResult { chapters[], paragraphs[], metadata }`
|
||
|
||
**段落字段**：
|
||
|
||
```typescript
|
||
interface Paragraph {
|
||
id: string; // 稳定 ID，如 "p-0017"
|
||
chapterId: string;
|
||
orderIndex: number;
|
||
text: string;
|
||
page: number;
|
||
language?: 'en' | 'zh';
|
||
bulletPoints?: string[]; // >150 词长段拆分要点
|
||
}
|
||
```
|
||
|
||
**失败策略**：抛出 typed error（`ScannedPdfError`, `ParseTimeoutError`），UI 映射为用户文案。
|
||
|
||
### 3.3 PrepareLectureUseCase
|
||
|
||
**职责**：编排备课流水线，驱动增量就绪事件。
|
||
|
||
详见 §5 流水线与 §6 状态机。
|
||
|
||
### 3.4 LlmClient
|
||
|
||
**职责**：统一 LLM 调用；支持 streaming。
|
||
|
||
| 方法 | 用途 |
|
||
|------|------|
|
||
| `generateSummary(paragraphs[])` | 全文摘要 |
|
||
| `generateBeats(summary, paragraphIndex[])` | 整体讲解 beats |
|
||
| `generateParagraphExplanation(para, summary, chapterTitle)` | 三层讲解 |
|
||
| `generateSentenceExplanation(sentence, context)` | 逐句讲解 |
|
||
| `answerQuestion(context, question)` | 问答 stream |
|
||
|
||
**配置**：provider、baseUrl、apiKey、model、temperature（默认 0.2–0.4）。
|
||
|
||
### 3.5 TtsClient
|
||
|
||
**职责**：文本 → mp3 + timestamps。
|
||
|
||
```typescript
|
||
interface TtsResult {
|
||
audioPath: string;
|
||
timestamps: WordTimestamp[]; // 可为空
|
||
durationMs: number;
|
||
}
|
||
|
||
interface WordTimestamp {
|
||
text: string;
|
||
startMs: number;
|
||
endMs: number;
|
||
}
|
||
```
|
||
|
||
**策略**：优先 provider 原生 boundaries；缺失则 `HighlightGranularity = SENTENCE`。
|
||
|
||
### 3.6 RagIndex
|
||
|
||
**职责**：段落级检索，供问答组装上下文。
|
||
|
||
**一期实现**：SQLite FTS5 或 BM25；MVP 可不引入 embedding。
|
||
|
||
```typescript
|
||
interface RagIndex {
|
||
build(paragraphs: Paragraph[]): void;
|
||
search(query: string, topK: number): Paragraph[];
|
||
}
|
||
```
|
||
|
||
### 3.7 SqliteRepository + AudioStorage
|
||
|
||
**职责**：结构化数据与二进制音频分离存储。
|
||
|
||
- SQLite：`{ZoteroDataDir}/bandu/bandu.db`
|
||
- 音频：`{ZoteroDataDir}/bandu/audio/{cacheKey}/{unitId}.mp3`
|
||
|
||
---
|
||
|
||
## 4. 数据模型
|
||
|
||
### 4.1 ER 关系
|
||
|
||
```
|
||
PaperCache 1──* Paragraph
|
||
PaperCache 1──1 Lecture
|
||
Lecture 1──* Beat
|
||
Lecture 1──* ParagraphExplanation
|
||
PaperCache 1──* QARecord
|
||
PaperCache 1──1 Progress
|
||
PaperCache 1──* Highlight
|
||
```
|
||
|
||
### 4.2 表结构（SQLite）
|
||
|
||
```sql
|
||
-- 论文缓存根表
|
||
CREATE TABLE paper_cache (
|
||
id TEXT PRIMARY KEY, -- hash(attachment_id + file_hash)
|
||
attachment_id TEXT NOT NULL,
|
||
item_id TEXT NOT NULL,
|
||
file_hash TEXT NOT NULL,
|
||
file_path TEXT NOT NULL,
|
||
title TEXT,
|
||
language TEXT, -- 'en' | 'zh'
|
||
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, -- {problem, method, result, limitation}
|
||
prompt_version TEXT NOT NULL,
|
||
created_at INTEGER NOT NULL
|
||
);
|
||
|
||
-- 整体讲解 beat
|
||
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, -- intro|method|experiment|conclusion|extension
|
||
script TEXT NOT NULL,
|
||
refs_json TEXT NOT NULL, -- ["p-0012","p-0013"]
|
||
audio_path TEXT,
|
||
timestamps_json TEXT,
|
||
tts_status TEXT NOT NULL -- pending|ready|failed
|
||
);
|
||
|
||
-- 逐段三层讲解
|
||
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, -- overview|paragraph
|
||
last_unit_id TEXT,
|
||
last_position_ms INTEGER DEFAULT 0,
|
||
listened_units_json TEXT, -- 已听 unit id 列表
|
||
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, -- beat|paragraph|sentence|global
|
||
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)
|
||
);
|
||
|
||
-- 段落 FTS（RAG）
|
||
CREATE VIRTUAL TABLE paragraph_fts USING fts5(
|
||
paragraph_id,
|
||
paper_id,
|
||
text,
|
||
tokenize='unicode61'
|
||
);
|
||
```
|
||
|
||
### 4.3 缓存键策略
|
||
|
||
```
|
||
cacheKey = SHA256(attachmentId + "|" + fileHash)
|
||
|
||
失效条件：
|
||
• fileHash 变化（PDF 被替换）
|
||
• 用户「强制重新备课」
|
||
• prompt_version _major 升级（可选策略：仅影响新生成）
|
||
```
|
||
|
||
### 4.4 Lecture JSON 摘要结构
|
||
|
||
```json
|
||
{
|
||
"problem": "…",
|
||
"method": "…",
|
||
"result": "…",
|
||
"limitation": "…"
|
||
}
|
||
```
|
||
|
||
### 4.5 Beat refs 校验算法
|
||
|
||
```
|
||
输入: beats[], validParagraphIds (Set)
|
||
对每个 beat:
|
||
beat.refs = beat.refs.filter(id => validParagraphIds.has(id))
|
||
if beat.refs.isEmpty:
|
||
beat.degraded = true // UI: 不展示原文高亮
|
||
输出: beats[]
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 核心流水线
|
||
|
||
### 5.1 端到端数据流
|
||
|
||
```
|
||
PDF path
|
||
→ [PdfParser] → paragraphs[] → SQLite
|
||
→ [LlmClient.generateSummary] → lecture.summary
|
||
→ [LlmClient.generateBeats] → beats[] → refs 校验 → SQLite
|
||
→ (event: beats_ready) → UI 可播整体模式
|
||
→ [LlmClient.generateParagraphExplanation] × N → SQLite
|
||
→ (event: paragraph_batch_ready)
|
||
→ [TtsClient.synthesize] × units → mp3 → SQLite
|
||
→ (event: unit_audio_ready)
|
||
```
|
||
|
||
### 5.2 增量备课时序
|
||
|
||
```
|
||
时间 ──────────────────────────────────────────────►
|
||
|
||
解析 ████████
|
||
摘要 ███
|
||
beats ██████ ← beats_ready（~1-2min）
|
||
逐段讲解 ████████████████████
|
||
TTS(beats) ████████ ← 整体模式有声音
|
||
TTS(段落) █████████████████
|
||
```
|
||
|
||
### 5.3 问答上下文组装
|
||
|
||
```
|
||
AskContext {
|
||
question: string
|
||
anchor: { type, id, text, explanation? }
|
||
summary: SummaryJson
|
||
ragParagraphs: Paragraph[] // topK=5
|
||
paperTitle: string
|
||
}
|
||
|
||
Prompt 模板顺序：
|
||
系统角色 → 全文摘要 → RAG 段落 → 锚点原文+讲解 → 用户问题
|
||
```
|
||
|
||
### 5.4 报告生成
|
||
|
||
```
|
||
ReportBuilder.build(paperId):
|
||
summary ← lecture.summary
|
||
progress ← progress.listened_units
|
||
qas ← qa_record ORDER BY created_at
|
||
highlights ← highlight JOIN paragraph
|
||
bibtex ← ZoteroAdapter.getCitationKey + export
|
||
|
||
MarkdownRenderer → ZoteroAdapter.createBanduNote
|
||
```
|
||
|
||
**报告策略（建议 MVP）**：同一 Item 只保留一个「伴读报告」笔记；再次生成时**更新**同名 Note（`BanDu 伴读报告: {title}`），避免笔记爆炸。
|
||
|
||
---
|
||
|
||
## 6. 状态机
|
||
|
||
### 6.1 论文 / 备课状态（lecture_status）
|
||
|
||
```
|
||
┌─────────┐
|
||
│ idle │ 未开始
|
||
└────┬────┘
|
||
│ start
|
||
▼
|
||
┌─────────┐
|
||
┌────│ parsing │────┐ fail
|
||
│ └────┬────┘ │
|
||
│ │ success ▼
|
||
│ │ ┌─────────┐
|
||
│ └───►│ parsed │
|
||
│ └────┬────┘
|
||
│ │
|
||
│ ▼
|
||
│ ┌──────────────┐
|
||
│ │ summarizing │
|
||
│ └──────┬───────┘
|
||
│ │
|
||
│ ▼
|
||
│ ┌──────────────┐
|
||
│ │ beats_generating │
|
||
│ └──────┬───────┘
|
||
│ │ beats_ready
|
||
│ ▼
|
||
│ ┌────────────────────┐
|
||
│ │ paragraphs_generating │◄──┐
|
||
│ └──────────┬─────────┘ │ batch loop
|
||
│ │ │
|
||
│ └─────────────┘
|
||
│ │ all para done
|
||
│ ▼
|
||
│ ┌────────────────────┐
|
||
│ │ tts_generating │
|
||
│ └──────────┬─────────┘
|
||
│ │
|
||
│ ▼
|
||
│ ┌──────────────┐
|
||
└─────────────►│ ready │
|
||
error └──────────────┘
|
||
┌─────────┐
|
||
│ failed │
|
||
└─────────┘
|
||
```
|
||
|
||
**可恢复**：每个阶段完成后持久化；重启插件从 `lecture_status` 继续，跳过已完成步骤。
|
||
|
||
### 6.2 播放器状态
|
||
|
||
```
|
||
PlayerState {
|
||
mode: 'overview' | 'paragraph'
|
||
currentUnitId: string
|
||
isPlaying: boolean
|
||
playbackRate: 1 | 1.5 | 2
|
||
highlightCursorMs: number
|
||
}
|
||
```
|
||
|
||
**跳播**：切换 `currentUnitId` → 加载对应 mp3 → seek(0) → 更新 Progress。
|
||
|
||
---
|
||
|
||
## 7. 接口设计（内部事件）
|
||
|
||
插件内使用 EventBus 解耦 UI 与长时间任务：
|
||
|
||
| 事件 | 载荷 | 订阅者 |
|
||
|------|------|--------|
|
||
| `parse:progress` | `{ percent, message }` | BanduPane |
|
||
| `lecture:beats_ready` | `{ paperId, beatCount }` | BanduPane, Player |
|
||
| `lecture:paragraph_ready` | `{ paperId, paragraphId }` | BanduPane |
|
||
| `tts:unit_ready` | `{ unitId, audioPath }` | Player |
|
||
| `lecture:failed` | `{ paperId, error }` | BanduPane |
|
||
| `qa:chunk` | `{ textDelta }` | QAPanel |
|
||
| `qa:complete` | `{ qaRecordId }` | QAPanel, Report |
|
||
|
||
**长时间任务**：在 Zotero 主线程外使用 Web Worker 或子进程（MinerU）；LLM/TTS 使用 async fetch，避免阻塞 UI。
|
||
|
||
---
|
||
|
||
## 8. 外部集成
|
||
|
||
### 8.1 LLM
|
||
|
||
| 提供商 | 协议 | 用途 |
|
||
|--------|------|------|
|
||
| OpenAI 兼容 API | HTTPS SSE | 备课 + 问答 |
|
||
| Ollama | localhost HTTP | 全本地备选 |
|
||
|
||
### 8.2 TTS
|
||
|
||
| 提供商 | 选型维度 |
|
||
|--------|----------|
|
||
| 火山 / Azure / MiniMax / ElevenLabs | 中文自然度、价格、word timestamps |
|
||
|
||
**抽象接口**：
|
||
|
||
```typescript
|
||
interface TtsProvider {
|
||
name: string;
|
||
synthesize(text: string, options: TtsOptions): Promise<TtsResult>;
|
||
supportsTimestamps: boolean;
|
||
}
|
||
```
|
||
|
||
### 8.3 MinerU
|
||
|
||
- **集成方式（待 Phase 0 确认）**：子进程 CLI，stdin/stdout JSON
|
||
- **打包**：插件安装包内含 MinerU 二进制或安装脚本；文档说明 Python 环境依赖
|
||
|
||
### 8.4 Better BibTeX（可选）
|
||
|
||
- 检测 `Zotero.BetterBibTeX` 是否存在
|
||
- 不存在：从 Item 字段生成简易 BibTeX 或留空字段
|
||
|
||
---
|
||
|
||
## 9. 安全与隐私
|
||
|
||
| 项 | 方案 |
|
||
|----|------|
|
||
| PDF 文件 | 不离开本地 |
|
||
| 发往 LLM 的数据 | 段落 text + 用户问题 + 摘要；设置页明示 |
|
||
| API Key | Zotero prefs 加密存储或 OS Keychain |
|
||
| 日志 | 不记录 Key、不完整记录段落正文（可截断） |
|
||
| Ollama | 默认 localhost，无外网 |
|
||
|
||
---
|
||
|
||
## 10. 部署与构建
|
||
|
||
### 10.1 技术栈
|
||
|
||
| 层 | 选型 |
|
||
|----|------|
|
||
| 插件框架 | [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template) |
|
||
| 语言 | TypeScript |
|
||
| UI | HTML + CSS（Fluent 风格贴近 Zotero） |
|
||
| 音频 | HTML5 `<audio>` |
|
||
| 数据库 | better-sqlite3 或 Zotero 内置 SQL（待 POC） |
|
||
| PDF | MinerU（Python，本地 CPU） |
|
||
|
||
### 10.2 目录结构（建议）
|
||
|
||
```
|
||
bandu/
|
||
├── addon/
|
||
│ ├── bootstrap.js
|
||
│ ├── manifest.json
|
||
│ └── prefs.js
|
||
├── src/
|
||
│ ├── ui/
|
||
│ │ ├── BanduPane.tsx
|
||
│ │ ├── LibraryWindow.tsx
|
||
│ │ └── SettingsPane.tsx
|
||
│ ├── application/
|
||
│ │ ├── PrepareLectureUseCase.ts
|
||
│ │ ├── PlayUseCase.ts
|
||
│ │ ├── AskQuestionUseCase.ts
|
||
│ │ └── GenerateReportUseCase.ts
|
||
│ ├── domain/
|
||
│ ├── infrastructure/
|
||
│ │ ├── zotero/
|
||
│ │ ├── pdf/
|
||
│ │ ├── llm/
|
||
│ │ ├── tts/
|
||
│ │ └── storage/
|
||
│ └── prompts/
|
||
├── tests/
|
||
└── docs/
|
||
```
|
||
|
||
### 10.3 版本兼容
|
||
|
||
- `manifest.json` 声明 `applications.zotero.strict_min_version` / `strict_max_version`
|
||
- CI 固定 Zotero 7.x 版本做 smoke test
|
||
|
||
---
|
||
|
||
## 11. Phase 0 技术验证（Go / No-Go）
|
||
|
||
| # | 验证项 | 通过标准 | 阻塞 MVP |
|
||
|---|--------|----------|----------|
|
||
| P0-1 | Item pane 嵌入自定义页 | 可展示 UI、读取当前 Item | 是 |
|
||
| P0-2 | 读取 PDF attachment 路径 | 路径有效、哈希可算 | 是 |
|
||
| P0-3 | `<audio>` 长音频播放 | 10 min+ 无泄漏/崩溃 | 是 |
|
||
| P0-4 | MinerU 解析 3 篇论文 | 段落切分可用率 ≥ 80% | 是 |
|
||
| P0-5 | TTS 中文样本 | 自然度可接受 | 是 |
|
||
| P0-6 | TTS timestamps | 有则记录格式；无则确认句子级降级 | 否（降级） |
|
||
| P0-7 | Zotero Note Markdown | 报告渲染可接受 | 否 |
|
||
|
||
---
|
||
|
||
## 12. 性能与扩展
|
||
|
||
### 12.1 长论文策略
|
||
|
||
| 页数 | 策略 |
|
||
|------|------|
|
||
| ≤ 30 | 全量逐段备课 |
|
||
| 30–80 | 逐段 lazy：按章节或用户点击生成 |
|
||
| > 80 | 默认仅整体讲解；逐段需用户确认（成本提示） |
|
||
|
||
### 12.2 并发控制
|
||
|
||
- LLM 备课：beats 串行或小批量并行（≤ 3）避免 rate limit
|
||
- TTS：队列化，优先 beats 音频
|
||
- 同一 paper 不允许重复触发备课（互斥锁）
|
||
|
||
---
|
||
|
||
## 13. 可观测性
|
||
|
||
| 类型 | 内容 |
|
||
|------|------|
|
||
| 结构化日志 | paperId, stage, durationMs, errorCode |
|
||
| 用户可见进度 | 解析 %、beats 数、段落 i/n、TTS i/n |
|
||
| Dogfooding 导出 | 单篇 metrics JSON（可选调试菜单） |
|
||
|
||
---
|
||
|
||
## 14. 风险与架构对策
|
||
|
||
| 风险 | 架构对策 |
|
||
|------|----------|
|
||
| Zotero API 变更 | Adapter 层隔离；pin 版本 |
|
||
| MinerU 打包复杂 | Phase 0 验证；文档化外部依赖安装 |
|
||
| refs 幻觉 | 校验器 + degraded beat |
|
||
| TTS 无 timestamps | HighlightGranularity 降级 |
|
||
| SQLite 锁 | 写操作单线程队列 |
|
||
| 备课中断 | 状态机 + 阶段持久化 |
|
||
|
||
---
|
||
|
||
## 15. 开放问题
|
||
|
||
1. SQLite 用 `better-sqlite3` 还是 Zotero `Services.storage` — 待插件 POC 验证 WASM/ native 限制
|
||
2. MinerU 随插件分发 vs 用户自行安装 Python 环境
|
||
3. 问答 TTS MVP 用流式还是整段合成（影响架构复杂度）
|
||
4. 伴读库窗口：全库扫描性能（>5000 items 时的索引策略）
|
||
|
||
---
|
||
|
||
## 16. 文档修订记录
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| v0.1 | 2026-08-29 | 自 PLAN.md 拆分为架构初稿 |
|