# 产品需求规格说明书（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 | 状态与 `