324 lines
16 KiB
Markdown
324 lines
16 KiB
Markdown
# 产品需求规格说明书（PRD）
|
||
|
||
| 字段 | 内容 |
|
||
|------|------|
|
||
| 产品名称 | BanDu（伴读）— Zotero 插件 |
|
||
| 中文名 | 伴读 |
|
||
| 英文名 | BanDu |
|
||
| 文档版本 | v0.1 |
|
||
| 状态 | 草案 |
|
||
| 关联文档 | [PLAN.md](./PLAN.md)（产品策划）、[ARCHITECTURE.md](./ARCHITECTURE.md)（架构设计） |
|
||
| 一期范围 | Zotero 7 桌面插件（macOS / Windows） |
|
||
|
||
---
|
||
|
||
## 1. 产品概述
|
||
|
||
### 1.1 一句话定位
|
||
|
||
在 Zotero 里给每篇论文配一位 AI 老师：先读完整篇论文并备好课，再按用户选择的模式授课（整体讲解 / 逐段精读 / 逐句按需），随时提问且系统不主动打扰；听完后将伴读笔记与参考文献卡片写回 Zotero，供写论文时复用。
|
||
|
||
**品牌**：中文名 **伴读**，英文名 **BanDu**（「伴读」音译）。
|
||
|
||
### 1.2 产品目标
|
||
|
||
| 目标 | 说明 |
|
||
|------|------|
|
||
| G1 降低读论文门槛 | 用户可在 10–20 分钟内通过「整体讲解」把握论文核心 |
|
||
| G2 支持深度精读 | 通过「逐段精读」与「逐句按需解释」吃透方法与实验 |
|
||
| G3 闭环沉淀知识 | 伴读报告、问答、重点标记留在 Zotero，可直接用于 Related Work |
|
||
| G4 零迁移成本 | 论文库沿用 Zotero，PDF 不出本地机器 |
|
||
|
||
### 1.3 成功指标（MVP 验证期）
|
||
|
||
| 指标 | 目标 | 测量方式 |
|
||
|------|------|----------|
|
||
| 整体讲解完成率 | ≥ 60% 启动后听完 | 播放进度日志 |
|
||
| 单篇备课可听时间 | 摘要 + beats 生成后 ≤ 2 min 可开听 | 备课流水线耗时 |
|
||
| 问答首字延迟 | ≤ 3 s（文字） | 问答链路埋点 |
|
||
| 报告复用率 | Dogfooding 10 篇中 ≥ 3 篇报告内容被粘贴进写作 | 人工记录 |
|
||
| 解析可用率 | 典型 8 页 NLP 论文 ≥ 90% 段落无需手动修正 | Dogfooding |
|
||
|
||
### 1.4 目标用户
|
||
|
||
| 角色 | 描述 | 一期优先级 |
|
||
|------|------|------------|
|
||
| 研究者（Primary） | 使用 Zotero 管理文献，需快速过大量论文并精读关键篇 | P0 |
|
||
| 研究生 | 英文论文阅读吃力，需要中文讲解与随时提问 | P0 |
|
||
| 论文写作者 | 需要 Related Work 素材、引用句与 BibTeX | P0 |
|
||
|
||
---
|
||
|
||
## 2. 范围定义
|
||
|
||
### 2.1 一期包含（MVP）
|
||
|
||
- Zotero 7 插件：Item pane「伴读」标签页 + 伴读库主窗口（简版）
|
||
- 读取 Zotero PDF 附件 → 本地解析 → 段落树
|
||
- 备课流水线：全文摘要 + 整体讲解 beats + 逐段三层讲解；增量备课
|
||
- TTS 合成 + 本地 mp3 缓存
|
||
- 播放器：整体讲解 / 逐段精读双模式、跳播、语速、文字面板高亮、PDF 页跳转
|
||
- 文字提问（锚定当前位置 / 全局 / 选中句子）→ 文字 + 语音回答
|
||
- 伴读报告 + 参考文献卡片 → Zotero 子笔记；BibTeX
|
||
- 设置页（LLM / TTS / 教师风格）、断点续播、本地缓存
|
||
|
||
### 2.2 一期明确不包含
|
||
|
||
| 功能 | 计划版本 |
|
||
|------|----------|
|
||
| 语音输入提问（ASR）、barge-in 打断 | v1.1 |
|
||
| 章节边界软提示 | v1.1 |
|
||
| 难点句清单（备课预标） | v1.1 |
|
||
| PDF viewer 内段落级高亮 | v1.1 |
|
||
| 英文原文朗读模式 | v1.1 |
|
||
| 检验模式（老师考读者） | v2 |
|
||
| 移动端 App、云同步、多用户订阅 | v2 |
|
||
|
||
### 2.3 不支持场景（需在 UI 明示）
|
||
|
||
- 扫描版 PDF（无 OCR 文本层）
|
||
- Item 无 PDF 附件或非 PDF 附件
|
||
- 加密且无法本地读取的 PDF
|
||
- 极长论文（> 80 页）默认仅推荐整体讲解模式（逐段按需生成）
|
||
|
||
---
|
||
|
||
## 3. 用户故事与用例
|
||
|
||
### 3.1 核心用户故事
|
||
|
||
| ID | 作为… | 我想要… | 以便… | 优先级 |
|
||
|----|-------|---------|-------|--------|
|
||
| US-01 | 研究者 | 选中 Zotero 论文后一键「备课」 | AI 先读完整篇再给我讲解 | P0 |
|
||
| US-02 | 研究者 | 选择「整体讲解」模式收听 | 20 分钟内把握论文核心 | P0 |
|
||
| US-03 | 研究者 | 选择「逐段精读」按章节听 | 深入理解方法与实验 | P0 |
|
||
| US-04 | 研究者 | 播放中随时文字提问 | 不打断思路又能澄清疑问 | P0 |
|
||
| US-05 | 研究者 | 选中难句点「解释这句」 | 快速理解长难句 | P0 |
|
||
| US-06 | 研究者 | 听完后自动生成伴读报告到 Zotero | 写论文时搜索即可调出素材 | P0 |
|
||
| US-07 | 研究者 | 二次打开同一篇论文秒进、离线重听 | 不重复花 API 费用 | P0 |
|
||
| US-08 | 研究者 | 在伴读库看到全部论文的备课/收听状态 | 快速找到未读论文 | P1 |
|
||
| US-09 | 研究者 | 标记重点段落 | 报告里汇总我关心的部分 | P0 |
|
||
| US-10 | 研究者 | 配置自己的 LLM / TTS API Key | 控制成本与隐私 | P0 |
|
||
|
||
### 3.2 用例：首次伴读一篇论文
|
||
|
||
**前置条件**：Zotero 7 已安装插件；Item 有 PDF 附件；用户已配置 LLM Key。
|
||
|
||
**主流程**：
|
||
|
||
1. 用户在 Zotero 选中带 PDF 的 Item
|
||
2. 打开 Item pane「伴读」标签页
|
||
3. 点击「开始备课」
|
||
4. 系统解析 PDF，展示进度（解析 → 摘要 → beats → 逐段讲解 → TTS）
|
||
5. 摘要 + beats 就绪后（约 1–2 min），整体讲解模式可用，用户开始收听
|
||
6. 用户可随时暂停、提问、切换逐段精读、标记重点
|
||
7. 用户点击「生成报告」或收听达阈值后，系统创建 Zotero 子笔记
|
||
|
||
**后置条件**：本地 SQLite + mp3 缓存就绪；Zotero 子笔记（若生成）可搜索。
|
||
|
||
### 3.3 用例：缓存命中二次打开
|
||
|
||
**前置条件**：该 attachment 已备课且文件哈希未变。
|
||
|
||
**主流程**：
|
||
|
||
1. 用户打开同一 Item 的伴读页
|
||
2. 系统校验 attachment ID + 文件哈希，命中缓存
|
||
3. 立即展示播放器，恢复上次播放进度
|
||
4. 不调用 LLM / TTS（除非用户触发重生成或问答）
|
||
|
||
---
|
||
|
||
## 4. 功能需求
|
||
|
||
### 4.1 插件与 Zotero 集成
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-001 | 插件基于 Zotero 7 官方 boilerplate，支持 macOS 与 Windows | P0 | 两平台可安装、启用 |
|
||
| FR-002 | 选中含 PDF 附件的 Item 时，Item pane 显示「伴读」标签页 | P0 | 无 PDF 时标签页禁用并提示原因 |
|
||
| FR-003 | 通过 Zotero API 读取 PDF attachment 本地路径 | P0 | 路径可读、文件哈希可计算 |
|
||
| FR-004 | 伴读报告写入 Item 下 `Zotero.Note` 子笔记（Markdown） | P0 | 笔记在 Zotero 内可搜索、可导出 .md |
|
||
| FR-005 | 有 Better BibTeX 时读取 citation key；无则降级 | P1 | 卡片中 BibTeX 字段正确或标注缺失 |
|
||
| FR-006 | 伴读库窗口列出库内论文及状态：未备课 / 已备课 / 已听 x% / 有报告 | P1 | 点击条目进入对应伴读页 |
|
||
|
||
### 4.2 PDF 解析与段落树
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-010 | 本地解析 PDF，输出章节 / 段落 / 要点三层结构 | P0 | 段落含唯一 ID、原文、页码、章节路径 |
|
||
| FR-011 | 支持双栏、公式、表格的常见学术论文版式 | P0 | Dogfooding 3 类典型论文可用 |
|
||
| FR-012 | 解析结果持久化至 SQLite，key = attachment ID + 文件哈希 | P0 | PDF 未变时跳过重复解析 |
|
||
| FR-013 | 解析进度与错误对用户可见 | P0 | 失败时给出可行动提示（如扫描版） |
|
||
| FR-014 | 文字面板展示解析原文，供用户核对 | P1 | 用户可发现 bad case |
|
||
|
||
### 4.3 备课（Lecture 生成）
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-020 | 生成全文摘要：问题 / 方法 / 结果 / 局限 | P0 | 四字段非空、中文 |
|
||
| FR-021 | 生成 8–15 个整体讲解 beat，按教学逻辑排序 | P0 | 每 beat 含讲解文本、类型标签、refs[] |
|
||
| FR-022 | beat 的 refs[] 仅允许引用已存在段落 ID；生成后校验，非法引用剔除 | P0 | 校验日志可审计；无效 refs 的 beat 降级 |
|
||
| FR-023 | 每个 beat 含三要素：为什么重要 / 具体例子或数字 / 易混淆点 | P0 | Prompt 模板约束 + 抽检 |
|
||
| FR-024 | 为每个段落生成三层讲解：讲了什么 / 怎么理解 / 全文定位 | P0 | 三层均非空 |
|
||
| FR-025 | 增量备课：摘要 + beats 完成后即可播放整体讲解 | P0 | 用户无需等逐段全部完成 |
|
||
| FR-026 | 逐段讲解后台继续生成，UI 显示进度 | P0 | 新段落就绪后可播放 |
|
||
| FR-027 | Lecture 对象本地缓存，二次打开不重复生成 | P0 | 除非文件哈希变化或用户强制重备 |
|
||
| FR-028 | 支持一键重生成单个 beat 或单段讲解 | P1 | 重生成后更新缓存与音频 |
|
||
|
||
### 4.4 TTS 与音频
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-030 | 讲解文本按 beat / 段落分片合成 mp3 并本地缓存 | P0 | 文件路径与 Lecture 单元绑定 |
|
||
| FR-031 | 英文论文音频为中文讲解；自动检测论文语言切换 Prompt | P0 | 英/中论文各测 1 篇 |
|
||
| FR-032 | 保存 word / character timestamps（若 TTS 提供） | P0 | 用于文字面板高亮 |
|
||
| FR-033 | TTS 不支持 timestamps 时，降级为句子级或段落级高亮 | P0 | UI 不崩溃，高亮粒度下降可接受 |
|
||
| FR-034 | 问答回答支持 TTS 播放（可先整段合成，非必须流式） | P0 | 每轮 Q&A 可重播语音 |
|
||
|
||
### 4.5 播放器
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-040 | 支持模式切换：整体讲解 / 逐段精读 | P0 | 切换后列表与播放单位正确 |
|
||
| FR-041 | 播放控制：播放 / 暂停 / 上一单位 / 下一单位 / 1x·1.5x·2x | P0 | 状态与 `<audio>` 同步 |
|
||
| FR-042 | 单位列表展示进度：已听 / 未听；播放中自动滚动 | P0 | 断点续播恢复正确单位 |
|
||
| FR-043 | 整体模式：文字面板展示 beat 文本 + refs 来源段落高亮 | P0 | 高亮与当前 beat 一致 |
|
||
| FR-044 | 逐段模式：左侧原文 + 右侧三层讲解，高亮跟随音频 | P0 | 至少句子级跟随 |
|
||
| FR-045 | 「看原文」跳转 PDF 对应页 | P0 | 页码与段落 page 字段一致 |
|
||
| FR-046 | 点击列表任意行跳播 | P0 | Seek 到该单位起始 |
|
||
| FR-047 | 段落支持「重点标记」★ | P0 | 标记写入进度并进入报告 |
|
||
|
||
### 4.6 问答
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-050 | 任意时刻文字提问，锚定类型：beat / 段落 / 句子 / 全局 | P0 | 上下文含锚点原文与讲解 |
|
||
| FR-051 | 暂停时提问入口视觉强化 | P1 | 暂停态输入框高亮 |
|
||
| FR-052 | 选中句子触发「解释这句」（逐句讲解） | P0 | 输出：翻译 + 句法拆解 + 上下文作用 |
|
||
| FR-053 | 回答基于 RAG：当前单位 + 全文摘要 + 检索相关段 | P0 | 长论文不整篇塞入 Prompt |
|
||
| FR-054 | 回答文字流式显示，随后 TTS 播放 | P0 | 首 token ≤ 3 s（网络正常） |
|
||
| FR-055 | 所有 Q&A 写入本地记录并纳入伴读报告 | P0 | 可按段落分组展示 |
|
||
| FR-056 | 不支持语音输入与 barge-in（MVP） | — | 仅文字输入 |
|
||
|
||
### 4.7 伴读报告与参考文献卡片
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-060 | 手动或条件触发「生成报告」 | P0 | 不覆盖已有报告时需确认（或版本策略见架构） |
|
||
| FR-061 | 报告结构：论文速览 / 收听情况 / 问答记录 / 重点标记 / 参考文献卡片 | P0 | Markdown 结构固定 |
|
||
| FR-062 | 参考文献卡片：中文速览 + 推荐引用句 + BibTeX | P0 | 可直接粘贴进 LaTeX 写作流 |
|
||
| FR-063 | 支持导出 .md 文件 | P1 | 与 Note 内容一致 |
|
||
|
||
### 4.8 设置
|
||
|
||
| ID | 需求描述 | 优先级 | 验收标准 |
|
||
|----|----------|--------|----------|
|
||
| FR-070 | 配置 LLM 提供商、Endpoint、API Key | P0 | 支持 OpenAI 兼容 API + Ollama |
|
||
| FR-071 | 配置 TTS 提供商与 Key | P0 | 至少支持一种中文 TTS |
|
||
| FR-072 | 教师风格 Prompt 预设（如：简洁 / 详细） | P1 | 变更后对**新生成**内容生效 |
|
||
| FR-073 | 明示数据流向：哪些文本会发往外部 API | P0 | 设置页固定文案 |
|
||
| FR-074 | API Key 安全存储（Zotero 偏好或 OS Keychain） | P0 | 不以明文写入日志 |
|
||
|
||
---
|
||
|
||
## 5. 非功能需求
|
||
|
||
| ID | 类别 | 需求描述 | 指标 |
|
||
|----|------|----------|------|
|
||
| NFR-001 | 性能 | 8 页论文本地解析 | ≤ 3 min（CPU） |
|
||
| NFR-002 | 性能 | 缓存命中后打开伴读页 | ≤ 2 s 可播放 |
|
||
| NFR-003 | 性能 | 问答首字延迟 | ≤ 3 s |
|
||
| NFR-004 | 成本 | 单篇 8 页论文首次备课总 API 成本 | ≤ ¥10 |
|
||
| NFR-005 | 可用性 | 二次打开 / 换模式重听 | 零 LLM/TTS 调用 |
|
||
| NFR-006 | 隐私 | PDF 文件不上传；仅段落文本按请求发送 | Local-first |
|
||
| NFR-007 | 离线 | 已缓存 Lecture + mp3 可离线播放 | 除问答外不依赖网络 |
|
||
| NFR-008 | 可靠性 | 备课/Task 中断后可恢复 | 状态机支持断点续跑 |
|
||
| NFR-009 | 兼容性 | Zotero 7.x 指定 minor 版本范围 | 文档 pin 版本 |
|
||
| NFR-010 | 可维护性 | UI 层与 Zotero API 适配层分离 | 代码模块边界清晰 |
|
||
| NFR-011 | 无障碍 | 播放器键盘可操作（播放/暂停/跳段） | P1 |
|
||
|
||
---
|
||
|
||
## 6. 界面需求摘要
|
||
|
||
伴读页布局见 [PLAN.md §3.6](./PLAN.md)；关键交互原则：
|
||
|
||
- **读者发起，系统不打扰**：播完不弹「有疑问吗」
|
||
- **原文始终可见**：讲解与原文并排，降低幻觉信任成本
|
||
- **进度可感知**：首次备课、增量生成、TTS 合成均有进度反馈
|
||
- **错误可恢复**：解析失败、API 失败提供重试与降级路径
|
||
|
||
### 6.1 状态展示
|
||
|
||
| 状态 | 用户可见文案示例 |
|
||
|------|------------------|
|
||
| 未备课 | 「点击开始备课」 |
|
||
| 解析中 | 「正在读取论文… 45%」 |
|
||
| 备课中（可部分播放） | 「整体讲解已就绪，逐段讲解生成中 12/58」 |
|
||
| 已备课 | 「老师已备课 ✓」 |
|
||
| 播放中 | 当前单位高亮 + 进度条 |
|
||
| 离线可听 | 「已缓存，离线可播放」 |
|
||
|
||
---
|
||
|
||
## 7. 内容质量需求（Prompt / 讲解）
|
||
|
||
| ID | 需求 |
|
||
|----|------|
|
||
| CQ-001 | 讲解必须 grounding 到段落原文，温度偏低 |
|
||
| CQ-002 | 公式转口语，不朗读 LaTeX 符号 |
|
||
| CQ-003 | 专有名词：英文保留 + 中文解释 |
|
||
| CQ-004 | beat 类型标签枚举：问题引入 / 核心方法 / 关键实验 / 结论局限 / 延伸思考 |
|
||
| CQ-005 | 问答需覆盖：翻译 / 理解 / 逻辑 / 关联 / 元认知五类问题 |
|
||
|
||
---
|
||
|
||
## 8. MVP 验收清单
|
||
|
||
- [ ] 在 Zotero 7 安装插件，Item pane 出现伴读页
|
||
- [ ] 对 1 篇 8 页英文 PDF 完成：解析 → 备课 → 整体讲解播放
|
||
- [ ] 切换到逐段精读并完成至少 1 个章节播放
|
||
- [ ] 提问 3 次（含 1 次全局 + 1 次逐句），文字与语音均有
|
||
- [ ] 标记 2 个重点段落
|
||
- [ ] 生成伴读报告至 Zotero 子笔记，含 BibTeX
|
||
- [ ] 关闭 Zotero 再打开，缓存命中、断点续播
|
||
- [ ] airplane 模式（或断网）下重听已缓存内容
|
||
- [ ] Dogfooding 累计 10 篇，记录指标表
|
||
|
||
---
|
||
|
||
## 9. 版本规划（需求视角）
|
||
|
||
| 版本 | 核心交付 |
|
||
|------|----------|
|
||
| Phase 0 | 三项 POC 通过：Zotero pane、MinerU 解析、TTS timestamps |
|
||
| MVP（M1–M4） | 本文 §2.1 全部 P0 需求 |
|
||
| v1.1 | ASR、barge-in、难点句清单、PDF 内高亮、理解度评估 |
|
||
| v2 | 移动端、云同步、检验模式 |
|
||
|
||
---
|
||
|
||
## 10. 术语表
|
||
|
||
| 术语 | 定义 |
|
||
|------|------|
|
||
| BanDu / 伴读 | 产品品牌名；英文 BanDu 为「伴读」音译，Zotero 插件全名 BanDu for Zotero |
|
||
| Lecture | 一次备课的完整产物：摘要 + beats + 逐段讲解 + 元数据 |
|
||
| Beat | 整体讲解模式下的播放单位，30 s–2 min，含 refs[] |
|
||
| 三层讲解 | 讲了什么 / 怎么理解 / 全文定位 |
|
||
| 增量备课 | 摘要与 beats 优先生成，逐段与 TTS 后台继续 |
|
||
| refs[] | Beat 引用的来源段落 ID 列表 |
|
||
| 伴读报告 | 听后汇总写入 Zotero 的 Markdown 笔记 |
|
||
|
||
---
|
||
|
||
## 11. 待决事项
|
||
|
||
| 事项 | 负责人 | 截止 |
|
||
|------|--------|------|
|
||
| TTS 提供商最终选型 | 技术 | Phase 0 |
|
||
| 报告生成：覆盖 vs 追加策略 | 产品 | M3 前 |
|
||
| 极长论文逐段生成策略（全量 vs 按章 lazy） | 产品 + 技术 | M1 前 |
|
||
| Better BibTeX 缺失时的 BibTeX 生成规则 | 技术 | M3 前 |
|