yhy/chatpapers

Fork 0

Files

T

yehongyu 50fd043a2d first commit

2026-07-20 14:40:17 +08:00

16 KiB

Raw Permalink Blame History

ChatPapers 需求文档

版本：v0.2（草案）
更新日期：2026-07-20
状态：待确认（Provider 预设范围已按产品意见更新）
关联：基于仓库根目录初步需求整理

1. 背景与目标

1.1 背景

研究人员日常在 Zotero 中管理大量 PDF 文献。现有 AI 阅读工具多为独立网页或外部应用，存在以下摩擦：

需反复上传 PDF，上下文与 Zotero 条目割裂
对话结果难以回流到文献库（笔记、标签、批注）
工作流在「文献管理器 ↔ AI 工具」之间频繁切换

1.2 产品目标

在 Zotero 9 内提供原生体验的 AI 论文助手，使用户能够：

对着当前 PDF 提问（选中文本 / 全文上下文）
一键生成结构化总结（摘要、贡献、方法、局限等）
把有价值的 AI 输出沉淀为 Zotero Note，与条目长期绑定

1.3 成功标准（MVP）

指标	目标
安装	用户可通过 `.xpi` 安装到 Zotero 9，启用后无需重启即可使用
可用性	打开带 PDF 附件的条目后，≤ 3 次点击进入对话
核心路径	「打开 PDF → 提问 → 得到带引用页码的回答 → 存为笔记」可完整走通
配置	一键切换常用 Provider 预设（含 Ollama / LM Studio / OpenRouter），并可自定义端点；错误提示可读、可排查
隐私	API Key 仅存本地；本地 Provider 默认不外传；云端仅向用户所选端点发送

2. 用户与场景

2.1 目标用户

角色	描述	核心诉求
研究生 / 科研人员	高频阅读、需要快速把握论文要点	总结、方法/实验追问
文献综述作者	批量阅读、需要可比的结构化输出	固定模板总结、笔记归档
隐私敏感用户	不愿使用封闭云端上传产品	自备 API / 本地模型兼容端点

2.2 核心用户故事

作为科研人员，我希望在阅读 PDF 时直接向 AI 提问选中段落，以便快速理解术语与论证。
作为科研人员，我希望一键生成论文结构化摘要并写入笔记，以便后续检索与写作引用。
作为用户，我希望使用自己的 API Key 与自定义 Base URL，以便接入公司代理、国产大模型或任意 OpenAI 兼容服务。
作为用户，我希望一键选择 Ollama / LM Studio / OpenRouter 等常用接入，以便本地离线或聚合云端模型都能立刻用上。
作为用户，我希望对话历史按「条目 / PDF」隔离保存，以便下次打开同一篇论文可续聊。
作为用户，我希望回答尽量标注依据页码或原文片段，以便回读核验，降低幻觉风险。

3. 范围定义

3.1 范围内（In Scope）— MVP

Zotero 9 Bootstrapped 插件安装与生命周期管理
PDF Reader 侧边栏 Chat UI（多轮对话）
当前打开 PDF 的文本提取与上下文组装
选中文本作为「引用上下文」提问
一键总结（可配置 Prompt 模板）
OpenAI Chat Completions 兼容协议（含流式输出）作为统一接入层
常用 Provider 预设（MVP 必做）：Ollama、LM Studio、OpenRouter，以及 OpenAI / DeepSeek 等（见 §4.4）
偏好设置页：Provider 预设、API Key、Base URL、Model、温度、最大 Token、语言、Prompt；本地端点可「探测可用模型」
将选中回复 / 总结保存为当前 Item 的子 Note
中英双语界面（Fluent：zh-CN / en-US）

3.2 范围内 — 后续版本（Post-MVP）

阶段	能力
v0.2	多 PDF / 多条目联合对话；从主窗口条目菜单发起 Chat
v0.3	批注（Highlight）联动：基于高亮内容追问；回复一键生成高亮建议
v0.4	RAG：长文分块 + 向量检索（可插拔 Embedding Provider）
v0.5	本地服务健康检查增强、模型拉取引导、离线模式全局提示
v0.6	批量总结 Collection；导出 Markdown / 结构化 JSON
探索	MCP Server；Anthropic / Gemini 原生协议；图表/公式 OCR

