486 lines
23 KiB
Markdown
486 lines
23 KiB
Markdown
# ChatPapers 双模式集成需求规格说明书
|
||
|
||
| 字段 | 内容 |
|
||
|------|------|
|
||
| 文档名称 | 双模式集成 PRD（方案 A） |
|
||
| 插件名称 | ChatPapers for Zotero |
|
||
| 新增模式 | BanDu（伴读） |
|
||
| 文档版本 | v0.1 |
|
||
| 状态 | 草案 |
|
||
| 目标平台 | Zotero 9（macOS / Windows） |
|
||
| 关联文档 | [ChatPapers 需求](../requirements.md)、[BanDu 策划](./PLAN.md)、[BanDu PRD](./PRD.md)、[BanDu 架构](./ARCHITECTURE.md) |
|
||
|
||
> **本文档定位**：在**不拆分、不 fork** 的前提下，将 BanDu（伴读）作为 ChatPapers 插件的**第二种工作模式**纳入同一产品。
|
||
> 原有 ChatPapers 对话模式的需求以 [requirements.md](../requirements.md) 为准，本文仅描述**集成策略、共享边界、伴读模式增量需求**。
|
||
|
||
---
|
||
|
||
## 1. 产品概述
|
||
|
||
### 1.1 一句话定位
|
||
|
||
**ChatPapers** = Zotero 内的 AI 论文助手：**对话模式**用于即时问答与总结，**伴读模式**用于 AI 老师式音频授课与知识沉淀——同一插件、同一论文库、两种互补工作流。
|
||
|
||
### 1.2 双模式心智模型
|
||
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ ChatPapers for Zotero │
|
||
│ （一个插件 · 一套 Zotero 集成） │
|
||
└───────────────┬─────────────────┘
|
||
│
|
||
┌─────────────────────┴─────────────────────┐
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────────────┐ ┌──────────────────────┐
|
||
│ 模式 A：对话 Chat │ │ 模式 B：伴读 BanDu │
|
||
│ 「我现在想问什么」 │ │ 「请老师先备课再讲」 │
|
||
├──────────────────────┤ ├──────────────────────┤
|
||
│ 即时问答 / 一键总结 │ │ 备课 → 听课 → 报告 │
|
||
│ 文字流式回复 │ │ 整体讲解 / 逐段精读 │
|
||
│ 选区提问 │ │ TTS 音频 + 播放器 │
|
||
│ 会话 JSON 持久化 │ │ Lecture SQLite 缓存 │
|
||
└──────────────────────┘ └──────────────────────┘
|
||
│ │
|
||
└─────────────────────┬─────────────────────┘
|
||
▼
|
||
共享：PDF 附件 · LLM 配置 · 子笔记 · BibTeX
|
||
```
|
||
|
||
### 1.3 为什么采用双模式（方案 A）
|
||
|
||
| 考量 | 说明 |
|
||
|------|------|
|
||
| 用户价值互补 | Chat 适合「带着问题读」；伴读适合「先听一遍再精读」 |
|
||
| 工程复用 | LLM 客户端、PDF 附件解析、笔记回写、引用导出、设置页已在 Chat 模式实现 |
|
||
| 安装成本 | 用户只装一个插件，不重复配置 Provider / API Key |
|
||
| 数据闭环 | 伴读报告与 Chat 笔记均写入同一 Zotero Item，写作时可统一检索 |
|
||
| 品牌演进 | 短期保留 ChatPapers 主品牌；伴读作为子品牌「BanDu」在 UI 内露出 |
|
||
|
||
### 1.4 产品目标（伴读模式增量）
|
||
|
||
| 目标 | 说明 |
|
||
|------|------|
|
||
| G-B1 降低读论文门槛 | 10–20 分钟整体讲解把握论文核心 |
|
||
| G-B2 支持深度精读 | 逐段三层讲解 + 按需逐句解释 |
|
||
| G-B3 闭环沉淀知识 | 伴读报告、问答、重点标记写入 Zotero 子笔记 |
|
||
| G-B4 零迁移成本 | 论文库沿用 Zotero，PDF 不出本地 |
|
||
|
||
### 1.5 成功指标（伴读 MVP 验证期）
|
||
|
||
| 指标 | 目标 |
|
||
|------|------|
|
||
| 整体讲解完成率 | ≥ 60% 启动后听完 |
|
||
| 单篇备课可听时间 | 摘要 + beats 生成后 ≤ 2 min 可开听 |
|
||
| 问答首字延迟 | ≤ 3 s（文字） |
|
||
| 解析可用率 | 典型 8 页 NLP 论文 ≥ 90% 段落无需手动修正 |
|
||
| 模式切换无摩擦 | 同一 Item 可在 Chat / 伴读 pane 间切换，互不丢状态 |
|
||
|
||
---
|
||
|
||
## 2. 范围定义
|
||
|
||
### 2.1 一期包含（伴读模式 MVP）
|
||
|
||
- 在现有 ChatPapers 插件内新增 Item pane **「伴读」** 标签页（与现有 **「ChatPapers」** 标签页并存）
|
||
- 读取 Zotero PDF 附件 → 本地结构化解析 → 段落树
|
||
- 备课流水线：全文摘要 + 整体讲解 beats + 逐段三层讲解；增量备课
|
||
- TTS 合成 + 本地 mp3 缓存
|
||
- 播放器：整体讲解 / 逐段精读、跳播、语速、文字面板高亮、PDF 页跳转
|
||
- 文字提问（锚定 beat / 段落 / 句子 / 全局）→ 文字 + 语音回答
|
||
- 伴读报告 + 参考文献卡片 → Zotero 子笔记
|
||
- 伴读专属设置项（TTS、教师风格）；LLM 设置与 Chat 模式**共享**
|
||
- 断点续播、本地 Lecture 缓存
|
||
|
||
### 2.2 一期明确不包含
|
||
|
||
| 功能 | 计划版本 | 备注 |
|
||
|------|----------|------|
|
||
| 语音输入（ASR）、barge-in | v1.1 | 两模式均不涉及 |
|
||
| 章节边界软提示、难点句清单 | v1.1 | 伴读专属 |
|
||
| PDF viewer 内段落级高亮 | v1.1 | 伴读专属 |
|
||
| 检验模式（老师考读者） | v2 | 伴读专属 |
|
||
| Chat 模式重构或合并 UI | — | Chat 保持独立 pane |
|
||
| 独立 BanDu 插件安装包 | — | 不 fork |
|
||
|
||
### 2.3 共享能力边界（不重复建设）
|
||
|
||
以下能力由 ChatPapers 基座提供，伴读模式**直接复用**，不在伴读 MVP 中重写：
|
||
|
||
| 共享模块 | 现有实现 | 伴读用法 |
|
||
|----------|----------|----------|
|
||
| Item pane 注册机制 | `readerPane.ts` | 注册第二个 section |
|
||
| PDF 附件定位 | `extractor.findPdfAttachment` | 获取路径；伴读另需 file hash |
|
||
| LLM 流式客户端 | `llm/client.ts` | 备课 + 问答 |
|
||
| Provider 预设 | `llm/providers.ts` | 共享同一套 LLM 配置 |
|
||
| 子笔记创建 | `zotero/notes.ts` | 伴读报告写入 |
|
||
| BibTeX / 引用导出 | `zotero/citeExport.ts` | 参考文献卡片 |
|
||
| PDF 选区读取 | `pdf/selection.ts` | 「解释这句」入口 |
|
||
| 偏好设置框架 | `ui/prefs.ts` | 扩展 TTS / 教师风格分组 |
|
||
| Markdown 渲染 | `utils/markdown.ts` | 报告预览（可选） |
|
||
|
||
### 2.4 模式专属能力（伴读新建）
|
||
|
||
| 模块 | 说明 | 代码归属（建议） |
|
||
|------|------|------------------|
|
||
| 结构化 PDF 解析 | MinerU → 段落树 | `src/modules/bandu/infrastructure/pdf/` |
|
||
| 备课流水线 | 摘要 / beats / 三层讲解 | `src/modules/bandu/application/` |
|
||
| TTS 客户端 | mp3 + timestamps | `src/modules/bandu/infrastructure/tts/` |
|
||
| SQLite 存储 | Lecture / 进度 / Q&A | `src/modules/bandu/infrastructure/storage/` |
|
||
| RAG 检索 | FTS5 段落检索 | `src/modules/bandu/infrastructure/rag/` |
|
||
| 播放器 UI | `<audio>` + 状态机 | `src/modules/bandu/ui/` |
|
||
| 伴读 pane | BanduPane | `src/modules/bandu/ui/banduPane.ts` |
|
||
|
||
---
|
||
|
||
## 3. 用户故事
|
||
|
||
### 3.1 跨模式用户故事
|
||
|
||
| ID | 作为… | 我想要… | 以便… | 优先级 |
|
||
|----|-------|---------|-------|--------|
|
||
| US-X01 | 研究者 | 在同一篇论文上切换「对话」与「伴读」 | 先听课再针对性 Chat，或 Chat 后再系统听课 | P1 |
|
||
| US-X02 | 研究者 | 只配置一次 LLM API Key | 两种模式共用，降低设置成本 | P0 |
|
||
| US-X03 | 研究者 | Chat 笔记与伴读报告都挂在同一 Item 下 | 写论文时在 Zotero 内统一搜索 | P0 |
|
||
|
||
### 3.2 伴读模式用户故事（P0）
|
||
|
||
| ID | 作为… | 我想要… | 以便… |
|
||
|----|-------|---------|-------|
|
||
| US-B01 | 研究者 | 选中论文后一键「开始备课」 | AI 先读完整篇再讲解 |
|
||
| US-B02 | 研究者 | 选择「整体讲解」收听 | 20 分钟内把握核心 |
|
||
| US-B03 | 研究者 | 选择「逐段精读」按章节听 | 深入理解方法与实验 |
|
||
| US-B04 | 研究者 | 播放中随时文字提问 | 不打断思路又能澄清疑问 |
|
||
| US-B05 | 研究者 | 选中难句点「解释这句」 | 快速理解长难句 |
|
||
| US-B06 | 研究者 | 听完后生成伴读报告到 Zotero | 写论文时搜索调出素材 |
|
||
| US-B07 | 研究者 | 二次打开同一篇秒进、离线重听 | 不重复花 API 费用 |
|
||
| US-B08 | 研究者 | 标记重点段落 | 报告汇总关心部分 |
|
||
| US-B09 | 研究者 | 配置 TTS API Key | 控制成本与音质 |
|
||
|
||
---
|
||
|
||
## 4. 界面与交互需求
|
||
|
||
### 4.1 Item Pane 双标签布局
|
||
|
||
```
|
||
Zotero Item Pane（同一 PDF 条目）
|
||
├── [ChatPapers] ← 现有：对话 / 总结 / 存笔记
|
||
└── [伴读 BanDu] ← 新增：备课 / 播放 / 报告
|
||
```
|
||
|
||
| ID | 需求 | 优先级 | 验收标准 |
|
||
|----|------|--------|----------|
|
||
| UI-001 | 两个 pane section 独立注册、独立生命周期 | P0 | 切换 tab 不互相 destroy 对方状态 |
|
||
| UI-002 | 伴读 pane 在无 PDF 时禁用并提示 | P0 | 与 Chat pane 行为一致 |
|
||
| UI-003 | 伴读 pane 头部展示论文标题 + 备课状态 | P0 | 见 §4.3 状态文案 |
|
||
| UI-004 | 设置页分「通用 LLM」「ChatPapers」「伴读」三个分组 | P0 | LLM 配置只填一次 |
|
||
| UI-005 | 伴读库窗口（全库状态列表） | P1 | MVP 可简版或后置 |
|
||
|
||
### 4.2 伴读页布局（BanDu Pane）
|
||
|
||
布局沿用 [PLAN.md §3.6](./PLAN.md) wireframe，关键区域：
|
||
|
||
- 模式切换：整体讲解 | 逐段精读
|
||
- 播放控制：▶ ⏸ ⏮ ⏭ 1x / 1.5x / 2x
|
||
- 左侧：单位列表（beats 或段落），含已听 / 未听 / ★ 标记
|
||
- 右侧：当前讲解文本 + 原文对照 + 提问区
|
||
- 底部/侧栏：「生成报告」「看原文（跳 PDF 页）」
|
||
|
||
### 4.3 状态展示
|
||
|
||
| 状态 | 用户可见文案 |
|
||
|------|--------------|
|
||
| 未备课 | 「点击开始备课」 |
|
||
| 解析中 | 「正在读取论文… {percent}%」 |
|
||
| 备课中（可部分播放） | 「整体讲解已就绪，逐段讲解生成中 {n}/{total}」 |
|
||
| 已备课 | 「老师已备课 ✓」 |
|
||
| 播放中 | 当前单位高亮 + 进度条 |
|
||
| 离线可听 | 「已缓存，离线可播放」 |
|
||
|
||
### 4.4 模式间交互原则
|
||
|
||
- **不强制串联**：用户可只用 Chat、只用伴读，或组合使用
|
||
- **不自动同步上下文**：Chat 会话历史不自动注入伴读问答（v1.1 可评估「从 Chat 导入问题」）
|
||
- **笔记类型区分**：Chat 存笔记标题前缀 `ChatPapers:`；伴读报告 `BanDu 伴读报告:`，避免覆盖
|
||
- **读者发起，系统不打扰**：伴读播完不弹「有疑问吗」（与 BanDu 策划一致）
|
||
|
||
---
|
||
|
||
## 5. 功能需求
|
||
|
||
### 5.1 插件集成（双模式）
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| DM-001 | 伴读作为 ChatPapers 插件内独立模块加载，不新增 addon ID | P0 | 单一 `.xpi`，manifest 不变 |
|
||
| DM-002 | `hooks.ts` 启动时同时注册 Chat pane 与 Bandu pane | P0 | 两 pane 均可用 |
|
||
| DM-003 | 模块代码物理隔离：`src/modules/bandu/` 与 `src/modules/ui/chatView.ts` 分离 | P0 | 无循环依赖 |
|
||
| DM-004 | 伴读不得修改 Chat 模式现有行为与 API | P0 | Chat 回归测试通过 |
|
||
|
||
### 5.2 PDF 解析与段落树（伴读专属）
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-B010 | 本地解析 PDF，输出章节 / 段落 / 要点三层结构 | P0 | 段落含唯一 ID、原文、页码、章节路径 |
|
||
| FR-B011 | 支持双栏、公式、表格的常见学术论文版式 | P0 | Dogfooding 3 类典型论文可用 |
|
||
| FR-B012 | 解析结果持久化至 SQLite，key = attachment ID + 文件哈希 | P0 | PDF 未变时跳过重复解析 |
|
||
| FR-B013 | 解析进度与错误对用户可见 | P0 | 扫描版等给出可行动提示 |
|
||
| FR-B014 | 文字面板展示解析原文供核对 | P1 | 用户可发现 bad case |
|
||
|
||
> **与 Chat 模式关系**：Chat 继续使用 `PDFWorker` 纯文本提取；伴读使用 MinerU 结构化解析。两路径并存，互不替换。
|
||
|
||
### 5.3 备课（Lecture 生成）
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-B020 | 生成全文摘要：问题 / 方法 / 结果 / 局限 | P0 | 四字段非空、中文 |
|
||
| FR-B021 | 生成 8–15 个整体讲解 beat，按教学逻辑排序 | P0 | 每 beat 含讲解文本、类型、refs[] |
|
||
| FR-B022 | beat 的 refs[] 生成后校验，非法引用剔除 | P0 | 无效 refs 的 beat 降级 |
|
||
| FR-B023 | 每个 beat 含三要素：为什么重要 / 例子或数字 / 易混淆点 | P0 | Prompt 约束 |
|
||
| FR-B024 | 每个段落生成三层讲解 | P0 | 讲了什么 / 怎么理解 / 全文定位 |
|
||
| FR-B025 | 增量备课：摘要 + beats 完成后即可播放整体讲解 | P0 | 无需等逐段全部完成 |
|
||
| FR-B026 | 逐段讲解后台继续生成，UI 显示进度 | P0 | 新段落就绪后可播放 |
|
||
| FR-B027 | Lecture 本地缓存，二次打开不重复生成 | P0 | 除非哈希变化或强制重备 |
|
||
|
||
### 5.4 TTS 与音频
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-B030 | 讲解文本按 beat / 段落分片合成 mp3 并本地缓存 | P0 | 路径与 Lecture 单元绑定 |
|
||
| FR-B031 | 英文论文音频为中文讲解 | P0 | 自动检测论文语言 |
|
||
| FR-B032 | 保存 word timestamps（若 TTS 提供） | P0 | 用于文字高亮 |
|
||
| FR-B033 | 无 timestamps 时降级句子级 / 段落级高亮 | P0 | UI 不崩溃 |
|
||
| FR-B034 | 问答回答支持 TTS 播放 | P0 | 每轮 Q&A 可重播 |
|
||
| FR-B035 | TTS 配置在设置页「伴读」分组，与 LLM 配置分离 | P0 | Chat 模式不依赖 TTS |
|
||
|
||
### 5.5 播放器
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-B040 | 模式切换：整体讲解 / 逐段精读 | P0 | 列表与播放单位正确 |
|
||
| FR-B041 | 播放 / 暂停 / 上一单位 / 下一单位 / 1x·1.5x·2x | P0 | 与 `<audio>` 同步 |
|
||
| FR-B042 | 单位列表展示已听 / 未听；断点续播 | P0 | 恢复正确单位 |
|
||
| FR-B043 | 整体模式：beat 文本 + refs 来源段落高亮 | P0 | — |
|
||
| FR-B044 | 逐段模式：原文 + 三层讲解，高亮跟随音频 | P0 | 至少句子级 |
|
||
| FR-B045 | 「看原文」跳转 PDF 对应页 | P0 | 页码与段落 page 一致 |
|
||
| FR-B046 | 点击列表任意行跳播 | P0 | Seek 到该单位起始 |
|
||
| FR-B047 | 段落「重点标记」★ | P0 | 写入进度并进入报告 |
|
||
|
||
### 5.6 问答（伴读上下文）
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-B050 | 文字提问，锚定 beat / 段落 / 句子 / 全局 | P0 | 上下文含锚点原文与讲解 |
|
||
| FR-B051 | 选中句子触发「解释这句」 | P0 | 翻译 + 句法 + 上下文作用 |
|
||
| FR-B052 | 回答基于 RAG：当前单位 + 摘要 + 检索相关段 | P0 | 长论文不整篇塞入 Prompt |
|
||
| FR-B053 | 回答文字流式显示，随后 TTS | P0 | 首 token ≤ 3 s |
|
||
| FR-B054 | Q&A 写入本地记录并纳入伴读报告 | P0 | 可按段落分组 |
|
||
|
||
> **与 Chat 模式关系**：伴读问答使用独立 `qa_record` 表与锚点模型；不复用 Chat 的 `sessions/*.json`，避免数据结构冲突。
|
||
|
||
### 5.7 伴读报告与参考文献
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-B060 | 手动或条件触发「生成报告」 | P0 | 更新策略：同名 Note 覆盖 |
|
||
| FR-B061 | 报告结构：速览 / 收听 / 问答 / 重点 / 参考文献卡片 | P0 | Markdown 结构固定 |
|
||
| FR-B062 | 参考文献卡片含 BibTeX | P0 | 复用 `citeExport` |
|
||
| FR-B063 | Note 标题格式 `BanDu 伴读报告: {title}` | P0 | 与 Chat 笔记可区分 |
|
||
|
||
### 5.8 设置（共享 + 专属）
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-S010 | LLM Provider / Base URL / API Key / Model | P0 | **共享**，两模式只读同一 prefs |
|
||
| FR-S011 | Chat 专属：system prompt、summary prompt、answer language | P0 | 已有，不变 |
|
||
| FR-S012 | 伴读专属：TTS Provider / API Key / 音色 | P0 | 新增 prefs 前缀或分组 |
|
||
| FR-S013 | 伴读专属：教师风格预设（简洁 / 详细） | P1 | 仅影响新生成内容 |
|
||
| FR-S014 | 数据流向说明（哪些文本发往外网） | P0 | 设置页固定文案 |
|
||
|
||
---
|
||
|
||
## 6. 非功能需求
|
||
|
||
| ID | 类别 | 需求描述 | 指标 |
|
||
|----|------|----------|------|
|
||
| NFR-D001 | 隔离性 | 伴读模块崩溃不影响 Chat pane 可用 | 异常捕获 + 独立 try/catch 边界 |
|
||
| NFR-D002 | 性能 | 8 页论文本地解析 | ≤ 3 min |
|
||
| NFR-D003 | 性能 | 缓存命中后打开伴读页 | ≤ 2 s 可播放 |
|
||
| NFR-D004 | 成本 | 单篇 8 页首次备课总 API 成本 | ≤ ¥10 |
|
||
| NFR-D005 | 隐私 | PDF 不上传；段落文本按请求发送 | Local-first |
|
||
| NFR-D006 | 离线 | 已缓存 Lecture + mp3 可离线播放 | 除问答外不依赖网络 |
|
||
| NFR-D007 | 可维护性 | UI / 领域 / Zotero 适配三层分离 | 见 ARCHITECTURE.md |
|
||
| NFR-D008 | 存储 | 伴读数据目录 `{Profile}/chatpapers/bandu/` | 与 `sessions/` 并列，不混用 |
|
||
| NFR-D009 | 兼容性 | Zotero 9.x | 与现有 manifest 一致 |
|
||
|
||
---
|
||
|
||
## 7. 数据与存储策略
|
||
|
||
### 7.1 目录布局
|
||
|
||
```
|
||
{ZoteroProfile}/chatpapers/
|
||
├── sessions/ # Chat 模式（已有）：*.json
|
||
└── bandu/ # 伴读模式（新增）
|
||
├── bandu.db # SQLite
|
||
└── audio/
|
||
└── {cacheKey}/
|
||
└── {unitId}.mp3
|
||
```
|
||
|
||
### 7.2 缓存键
|
||
|
||
```
|
||
cacheKey = SHA256(attachmentId + "|" + fileHash)
|
||
```
|
||
|
||
Chat 模式继续使用 `itemKey + attachmentKey` 会话文件；伴读使用 `cacheKey`，**互不干扰**。
|
||
|
||
### 7.3 笔记命名约定
|
||
|
||
| 来源 | Note 标题前缀 | 覆盖策略 |
|
||
|------|---------------|----------|
|
||
| ChatPapers | `ChatPapers:` 或用户自定义 | 每次新建或用户选择 |
|
||
| BanDu | `BanDu 伴读报告:` | 同名更新，避免笔记爆炸 |
|
||
|
||
---
|
||
|
||
## 8. 技术集成约束
|
||
|
||
### 8.1 建议目录结构
|
||
|
||
```
|
||
src/
|
||
├── hooks.ts # 注册双 pane
|
||
├── modules/
|
||
│ ├── ui/
|
||
│ │ ├── readerPane.ts # 注册 Chat + Bandu section
|
||
│ │ ├── chatView.ts # Chat 模式（不动）
|
||
│ │ └── prefs.ts # 扩展伴读设置分组
|
||
│ ├── llm/ # 共享
|
||
│ ├── pdf/
|
||
│ │ ├── extractor.ts # 共享：附件定位
|
||
│ │ └── selection.ts # 共享：选区
|
||
│ ├── zotero/ # 共享：notes, citeExport
|
||
│ ├── storage/
|
||
│ │ └── sessions.ts # Chat 专属（不动）
|
||
│ └── bandu/ # 伴读专属（新建）
|
||
│ ├── ui/
|
||
│ │ ├── banduPane.ts
|
||
│ │ └── player/
|
||
│ ├── application/
|
||
│ ├── domain/
|
||
│ └── infrastructure/
|
||
│ ├── pdf/ # MinerU 封装
|
||
│ ├── tts/
|
||
│ ├── storage/ # SQLite
|
||
│ └── rag/
|
||
```
|
||
|
||
### 8.2 依赖规则
|
||
|
||
```
|
||
bandu/* ──可引用──► llm/, pdf/extractor, pdf/selection, zotero/, utils/
|
||
chatView ──不可引用──► bandu/* （Chat 保持独立，避免耦合）
|
||
bandu/* ──不可引用──► chatView, storage/sessions
|
||
```
|
||
|
||
### 8.3 Phase 0 验证项（开工前 Go / No-Go）
|
||
|
||
| # | 验证项 | 通过标准 | 阻塞 MVP |
|
||
|---|--------|----------|----------|
|
||
| P0-1 | 第二 Item pane section 注册 | 与 Chat pane 并存无冲突 | 是 |
|
||
| P0-2 | MinerU 解析 3 篇论文 | 段落可用率 ≥ 80% | 是 |
|
||
| P0-3 | Zotero 9 插件内 SQLite 读写 | CRUD 正常 | 是 |
|
||
| P0-4 | `<audio>` 长音频播放 | 10 min+ 无泄漏 | 是 |
|
||
| P0-5 | TTS 中文样本 + timestamps | 自然度可接受；无则确认降级 | 否 |
|
||
|
||
---
|
||
|
||
## 9. 版本与路线图
|
||
|
||
### 9.1 与现有 ChatPapers 版本关系
|
||
|
||
| 插件版本 | Chat 模式 | 伴读模式 |
|
||
|----------|-----------|----------|
|
||
| v0.2.x（当前） | 对话 / 总结 / 多 PDF | — |
|
||
| v0.3.0 | 维护 | Phase 0 POC |
|
||
| v0.4.0 – v0.5.0 | 维护 | M1–M2：解析 + 备课 + TTS + 播放器 |
|
||
| v0.6.0 | 维护 | M3–M4：问答 RAG + 报告 + dogfooding |
|
||
| v1.0.0 | 稳定 | 伴读 MVP 功能完整 |
|
||
|
||
### 9.2 伴读模式开发里程碑
|
||
|
||
| 阶段 | 时间 | 交付 |
|
||
|------|------|------|
|
||
| Phase 0 | 第 0 周 | 三项 POC + 双 pane 骨架占位 |
|
||
| M1 | 第 1–2 周 | MinerU 解析 + 段落树 + 备课流水线（纯文本） |
|
||
| M2 | 第 3–4 周 | TTS + 播放器双模式 + 高亮 |
|
||
| M3 | 第 5–6 周 | 锚定问答 RAG + 伴读报告回写 |
|
||
| M4 | 第 7–8 周 | 增量缓存 / 断点续播 / 设置 / dogfooding 10 篇 |
|
||
|
||
---
|
||
|
||
## 10. MVP 验收清单（伴读模式）
|
||
|
||
- [ ] 安装单一 ChatPapers `.xpi`，Item pane 同时出现 ChatPapers 与伴读两个标签
|
||
- [ ] LLM 配置一次，两模式均可调用
|
||
- [ ] 对 1 篇 8 页英文 PDF 完成：解析 → 备课 → 整体讲解播放
|
||
- [ ] 切换到逐段精读并完成至少 1 个章节播放
|
||
- [ ] 提问 3 次（含 1 次全局 + 1 次逐句），文字与语音均有
|
||
- [ ] 标记 2 个重点段落
|
||
- [ ] 生成伴读报告至 Zotero 子笔记，含 BibTeX；与 Chat 笔记共存不覆盖
|
||
- [ ] 关闭 Zotero 再打开，缓存命中、断点续播
|
||
- [ ] 断网重听已缓存内容
|
||
- [ ] Chat 模式原有功能回归通过（对话 / 总结 / 存笔记）
|
||
|
||
---
|
||
|
||
## 11. 术语表
|
||
|
||
| 术语 | 定义 |
|
||
|------|------|
|
||
| Chat 模式 | ChatPapers 现有对话 / 总结工作流 |
|
||
| 伴读模式 / BanDu | 本插件内第二种工作流：备课 → 听课 → 报告 |
|
||
| 双模式 | 同一插件、两个 Item pane、共享 LLM 与 Zotero 集成 |
|
||
| Lecture | 一次备课产物：摘要 + beats + 逐段讲解 |
|
||
| Beat | 整体讲解播放单位，含 refs[] |
|
||
| 共享层 | llm / zotero / pdf 附件 / utils，两模式复用 |
|
||
|
||
---
|
||
|
||
## 12. 文档关系
|
||
|
||
```
|
||
docs/requirements.md ChatPapers 对话模式需求（不变）
|
||
docs/newidea/
|
||
├── PLAN.md BanDu 产品策划（参考）
|
||
├── PRD.md BanDu 独立 PRD（参考）
|
||
├── ARCHITECTURE.md BanDu 技术架构（参考）
|
||
└── DUAL_MODE_PRD.md ★ 本文：双模式集成需求（实施依据）
|
||
```
|
||
|
||
**实施优先级**：开发伴读功能时，以**本文**为集成需求主文档；细节 Prompt、数据表、状态机见 ARCHITECTURE.md；产品动机与竞品见 PLAN.md。
|
||
|
||
---
|
||
|
||
## 13. 待决事项
|
||
|
||
| 事项 | 负责人 | 备注 |
|
||
|------|--------|------|
|
||
| TTS 提供商选型 | 技术 | Phase 0 |
|
||
| SQLite 实现方案（better-sqlite3 vs sql.js） | 技术 | Phase 0 |
|
||
| 伴读 pane 图标与 l10n 命名（BanDu / 伴读） | 产品 | M1 前 |
|
||
| Chat → 伴读上下文导入是否做 v1.1 | 产品 | MVP 不做 |
|
||
| 插件对外宣传：单品牌 vs 双品牌露出 | 产品 | MVP 后 |
|
||
|
||
---
|
||
|
||
## 14. 文档修订记录
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| v0.1 | 2026-08-29 | 初稿：方案 A 双模式集成需求 |
|