产品需求规格说明书（PRD）
| 字段 |
内容 |
| 产品名称 |
BanDu（伴读）— Zotero 插件 |
| 中文名 |
伴读 |
| 英文名 |
BanDu |
| 文档版本 |
v0.1 |
| 状态 |
草案 |
| 关联文档 |
PLAN.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。
主流程：
- 用户在 Zotero 选中带 PDF 的 Item
- 打开 Item pane「伴读」标签页
- 点击「开始备课」
- 系统解析 PDF，展示进度（解析 → 摘要 → beats → 逐段讲解 → TTS）
- 摘要 + beats 就绪后（约 1–2 min），整体讲解模式可用，用户开始收听
- 用户可随时暂停、提问、切换逐段精读、标记重点
- 用户点击「生成报告」或收听达阈值后，系统创建 Zotero 子笔记
后置条件：本地 SQLite + mp3 缓存就绪；Zotero 子笔记（若生成）可搜索。
3.3 用例：缓存命中二次打开
前置条件：该 attachment 已备课且文件哈希未变。
主流程：
- 用户打开同一 Item 的伴读页
- 系统校验 attachment ID + 文件哈希，命中缓存
- 立即展示播放器，恢复上次播放进度
- 不调用 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；关键交互原则：
- 读者发起，系统不打扰：播完不弹「有疑问吗」
- 原文始终可见：讲解与原文并排，降低幻觉信任成本
- 进度可感知：首次备课、增量生成、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 验收清单
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 前 |