3.3 范围外（Out of Scope）— 当前明确不做

不替代 Zotero 原生 PDF 阅读器
不做独立桌面端或 Web SaaS
不自建账号体系与云端同步对话（对话仅本地）
不提供付费模型转售 / 内置官方 Key
不保证扫描版纯图片 PDF 的 OCR（可作为后续可选引擎）
不兼容 Zotero 6 / 7 / 8（以 Zotero 9 为主；若成本低可放宽 strict_min_version）

4. 功能需求

4.1 安装与入口

ID	需求	优先级
F-01	提供可安装的 `.xpi`；`manifest.json` 声明兼容 Zotero 9	P0
F-02	插件启用/禁用无需重启 Zotero；`shutdown` 清理 UI 与监听	P0
F-03	PDF Reader 右侧边栏提供 ChatPapers Tab / Pane	P0
F-04	主窗口「工具 → ChatPapers 设置」或偏好面板入口	P0
F-05	条目右键菜单：「用 ChatPapers 总结」（Post-MVP 可升为 P0）	P1

4.2 上下文与 PDF

ID	需求	优先级
F-10	识别当前 Reader 打开的 PDF Attachment，绑定 Item Key	P0
F-11	提取 PDF 纯文本（优先 Zotero / PDF.js 已有全文能力）	P0
F-12	超长文本按策略截断或分块（见 5.2）；UI 提示「已截断」	P0
F-13	支持将 Reader 中选中文本注入本轮用户消息	P0
F-14	可选：附带条目标题、作者、年份、DOI、摘要到 System Prompt	P1
F-15	扫描版 / 无文本层 PDF：明确提示无法提取，引导用户处理	P1

4.3 对话与总结

ID	需求	优先级
F-20	多轮对话；支持停止生成（Abort）	P0
F-21	流式展示 Token（SSE / stream）	P0
F-22	内置「总结」动作：使用可编辑模板生成结构化摘要	P0
F-23	预设快捷指令：术语解释、方法复述、局限与质疑、相关工作	P1
F-24	Markdown 渲染回复（标题、列表、代码块、引用）	P0
F-25	复制回复；清空当前会话；新建会话	P0
F-26	会话按 `itemKey + attachmentKey` 本地持久化	P1
F-27	回答尽量要求模型标注页码 / 引用片段（Prompt 约束 + UI 展示）	P1

4.4 AI Provider

设计原则：不绑定单一厂商。MVP 以 OpenAI Chat Completions 兼容协议 为统一客户端；各服务通过「预设 + 可编辑 Base URL / Model / Key」接入。Ollama、LM Studio、OpenRouter 均为 P0。

ID	需求	优先级
F-30	统一客户端支持 OpenAI 兼容 `POST .../chat/completions`（含 stream）	P0
F-31	可配置 Base URL、API Key、Model、Timeout；切换预设时自动填充默认值且允许覆写	P0
F-32	内置 Provider 预设表（见下方）；含 Ollama / LM Studio / OpenRouter 及常用云端	P0
F-33	请求失败：展示 HTTP 状态、可理解错误与重试；本地服务未启动时给出启动提示	P0
F-34	本地 Provider（Ollama / LM Studio）：可选「刷新模型列表」（调用兼容 `/models` 或等价接口）	P1
F-35	本地 Provider：API Key 可为空；UI 不强制填写	P0
F-36	OpenRouter：支持可选 `HTTP-Referer` / `X-Title` 等推荐头（可配置）	P1
F-37	可选记录最近一次请求的 Token 用量（若 API 返回）	P2
F-38	Anthropic Messages / Gemini 原生协议（非兼容层）	P2（Post-MVP）

MVP 内置 Provider 预设

