first commit

docs/requirements.md

@@ -0,0 +1,344 @@
+# ChatPapers 需求文档
+
+> 版本：v0.2（草案）  
+> 更新日期：2026-07-20  
+> 状态：待确认（Provider 预设范围已按产品意见更新）  
+> 关联：基于仓库根目录初步需求整理
+
+---
+
+## 1. 背景与目标
+
+### 1.1 背景
+
+研究人员日常在 Zotero 中管理大量 PDF 文献。现有 AI 阅读工具多为独立网页或外部应用，存在以下摩擦：
+
+- 需反复上传 PDF，上下文与 Zotero 条目割裂
+- 对话结果难以回流到文献库（笔记、标签、批注）
+- 工作流在「文献管理器 ↔ AI 工具」之间频繁切换
+
+### 1.2 产品目标
+
+在 **Zotero 9** 内提供原生体验的 AI 论文助手，使用户能够：
+
+1. **对着当前 PDF 提问**（选中文本 / 全文上下文）
+2. **一键生成结构化总结**（摘要、贡献、方法、局限等）
+3. **把有价值的 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 核心用户故事
+
+1. **作为**科研人员，**我希望**在阅读 PDF 时直接向 AI 提问选中段落，**以便**快速理解术语与论证。
+2. **作为**科研人员，**我希望**一键生成论文结构化摘要并写入笔记，**以便**后续检索与写作引用。
+3. **作为**用户，**我希望**使用自己的 API Key 与自定义 Base URL，**以便**接入公司代理、国产大模型或任意 OpenAI 兼容服务。
+4. **作为**用户，**我希望**一键选择 Ollama / LM Studio / OpenRouter 等常用接入，**以便**本地离线或聚合云端模型都能立刻用上。
+5. **作为**用户，**我希望**对话历史按「条目 / PDF」隔离保存，**以便**下次打开同一篇论文可续聊。
+6. **作为**用户，**我希望**回答尽量标注依据页码或原文片段，**以便**回读核验，降低幻觉风险。
+
+---
+
+## 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 主要界面
+
+1. **PDF Reader 侧边栏 — Chat**
+   - 顶部：当前论文短标题、模型名、设置入口
+   - 中部：消息列表（User / Assistant）
+   - 底部：输入框、附加选区按钮、发送、停止、快捷动作（总结）
+2. **偏好面板 — ChatPapers**
+   - Provider、凭据、模型、生成参数、Prompt 模板、隐私说明
+3. **（可选）独立对话窗口**：侧边栏空间不足时弹出（P2）
+
+### 6.2 关键流程（MVP 主路径）
+
+```text
+安装插件 → 配置 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. 待决策事项（需产品确认）
+
+请在开工前确认以下选项：
+
+1. **开源协议**：AGPL-3.0 vs MIT？
+2. **是否兼容 Zotero 8**：仅 9，还是 `8.*`–`9.*`？
+3. **MVP 是否必须流式输出**：可先非流式降低复杂度？
+4. **长文策略**：仅截断 / 先分块摘要再问答 / 直接上简单 RAG？
+5. **默认 Provider 与默认模型**：建议默认 `openrouter` 或 `ollama`？各预设的默认 model 字符串？（当前草案：无强制默认云，首次打开引导选择）
+6. **品牌名是否确定为 ChatPapers**（插件 ID、命名空间将据此固定）？
+7. **对话历史是否需要跨设备同步**（当前默认：不同步）？
+8. ~~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 等）**。