yhy/chatpapers
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
37025276132d3d5cc105da4cc4323438fa28709b
chatpapers/docs/newidea/DUAL_MODE_PRD.md
T
yhy 3a2438f566 增加语音对话功能
2026-08-29 22:13:55 +08:00

23 KiB
Raw Blame History

ChatPapers 双模式集成需求规格说明书

字段 内容
文档名称 双模式集成 PRD（方案 A）
插件名称 ChatPapers for Zotero
新增模式 BanDu（伴读）
文档版本 v0.1
状态 草案
目标平台 Zotero 9（macOS / Windows）
关联文档 ChatPapers 需求、BanDu 策划、BanDu PRD、BanDu 架构

本文档定位：在不拆分、不 fork 的前提下，将 BanDu（伴读）作为 ChatPapers 插件的第二种工作模式纳入同一产品。
原有 ChatPapers 对话模式的需求以 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 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 双模式集成需求
Reference in New Issue View Git Blame Copy Permalink