预设 ID	显示名	默认 Base URL	API Key	说明
`ollama`	Ollama	`http://127.0.0.1:11434/v1`	可空	本机本地模型；需用户先 `ollama serve`
`lmstudio`	LM Studio	`http://127.0.0.1:1234/v1`	可空	本机 Local Server；端口以用户设置为准
`openrouter`	OpenRouter	`https://openrouter.ai/api/v1`	必填	聚合多模型；模型名形如 `vendor/model`
`openai`	OpenAI	`https://api.openai.com/v1`	必填	官方 API
`deepseek`	DeepSeek	`https://api.deepseek.com/v1`	必填	常用国产云端
`siliconflow`	硅基流动	`https://api.siliconflow.cn/v1`	必填	常用聚合
`custom`	自定义	用户填写	按服务要求	任意 OpenAI 兼容网关 / 代理

说明：上述默认端口/路径以各产品当前常见配置为准；设置页需提示「若改过端口请手动改 Base URL」。

4.5 与 Zotero 数据联动

ID	需求	优先级
F-40	「保存为笔记」：创建子 Note，标题可配置（默认含日期）	P0
F-41	可选将总结追加到已有 Note，而非总是新建	P1
F-42	不自动修改条目元数据（标题、标签等），除非用户显式操作	P0
F-43	（后续）根据 AI 建议创建 Highlight Annotation	P2

4.6 设置与安全

ID	需求	优先级
F-50	偏好面板完整配置项（见附录 A）	P0
F-51	API Key 使用 Zotero Preferences / 安全存储惯例，不明文写入日志	P0
F-52	默认不上传全文以外的库数据；设置页说明「将发送哪些内容」	P0
F-53	「发送前预览上下文」开关（调试用）	P2

5. 非功能需求

5.1 兼容性

目标：Zotero 9（发布于 2026 年）
applications.zotero.strict_max_version：9.*
strict_min_version：建议 9.0（若需覆盖 8.x，需单独验证后下调）
OS：Windows / macOS / Linux（随 Zotero 官方桌面端）

5.2 性能与限制

项	建议默认值	说明
单次上下文最大字符	80,000（可配置）	超出则截断或分块摘要后再问
流式首字延迟	受模型与网络影响；UI 需有 loading	—
并发请求	单会话同时仅 1 个进行中请求	新请求可取消旧请求
会话历史条数	默认保留最近 50 轮	可清理

5.3 可靠性

网络超时可配置（默认 120s）
Provider 4xx/5xx 不导致插件崩溃
PDF 提取失败有明确降级提示

5.4 可维护性

TypeScript 源码 + ESLint
模块边界清晰：UI / PDF / LLM / Storage / Prefs
关键日志带命名空间前缀，可开关 verbose

5.5 国际化与无障碍

Fluent 本地化，至少中英
侧边栏控件具备可访问名称；支持键盘发送（Enter / Ctrl+Enter 策略可配置）

5.6 许可

建议开源协议：AGPL-3.0 或 MIT（待决策）
第三方依赖遵循各自许可，在 NOTICE 中声明

6. 信息架构与交互草案

6.1 主要界面

PDF Reader 侧边栏 — Chat
- 顶部：当前论文短标题、模型名、设置入口
- 中部：消息列表（User / Assistant）
- 底部：输入框、附加选区按钮、发送、停止、快捷动作（总结）
偏好面板 — ChatPapers
- Provider、凭据、模型、生成参数、Prompt 模板、隐私说明
（可选）独立对话窗口：侧边栏空间不足时弹出（P2）

6.2 关键流程（MVP 主路径）

安装插件 → 配置 API → 打开 PDF
    → 打开 ChatPapers 面板
    →（可选）选中文本「添加到上下文」
    → 输入问题 / 点击「总结」
    → 流式显示回答
    →「保存为笔记」→ 条目下新增 Note

7. 数据与隐私

7.1 本地数据

数据	存储位置	说明
Provider 预设、API Key、模型等	Zotero Preferences	前缀如 `extensions.chatpapers.*`
会话历史	插件本地存储（prefs JSON / SQLite / 文件，待技术选型）	按条目隔离
笔记内容	Zotero 数据库（用户主动保存时）	标准 Note 条目

7.2 外发数据

仅在用户点击发送 / 总结时，向用户当前所选 API 端点发送：

System Prompt（含模板与元数据，按设置）
组装后的 PDF 文本片段 / 选区
对话历史（按窗口策略）

行为约定：

选择 Ollama / LM Studio 时，请求发往本机，不经过第三方云（除非用户改成远程 Base URL）
选择 OpenRouter / OpenAI 等云端 时，内容发往对应服务商，设置页需显著提示
不默认发送：整个 Zotero 库、未打开条目、其他附件

8. 里程碑

里程碑	交付物	验收要点
M0	需求/开发文档定稿	本文档与开发文档评审通过
M1	插件骨架可安装	Zotero 9 加载、侧边栏占位、偏好页
M2	PDF 文本 + 单轮问答	能对当前 PDF 提问并显示回复
M3	流式 + 总结 + 存笔记	MVP 主路径闭环
M4	会话持久化 + i18n + 打包发布	可分发 `.xpi` 与更新清单
M5+	Post-MVP 能力	按优先级排期

9. 风险与依赖

风险	影响	缓解
Zotero 9 Reader / PDF API 变动	文本提取或侧边栏注入失败	跟进官方 changelog；抽象 Reader Adapter
超长论文超出模型上下文	回答质量下降	分块摘要、RAG、截断提示
扫描版 PDF 无文本	核心功能不可用	明确提示；后续可选 OCR
API 费用与密钥泄露	用户损失	本地存储、日志脱敏、用量提示
竞品功能重叠（PapersGPT 等）	差异化不足	聚焦「轻量、可自托管、笔记回流」

10. 待决策事项（需产品确认）

请在开工前确认以下选项：

开源协议：AGPL-3.0 vs MIT？
是否兼容 Zotero 8：仅 9，还是 8.*–9.*？
MVP 是否必须流式输出：可先非流式降低复杂度？
长文策略：仅截断 / 先分块摘要再问答 / 直接上简单 RAG？
默认 Provider 与默认模型：建议默认 openrouter 或 ollama？各预设的默认 model 字符串？（当前草案：无强制默认云，首次打开引导选择）
品牌名是否确定为 ChatPapers（插件 ID、命名空间将据此固定）？
对话历史是否需要跨设备同步（当前默认：不同步）？
~~Ollama / LM Studio / OpenRouter 是否进 MVP~~ → 已确认进 MVP（P0）

附录 A. 偏好项清单（草案）

Preference Key	类型	默认	说明
`extensions.chatpapers.provider`	string	`""`（首次引导）	预设 ID：`ollama` / `lmstudio` / `openrouter` / … / `custom`
`extensions.chatpapers.apiBaseUrl`	string	随预设	API 根路径（可覆写）
`extensions.chatpapers.apiKey`	string	`""`	API Key；本地预设可空
`extensions.chatpapers.model`	string	随预设	模型名
`extensions.chatpapers.openrouterReferer`	string	`https://github.com/chatpapers`	OpenRouter 可选 Referer
`extensions.chatpapers.openrouterTitle`	string	`ChatPapers`	OpenRouter 可选 X-Title
`extensions.chatpapers.temperature`	number	`0.3`	温度
`extensions.chatpapers.maxTokens`	number	`2048`	最大生成 Token
`extensions.chatpapers.timeoutMs`	number	`120000`	超时（本地大模型可调大）
`extensions.chatpapers.maxContextChars`	number	`80000`	上下文上限
`extensions.chatpapers.answerLanguage`	string	`zh-CN`	回答语言偏好
`extensions.chatpapers.systemPrompt`	string	（内置模板）	可覆盖
`extensions.chatpapers.summaryPrompt`	string	（内置模板）	总结模板
`extensions.chatpapers.sendMetadata`	bool	`true`	是否附带条目元数据
`extensions.chatpapers.verboseLog`	bool	`false`	调试日志

附录 B. 竞品参考（仅作范围对照，非抄袭目标）

PapersGPT、Zotero-easyGPT、llm-for-zotero：侧边栏对话 / 多模型
Zotero MCP 类插件：对外暴露库能力给 Cursor/Claude

ChatPapers MVP：单 PDF 对话 + 总结 + 笔记回流 + 多 Provider 预设（Ollama / LM Studio / OpenRouter 等）。

16 KiB Raw Permalink Blame History Unescape Escape